TypeScript SDK

The gallery-platform package is the official TypeScript SDK for the API. Its resource surface is generated from the same OpenAPI document that powers this reference, so every operation, parameter, and response is typed and always in sync with the server.

npm install gallery-platform

Create a client

import { GalleryPlatform } from "gallery-platform";

const gp = new GalleryPlatform({
  apiKey: process.env.GALLERY_PLATFORM_API_KEY, // gpk_… or opk_…
  baseUrl: "https://gallery.example/api/v1",    // your platform host + /api/v1
});

The client mirrors the API's resources: gp.artworks, gp.artworks.images, gp.contacts, gp.contacts.tasks, gp.offers, gp.sales, gp.invoices, gp.lists, and — for organization (opk_) keys — the org plane under gp.org. As everywhere in the API, the gallery is implicit in the key: there is no tenant id to pass.

Make calls

Every call returns a typed result; destructure data and error:

const { data, error } = await gp.artworks.list({
  query: { status: ["available"], limit: 50 },
});

if (error) {
  // error is an APIError carrying the problem details (code, status, …)
} else {
  for (const artwork of data.data) console.log(artwork.title);
}

Prefer exceptions? Pass throwOnError: true on any call and the same error is thrown instead:

const { data: artwork } = await gp.artworks.get({
  path: { id: "…" },
  throwOnError: true,
});

Errors

Failures follow the API's RFC 9457 problem details. The SDK wraps them in APIError — branch on the stable code:

import { APIError } from "gallery-platform";

if (error instanceof APIError) {
  switch (error.code) {
    case "not_found":            // …
    case "plan_limit_exceeded":  // …
    case "rate_limited":         // error.retryAfter (seconds)
  }
}

APIConnectionError means no HTTP response was received at all.

Pagination

List endpoints use keyset cursors. paginate iterates items across pages, fetching each page on demand:

import { paginate } from "gallery-platform";

for await (const artwork of paginate((cursor) =>
  gp.artworks.list({ query: { status: ["available"], limit: 100, cursor } }),
)) {
  console.log(artwork.title);
}

paginatePages does the same but yields whole pages.

Retries and idempotency

The SDK retries connection errors, 408, 429, and 5xx responses (twice by default) with exponential backoff, honoring Retry-After. Retried writes are safe: every POST is stamped with a UUID Idempotency-Key before the first attempt, and a retry re-sends the same key, so the API replays the stored success instead of re-running the write. A key you set yourself always wins; maxRetries: 0 disables retries.

Requirements

Node.js ≥ 20.19 (or any runtime with fetch — browsers, edge workers). ESM and CommonJS. No runtime dependencies.