@ghxstship/xos-sdk
The TypeScript SDK for the XOS public API. Models, method signatures and the operation table are generated from the OpenAPI v1 document, so every operation in the API reference is a typed method. It runs on Node.js 22.12 or later, in browsers and on edge runtimes, and has no dependencies.
npm install @ghxstship/xos-sdk
Use
import { XosClient } from "@ghxstship/xos-sdk";
const xos = new XosClient({
baseUrl: "https://api.ghxstship.tech/v1",
apiKey: process.env.XOS_API_KEY,
});
const { data: project, etag } = await xos.projects.get(projectId);
await xos.projects.update(projectId, { name: "Harborfront Fall Series" }, { ifMatch: etag! });
for await (const po of xos.purchaseOrders.listAll({ filter: { po_state: { eq: "Approved" } } })) {
console.log(po.po_number);
}
- POST methods send an
Idempotency-Keyand reuse it on retries. - Updates require
ifMatch; a stale ETag fails withXosPreconditionFailedError. - Problem responses are raised as typed
XosApiErrorsubclasses, such asXosValidationErrorandXosNotFoundError. - Rate limits and
Retry-Afterare honored, withmaxRetries(default 2) andtimeoutMs(default 30000).
Verify webhook signatures with the @ghxstship/xos-sdk/webhooks entry point:
import { verifyWebhookSignature } from "@ghxstship/xos-sdk/webhooks";
const result = await verifyWebhookSignature({
payload: rawBody, // the body exactly as received
header: request.headers.get("XOS-Signature") ?? "",
secret: process.env.XOS_WEBHOOK_SECRET!,
});
Documentation
- Guide: TypeScript SDK
- API reference: the docs site, generated from
packages/api/openapi/v1.json
Versioning
The package version follows the XOS release (v4.0.0 publishes 4.0.0). Within /v1 the API changes only additively, so a newer SDK keeps working against an older server for every operation both know.
License
MIT. See LICENSE. The XOS platform itself is AGPL-3.0-only.