@onebooks/node 0.0.0-stage → 0.1.0

package/dist/oauth.js

@@ -0,0 +1,140 @@
+import { oauthErrorFromResponse } from './errors.js';
+const DEFAULT_API_BASE = 'https://api.getonebooks.com';
+const DEFAULT_AUTHORIZE_URL = 'https://app.getonebooks.com/oauth/authorize';
+const TOKEN_EXCHANGE_GRANT = 'urn:ietf:params:oauth:grant-type:token-exchange';
+const SESSION_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:jwt';
+function getWebCrypto() {
+    const c = globalThis.crypto;
+    if (!c) {
+        throw new Error('@onebooks/node: Web Crypto API not available in this runtime (requires Node >= 20).');
+    }
+    return c;
+}
+function base64url(bytes) {
+    return Buffer.from(bytes).toString('base64url');
+}
+/** RFC 7636 PKCE pair: a 43-character verifier and its S256 challenge. */
+export async function createPkcePair() {
+    const crypto = getWebCrypto();
+    const verifierBytes = new Uint8Array(32);
+    crypto.getRandomValues(verifierBytes);
+    const codeVerifier = base64url(verifierBytes);
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier));
+    const codeChallenge = base64url(new Uint8Array(digest));
+    return { codeVerifier, codeChallenge, codeChallengeMethod: 'S256' };
+}
+/** Builds the `https://app.getonebooks.com/oauth/authorize` URL (Step 1 of the code + PKCE flow). */
+export function buildAuthorizeUrl(options) {
+    const url = new URL(options.authorizeUrl ?? DEFAULT_AUTHORIZE_URL);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', options.clientId);
+    url.searchParams.set('redirect_uri', options.redirectUri);
+    url.searchParams.set('scope', options.scopes.join(' '));
+    url.searchParams.set('state', options.state);
+    url.searchParams.set('code_challenge', options.codeChallenge);
+    url.searchParams.set('code_challenge_method', options.codeChallengeMethod ?? 'S256');
+    return url.toString();
+}
+function tokenEndpoint(apiBase, pathname) {
+    return `${(apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, '')}${pathname}`;
+}
+function basicAuthHeader(clientId, clientSecret) {
+    return `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`;
+}
+/**
+ * A failed response's body: parsed JSON, or the raw text when it isn't JSON
+ * (a gateway's HTML error page, say) — never a SyntaxError in place of the
+ * `OneBooksApiError`.
+ */
+async function readErrorBody(res) {
+    const text = await res.text().catch(() => '');
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+async function postForm(url, params, auth, fetchImpl) {
+    const body = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            body.set(key, value);
+    }
+    const headers = { 'Content-Type': 'application/x-www-form-urlencoded' };
+    if (auth.clientSecret) {
+        headers.Authorization = basicAuthHeader(auth.clientId, auth.clientSecret);
+    }
+    else {
+        body.set('client_id', auth.clientId);
+    }
+    const res = await fetchImpl(url, { method: 'POST', headers, body: body.toString() });
+    if (!res.ok) {
+        // RFC 6749 §5.2 `{ error, error_description? }` (or, from an older server,
+        // the code in `message`) — see oauthErrorFromResponse. Never retried here:
+        // a 429 carries `retryAfter` for the caller to honour.
+        throw oauthErrorFromResponse(res, await readErrorBody(res));
+    }
+    const text = await res.text();
+    return text ? JSON.parse(text) : {};
+}
+/** Step 3: exchange an authorization code for tokens (`POST /oauth/token`). */
+export async function exchangeCode(options) {
+    const result = await postForm(tokenEndpoint(options.apiBase, '/oauth/token'), {
+        grant_type: 'authorization_code',
+        code: options.code,
+        redirect_uri: options.redirectUri,
+        code_verifier: options.codeVerifier,
+    }, options, options.fetch ?? fetch);
+    return result;
+}
+/** Refreshes an access token. Rotation is strict: persist BOTH new tokens before discarding the old ones. */
+export async function refresh(options) {
+    const result = await postForm(tokenEndpoint(options.apiBase, '/oauth/token'), { grant_type: 'refresh_token', refresh_token: options.refreshToken }, options, options.fetch ?? fetch);
+    return result;
+}
+/**
+ * `POST /oauth/revoke` (RFC 7009) — resolves for an unknown or already-invalid
+ * token too; rejects only when the request itself fails (`invalid_client`, a
+ * rate limit, …).
+ */
+export async function revoke(options) {
+    const fetchImpl = options.fetch ?? fetch;
+    const url = tokenEndpoint(options.apiBase, '/oauth/revoke');
+    const body = new URLSearchParams();
+    body.set('token', options.token);
+    if (options.tokenTypeHint)
+        body.set('token_type_hint', options.tokenTypeHint);
+    const headers = { 'Content-Type': 'application/x-www-form-urlencoded' };
+    if (options.clientSecret) {
+        headers.Authorization = basicAuthHeader(options.clientId, options.clientSecret);
+    }
+    else {
+        body.set('client_id', options.clientId);
+    }
+    const res = await fetchImpl(url, { method: 'POST', headers, body: body.toString() });
+    if (!res.ok) {
+        throw oauthErrorFromResponse(res, await readErrorBody(res));
+    }
+}
+/**
+ * RFC 8693 token exchange (Contract 3): trades an App Bridge session token
+ * (short-lived, ~60s) for a normal access/refresh token pair scoped to the
+ * installation. Confidential clients only.
+ */
+export async function exchangeSessionToken(options) {
+    const result = await postForm(tokenEndpoint(options.apiBase, '/oauth/token'), {
+        grant_type: TOKEN_EXCHANGE_GRANT,
+        subject_token: options.sessionToken,
+        subject_token_type: SESSION_TOKEN_TYPE,
+    }, { clientId: options.clientId, clientSecret: options.clientSecret }, options.fetch ?? fetch);
+    return result;
+}
+/** `POST /oauth/introspect` — a debugging aid, not a production hot path (just call the API and handle 401). */
+export async function introspect(options) {
+    const result = await postForm(tokenEndpoint(options.apiBase, '/oauth/introspect'), { token: options.token }, options, options.fetch ?? fetch);
+    return result;
+}
+//# sourceMappingURL=oauth.js.map

