# JavaScript SDK

The JavaScript SDK is TypeScript-first and exposes services for:

- receipt processing
- credit note processing
- matching
- verification
- store management


Source code and releases: [cheqi-io/cheqi-sdk-javascript](https://github.com/cheqi-io/cheqi-sdk-javascript)

## Installation

```bash
npm install @cheqi/sdk@0.4.0
```

## Initialization

```javascript
import { CheqiSDK, Environment } from "@cheqi/sdk";

const sdk = CheqiSDK.builder()
  .apiEndpoint(Environment.SANDBOX)
  .apiKey(process.env.CHEQI_API_KEY)
  .build();
```

Custom endpoint:

```javascript
const sdk = CheqiSDK.builder()
  .customApiEndpoint("http://localhost:8080")
  .receiptDownloadBaseUrl("http://localhost:5190")
  .apiKey(process.env.CHEQI_API_KEY)
  .build();
```

## Receipt flow

```javascript
import { PaymentType, UnitCode } from "@cheqi/sdk";

const customer = {
  paymentType: PaymentType.CARD_PAYMENT,
  cardDetails: {
    paymentAccountReference: "PAR123456789",
    cardProvider: "VISA",
  },
  recipientEmail: "customer@example.com",
};

const receiptRequest = {
  documentNumber: "INV-2026-001",
  issueDate: new Date().toISOString(),
  currency: "EUR",
  receiptSubtotal: 10.00,
  totalBeforeTax: 10.00,
  totalTaxAmount: 2.10,
  totalAmount: 12.10,
  products: [
    {
      name: "Coffee",
      identifier: "SKU-COFFEE-001",
      quantity: 2,
      baseQuantity: 1,
      unitCode: UnitCode.C62, // C62 = "each" (a single unit); see UnitCode for other UN/ECE codes
      unitPrice: 5.00,
      subtotal: 10.00,
      total: 12.10,
      taxes: [
        {
          rate: 21.0,
          type: "VAT",
          taxableAmount: 10.00,
          amount: 2.10,
        },
      ],
    },
  ],
  taxes: [
    {
      rate: 21.0,
      type: "VAT",
      taxableAmount: 10.00,
      amount: 2.10,
      label: "VAT 21%",
    },
  ],
};

const result = await sdk.receiptService.processCompleteReceipt(
  customer,
  receiptRequest
);
```

`processCompleteReceipt` handles the selected delivery route and transient download states:

- `DIGITAL` uses normal encrypted delivery.
- `EMAIL_FALLBACK` uses the configured email fallback.
- `DOWNLOAD_FALLBACK` creates and uploads a client-encrypted download link.
- `routeFound: false` returns `CUSTOMER_NOT_FOUND` without bypassing a disabled download fallback.
- a transient matching or template failure returns `PENDING_DOWNLOAD_TEMPLATE` with a customer URL.
- an ambiguous upload returns `PENDING_DOWNLOAD_UPLOAD` with the exact ciphertext to persist and retry.


Your integration owns durable storage, scheduling, retries, monitoring, and retention for pending results. See [Download links](/receipts/download-fallback) for the recovery contract.

OAuth access token:

```javascript
const result = await sdk.receiptService.processCompleteReceipt(
  customer,
  receiptRequest,
  accessToken
);
```

## Matching flow

```javascript
const matchResponse = await sdk.matchingService.matchCustomer(customer);
```

Use the returned `buyerCountryCode`, `buyerType`, and `acceptedFormats` when you build a manual template-generation request. `buyerCountryCode`, `buyerType`, and `taxesApplied` are mandatory for direct template generation. The complete receipt flow fills those template-generation fields from recipient resolution for you.

## Verification flow

```javascript
const cheqiHash = sdk.verificationService.calculateCheqiReceiptHash(cheqiReceiptJson);
const ublHash = sdk.verificationService.calculateUblHash(ublPurchaseReceiptXml);
```

## Credit note flow

The JavaScript SDK also exposes `sdk.creditNoteService` for complete credit note processing against an existing `cheqiReceiptId`. Use this when documenting or implementing returns, not the receipt service.

## Store flows

The SDK exposes:

- `sdk.storeService`


Use the store service for branch/store management flows.