Payrolla Node.js Client

Official TypeScript/JavaScript client for the Payrolla Payroll Calculation Service.

Features

• Fluent API - Three ergonomic API surfaces for different use cases
• Type-safe - Full TypeScript support with comprehensive type definitions
• Modern - Built with native fetch API (Node.js 16+)
• Zero dependencies - Lightweight with no external dependencies
• Secure - Built-in API key and token authentication
• TR-focused - Optimized for Turkish payroll calculations
• Well-documented - Comprehensive JSDoc comments and examples

Installation

npm install payrolla

Requirements

• Node.js 16.0.0 or higher (for native fetch support)

Quick Start

import { PayrollaClient } from 'payrolla';

// Create client with API key
const client = new PayrollaClient({
  apiKey: 'pk_live_xxxxx', // Get from your Payrolla dashboard
});

// Calculate net monthly payroll (Primary TR DSL - Recommended)
const result = await client
  .netMonthly(100_000)              // Net monthly wage
  .forPeriod(2025, 1)               // January 2025
  .regularDays(26, { name: 'Mesai' })
  .overtime(10, 1.5)                // 10 hours with 1.5x coefficient
  .calculate();

console.log('Total cost:', result.totalcost);
console.log('Net wage:', result.payrolls[0].payrollResult.totalNet);

Authentication

The client uses API key authentication via the x-api-key header.

const client = new PayrollaClient({
  apiKey: 'pk_live_xxxxx', // Get from your Payrolla dashboard
});

All requests automatically go to https://api.payrolla.app and include your API key in the headers.

API Surfaces

Payrolla client provides three API surfaces to match your coding style and use case:

1. Primary TR DSL (Recommended)

Opinionated, concise, Turkey-focused API. Best for most use cases.

// Net monthly wage
await client
  .netMonthly(100_000)
  .forPeriod(2025, 1)
  .calculate();

// Gross daily wage
await client
  .grossDaily(3_500)
  .forPeriod(2025, 1)
  .regularDays(22)
  .calculate();

// Net hourly wage
await client
  .netHourly(450)
  .forPeriod(2025, 1)
  .regularHours(160)
  .calculate();

2. Staged Builder (Power Users)

More explicit control over all parameters.

await client
  .newCalculation()
  .setMonthlyWage(100_000, 'Net')
  .forPeriod(2025, 1)
  .withMinWageExemption(true)
  .use30DayMonth()
  .calculate();

3. Raw Call (Full Control)

Direct API access with complete WageCalculationModel.

await client.calculate({
  calcDate: '2025-01-01',
  wageAmount: 100_000,
  cumulativeIncomeTaxBase: 0,
  cumulativeMinWageIncomeTaxBase: 0,
  ssiType: SSIType.S4A,
  wageCalculationType: CalculationType.Net,
  wagePeriodType: PaymentPeriodType.Monthly,
  periodCount: 1,
  periodLengthType: PeriodLengthType.Month,
  // ... other fields
});

Examples

Multi-line Regular Payments

const result = await client
  .netMonthly(100_000)
  .forPeriod(2025, 1)
  .regularDays(26, { name: 'Mesai', ref: '1' })
  .regularDays(5, { name: 'Hafta sonu', ref: '2' })
  .extraPayNet(50_000, { name: 'Bonus', ref: '3' })
  .calculate();

With Transferred SSI Base

const result = await client
  .grossMonthly(150_000)
  .forPeriod(2025, 1)
  .withTransferredSSI({ base1: 40000, base2: 200000 })
  .calculate();

Social Aid with Date-aware Exemptions

import { Predefined } from 'payrolla';

const result = await client
  .netMonthly(60_000)
  .forPeriod(2025, 1)
  .socialAid(3_000, Predefined.ChildAid) // Exemptions resolved by date
  .calculate();

30-day Month Calculation

const result = await client
  .netMonthly(100_000)
  .forPeriod(2025, 1)
  .use30DayMonth() // Use 30-day month instead of calendar days
  .calculate();

Validation Before Calculation

const builder = client
  .netMonthly(100_000)
  .forPeriod(2025, 1);

// Validate without executing
const validation = builder.validate();
if (!validation.isValid) {
  console.error('Validation errors:', validation.errors);
  return;
}

// Execute calculation
const result = await builder.calculate();

Build Model Without Execution

// Get the model synchronously without making API call
const model = client
  .netMonthly(100_000)
  .forPeriod(2025, 1)
  .build();

console.log('Model:', model);
// Use the model later or pass it to another function

Configuration

Client Options

const client = new PayrollaClient({
  apiKey: 'pk_live_xxxxx',  // API key (required)
  timeout: 60000,           // Optional timeout in ms (default: 30000)
});

Debug Mode

Enable debug logging for troubleshooting:

# Set environment variable
export PAYROLLA_DEBUG=true

# Or in .env file
PAYROLLA_DEBUG=true

Builder API Reference

Initialization Methods

• netMonthly(amount) - Start with net monthly wage
• grossMonthly(amount) - Start with gross monthly wage
• netDaily(amount) - Start with net daily wage
• grossDaily(amount) - Start with gross daily wage
• netHourly(amount) - Start with net hourly wage
• grossHourly(amount) - Start with gross hourly wage
• newCalculation() - Start with empty builder

Configuration Methods

• forPeriod(year, month) - Set calculation period
• withSSIType(type) - Set SSI type (S4A, S4B, S4C)
• withMinWageExemption(enabled?) - Enable/disable min wage exemption
• withTransferredSSI({ base1?, base2? }) - Set transferred SSI bases
• withDisabilityDiscount(amount) - Set disability discount
• use30DayMonth() - Use 30-day month
• useCalendarDayMonth() - Use calendar day month

Payment Methods

• regularDays(days, opts?) - Add regular payment by days
• regularHours(hours, opts?) - Add regular payment by hours
• overtime(hours, coeff?, opts?) - Add overtime payment
• extraPayNet(amount, opts?) - Add extra net payment
• extraPayGross(amount, opts?) - Add extra gross payment
• socialAid(amount, predefined?, opts?) - Add social aid

Execution Methods

• validate() - Validate builder state (synchronous)
• build() - Build WageCalculationModel (synchronous)
• calculate() - Execute calculation (async)

Type Exports

All TypeScript types and enums are exported:

import {
  PayrollaClient,
  SSIType,
  CalculationType,
  PaymentPeriodType,
  PaymentType,
  PaymentDetailType,
  MonthDayCount,
  Predefined,
  WageCalculationModel,
  WageResultModel,
  // ... and more
} from 'payrolla';

Error Handling

import { ApiError, AuthenticationError, NetworkError } from 'payrolla';

try {
  const result = await client
    .netMonthly(100_000)
    .forPeriod(2025, 1)
    .calculate();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof ApiError) {
    console.error('API error:', error.message, error.statusCode);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else {
    console.error('Unknown error:', error);
  }
}

Support

For issues and questions, please visit: https://github.com/runpayrolla/payrolla-node/issues

License

MIT License - see LICENSE file for details