package/dist/oauth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.js","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}

package/dist/session-token.d.ts

@@ -0,0 +1,36 @@
+import { type JWTPayload } from 'jose';
+export interface SessionTokenClaims extends JWTPayload {
+    iss: string;
+    aud: string;
+    sub: string;
+    /** Business id the embedded app is viewing. */
+    bid: string;
+    role: string;
+    locale: string;
+    jti: string;
+    iat: number;
+    nbf: number;
+    exp: number;
+    typ: 'onebooks.app_session';
+}
+export interface VerifySessionTokenOptions {
+    /** Your app's OAuth client_id — checked against the token's `aud`. */
+    clientId: string;
+    /** Default `https://api.getonebooks.com`; also determines the default JWKS URL and expected `iss`. */
+    apiBase?: string;
+    /** Default `<apiBase origin>/.well-known/jwks.json`. */
+    jwksUrl?: string;
+    /** Default 30. */
+    clockToleranceSec?: number;
+}
+/**
+ * Verifies an App Bridge session token (Contract 3): ES256 signature against
+ * `GET /.well-known/jwks.json`, `aud === clientId`, `iss === apiBase origin`,
+ * `exp`/`nbf` within `clockToleranceSec`, and the `typ` claim — a JWT that
+ * merely happens to be signed by the same keys but was minted for a
+ * different purpose (e.g. a future token type) will carry a different `typ`
+ * and must not be accepted here. Throws (jose's `JWTVerifyResult`-shaped
+ * errors, e.g. `JWTExpired`, `JWTClaimValidationFailed`) on any failure.
+ */
+export declare function verifySessionToken(token: string, options: VerifySessionTokenOptions): Promise<SessionTokenClaims>;
+//# sourceMappingURL=session-token.d.ts.map

