@onebooks/node 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OneBooks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,360 @@
-# Temporary Holding Version
+# @onebooks/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Server-side SDK for the OneBooks API: an authenticated HTTP client with
+sane retries, OAuth 2.0 helpers (PKCE, code exchange, refresh, RFC 8693
+session-token exchange), ES256 App Bridge session-token verification (via
+JWKS), and webhook signature verification.
+
+ESM, TypeScript, Node ≥ 20. One runtime dependency: [`jose`](https://github.com/panva/jose)
+(JWKS fetching + ES256 verification).
+
+## Install
+
+```bash
+npm install @onebooks/node
+```
+
+## Quickstart
+
+```ts
+import { OneBooksClient } from '@onebooks/node';
+
+const client = new OneBooksClient({ accessToken: process.env.ONEBOOKS_ACCESS_TOKEN! });
+
+const invoice = await client.get(`/invoices/${invoiceId}`);
+
+// A write the API de-duplicates by Idempotency-Key — and that the SDK may
+// therefore safely retry after a dropped connection (see "Retries").
+const created = await client.post('/invoices', { customerId, lineItems }, {
+  idempotencyKey: crypto.randomUUID(),
+});
+
+// List endpoints are page-based and return their own shape:
+const { invoices, total } = await client.get<{ invoices: unknown[]; total: number }>('/invoices', {
+  query: { page: 1, limit: 50 },
+});
+
+// The event log is cursor-paginated — iterate it without managing cursors:
+for await (const event of client.events.iterate({ types: ['invoice.paid'] })) {
+  console.log(event.type, event.resourceId);
+}
+```
+
+## `OneBooksClient`
+
+```ts
+new OneBooksClient({
+  accessToken?: string;
+  getAccessToken?: () => string | Promise<string>;
+  apiBase?: string;      // default "https://api.getonebooks.com"
+  apiVersion?: string;   // sent as the "OneBooks-Version" header
+  maxRetries?: number;   // default 3
+  fetch?: typeof fetch;  // override for tests / custom runtimes
+})
+```
+
+Provide **either** `accessToken` (a static token) **or** `getAccessToken`
+(called before every request — use this if you refresh tokens elsewhere, a
+token store, per-installation tokens, etc). Exactly one is required; the
+constructor throws otherwise.
+
+### `request(method, path, options?)`
+
+```ts
+client.request<T>(method: 'GET'|'POST'|'PUT'|'PATCH'|'DELETE', path: string, options?: {
+  query?: Record<string, string | number | boolean | Array<string|number> | null | undefined>;
+  body?: unknown;
+  idempotencyKey?: string;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}): Promise<T>
+```
+
+Also exposed as `client.get(path, options?)`, `client.delete(path, options?)`
+and `client.post/put/patch(path, body?, options?)`.
+
+### Retries
+
+Up to `maxRetries` (default 3) extra attempts, by this rule:
+
+| Failure | Retried for |
+|---|---|
+| `429 Too Many Requests` | **Every method.** A rate-limited request was never processed, so replaying it is always safe. Honors `Retry-After` (seconds or an HTTP date). |
+| Network error (connection reset, timeout, DNS), `502`, `503`, `504` | **`GET`/`HEAD` only — or any method when you pass `idempotencyKey`.** Jittered exponential backoff. |
+| Anything else (`400`, `401`, `403`, `404`, `409`, `422`, `500`, …) | Never. |
+
+Why writes are different: after a network error or a gateway `5xx` the API
+may already have processed the request — only the response was lost. Blindly
+re-sending a `POST /customers` would create a second customer. With an
+`idempotencyKey` the SDK re-sends the **same** `Idempotency-Key` header, and
+the API returns the original result instead of acting twice.
+
+Only these endpoints de-duplicate on `Idempotency-Key` today:
+`POST /invoices`, `POST /invoices/:id/payments`, `POST /payments`,
+`POST /payments/allocate` and `POST /journal`. Elsewhere the header is
+accepted but ignored — setting a key there makes the SDK retry, yet the
+server cannot de-duplicate, so only set one where it is honored (or where a
+duplicate is harmless). A write without a key fails fast instead: catch the
+error and reconcile (for example, look the record up) before trying again.
+
+On exhausting retries, or on any non-retried failure, the promise rejects
+with `OneBooksApiError` (a network error is re-thrown as-is):
+
+```ts
+class OneBooksApiError extends Error {
+  status: number;
+  code?: string;                  // machine-readable code; absent for class-validator array messages and OAuth endpoints
+  body: unknown;                  // the full parsed (or raw text) response body
+  oauthError?: OAuthErrorCode;    // OAuth helpers only: the RFC 6749 `error` code, e.g. "invalid_grant"
+  oauthErrorDescription?: string; // OAuth helpers only: `error_description`, when sent
+  retryAfter?: number;            // seconds, from the response's Retry-After header (every 429 has one)
+}
+```
+
+Branch on `.code`, not `.message` — see the [errors doc](../../developer-web/src/content/docs/errors.mdx).
+Errors from the [OAuth helpers](#errors-from-the-oauth-helpers) carry
+`.oauthError` instead.
+
+### `paginate(path, query?, options?)`
+
+```ts
+for await (const event of client.paginate<OneBooksEventEnvelope>('/events', { types: 'invoice.paid' }, { cursorParam: 'after' })) { ... }
+```
+
+Async-iterates every item of a **cursor-paginated** endpoint — one that
+returns `{ data, hasMore, nextCursor }`. `options.cursorParam` names the
+query parameter the endpoint reads the cursor from (default `"cursor"`).
+
+Today the only cursor-paginated partner endpoint is `GET /events` (cursor
+parameter `after`) — prefer `client.events.iterate()`, which wraps exactly
+this. Resource lists such as `GET /invoices` are **page-based** and return
+their own shape (`{ invoices, total }`, with `page`/`limit` query
+parameters), so `paginate()` does not apply to them; page them with
+`client.get()`.
+
+### `appData` — Contract 6 partner app-data API
+
+```ts
+await client.appData.definitions();                    // -> AppDataDefinition[]
+await client.appData.get({ resourceType: 'INVOICE', resourceId: 'inv_1' });      // -> AppDataValue[]
+await client.appData.get({ resourceType: 'INVOICE', resourceIds: ['a', 'b'] });  // -> AppDataValue[]
+await client.appData.set([{ resourceType: 'INVOICE', resourceId: 'inv_1', key: 'tracking_number', value: '1Z...' }]); // up to 25; value: null deletes
+await client.appData.delete(valueId);
+```
+
+### `events` — Contract 6 partner events API
+
+```ts
+const page = await client.events.list({ types: ['invoice.paid'], limit: 50 });
+const event = await client.events.get(eventId);
+
+for await (const event of client.events.iterate({ after: lastSeenEventId })) {
+  // process, then persist event.id as your new "after" cursor
+}
+```
+
+## OAuth helpers (`oauth`)
+
+Standalone functions — you need these *before* you have a client/token, so
+they don't hang off `OneBooksClient`:
+
+```ts
+import { oauth } from '@onebooks/node';
+
+const { codeVerifier, codeChallenge } = await oauth.createPkcePair();
+
+const authorizeUrl = oauth.buildAuthorizeUrl({
+  clientId, redirectUri, scopes: ['invoices:read'], state, codeChallenge,
+});
+// -> redirect the user's browser here
+
+// ... on your callback route:
+const tokens = await oauth.exchangeCode({
+  clientId, clientSecret /* confidential only */, code, redirectUri, codeVerifier,
+});
+
+const refreshed = await oauth.refresh({ clientId, clientSecret, refreshToken: tokens.refresh_token! });
+
+await oauth.revoke({ clientId, clientSecret, token: tokens.refresh_token!, tokenTypeHint: 'refresh_token' });
+
+const introspection = await oauth.introspect({ clientId, clientSecret, token: tokens.access_token });
+```
+
+A **public** (PKCE) client omits `clientSecret` everywhere above — the SDK
+sends `client_id` in the request body instead of an `Authorization: Basic`
+header, matching the [authentication doc](../../developer-web/src/content/docs/authentication.mdx).
+
+### Errors from the OAuth helpers
+
+`/oauth/token`, `/oauth/revoke` and `/oauth/introspect` answer errors the
+standard OAuth way (RFC 6749 §5.2, RFC 7009, RFC 7662), not in the OneBooks
+`{ statusCode, message, code }` shape the rest of the API uses:
+
+```json
+{ "error": "invalid_grant", "error_description": "refresh token reuse detected" }
+```
+
+Every helper rejects with `OneBooksApiError`, with the code in
+`.oauthError` and the optional description in `.oauthErrorDescription`.
+`.message` reads `"invalid_grant: refresh token reuse detected"` (just the
+code when there is no description), and `.code` stays unset. Branch on
+`.oauthError`:
+
+```ts
+import { OneBooksApiError, oauth } from '@onebooks/node';
+
+try {
+  tokens = await oauth.refresh({ clientId, clientSecret, refreshToken });
+} catch (err) {
+  if (err instanceof OneBooksApiError && err.oauthError === 'invalid_grant') {
+    // expired, revoked, reused, or the business uninstalled you: re-authorize
+  } else if (err instanceof OneBooksApiError && err.status === 429) {
+    // rate limited: wait err.retryAfter seconds before the next token request
+  } else {
+    throw err;
+  }
+}
+```
+
+- `invalid_client` (HTTP `401`) is a configuration problem — a wrong or
+  missing secret, or an app that is suspended or deactivated. Fix it rather
+  than retrying: repeated failures lock the caller out for a minute.
+- The helpers **don't retry**, a `429` included. Its body is
+  `{ "error": "temporarily_unavailable", … }`, and `.retryAfter` holds the
+  `Retry-After` seconds to wait.
+- A `5xx` answers `server_error`. A proxy's non-JSON error page still
+  rejects with `OneBooksApiError`: `.message` is the HTTP status text and
+  `.body` the raw text.
+- The helpers also read the code from `message`, where these endpoints put
+  it before 2026-09-23 (`{ "statusCode": 400, "message": "invalid_grant: expired", … }`),
+  so `.oauthError` is filled against an older server too.
+
+### `exchangeSessionToken` — Contract 3 (embedded apps)
+
+For an app embedded via App Bridge: trade the short-lived session token
+(`app.sessionToken()` on the frontend) for a normal access/refresh token pair
+scoped to that installation. **Confidential clients only.**
+
+```ts
+const tokens = await oauth.exchangeSessionToken({
+  clientId: process.env.ONEBOOKS_CLIENT_ID!,
+  clientSecret: process.env.ONEBOOKS_CLIENT_SECRET!,
+  sessionToken, // from your frontend, e.g. a header your embedded page sent you
+});
+```
+
+**Exchange once, cache the pair; verify — don't exchange — on every
+request.** Each session token can be exchanged exactly **once**: the token
+endpoint records its `jti`, and a second exchange of the same token fails
+with `invalid_grant`. App Bridge deliberately reuses one session token for
+up to ~50 seconds across all of a page's `app.fetch()` calls, so a backend
+that exchanges on every request breaks on its second request. The pattern:
+
+```ts
+const claims = await verifySessionToken(sessionToken, { clientId });   // every request
+const key = `${claims.bid}:${claims.sub}`;
+let pair = await store.get(key);
+if (!pair) {
+  pair = await oauth.exchangeSessionToken({ clientId, clientSecret, sessionToken }); // once
+  await store.set(key, pair);
+} else if (expiresSoon(pair)) {
+  pair = await oauth.refresh({ clientId, clientSecret, refreshToken: pair.refresh_token! });
+  await store.set(key, pair);
+}
+// If the refresh fails (tokens revoked — e.g. uninstall, suspension) or the
+// API answers 401, drop the stored pair and exchange a FRESH session token.
+```
+
+Run that exchange/refresh **one at a time per key**: a page's parallel
+requests carry the same session token, so when two of them find no stored
+pair and both exchange it, the second gets `invalid_grant`. Let concurrent
+requests wait for the exchange or refresh already in flight.
+
+The starter template (`developer-sdk/templates/embedded-node/lib/session-tokens.mjs`,
+wired up in `lib/onebooks.mjs`) implements exactly this, including the
+fallback and the one-at-a-time rule.
+
+## `verifySessionToken(token, options)`
+
+Verifies an App Bridge session token server-side (ES256, JWKS from
+`GET /.well-known/jwks.json`) — use this in **every** backend route your
+embedded app calls, to authenticate the (business, user) making the request
+(verification is local and repeatable; only the exchange is single-use):
+
+```ts
+import { verifySessionToken } from '@onebooks/node';
+
+const claims = await verifySessionToken(token, { clientId: process.env.ONEBOOKS_CLIENT_ID! });
+// claims: { iss, aud, sub (userId), bid (businessId), role, locale, jti, iat, nbf, exp, typ }
+```
+
+Checks performed: ES256 signature against the live JWKS (fetched once,
+cached, and refreshed automatically by `jose` on a `kid` it hasn't seen),
+`aud === clientId`, `iss === apiBase`'s origin, `exp`/`nbf` within
+`clockToleranceSec` (default 30s), and the `typ` claim equals
+`"onebooks.app_session"` — a token minted for some other purpose but
+sharing the same signing keys must not be accepted here. Throws (a `jose`
+error, e.g. `JWTExpired`) on any failure.
+
+Options: `{ clientId, apiBase? (default the OneBooks API), jwksUrl? (default
+"<apiBase origin>/.well-known/jwks.json"), clockToleranceSec? (default 30) }`.
+
+## `verifyWebhook(options)`
+
+```ts
+import { verifyWebhook } from '@onebooks/node';
+import { createServer } from 'node:http';
+
+const server = createServer(async (req, res) => {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  const rawBody = Buffer.concat(chunks); // MUST verify against the raw bytes, not a parsed/re-serialized body
+
+  try {
+    const event = verifyWebhook({
+      rawBody,
+      signatureHeader: req.headers['x-webhook-signature'] as string,
+      secrets: [process.env.ONEBOOKS_WEBHOOK_SECRET!], // pass [new, old] while rotating
+    });
+    // event: { id, eventId, type, apiVersion, businessId, created, data }
+    res.writeHead(200).end();
+    void handle(event);
+  } catch {
+    res.writeHead(400).end();
+  }
+});
+```
+
+Verifies `X-Webhook-Signature: t=<unix>,v1=<hex>[,v1=<hex>]` — HMAC-SHA256 of
+`` `${t}.${rawBody}` `` — with a constant-time comparison, and rejects a
+timestamp older than `toleranceSec` (default 300) to blunt replay of a
+captured delivery. **Accepts the delivery if ANY provided secret matches ANY
+`v1` value**, so passing both your current and previous secret during a
+rotation window (`secrets: [current, previous]`) verifies deliveries signed
+with either. Throws on any failure; on success, returns the parsed event —
+never a boolean, so a caller can't accidentally ignore a failed check.
+
+`parseWebhookEvent(rawBody)` parses the envelope **without** verifying
+anything — only use it on a body you already ran through `verifyWebhook()`.
+
+## Development
+
+```bash
+npm install
+npm run build       # tsc -> dist/
+npm test            # node:test via tsx — no network, no real timers beyond real retry backoff
+npm run typecheck
+```
+
+Tests cover: webhook verification (valid / tampered / stale timestamp /
+secret rotation with two `v1` values), session-token verification against a
+locally generated ES256 key and a mocked JWKS fetch (aud mismatch, expired,
+wrong `typ`, unknown signing key, clock tolerance) — **no real network
+call** — the client's retry rule against a fake `fetch` (including that
+a write without an idempotency key is never replayed), and the OAuth
+helpers' error parsing for both the RFC 6749 body and an older server's
+`message` body, `Retry-After` on a `429`, and a non-JSON gateway page.
+
+## License
+
+MIT

package/dist/app-data.d.ts

@@ -0,0 +1,107 @@
+import type { QueryParams } from './types.js';
+interface RequestClient {
+    get<T>(path: string, options?: {
+        query?: QueryParams;
+    }): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+/** `en` is required; other locales are filled in as the app's listing supports them. */
+export interface LocalizedText {
+    en: string;
+    [locale: string]: string | undefined;
+}
+/** Matches Prisma's `AppDataResourceType` enum exactly (`schema.prisma`). */
+export type AppDataResourceType = 'BUSINESS' | 'CUSTOMER' | 'SUPPLIER' | 'ITEM' | 'INVOICE' | 'QUOTE' | 'SALES_RETURN' | 'PURCHASE' | 'PURCHASE_RETURN' | 'PAYMENT' | 'SUPPLIER_PAYMENT' | 'EXPENSE';
+/** Matches Prisma's `AppDataType` enum exactly (`schema.prisma`). */
+export type AppDataFieldType = 'TEXT' | 'MULTILINE_TEXT' | 'INTEGER' | 'DECIMAL' | 'BOOLEAN' | 'DATE' | 'DATETIME' | 'URL' | 'CHOICE' | 'JSON';
+/** Matches Prisma's `AppDataUpdatedVia` enum exactly. */
+export type AppDataUpdatedVia = 'APP' | 'MERCHANT';
+export interface AppDataValidationRules {
+    /** TEXT / MULTILINE_TEXT only. */
+    maxLength?: number;
+    /** INTEGER / DECIMAL only. */
+    min?: number;
+    /** INTEGER / DECIMAL only. */
+    max?: number;
+}
+/**
+ * A field your app has declared via the developer console (Contract 6:
+ * `GET /app-data/definitions`).
+ *
+ * Server-side validation per `type` (`app-data-values.ts` — informational;
+ * this SDK does not re-validate client-side, the server is authoritative):
+ * `TEXT` — string, no line breaks, ≤ `validation.maxLength` (default 255).
+ * `MULTILINE_TEXT` — string, ≤ `validation.maxLength` (default 5000).
+ * `INTEGER` — a safe integer, within `validation.min`/`max`.
+ * `DECIMAL` — a finite number with ≤ 6 decimal places, within `validation.min`/`max`.
+ * `BOOLEAN` — `true`/`false`.
+ * `DATE` — `"YYYY-MM-DD"`, a real calendar date.
+ * `DATETIME` — an ISO-8601 date-time string; stored normalized to `Date#toISOString()`.
+ * `URL` — an absolute **https** URL, ≤ 2048 characters.
+ * `CHOICE` — a string that is one of this definition's `choices`.
+ * `JSON` — an object or array that serializes to ≤ 16 KB.
+ * In every case, `value: null` deletes the stored value regardless of type.
+ */
+export interface AppDataDefinition {
+    id: string;
+    resourceType: AppDataResourceType;
+    key: string;
+    type: AppDataFieldType;
+    name: LocalizedText;
+    description: LocalizedText | null;
+    choices: string[];
+    validation: AppDataValidationRules | null;
+    merchantVisible: boolean;
+    merchantEditable: boolean;
+    position: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AppDataValue {
+    /** Null when this entry is the echo of a delete (a `set()` call with `value: null`). */
+    id: string | null;
+    resourceType: AppDataResourceType;
+    resourceId: string;
+    key: string;
+    value: unknown;
+    updatedVia: AppDataUpdatedVia;
+    updatedAt: string;
+}
+export interface AppDataGetParams {
+    resourceType: AppDataResourceType;
+    resourceId?: string;
+    /** At most 50. */
+    resourceIds?: string[];
+}
+export interface AppDataSetInput {
+    resourceType: AppDataResourceType;
+    /** At most 255 characters. */
+    resourceId: string;
+    /** Must match an existing definition key for this app + resourceType (`/^[a-z][a-z0-9_]{0,63}$/`). */
+    key: string;
+    /** The typed value (shape depends on the field's type — see {@link AppDataDefinition}). `null` deletes the value. */
+    value: unknown;
+}
+/** Partner app-data API (Contract 6): `client.appData.*`. */
+export declare class AppDataResource {
+    private readonly client;
+    constructor(client: RequestClient);
+    /** `GET /app-data/definitions` — every field your app has declared. */
+    definitions(): Promise<AppDataDefinition[]>;
+    /**
+     * `GET /app-data?resourceType=…&resourceId=…` (or `&resourceIds=a,b`, at
+     * most 50). Provide exactly one of `resourceId` / `resourceIds`.
+     */
+    get(params: AppDataGetParams): Promise<AppDataValue[]>;
+    /**
+     * `PUT /app-data { values }` — 1 to 25 per call (the server rejects an
+     * empty array; this SDK short-circuits to `[]` instead of making that
+     * call); `value: null` deletes that value.
+     */
+    set(values: AppDataSetInput[]): Promise<AppDataValue[]>;
+    /** `DELETE /app-data/:id`. */
+    delete(id: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=app-data.d.ts.map

package/dist/app-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-data.d.ts","sourceRoot":"","sources":["../src/app-data.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,UAAU,aAAa;IACrB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACrC;AAED,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,UAAU,GACV,UAAU,GACV,MAAM,GACN,SAAS,GACT,OAAO,GACP,cAAc,GACd,UAAU,GACV,iBAAiB,GACjB,SAAS,GACT,kBAAkB,GAClB,SAAS,CAAC;AAEd,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,gBAAgB,GAChB,SAAS,GACT,SAAS,GACT,SAAS,GACT,MAAM,GACN,UAAU,GACV,KAAK,GACL,QAAQ,GACR,MAAM,CAAC;AAEX,yDAAyD;AACzD,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,UAAU,CAAC;AAEnD,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,mBAAmB,CAAC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,aAAa,GAAG,IAAI,CAAC;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC1C,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,wFAAwF;IACxF,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,iBAAiB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,mBAAmB,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,mBAAmB,CAAC;IAClC,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,sGAAsG;IACtG,GAAG,EAAE,MAAM,CAAC;IACZ,qHAAqH;IACrH,KAAK,EAAE,OAAO,CAAC;CAChB;AAID,6DAA6D;AAC7D,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAElD,uEAAuE;IACjE,WAAW,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAKjD;;;OAGG;IACG,GAAG,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAW5D;;;;OAIG;IACG,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAS7D,8BAA8B;IACxB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC"}

package/dist/app-data.js

@@ -0,0 +1,48 @@
+const MAX_SET_BATCH = 25;
+/** Partner app-data API (Contract 6): `client.appData.*`. */
+export class AppDataResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** `GET /app-data/definitions` — every field your app has declared. */
+    async definitions() {
+        const res = await this.client.get('/app-data/definitions');
+        return res.data;
+    }
+    /**
+     * `GET /app-data?resourceType=…&resourceId=…` (or `&resourceIds=a,b`, at
+     * most 50). Provide exactly one of `resourceId` / `resourceIds`.
+     */
+    async get(params) {
+        if (!params.resourceId && !params.resourceIds) {
+            throw new Error('appData.get(): provide either "resourceId" or "resourceIds".');
+        }
+        const query = { resourceType: params.resourceType };
+        if (params.resourceId)
+            query.resourceId = params.resourceId;
+        if (params.resourceIds)
+            query.resourceIds = params.resourceIds.join(',');
+        const res = await this.client.get('/app-data', { query });
+        return res.data;
+    }
+    /**
+     * `PUT /app-data { values }` — 1 to 25 per call (the server rejects an
+     * empty array; this SDK short-circuits to `[]` instead of making that
+     * call); `value: null` deletes that value.
+     */
+    async set(values) {
+        if (values.length === 0)
+            return [];
+        if (values.length > MAX_SET_BATCH) {
+            throw new RangeError(`appData.set(): at most ${MAX_SET_BATCH} values per call (got ${values.length}).`);
+        }
+        const res = await this.client.put('/app-data', { values });
+        return res.data;
+    }
+    /** `DELETE /app-data/:id`. */
+    async delete(id) {
+        await this.client.delete(`/app-data/${encodeURIComponent(id)}`);
+    }
+}
+//# sourceMappingURL=app-data.js.map

package/dist/app-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-data.js","sourceRoot":"","sources":["../src/app-data.ts"],"names":[],"mappings":"AAuHA,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,6DAA6D;AAC7D,MAAM,OAAO,eAAe;IACG;IAA7B,YAA6B,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAG,CAAC;IAEtD,uEAAuE;IACvE,KAAK,CAAC,WAAW;QACf,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAgC,uBAAuB,CAAC,CAAC;QAC1F,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG,CAAC,MAAwB;QAChC,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;QAClF,CAAC;QACD,MAAM,KAAK,GAAgB,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC;QACjE,IAAI,MAAM,CAAC,UAAU;YAAE,KAAK,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QAC5D,IAAI,MAAM,CAAC,WAAW;YAAE,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAA2B,WAAW,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACpF,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAG,CAAC,MAAyB;QACjC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACnC,IAAI,MAAM,CAAC,MAAM,GAAG,aAAa,EAAE,CAAC;YAClC,MAAM,IAAI,UAAU,CAAC,0BAA0B,aAAa,yBAAyB,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;QAC1G,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAA2B,WAAW,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QACrF,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IAED,8BAA8B;IAC9B,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAO,aAAa,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC;CACF"}

package/dist/client.d.ts

@@ -0,0 +1,58 @@
+import { AppDataResource } from './app-data.js';
+import { EventsResource } from './events.js';
+import type { HttpMethod, OneBooksClientOptions, QueryParams, RequestOptions } from './types.js';
+/**
+ * The retry rule, in one place:
+ * - `429` is retried for EVERY method — a rate-limited request was never
+ *   processed, so replaying it can't duplicate anything.
+ * - A network error or `502`/`503`/`504` is retried only for `GET`/`HEAD`, or
+ *   for any other method when the call set an `idempotencyKey` — otherwise a
+ *   POST that the API processed before the connection dropped would be sent
+ *   twice (a duplicate customer, expense, quote, …).
+ * - Nothing else is ever retried.
+ */
+export declare function canReplayAfterAmbiguousFailure(method: HttpMethod, idempotencyKey: string | undefined): boolean;
+/**
+ * Server-side OneBooks API client: authenticated `request()` with retries,
+ * plus `appData`/`events` resource helpers. OAuth flow helpers (PKCE, code
+ * exchange, session-token exchange, …) are standalone — see `oauth.ts` — since
+ * you need them before a client (and its token) exists.
+ */
+export declare class OneBooksClient {
+    readonly apiBase: string;
+    readonly apiVersion?: string;
+    readonly appData: AppDataResource;
+    readonly events: EventsResource;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    private readonly staticToken?;
+    private readonly getAccessTokenFn?;
+    constructor(options: OneBooksClientOptions);
+    private resolveAccessToken;
+    private buildUrl;
+    /**
+     * Issues one authenticated API request. Retries (up to `maxRetries`) a
+     * `429` for any method, honoring `Retry-After`; retries a network error or
+     * `502`/`503`/`504` (jittered backoff) only for `GET`/`HEAD` or when
+     * `options.idempotencyKey` is set — see `canReplayAfterAmbiguousFailure`.
+     * Never retries any other status. Resolves the parsed JSON body (or
+     * `undefined` for a `204`); throws `OneBooksApiError` on a non-retried
+     * failure (or rethrows the network error).
+     */
+    request<T = unknown>(method: HttpMethod, path: string, options?: RequestOptions): Promise<T>;
+    get<T = unknown>(path: string, options?: Omit<RequestOptions, 'body'>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, options?: Omit<RequestOptions, 'body'>): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, options?: Omit<RequestOptions, 'body'>): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown, options?: Omit<RequestOptions, 'body'>): Promise<T>;
+    delete<T = unknown>(path: string, options?: Omit<RequestOptions, 'body'>): Promise<T>;
+    /**
+     * Async-iterates every item of a `{ data, hasMore, nextCursor }` endpoint,
+     * paging automatically. `cursorParam` names the query parameter the
+     * endpoint reads the cursor from (default `"cursor"`; the events endpoint
+     * uses `"after"` — see `events.iterate()`, built on this).
+     */
+    paginate<T = unknown>(path: string, query?: QueryParams, paginateOptions?: {
+        cursorParam?: string;
+    }): AsyncGenerator<T, void, undefined>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EACV,UAAU,EACV,qBAAqB,EAErB,WAAW,EACX,cAAc,EACf,MAAM,YAAY,CAAC;AAWpB;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE9G;AA2CD;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAiC;gBAEvD,OAAO,EAAE,qBAAqB;YAe5B,kBAAkB;IAMhC,OAAO,CAAC,QAAQ;IAiBhB;;;;;;;;OAQG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EACvB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC;IAkDb,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIlF,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAInG,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIlG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIpG,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrF;;;;;OAKG;IACI,QAAQ,CAAC,CAAC,GAAG,OAAO,EACzB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,WAAgB,EACvB,eAAe,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GAC7C,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;CAYtC"}