@rustgrid/sdk

First-party TypeScript SDK for RustGrid (HTTP).

• Typed models generated from openapi.json
• Ergonomic resources (rg.tickets.*, rg.projects.*, ...)
• Automatic x-request-id propagation
• Optional auth refresh hook
• Tenant scoping via X-Tenant-Id

Install

pnpm add @rustgrid/sdk
# or
npm i @rustgrid/sdk

Quickstart

import { RustGrid } from "@rustgrid/sdk";

const rg = new RustGrid({
  baseUrl: "https://app.rustgrid.com",
  tenantId: "<tenant-uuid>",
  accessToken: async () => localStorage.getItem("rg_token"),
  requestId: () => crypto.randomUUID(),
  clientName: "myapp/1.0.0",
});

const me = await rg.account.me();
console.log(me.data.user_id, me.data.permissions);

const created = await rg.tickets.create({ title: "Hello", project_key: "RG" }, { idempotencyKey: crypto.randomUUID() });
console.log(created.status, created.data, created.requestId, created.etag);

Auth refresh (optional)

const rg = new RustGrid({
  baseUrl,
  tenantId,
  auth: {
    async getAccessToken() { return tokenStore.get(); },
    async onAuthError() {
      await tokenStore.refresh();
      return true; // retry once
    },
  },
});

Regenerating types

The SDK ships with a generated src/gen/schema.ts. When the backend OpenAPI changes:

cp /path/to/openapi.json ./openapi.json
pnpm gen:types
pnpm build

Pagination iterator

for await (const t of rg.tickets.iterate({ project_id: projectId, size: 50 })) {
  console.log(t.id, t.title);
}

ETag / optimistic concurrency

const res = await rg.projects.get(projectId);
const etag = res.etag; // from header
await rg.projects.update(projectId, { name: "New" }, { ifMatch: etag! });

Retry policy (idempotent + 429 aware)

Retries are off-limits for non-idempotent requests unless you provide Idempotency-Key. For idempotent methods (GET/PUT/DELETE) and POST/PATCH with Idempotency-Key, the client can retry on:

• network errors
• 429 Too Many Requests (honors Retry-After when present)

const page = await rg.tickets.list(
  { size: 50 },
  { retry: { maxAttempts: 3, baseDelayMs: 250 } }
);

Examples

• examples/node-basic – Node 18+ script (env var driven)
• examples/browser-vite – Browser demo with Vite

Release checklist

pnpm i
pnpm typecheck
pnpm build
pnpm publish:dry
# then publish (when ready):
# npm publish --access public

GitHub Actions

• CI runs on PRs and main: typecheck, build, and publish:dry
• Release runs on tags v* and publishes to npm (requires NPM_TOKEN secret)

See docs/RELEASING.md.