package/dist/session-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-token.d.ts","sourceRoot":"","sources":["../src/session-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AAKtE,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,sBAAsB,CAAC;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACxC,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,sGAAsG;IACtG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAkB7B"}

package/dist/session-token.js

@@ -0,0 +1,41 @@
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+const DEFAULT_API_BASE = 'https://api.getonebooks.com';
+const SESSION_TOKEN_TYP = 'onebooks.app_session';
+// createRemoteJWKSet caches the fetched JWKS (and honors standard HTTP
+// caching) internally, but constructing a new one per call would throw that
+// cache away — keep one instance per JWKS URL for the life of the process.
+const jwksCache = new Map();
+function getRemoteJwks(jwksUrl) {
+    let jwks = jwksCache.get(jwksUrl);
+    if (!jwks) {
+        jwks = createRemoteJWKSet(new URL(jwksUrl));
+        jwksCache.set(jwksUrl, jwks);
+    }
+    return jwks;
+}
+/**
+ * Verifies an App Bridge session token (Contract 3): ES256 signature against
+ * `GET /.well-known/jwks.json`, `aud === clientId`, `iss === apiBase origin`,
+ * `exp`/`nbf` within `clockToleranceSec`, and the `typ` claim — a JWT that
+ * merely happens to be signed by the same keys but was minted for a
+ * different purpose (e.g. a future token type) will carry a different `typ`
+ * and must not be accepted here. Throws (jose's `JWTVerifyResult`-shaped
+ * errors, e.g. `JWTExpired`, `JWTClaimValidationFailed`) on any failure.
+ */
+export async function verifySessionToken(token, options) {
+    const apiBase = options.apiBase ?? DEFAULT_API_BASE;
+    const issuer = new URL(apiBase).origin;
+    const jwksUrl = options.jwksUrl ?? `${issuer}/.well-known/jwks.json`;
+    const jwks = getRemoteJwks(jwksUrl);
+    const { payload } = await jwtVerify(token, jwks, {
+        algorithms: ['ES256'],
+        audience: options.clientId,
+        issuer,
+        clockTolerance: options.clockToleranceSec ?? 30,
+    });
+    if (payload.typ !== SESSION_TOKEN_TYP) {
+        throw new Error(`OneBooks session token: unexpected "typ" claim (expected "${SESSION_TOKEN_TYP}", got ${JSON.stringify(payload.typ)}).`);
+    }
+    return payload;
+}
+//# sourceMappingURL=session-token.js.map

