TypeScript SDK

Install

Node 18.17 or newer, or any runtime with a global fetch. The package ships its own types — there is no @types package to add.

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 mints a new one before it expires, so there is no token handling in your code.

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);
}

Every method returns the response's content — the { message, content } envelope is unwrapped for you.

Configuration

Every method also takes an options object last, for one call only: companyId, signal, timeout, maxRetries and headers.

await pxb.products.get('prod_1', { companyId: 'co_2', signal: AbortSignal.timeout(5000) });

Pagination

A list method returns one page plus its pagination block. When you want everything, listAll walks the pages for you — as large as the API serves them — and stops when they run out.

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

Errors

Anything that isn't a 2xx throws a PxbError carrying the status, the server's 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. A request that never got a response has status 0, with the underlying failure on cause.

import { PxbError } from '@pixelbase/sdk';

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

A rejected client secret throws before any request is sent, with code set to invalid_client.

Retries

• A 429 is always retried, after the Retry-After the server sent. It was refused before anything ran, so even a create is safe to send again.
• A 5xx or a dropped connection is retried with exponential backoff — except on a POST, which might have landed. Read it back before trying again.
• A 401 mints a fresh token and tries once more, in case the old one was revoked early.

Methods

One namespace per collection, each with the operations the API implements for it. This table is generated from the same spec as the package, and each method links to the endpoint it calls.

For anything not listed, pxb.request(method, path, { query, body }) calls any path under /api/public/v1/ with the same authentication, retries and errors.

Conventions

• Types come from the API reference. Request types are generated from the same source as the endpoint reference, so they can't drift from what it documents. Response types come from its examples, so beyond id a record's fields are optional — an example shows what a field looks like, not that it is always set.
• 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.