> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shorpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Polling and TypeScript SDK

> Reconcile resources and use the typed v1 client.

## 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.

```ts theme={null}
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.