package/dist/session-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-token.js","sourceRoot":"","sources":["../src/session-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAmB,MAAM,MAAM,CAAC;AAEtE,MAAM,gBAAgB,GAAG,6BAA6B,CAAC;AACvD,MAAM,iBAAiB,GAAG,sBAAsB,CAAC;AA4BjD,uEAAuE;AACvE,4EAA4E;AAC5E,2EAA2E;AAC3E,MAAM,SAAS,GAAG,IAAI,GAAG,EAAiD,CAAC;AAE3E,SAAS,aAAa,CAAC,OAAe;IACpC,IAAI,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,GAAG,kBAAkB,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5C,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAa,EACb,OAAkC;IAElC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACpD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IACvC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,GAAG,MAAM,wBAAwB,CAAC;IACrE,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAEpC,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE;QAC/C,UAAU,EAAE,CAAC,OAAO,CAAC;QACrB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,MAAM;QACN,cAAc,EAAE,OAAO,CAAC,iBAAiB,IAAI,EAAE;KAChD,CAAC,CAAC;IAEH,IAAI,OAAO,CAAC,GAAG,KAAK,iBAAiB,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,6DAA6D,iBAAiB,UAAU,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3I,CAAC;IAED,OAAO,OAA6B,CAAC;AACvC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+export type HttpMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type QueryValue = string | number | boolean | undefined | null | Array<string | number>;
+export type QueryParams = Record<string, QueryValue>;
+export interface OneBooksClientOptions {
+    /** A static access token. Provide this OR `getAccessToken`, not both. */
+    accessToken?: string;
+    /**
+     * Called before every request to obtain a (possibly refreshed) access
+     * token. Use this over a static `accessToken` whenever your app refreshes
+     * tokens elsewhere (a token store, `oauth.refresh`, `exchangeSessionToken`
+     * re-run per request, etc).
+     */
+    getAccessToken?: () => string | Promise<string>;
+    /** Default `https://api.getonebooks.com`. */
+    apiBase?: string;
+    /** Sent as the `OneBooks-Version` request header when set. */
+    apiVersion?: string;
+    /**
+     * Max retry attempts. Default 3. A `429` is retried for every method; a
+     * network error or `502`/`503`/`504` only for GET/HEAD or a request with an
+     * `idempotencyKey` (see `canReplayAfterAmbiguousFailure`).
+     */
+    maxRetries?: number;
+    /** Override for testing, or to plug in a non-global fetch implementation. */
+    fetch?: typeof fetch;
+}
+export interface RequestOptions {
+    query?: QueryParams;
+    body?: unknown;
+    /**
+     * Sent as the `Idempotency-Key` header. Setting it also makes a non-GET
+     * request safe to retry after a network error or `502`/`503`/`504`. Only
+     * some write endpoints de-duplicate on it (e.g. invoice create, payments,
+     * manual journals) — elsewhere it is accepted but has no server-side
+     * effect, so it does not make a retried write safe there.
+     */
+    idempotencyKey?: string;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+export interface PaginatedResponse<T> {
+    data: T[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE9E,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;AAC/F,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/webhook.d.ts

@@ -0,0 +1,41 @@
+/** The webhook delivery body (Contract 5). */
+export interface WebhookEventEnvelope<T = unknown> {
+    id: string;
+    eventId: string | null;
+    type: string;
+    apiVersion: string;
+    businessId: string;
+    created: number;
+    data: T;
+}
+export interface VerifyWebhookOptions {
+    /** The exact raw request body bytes/string — signing covers the raw body, not a re-serialized JSON.parse/stringify round trip. */
+    rawBody: string | Buffer;
+    /** The `X-Webhook-Signature` header value, e.g. `t=1765465600,v1=abc…[,v1=def…]`. */
+    signatureHeader: string | null | undefined;
+    /** Provide `secret` OR `secrets` (during a rotation window, pass both the new and previous secret). */
+    secret?: string;
+    secrets?: string[];
+    /** Default 300. */
+    toleranceSec?: number;
+}
+/**
+ * Verifies a webhook delivery's `X-Webhook-Signature` header
+ * (`t=<unix>,v1=<hex>[,v1=<hex>]`, HMAC-SHA256 of `"<t>.<rawBody>"`) and
+ * returns the parsed event on success. Accepts the delivery if **any**
+ * provided secret matches **any** `v1` value (supports secret rotation:
+ * pass both the current and previous secret while a rotation is in
+ * progress). Rejects timestamps outside `toleranceSec` of now, to blunt
+ * replay of a captured delivery. Throws on any verification failure — never
+ * returns a "valid: false" value, so a caller can't accidentally ignore the
+ * result.
+ */
+export declare function verifyWebhook<T = unknown>(options: VerifyWebhookOptions): WebhookEventEnvelope<T>;
+/**
+ * Parses a webhook delivery body WITHOUT verifying its signature. Only use
+ * this on a body you already ran through `verifyWebhook()` (e.g. to type a
+ * value you verified earlier) — this function performs no cryptographic
+ * check on its own.
+ */
+export declare function parseWebhookEvent<T = unknown>(rawBody: string | Buffer): WebhookEventEnvelope<T>;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"AAEA,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,CAAC,CAAC;CACT;AAED,MAAM,WAAW,oBAAoB;IACnC,kIAAkI;IAClI,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,qFAAqF;IACrF,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC3C,uGAAuG;IACvG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,mBAAmB;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAwCD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CAAC,CAAC,CAAC,CA+BjG;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAGhG"}

package/dist/webhook.js

@@ -0,0 +1,86 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+function parseSignatureHeader(header) {
+    let timestamp;
+    const signatures = [];
+    for (const part of header.split(',')) {
+        const eq = part.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = part.slice(0, eq).trim();
+        const value = part.slice(eq + 1).trim();
+        if (key === 't')
+            timestamp = value;
+        else if (key === 'v1' && value)
+            signatures.push(value);
+    }
+    if (!timestamp || signatures.length === 0) {
+        throw new Error('OneBooks webhook: malformed X-Webhook-Signature header.');
+    }
+    return { timestamp, signatures };
+}
+function hmacSha256(secret, payload) {
+    return createHmac('sha256', secret).update(payload, 'utf8').digest();
+}
+/** Constant-time compare of a hex-encoded signature against the expected digest. */
+function signatureMatches(hexSignature, expected) {
+    let provided;
+    try {
+        provided = Buffer.from(hexSignature, 'hex');
+    }
+    catch {
+        return false;
+    }
+    if (provided.length !== expected.length)
+        return false;
+    return timingSafeEqual(provided, expected);
+}
+/**
+ * Verifies a webhook delivery's `X-Webhook-Signature` header
+ * (`t=<unix>,v1=<hex>[,v1=<hex>]`, HMAC-SHA256 of `"<t>.<rawBody>"`) and
+ * returns the parsed event on success. Accepts the delivery if **any**
+ * provided secret matches **any** `v1` value (supports secret rotation:
+ * pass both the current and previous secret while a rotation is in
+ * progress). Rejects timestamps outside `toleranceSec` of now, to blunt
+ * replay of a captured delivery. Throws on any verification failure — never
+ * returns a "valid: false" value, so a caller can't accidentally ignore the
+ * result.
+ */
+export function verifyWebhook(options) {
+    const secrets = options.secrets ?? (options.secret ? [options.secret] : []);
+    if (secrets.length === 0) {
+        throw new Error('OneBooks webhook: provide at least one secret ("secret" or "secrets").');
+    }
+    if (!options.signatureHeader) {
+        throw new Error('OneBooks webhook: missing X-Webhook-Signature header.');
+    }
+    const { timestamp, signatures } = parseSignatureHeader(options.signatureHeader);
+    const toleranceSec = options.toleranceSec ?? 300;
+    const timestampNum = Number(timestamp);
+    if (!Number.isFinite(timestampNum)) {
+        throw new Error('OneBooks webhook: invalid timestamp in X-Webhook-Signature header.');
+    }
+    if (Math.abs(Date.now() / 1000 - timestampNum) > toleranceSec) {
+        throw new Error('OneBooks webhook: timestamp outside tolerance (stale or replayed delivery?).');
+    }
+    const rawBody = typeof options.rawBody === 'string' ? options.rawBody : options.rawBody.toString('utf8');
+    const signedPayload = `${timestamp}.${rawBody}`;
+    const verified = secrets.some((secret) => {
+        const expected = hmacSha256(secret, signedPayload);
+        return signatures.some((sig) => signatureMatches(sig, expected));
+    });
+    if (!verified) {
+        throw new Error('OneBooks webhook: signature verification failed.');
+    }
+    return JSON.parse(rawBody);
+}
+/**
+ * Parses a webhook delivery body WITHOUT verifying its signature. Only use
+ * this on a body you already ran through `verifyWebhook()` (e.g. to type a
+ * value you verified earlier) — this function performs no cryptographic
+ * check on its own.
+ */
+export function parseWebhookEvent(rawBody) {
+    const text = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+    return JSON.parse(text);
+}
+//# sourceMappingURL=webhook.js.map

package/dist/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@onebooks/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Server-side SDK for the OneBooks API: authenticated requests with retries, OAuth helpers (PKCE, code exchange, refresh, session-token exchange), ES256 session-token verification and webhook signature verification.",
+  "keywords": [
+    "onebooks",
+    "accounting",
+    "api-client",
+    "oauth",
+    "webhooks",
+    "session-token",
+    "sdk"
+  ],
+  "license": "MIT",
+  "homepage": "https://developer.getonebooks.com/docs/sdk-node/",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsx --test test/**/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "jose": "^6.2.12"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "tsx": "^4.20.0",
+    "typescript": "~5.9.3"
+  }
+}