---
title: "TypeScript and Node.js SDK — Anis Developers"
description: "The Anis Partner SDK for Node.js 22 and later, written in TypeScript — install, configure, call, place orders safely, handle refusals and observe."
url: https://developers.anis.ly/sdks/typescript/
language: en
---

> Every page of this documentation: https://developers.anis.ly/llms.txt

# TypeScript and Node.js SDK

`@anis-ly/partners` — for **Node.js 22 and later**, written in TypeScript, with ES module and CommonJS builds and full types. It uses Node’s own `fetch` and WebCrypto; its one dependency is the OpenTelemetry API.

- Package: [npmjs.com/package/@anis-ly/partners](https://www.npmjs.com/package/@anis-ly/partners)
- Source code: [github.com/anis-ly/anis.partners-sdk-node](https://github.com/anis-ly/anis.partners-sdk-node)

> **An optional helper, provided as is**
>
> Every Anis SDK is provided free of charge under the MIT License, “as is”, without warranty of any kind. Anis (Aniscom for Technical Services) accepts no responsibility or liability for its use or for any loss arising from it. You remain responsible for your own integration — recording orders before you send them, recovery, key custody and testing. The source code is public: read it to understand exactly what it does before you rely on it. You do not need an SDK — you can call the Anis Partner API directly using these guides and the [API reference](https://developers.anis.ly/reference.md).

SDK **2.2.0**. SDK 1.x is deprecated; see the [changelog](https://developers.anis.ly/changelog.md).

## Install

```bash
npm install @anis-ly/partners@2.2.0
```

Every release is published from GitHub with a signed provenance statement, which npm shows on the package page.

## Configure

```ts
import { AnisPartnersClient, PemP256Signer } from '@anis-ly/partners';

const signer = (await PemP256Signer.fromPemFile('/secure/partner-key.pem')).forKey(keyId);
const client = AnisPartnersClient.create({
  options: {
    authority: 'https://<the address Anis gave you>',
    signatureLifetimeSeconds: 60,
    acceptLanguage: 'ar',
    signingKeyCacheSeconds: 300,
    timeoutMs: 30_000,
  },
  signer,
});
```

The settings are checked when you create the client: an address that is not HTTPS (plain HTTP is accepted only on your own machine), a signature lifetime outside 1 to 60 seconds, or a key cache longer than 5 minutes stops it there.

**The signer is a separate step on purpose.** `PemP256Signer` signs with a key file. For a vault or hardware module, implement `RequestSigner` — your `keyId` and a `sign(bytes)` method that returns the 64-byte signature — and the key never enters your process.

**Serverless and multi-instance hosts:** pass a `keyCache` (`get` and `set`) so instances share Anis’s public signing-key document instead of each fetching it. Use a cache only your application can write. The SDK keeps Anis’s key list for at most 5 minutes, counted from when it was fetched, even when it comes from the shared cache.

Every call accepts `{ signal }`, an `AbortSignal` that cancels everything the call does.

## Use it

```ts
const profile = await client.profile.get();

for await (const wallet of client.wallets.list()) {                       // every page, followed for you
  console.log(wallet.name ?? wallet.id, wallet.balance.toString());
}

for await (const card of client.catalogue.listCards(walletId, subcategoryId)) {
  console.log(card.id, card.unitPrice?.toString());
}

const credential = await client.ownedCards.reveal(walletId, soldCardId);
```

Amounts are `Money` values with exactly three decimal places — never JavaScript numbers. `Money.of('10.500', 'LYD')` and `price.multiply(2)` do exact arithmetic.

## What it verifies

SDK 2.0.1 and later verify **every answer** of the calls Anis signs — place an order, read an order, reveal a card, reveal an invoice’s cards, the four enrolment calls, application suspension, key revocation and the signature self-check — success and every refusal. It requires the signature there: an answer on one of these calls without a valid signature is thrown away (`UnverifiableResponseError`) and, on an order, comes back as `unknown`. It does not verify the information calls — your profile, wallets, the catalogue and your owned cards (list and read): their answers carry no signature, and TLS protects them. It still signs every request. See [Verifying answers](https://developers.anis.ly/docs/verifying-answers.md) for which answers are signed.

## Orders

```ts
const price = card.unitPrice;
if (!price) throw new Error('This card has no price for this wallet.');

const operationId = crypto.randomUUID();                                   // yours
const request = { cardId: card.id, quantity: 2, expectedUnitPrice: price, expectedTotal: price.multiply(2) };
await saveOrderIntent(operationId, walletId, request);                     // store it BEFORE sending

const result = await client.orders.create(walletId, operationId, request);

if (result.kind === 'completed') await storeCredentials(result.credentials);   // store FIRST

switch (result.kind) {
  case 'completed':
    if (result.codesWithheld) await reportCodesWithheld(operationId);       // paid, codes withheld: do not buy again; write to support@anis.ly
    break;
  case 'replayed':
    await ensureStored(result.order);                                     // sent earlier: reveal by invoice if you never stored them
    break;
  case 'processing':
  case 'unknown':
    await resumeLater(operationId, result.suggestedDelayMs);             // may still complete: resume with the SAME id
    break;
  case 'notPlaced':
    await closeNotPlaced(operationId, result.refusal);                   // nothing bought: fix the cause, new order, new id
    break;
}
```

`client.orders.resume(walletId, operationId, request)` sends the same order again under the same id — the way to recover — and returns the same five outcomes. Recovery is always this signed resend, never a loop of `client.orders.get()`, which only reads state. An order whose status is `recoveryExhausted` is **not** failed: keep resuming the same id, slowly (minutes, not seconds), and tell [support@anis.ly](mailto:support@anis.ly) the operation id. See [Orders and recovery](https://developers.anis.ly/docs/orders-and-recovery.md) for the full rules.

> **No retry wrapper around fetch**
>
> A retrying `fetch` resends the same signed request with the same one-time value, and Anis refuses the copy. Recover orders with `orders.resume()`, which signs a fresh request.

## Refusals

An order does not throw a refusal: it comes back as `notPlaced` or `unknown`. Other calls reject with an `AnisApiError` (or a subclass such as `PriceChangedError` or `InsufficientBalanceError`) carrying `code`, `requestId`, `retryAfter` and `isReplayed`. Each [error page](https://developers.anis.ly/errors.md) names the code.

| Error | Means | On an order |
| --- | --- | --- |
| `UnverifiableResponseError` | An answer on a signed call could not be shown to come from Anis; it was thrown away | Not thrown — `unknown`: resume with the same id |
| `LimitExceededError` (`spending_limit_exceeded`, 429) | The order would pass the application’s or wallet’s spending cap for the current window; nothing was bought or charged | Not thrown — `notPlaced`. After `retryAfter` seconds, place a new order with a new id; never resume this one |
| `RequestSigningError` | Your signer failed; nothing was sent | Thrown — send it again once the signer works |
| `TypeError`, `RangeError` | Your input was wrong (an id that is not a UUID, a total that is not unit price × quantity); nothing was sent | Thrown before anything is sent |

Every SDK error extends `AnisPartnersError`, so one `instanceof` check covers them all.

## Observability

Pass any logger with `debug`, `info`, `warn` and `error` (pino, winston and `console` all fit) as `logger`; traces and metrics go through OpenTelemetry under `@anis-ly/partners`. No key, signature, one-time value or card code is ever recorded. See [Observability](https://developers.anis.ly/docs/observability.md) for what to alert on.

## Methods and card answers

Owned-card calls use `/v1/wallets/{walletId}/owned-cards`, its `/{soldCardId}` read and `/{soldCardId}/reveal`, and `/v1/wallets/{walletId}/invoices/{invoiceId}/owned-cards/reveal`. Catalogue card reads use `GET /v1/wallets/{walletId}/catalog/cards/{cardId}`.

`CardSummary` is shared by owned cards, reveals and order `soldCards`: card id and localized name, optional face value and logo, subcategory and category. Owned cards use `soldCardId` and `operationId`. Revealed credentials inside orders include invoice id, card summary and purchase time too. Empty strings and empty localized text are omitted. Money is a string with three decimals and an uppercase three-letter currency — negative only for a wallet balance while the wallet uses allowed debt; read a wallet’s currency from `balance.currency`.

The SDK requires the v2 signing tag, both request signature headers in the covered list, and the key-document lifecycle checks. See [Verifying answers](https://developers.anis.ly/docs/verifying-answers.md). Stops are immediate; only Anis staff can resume an application, and revoking your current key requires new enrolment. See [Security](https://developers.anis.ly/docs/security.md).

```ts
const reason = "Suspected compromise";
const catalogueCard = await client.catalogue.getCard(walletId, cardId);
const suspended = await client.access.suspendApplication(reason);
const revoked = await client.access.revokeKey(keyId, reason);
```

## Product resources in SDK 2.2.0

SDK 2.2.0 adds `meterCharges`, `directRechargeProducts` (products, locations, quote), `directRecharges` (create, a list of your own, read and recipient updates), `webhookEndpoint`, `webhookEvents`, a webhook signature verifier and updated error types. Upgrade from 2.1.0 to use them. Follow the [meter](https://developers.anis.ly/docs/meter-charges.md), [Direct recharge](https://developers.anis.ly/docs/direct-recharge.md) and [webhook](https://developers.anis.ly/docs/webhooks.md) guides for HTTP behavior. Keep the operation id and exact body before a money-moving call; a lost answer is recovered with the same id. Each SDK’s README and its docs/webhooks.md give the method names and the verifier’s arguments.