parasut-api-client

TypeScript client for Parasut API v4. Handles auth, token refresh, rate limiting, and maps every endpoint in the spec.

Install

npm install parasut-api-client

Quick start

import { ParasutClient } from 'parasut-api-client';

const client = new ParasutClient({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  username: 'YOUR_EMAIL',
  password: 'YOUR_PASSWORD',
  companyId: 'YOUR_COMPANY_ID', // optional — defaults to first company
});

await client.initialize(); // authenticates + fetches user info & company list

const invoices = await client.salesInvoice.list();
const contact = await client.contacts.show('123');

Auth

Uses OAuth2 password grant. Tokens are fetched on initialize() and refreshed automatically when they expire — tries refresh_token first, falls back to password grant.

Rate limiting is built in (10 req / 10s, matching the API's limit).

Token sharing across instances

If you're running multiple processes or want to cache tokens (e.g. in Redis), use xid and onTokenReceived:

const client = new ParasutClient({
  xid: 'my-app-instance',
  // ...credentials
  onTokenReceived(token, expiresAt, xid) {
    redis.hset(`parasut:${xid}`, { token, expiresAt });
  },
});

Another instance can inject a cached token:

client.updateToken(cachedToken, cachedExpiresAt, 'my-app-instance');

Modules

Every method is typed — returns ApiResponse<T> or ApiListResponse<T> instead of any.

| Module | What it covers | | --- | --- | | salesInvoice | CRUD, payments, cancel, recover, convert to invoice, PDF | | salesOffer | CRUD, PDF | | purchaseBills | CRUD, payments, cancel, recover | | contacts | CRUD, debit/credit transactions, contact people | | products | CRUD | | accounts | CRUD, debit/credit transactions | | transactions | Show, delete | | employees | CRUD, archive/unarchive | | salaries | CRUD, payments | | taxes | CRUD, payments | | bankFees | CRUD, payments | | tags | CRUD | | itemCategories | CRUD | | warehouses | CRUD | | shipmentDocuments | CRUD | | stockMovements | List, show | | stockUpdates | List | | inventoryLevels | List | | eInvoice | Create, show, PDF | | eArchive | Create, show, PDF | | eSmm | Create, show, PDF | | eInvoiceInboxes | List | | webhooks | CRUD | | trackableJobs | Show | | sharings | Create (send doc via email/link) | | companies | List, show | | apiHome | GET /me (user info) |

Examples

Create a sales invoice

const invoice = await client.salesInvoice.create({
  data: {
    type: 'sales_invoices',
    attributes: {
      item_type: 'invoice',
      issue_date: '2026-01-15',
      currency: 'TRL',
    },
    relationships: {
      contact: {
        data: { id: '123', type: 'contacts' },
      },
      details: {
        data: [
          {
            type: 'sales_invoice_details',
            attributes: {
              quantity: 1,
              unit_price: 100.0,
              vat_rate: 18,
              description: 'Consulting',
            },
          },
        ],
      },
    },
  },
});

Pagination, filtering, includes

const page = await client.contacts.list({
  page: 1,
  per_page: 25,
  filter: { name: 'Acme' },
  sort: '-created_at',
  include: 'contact_people',
});

// page.data  — array of contacts
// page.meta  — { current_page, total_pages, total_count, ... }

Error handling

API errors come back as ParasutApiError with the full response body:

import { ParasutApiError } from 'parasut-api-client';

try {
  await client.contacts.show('nonexistent');
} catch (err) {
  if (err instanceof ParasutApiError) {
    console.log(err.status);     // 404
    console.log(err.statusText); // "Not Found"
    console.log(err.body);       // full JSON:API error body
  }
}

Must call initialize() first

Accessing any module before initialize() throws a clear error:

const client = new ParasutClient({ /* ... */ });
client.contacts.list(); // throws: "Cannot access contacts.list before calling client.initialize()"

Development

npm run build        # compile typescript
npm test             # run tests (168 unit tests)
npm run test:watch   # watch mode
npm run test:coverage

Upgrading from v1

See CHANGELOG.md for the full list. The big ones:

• Removed methods that didn't actually exist in the API: salesInvoice.listLines(), .print(), .sendEmail(), .approve(), transactions.update(), bankFees.list()
• salesOffer.getPdf() renamed to salesOffer.createPdf() (it's a POST)
• salesInvoice.cancel() is now DELETE (was incorrectly PATCH)
• API errors throw ParasutApiError instead of generic Error
• Must call await client.initialize() before using modules

Links

• Parasut API docs
• JSON:API spec

License

MIT