Build an integration

TypeScript SDK

Use typed methods for Asteri’s API, with authentication and error handling included.

On this page

Install the SDK

The package is @asteri/public-api-sdk. Use it in a server-side TypeScript or JavaScript integration.

Package install

pnpm add @asteri/public-api-sdk

Release tarballs and the matching OpenAPI document are also available from the current release downloads.

Create a client and make a request

Set the app origin and read your API key from a server environment secret. The client sends the bearer header and the key selects the company.

List customers and create an estimate

import { randomUUID } from 'node:crypto';
import { AsteriPublicApiClient } from '@asteri/public-api-sdk';

const client = new AsteriPublicApiClient({
  baseUrl: 'http://localhost:3000',
  apiKey: process.env.ASTERI_API_KEY!,
});

const customers = await client.customers.list({
  query: { limit: 25 },
});

const estimate = await client.estimates.create(
  {
    customer_id: '8af2ca8e-8f31-4e6e-a46c-0703b61f7ca3',
    currency: 'USD',
    line_items: [
      { name: 'Quarterly hood cleaning', quantity: 1, unit_price: 1825 },
    ],
  },
  { idempotencyKey: randomUUID() }
);

Save a unique idempotency key for each intended write before sending it. Reuse that value if you retry the same action. The example generates a new key for a new estimate.

Handle API errors

Non-success responses throw AsteriApiError. Read the status, parsed response, retry delay, and contract version directly from the error.

Inspect an API error

import { AsteriApiError, AsteriPublicApiClient } from '@asteri/public-api-sdk';

const client = new AsteriPublicApiClient({
  baseUrl: 'http://localhost:3000',
  apiKey: process.env.ASTERI_API_KEY!,
});

try {
  await client.customers.list();
} catch (error) {
  if (error instanceof AsteriApiError) {
    console.error(error.status);
    console.error(error.payload);
    console.error(error.retryAfter);
  }

  throw error;
}

For rate limits, wait for retryAfter before retrying. Correct authentication and permission problems before sending the request again.

Read every page of customers

Pagination helpers keep requesting pages until the list is complete. They reject malformed cursors or a reached page limit so your integration can handle an incomplete read explicitly.

List all customers

import { AsteriPublicApiClient, listAllCustomers } from '@asteri/public-api-sdk';

const client = new AsteriPublicApiClient({
  baseUrl: 'http://localhost:3000',
  apiKey: process.env.ASTERI_API_KEY!,
});

const customers = await listAllCustomers(client, {
  pageSize: 100,
});

Understand API paginationSee how cursors and page sizes work in collection responses.

Download a matching release

The SDK and OpenAPI document are versioned together. The current release artifacts use the prerelease tag public-api-preview-latest.

Open release downloads

Install asteri-public-api-sdk-0.1.0.tgz

npm install https://github.com/Asteri-Labs/asteri/releases/download/public-api-preview-latest/asteri-public-api-sdk-0.1.0.tgz

Download asteri-public-api-openapi.json

curl -L https://github.com/Asteri-Labs/asteri/releases/download/public-api-preview-latest/asteri-public-api-openapi.json -o asteri-public-api-openapi.json

Working in the Asteri repository

These commands are for contributors running an Asteri checkout. You do not need them to call the API from your own application.

Workspace install, runnable examples, and client generation

Install from the workspace

Workspace install

pnpm --filter web add @asteri/public-api-sdk@workspace:*

Run the SDK examples

The repository includes list-all-customers.ts and create-estimate.ts in packages/public-api-sdk/examples.

Read customers

ASTERI_BASE_URL=http://localhost:3000 \
ASTERI_API_KEY=ast_live_your_key \
pnpm -C packages/public-api-sdk example:list-all-customers

Create an estimate

ASTERI_BASE_URL=http://localhost:3000 \
ASTERI_API_KEY=ast_live_your_key \
ASTERI_CUSTOMER_ID=customer-uuid \
pnpm -C packages/public-api-sdk example:create-estimate

Run the starter app

apps/public-api-starter includes customer, appointment, and estimate creation plus a local webhook inbox at /webhooks/asteri.

Start the local example app

ASTERI_BASE_URL=http://localhost:3000 \
ASTERI_API_KEY=ast_live_your_key \
ASTERI_WEBHOOK_SECRET=your_webhook_secret \
PORT=4010 \
pnpm dev:public-api-starter

Regenerate the client

After a contract change, generate the client from this checkout’s OpenAPI definitions. Keep generated files out of manual edits.

Generate the SDK

pnpm sdk:public-api:generate