SDK

TypeScript SDK

A typed TypeScript client for the Pixelbase API. Token exchange, refresh, pagination and errors are handled for you, so your code deals in customers and orders rather than in requests.

The SDK is in preview and the package is not published yet. Everything on this page is the shape it will ship with — until then, the REST API and the CLI do all of the same things today.

Install

Node 18.17 or newer. The package ships its own types — there is no @types package to add.

bash
npm install @pixelbase/sdk

Quick start

Create an API client on the Dev Tools page and pass its credentials. The client exchanges them for an access token on the first call and refreshes it before it expires, so there is no token handling in your code.

typescript
import { Pixelbase } from '@pixelbase/sdk';

const pxb = new Pixelbase({
  clientId: process.env.PXB_CLIENT_ID!,
  clientSecret: process.env.PXB_CLIENT_SECRET!
});

const { customers } = await pxb.customers.list({
  locationId: 'loc_abc123',
  limit: 20
});

for (const customer of customers) {
  console.log(customer.fullname, customer.email);
}

Configuration

clientIdRequired. The client_id of an API client.
clientSecretRequired. Its client_secret. Read it from the environment — never commit it.
baseUrlOptional. Defaults to https://www.pxb.app/api/public/v1. Point it at a preview deployment or a local server when testing.
companyIdOptional. Sent as X-Company-Id on every request. Only needed for a personal client whose owner belongs to more than one company — see Authentication.
maxRetriesOptional, defaults to 2. Retries a 429 or 5xx with exponential backoff, honouring Retry-After.

Pagination

Every list method returns one page plus its pagination block. When you want all of them, the async iterator walks the pages for you and stops when they run out.

typescript
for await (const order of pxb.orders.listAll({ locationId })) {
  await handle(order);
}

Errors

Anything that isn't a 2xx throws a PixelbaseError carrying the status, the message and — for a scope failure — exactly which scopes were missing, so you can tell a misconfigured client from a genuine failure without parsing prose.

typescript
import { PixelbaseError } from '@pixelbase/sdk';

try {
  await pxb.products.create({ locationId, name: 'Espresso', price: 400 });
} catch (err) {
  if (err instanceof PixelbaseError && err.status === 403) {
    console.error('Missing scopes:', err.missingScopes);
    return;
  }
  throw err;
}

Conventions

  • One namespace per collection. pxb.customers, pxb.orders, pxb.supportCases — each with list, get, create, update.
  • Types come from the API. Request and response types are generated from the same source as the endpoint reference, so they can't drift from what the server accepts.
  • Server-side only. The client credentials grant is not safe in a browser — anything shipped to a user can be read by that user. Call it from your own backend.
  • Scopes still apply. The SDK is a wrapper over the same API, so a client without products:write cannot write products through it either.