TypeScript SDK

@isnap/sdk is the TypeScript client of the iSnap API, published on npm under the MIT license. It runs in a server process, on Node.js or Bun. Read this page to install it, to check what it requires and to make a first call. These pages describe version 2.2.1.

Install

npm install @isnap/sdk

bun add @isnap/sdk

pnpm add @isnap/sdk

yarn add @isnap/sdk

The package has no runtime dependency and no peer dependency. It contains compiled JavaScript, its own type declarations, and four short scripts in its examples directory. The examples of these pages are other scripts: copy them from here. The SDK follows Semantic Versioning. Its version is independent of the API version: see Versions.

Requirements

Requirement	Detail
Runtime	Node.js 20 or later, or Bun 1.2 or later.
Runtime features	A global `fetch`, `Headers`, `AbortController` and `DOMException`, `crypto.randomUUID()`, a global `Buffer`, and the `node:crypto` module. The SDK includes no polyfill.
Module format	ESM only: the package is an ECMAScript module. There is one entry point, `@isnap/sdk`. Every export is a named export: there is no default export and no subpath export.
Where it runs	On a server. The SDK does not build for a browser.
TypeScript	Type declarations are included. The package declares no minimum TypeScript version.

ESM and CommonJS

Import the SDK from an ECMAScript module:

import { ISnapClient } from '@isnap/sdk'

In Node.js, require('@isnap/sdk') fails with ERR_PACKAGE_PATH_NOT_EXPORTED. CommonJS code loads the SDK with a dynamic import():

async function main () {
  const { ISnapClient } = await import('@isnap/sdk')
  const client = new ISnapClient({ apiKey: process.env.ISNAP_API_KEY ?? '', maxRetries: 2 })
  const { version } = await client.version()
  console.log(version)
}

main().catch((err) => {
  console.error(err)
  process.exitCode = 1
})

Server side only

The SDK is a server-side library. Its entry point imports node:crypto, so a browser bundle fails to build even when your code imports only the client. An API key is a secret: keep it on a server, and call the API from there.

TypeScript settings

The type declarations use the web platform types HeadersInit, Headers, RequestInit, Response, Blob and AbortSignal. A project therefore needs "lib": ["DOM"], or "skipLibCheck": true. Import the SDK from an ECMAScript module, with moduleResolution set to bundler, node16 or nodenext. A static import from a CommonJS file does not work:

Under node16, and under nodenext before TypeScript 5.8, it is a compile error (TS1479).
Under nodenext with TypeScript 5.8 or later, and under node10 with TypeScript 5, it compiles and then fails at run time with ERR_PACKAGE_PATH_NOT_EXPORTED. TypeScript 6 reports node10 as an error unless ignoreDeprecations is set, and TypeScript 7 refuses it.

Load the SDK from CommonJS with a dynamic import(), as in ESM and CommonJS. In TypeScript, this needs module set to node16 or nodenext: under commonjs, TypeScript compiles import() to a require(), which fails the same way. This tsconfig.json meets both requirements: it includes DOM, and it resolves modules with nodenext. It also loads the Node.js types, which TypeScript 6 and later do not load by default: install typescript and @types/node as development dependencies. With nodenext, a .ts file is an ECMAScript module when the nearest package.json has "type": "module":

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "lib": ["ES2022", "DOM"],
    "types": ["node"],
    "strict": true
  }
}

Make a first call

Create an API key in the iSnap dashboard and put it in the ISNAP_API_KEY environment variable. The SDK reads no environment variable: your code passes the key to the client.

import { ISnapClient } from '@isnap/sdk'

// The constructor throws when the key is missing or empty.
const client = new ISnapClient({ apiKey: process.env.ISNAP_API_KEY ?? '', maxRetries: 2 })

const { version } = await client.version()
console.log(`API version: ${version}`)

const { lines } = await client.lines.listMine()
for (const line of lines) {
  console.log(line.id, line.status)
}

client.version() calls GET /v1/version, which needs no credential. client.lines.listMine() calls GET /v1/lines/my: when the API refuses the key, the call throws AuthenticationError. Authentication describes the keys and the refusals. Creating a client makes no network call. Every method returns a promise that resolves with the data of the response or throws: see Errors and retries. The four list iterators are the exception: they return an AsyncIterable, see Pagination.

What the SDK adds to plain HTTP

The SDK adds	What it does	Read
Typed methods	One method for every operation of the API reference except `GET /v1/attention`. Request and response types are generated from the OpenAPI document.	Method reference
Typed errors	A failed call throws an error class chosen from the status, with `code`, `traceId` and `requestId`.	Errors
Automatic retries	A call is retried after a connection failure, a timeout, a `500`, a `503` and some `429` responses.	Automatic retries
An idempotency key on every write	By default, every `POST`, `PATCH`, `PUT` and `DELETE` call carries an `Idempotency-Key` header. The API reads it on eight operations only.	Idempotency keys
List iterators	A `for await` loop walks the pages of a cursor list.	Pagination
Webhook verification	`verifyWebhook` checks the signature and the timestamp of a delivery and returns the event.	Webhooks

Help

Write to support@isnap.ai with the trace_id and request_id of the response. The SDK exposes them as traceId and requestId on the error it throws.

​Install

​Requirements

​ESM and CommonJS

​Server side only

​TypeScript settings

​Make a first call

​What the SDK adds to plain HTTP

​Help