Polling and TypeScript SDK - Shor Documentation

Reconcile current state

List endpoints accept limit from 1 to 100 (default 50) and an opaque cursor. Keep filters unchanged while following a cursor. Cursors are bound to the workspace, resource and filters; never construct or edit them. Contracts, timesheets and payments support inclusive updatedSince. These feeds expose current state, not an event log or a snapshot across pages. Records can move while you scan. Treat polling as at-least-once: deduplicate by resource ID and update timestamp/version, retain an overlap window, and periodically do a full resync. Do not infer deletion from absence on one page or advance your checkpoint to the time the final page arrived. Preserve the start of a scan as your next watermark, with overlap. Contracts support includeDeleted=true so you can reconcile tombstones through deletedAt. A deleted worker’s embedded name is removed. Timesheets and payments have no public deletion feed. Milestones have no reliable update timestamp: enumerate each contract’s milestones again and compare their version values. Do not use a created-at cursor as a milestone change feed. Status-filtered lists are useful for queues, but a resource leaving that status will disappear; use unfiltered reconciliation scans for your local replica. Balance reads are an observation across ledger and database state, with an asOf timestamp, not a transactional guarantee or authorization to spend. Available balance deducts unposted outbound commitments and pending withdrawals, floored at zero. The current ledger does not expose pending incoming funds, so pending is 0 under the existing wallet semantics. An unavailable or numerically unsafe ledger response returns 503.

TypeScript client

The SDK’s ShorV1Client is the public API client. The existing ShorClient retains its internal application API behavior. Use the SDK version released for your environment; package publication is separate from API rollout.

import { ShorV1Client } from '@shor/sdk';

const shor = new ShorV1Client({
  baseUrl: process.env.SHOR_API_URL!,
  accessToken: process.env.SHOR_API_KEY!,
});

const business = await shor.business.get();
const page = await shor.timesheets.list({ status: 'submitted', limit: 50 });
const reviewed = await shor.timesheets.get(page.data[0].id);
// Obtain the operator's approval for these fetched details first.
const result = await shor.timesheets.approve(
  reviewed.id,
  { expectedVersion: reviewed.version },
  { idempotencyKey: crypto.randomUUID() },
);
if (result.paymentId) {
  const payment = await shor.payments.get(result.paymentId);
}

Namespaces cover business, contracts, timesheets, milestones, payments and balances. Pass an AbortSignal to cancel a request. Defaults are a 15-second total deadline and two retries for network failures and 429/502/503/504 responses. The same payload and intent key are retained across write retries. 409 and authorization errors are not automatically retried. ShorV1Error includes the HTTP status, stable code, request ID and Retry-After seconds, without retaining raw provider responses or request secrets. The public API currently excludes signing/activation, payout initiation, arbitrary ledger addresses, full worker profiles, search, upcoming-payment summaries and webhooks. Use the Shor application for those workflows.

Generated OpenAPI client

For direct access to generated operation types, use createShorV1OpenApiClient({ baseUrl, accessToken }) from @shor/sdk/openapi and call client.GET('/contracts', { params: { query: { limit: 25 } } }). Writes require params.header['Idempotency-Key']. This low-level client returns { data, error, response }, applies bearer authentication, a 15-second timeout and redirect rejection. It does not retry or runtime-validate response DTOs; use ShorV1Client for those policies. ShorV1Paths and ShorV1Operations are generated from the same committed OpenAPI document.

​Reconcile current state

​TypeScript client

​Generated OpenAPI client

Reconcile current state

TypeScript client

Generated OpenAPI client