@isnap/sdk 0.1.0 → 1.1.0-next.38

package/dist/webhooks/parse.js

@@ -0,0 +1,47 @@
+import { WebhookSignatureError } from '../errors.js';
+/**
+ * Parse a raw webhook delivery body into a typed envelope. Throws
+ * `WebhookSignatureError` if the body is not valid JSON or doesn't carry
+ * the §4.1 envelope shape (`event_id`, `event_type`, `data`). Use
+ * `verifyWebhook` for the full HMAC + replay-window verification — this
+ * is the parsing-only half for cases where verification happened
+ * out-of-band (e.g. behind a trusted gateway).
+ *
+ * **Consumers MUST dedupe by `event.event_id`** — webhook delivery is
+ * at-least-once, so retries replay the same envelope. Without dedup,
+ * processing the same event twice produces duplicate side-effects.
+ */
+export function parseWebhookEvent(rawBody) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawBody);
+    }
+    catch (err) {
+        throw new WebhookSignatureError(`Webhook body is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new WebhookSignatureError('Webhook body must be a JSON object');
+    }
+    const obj = parsed;
+    if (typeof obj.api_version !== 'string' || obj.api_version.length === 0) {
+        throw new WebhookSignatureError('Webhook envelope missing api_version');
+    }
+    if (typeof obj.event_id !== 'string' || obj.event_id.length === 0) {
+        throw new WebhookSignatureError('Webhook envelope missing event_id');
+    }
+    if (typeof obj.event_type !== 'string' || obj.event_type.length === 0) {
+        throw new WebhookSignatureError('Webhook envelope missing event_type');
+    }
+    if (typeof obj.created_at !== 'string' || obj.created_at.length === 0) {
+        throw new WebhookSignatureError('Webhook envelope missing created_at');
+    }
+    // `data` must be a plain object — arrays satisfy `typeof === 'object'`
+    // but the contract §4.1 envelope is `{ ...fields, data: { message: ... } }`,
+    // never an array. Rejecting at the boundary keeps the
+    // `Record<string, unknown>` declared type aligned with runtime.
+    if (typeof obj.data !== 'object' || obj.data === null || Array.isArray(obj.data)) {
+        throw new WebhookSignatureError('Webhook envelope missing data');
+    }
+    return obj;
+}
+//# sourceMappingURL=parse.js.map

package/dist/webhooks/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/webhooks/parse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAGpD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,IAAI,MAAe,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,qBAAqB,CAC7B,mCAAmC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACtF,CAAA;IACH,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,qBAAqB,CAAC,oCAAoC,CAAC,CAAA;IACvE,CAAC;IACD,MAAM,GAAG,GAAG,MAAiC,CAAA;IAC7C,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,IAAI,GAAG,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,qBAAqB,CAAC,sCAAsC,CAAC,CAAA;IACzE,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,qBAAqB,CAAC,mCAAmC,CAAC,CAAA;IACtE,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,qBAAqB,CAAC,qCAAqC,CAAC,CAAA;IACxE,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,qBAAqB,CAAC,qCAAqC,CAAC,CAAA;IACxE,CAAC;IACD,uEAAuE;IACvE,6EAA6E;IAC7E,sDAAsD;IACtD,gEAAgE;IAChE,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACjF,MAAM,IAAI,qBAAqB,CAAC,+BAA+B,CAAC,CAAA;IAClE,CAAC;IACD,OAAO,GAAkC,CAAA;AAC3C,CAAC"}

package/dist/webhooks/types.d.ts

@@ -0,0 +1,93 @@
+import type { Message, Reaction } from '../resources/messages.js';
+/**
+ * Common envelope for every webhook event. Per contract §4.1: every
+ * delivery body is shaped `{ api_version, event_id, event_type,
+ * created_at, trace_id?, data }`. `data` is a per-event-type payload —
+ * the type guards below narrow it to a typed shape.
+ */
+export interface WebhookEventBase {
+    api_version: string;
+    event_id: string;
+    event_type: string;
+    created_at: string;
+    trace_id?: string;
+    data: Record<string, unknown>;
+}
+export type MessageEventType = 'message.queued' | 'message.scheduled' | 'message.sent' | 'message.delivered' | 'message.failed' | 'message.received' | 'message.read' | 'message.cancelled';
+export interface MessageEvent extends WebhookEventBase {
+    event_type: `message.${string}`;
+    data: {
+        message: Message;
+    };
+}
+export type ReactionEventType = 'reaction.added' | 'reaction.received' | 'reaction.removed';
+export interface ReactionEvent extends WebhookEventBase {
+    event_type: `reaction.${string}`;
+    data: {
+        reaction: Reaction;
+    };
+}
+export type LineEventType = 'line.connected' | 'line.disconnected' | 'line.offline' | 'line.degraded' | 'line.apple_id_flagged' | 'line.quota_warning' | 'line.quota_exceeded';
+/**
+ * `data` is intentionally typed as `Record<string, unknown>` until the
+ * contract pins per-event-type field shapes. Today's payloads vary by
+ * event (e.g. `line.apple_id_flagged` carries `flag_reason`,
+ * `line.quota_warning` carries `bucket` + `usage`), and surfacing a
+ * union with optional fields would let TypeScript autocomplete suggest
+ * keys that aren't present at runtime. Tighten when the contract is
+ * amended to specify the per-event shapes.
+ */
+export interface LineEvent extends WebhookEventBase {
+    event_type: `line.${string}`;
+    data: Record<string, unknown>;
+}
+export type TypingIndicatorEventType = 'typing_indicator.started' | 'typing_indicator.stopped';
+/**
+ * `data` is intentionally `Record<string, unknown>` — the partner-facing
+ * shape is not yet documented in the contract. See `LineEvent` for the
+ * same rationale.
+ */
+export interface TypingIndicatorEvent extends WebhookEventBase {
+    event_type: `typing_indicator.${string}`;
+    data: Record<string, unknown>;
+}
+export type TrialEventType = 'trial.linked' | 'trial.dormant' | 'trial.reactivated';
+/** See `LineEvent` for why `data` is loose. */
+export interface TrialEvent extends WebhookEventBase {
+    event_type: `trial.${string}`;
+    data: Record<string, unknown>;
+}
+export type PreOrderEventType = 'pre_order.fulfilled' | 'pre_order.cancelled' | 'pre_order.refunded';
+/**
+ * Pre-order lifecycle events fired when ops procures hardware against a
+ * customer pre-order. `pre_order.fulfilled` carries the freshly-activated
+ * `line_id` so partner dashboards can wire it without a follow-up GET.
+ * `data` is left loose for the same reason as `LineEvent` until the
+ * per-event-type shapes are pinned in the contract.
+ */
+export interface PreOrderEvent extends WebhookEventBase {
+    event_type: `pre_order.${string}`;
+    data: Record<string, unknown>;
+}
+/**
+ * Discriminated union over the typed event families plus `WebhookEventBase`
+ * as the catch-all for event types not yet known to this SDK version.
+ * Use a type guard (`isMessageEvent`, `isReactionEvent`, ...) to narrow
+ * inside an event handler:
+ *
+ * ```ts
+ * function handle(event: WebhookEvent) {
+ *   if (isMessageEvent(event)) {
+ *     console.log(event.data.message.id)  // typed as Message
+ *   }
+ * }
+ * ```
+ */
+export type WebhookEvent = MessageEvent | ReactionEvent | LineEvent | TypingIndicatorEvent | TrialEvent | PreOrderEvent | WebhookEventBase;
+export declare function isMessageEvent(event: WebhookEventBase): event is MessageEvent;
+export declare function isReactionEvent(event: WebhookEventBase): event is ReactionEvent;
+export declare function isLineEvent(event: WebhookEventBase): event is LineEvent;
+export declare function isTypingIndicatorEvent(event: WebhookEventBase): event is TypingIndicatorEvent;
+export declare function isTrialEvent(event: WebhookEventBase): event is TrialEvent;
+export declare function isPreOrderEvent(event: WebhookEventBase): event is PreOrderEvent;
+//# sourceMappingURL=types.d.ts.map

package/dist/webhooks/types.d.ts.map

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

package/dist/webhooks/types.js

@@ -0,0 +1,20 @@
+/* ─────────────────────────── Type guards ─────────────────────────────── */
+export function isMessageEvent(event) {
+    return event.event_type.startsWith('message.');
+}
+export function isReactionEvent(event) {
+    return event.event_type.startsWith('reaction.');
+}
+export function isLineEvent(event) {
+    return event.event_type.startsWith('line.');
+}
+export function isTypingIndicatorEvent(event) {
+    return event.event_type.startsWith('typing_indicator.');
+}
+export function isTrialEvent(event) {
+    return event.event_type.startsWith('trial.');
+}
+export function isPreOrderEvent(event) {
+    return event.event_type.startsWith('pre_order.');
+}
+//# sourceMappingURL=types.js.map

package/dist/webhooks/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/webhooks/types.ts"],"names":[],"mappings":"AA0JA,6EAA6E;AAE7E,MAAM,UAAU,cAAc,CAAC,KAAuB;IACpD,OAAO,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,CAAA;AAChD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAuB;IACrD,OAAO,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,WAAW,CAAC,CAAA;AACjD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,OAAO,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAA;AAC7C,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,KAAuB;IAEvB,OAAO,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAA;AACzD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAuB;IAClD,OAAO,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAA;AAC9C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAuB;IACrD,OAAO,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,YAAY,CAAC,CAAA;AAClD,CAAC"}

package/dist/webhooks/verify.d.ts

@@ -0,0 +1,41 @@
+import type { WebhookEventBase } from './types.js';
+export interface VerifyWebhookOptions {
+    /**
+     * Maximum drift in seconds between the request timestamp and the
+     * verifier's clock. Defaults to 300 (5 minutes) per contract §4.4.
+     * Set higher only if your server is reverse-proxied through a queue
+     * that may stall messages.
+     */
+    tolerance?: number;
+    /**
+     * Override the "now" clock — exposed primarily so tests can pin a
+     * deterministic time. Returns unix seconds.
+     */
+    now?: () => number;
+}
+/**
+ * Verify an incoming webhook delivery using the iSnap signing scheme:
+ *
+ * - `X-iSnap-Signature` header carries the hex-encoded
+ *   `HMAC-SHA256(secret, "<timestamp>.<rawBody>")`
+ * - `X-iSnap-Timestamp` header carries the unix-second issuance time
+ *
+ * Throws `WebhookSignatureError` on missing headers, malformed
+ * timestamp, expired timestamp (outside `tolerance`), or signature
+ * mismatch. Returns the parsed event envelope on success.
+ *
+ * `secret` may be a single secret string OR an array — pass `[newSecret,
+ * oldSecret]` during the 5-minute rotate-secret grace window so both
+ * still validate. The verifier tries each in order and returns on the
+ * first match.
+ *
+ * Headers may be a `Record<string, string>` (e.g. Express's `req.headers`)
+ * or a `Headers` instance — both are read case-insensitively.
+ *
+ * **Consumers MUST dedupe by `event.event_id`** — retries replay the same
+ * envelope (same `event_id`, same body, same signature, refreshed
+ * timestamp). Without consumer-side dedup, an at-least-once delivery
+ * model produces duplicate side-effects on the partner system.
+ */
+export declare function verifyWebhook(rawBody: string, headers: Record<string, string | string[] | undefined> | Headers, secret: string | readonly string[], options?: VerifyWebhookOptions): WebhookEventBase;
+//# sourceMappingURL=verify.d.ts.map

package/dist/webhooks/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/webhooks/verify.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAIlD,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,OAAO,EAChE,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAClC,OAAO,GAAE,oBAAyB,GACjC,gBAAgB,CA+DlB"}

package/dist/webhooks/verify.js

@@ -0,0 +1,110 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { WebhookSignatureError } from '../errors.js';
+import { parseWebhookEvent } from './parse.js';
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * Verify an incoming webhook delivery using the iSnap signing scheme:
+ *
+ * - `X-iSnap-Signature` header carries the hex-encoded
+ *   `HMAC-SHA256(secret, "<timestamp>.<rawBody>")`
+ * - `X-iSnap-Timestamp` header carries the unix-second issuance time
+ *
+ * Throws `WebhookSignatureError` on missing headers, malformed
+ * timestamp, expired timestamp (outside `tolerance`), or signature
+ * mismatch. Returns the parsed event envelope on success.
+ *
+ * `secret` may be a single secret string OR an array — pass `[newSecret,
+ * oldSecret]` during the 5-minute rotate-secret grace window so both
+ * still validate. The verifier tries each in order and returns on the
+ * first match.
+ *
+ * Headers may be a `Record<string, string>` (e.g. Express's `req.headers`)
+ * or a `Headers` instance — both are read case-insensitively.
+ *
+ * **Consumers MUST dedupe by `event.event_id`** — retries replay the same
+ * envelope (same `event_id`, same body, same signature, refreshed
+ * timestamp). Without consumer-side dedup, an at-least-once delivery
+ * model produces duplicate side-effects on the partner system.
+ */
+export function verifyWebhook(rawBody, headers, secret, options = {}) {
+    const sigHeader = getHeader(headers, 'x-isnap-signature');
+    if (!sigHeader) {
+        throw new WebhookSignatureError('Missing X-iSnap-Signature header');
+    }
+    const tsHeader = getHeader(headers, 'x-isnap-timestamp');
+    if (!tsHeader) {
+        throw new WebhookSignatureError('Missing X-iSnap-Timestamp header');
+    }
+    // Strict integer-only check — `Number.parseInt` would happily accept
+    // `"1714478400foo"` and silently truncate. The HMAC compare downstream
+    // catches the resulting payload mismatch, but rejecting earlier here
+    // surfaces a clearer error and avoids one unnecessary HMAC computation.
+    if (!/^\d+$/.test(tsHeader)) {
+        throw new WebhookSignatureError(`Malformed X-iSnap-Timestamp: ${tsHeader}`);
+    }
+    const timestamp = Number(tsHeader);
+    if (!Number.isFinite(timestamp) || timestamp <= 0) {
+        throw new WebhookSignatureError(`Malformed X-iSnap-Timestamp: ${tsHeader}`);
+    }
+    const tolerance = options.tolerance ?? DEFAULT_TOLERANCE_SECONDS;
+    // Validate before use — `Math.abs(...) > NaN` is always false (so the
+    // replay-window check would silently pass), `Math.abs(...) > -1` is
+    // always true (every timestamp rejected), and `Infinity` makes every
+    // timestamp pass. Reject the bad inputs explicitly so misuse fails
+    // loudly at the verify call site instead of hiding a security gap.
+    if (!Number.isFinite(tolerance) || tolerance < 0) {
+        throw new WebhookSignatureError(`tolerance must be a finite non-negative number (got ${String(tolerance)})`);
+    }
+    const nowSec = (options.now ?? defaultNow)();
+    if (Math.abs(nowSec - timestamp) > tolerance) {
+        throw new WebhookSignatureError(`Webhook timestamp is outside the ${tolerance}s tolerance window (drift: ${nowSec - timestamp}s)`);
+    }
+    const candidates = typeof secret === 'string' ? [secret] : secret;
+    if (candidates.length === 0) {
+        throw new WebhookSignatureError('No webhook secret(s) provided');
+    }
+    const provided = decodeHex(sigHeader);
+    if (!provided) {
+        throw new WebhookSignatureError('X-iSnap-Signature is not valid hex');
+    }
+    const signedPayload = `${timestamp}.${rawBody}`;
+    // Multi-secret loop returns early on first match — this is a minor
+    // timing side-channel during the rotate-secret grace window (an
+    // attacker who controls request timing could distinguish "matched first
+    // candidate" from "matched second"). Practical exploit value is near
+    // zero: knowing which secret matched does not help forge signatures
+    // for either secret. Worth revisiting if real partners run rotation
+    // through hostile networks.
+    for (const candidate of candidates) {
+        const expected = createHmac('sha256', candidate).update(signedPayload).digest();
+        if (provided.length === expected.length && timingSafeEqual(provided, expected)) {
+            return parseWebhookEvent(rawBody);
+        }
+    }
+    throw new WebhookSignatureError('Webhook signature did not match any provided secret');
+}
+function getHeader(headers, name) {
+    if (typeof Headers !== 'undefined' && headers instanceof Headers) {
+        return headers.get(name);
+    }
+    const lower = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== lower)
+            continue;
+        if (Array.isArray(value))
+            return value[0] ?? null;
+        if (typeof value === 'string')
+            return value;
+        return null;
+    }
+    return null;
+}
+function decodeHex(hex) {
+    if (!/^[0-9a-fA-F]+$/.test(hex) || hex.length % 2 !== 0)
+        return null;
+    return Buffer.from(hex, 'hex');
+}
+function defaultNow() {
+    return Math.floor(Date.now() / 1000);
+}
+//# sourceMappingURL=verify.js.map

package/dist/webhooks/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/webhooks/verify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAG9C,MAAM,yBAAyB,GAAG,GAAG,CAAA;AAiBrC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAe,EACf,OAAgE,EAChE,MAAkC,EAClC,UAAgC,EAAE;IAElC,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAA;IACzD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,qBAAqB,CAAC,kCAAkC,CAAC,CAAA;IACrE,CAAC;IACD,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAA;IACxD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,qBAAqB,CAAC,kCAAkC,CAAC,CAAA;IACrE,CAAC;IACD,qEAAqE;IACrE,uEAAuE;IACvE,qEAAqE;IACrE,wEAAwE;IACxE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,qBAAqB,CAAC,gCAAgC,QAAQ,EAAE,CAAC,CAAA;IAC7E,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;IAClC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,qBAAqB,CAAC,gCAAgC,QAAQ,EAAE,CAAC,CAAA;IAC7E,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,yBAAyB,CAAA;IAChE,sEAAsE;IACtE,oEAAoE;IACpE,qEAAqE;IACrE,mEAAmE;IACnE,mEAAmE;IACnE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,qBAAqB,CAC7B,uDAAuD,MAAM,CAAC,SAAS,CAAC,GAAG,CAC5E,CAAA;IACH,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,UAAU,CAAC,EAAE,CAAA;IAC5C,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,EAAE,CAAC;QAC7C,MAAM,IAAI,qBAAqB,CAC7B,oCAAoC,SAAS,8BAA8B,MAAM,GAAG,SAAS,IAAI,CAClG,CAAA;IACH,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;IACjE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,qBAAqB,CAAC,+BAA+B,CAAC,CAAA;IAClE,CAAC;IAED,MAAM,QAAQ,GAAG,SAAS,CAAC,SAAS,CAAC,CAAA;IACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,qBAAqB,CAAC,oCAAoC,CAAC,CAAA;IACvE,CAAC;IACD,MAAM,aAAa,GAAG,GAAG,SAAS,IAAI,OAAO,EAAE,CAAA;IAC/C,mEAAmE;IACnE,gEAAgE;IAChE,wEAAwE;IACxE,qEAAqE;IACrE,oEAAoE;IACpE,oEAAoE;IACpE,4BAA4B;IAC5B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,MAAM,EAAE,CAAA;QAC/E,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,eAAe,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;YAC/E,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAA;QACnC,CAAC;IACH,CAAC;IACD,MAAM,IAAI,qBAAqB,CAAC,qDAAqD,CAAC,CAAA;AACxF,CAAC;AAED,SAAS,SAAS,CAChB,OAAgE,EAChE,IAAY;IAEZ,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,YAAY,OAAO,EAAE,CAAC;QACjE,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC1B,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;IAChC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,KAAK;YAAE,SAAQ;QACzC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAA;QACjD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAA;QAC3C,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACpE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;AAChC,CAAC;AAED,SAAS,UAAU;IACjB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;AACtC,CAAC"}

package/package.json

@@ -1,50 +1,65 @@
 {
   "name": "@isnap/sdk",
-  "version": "0.1.0",
-  "description": "Official Node.js/TypeScript SDK for the iSnap messaging API. Zero runtime dependencies.",
+  "version": "1.1.0-next.38",
+  "description": "Official TypeScript SDK for the iSnap P2P telephony API",
+  "license": "MIT",
   "type": "module",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./webhook-verify": {
-      "import": "./dist/webhook-verify.js",
-      "types": "./dist/webhook-verify.d.ts"
-    },
-    "./webhooks": {
-      "import": "./dist/webhook-events.js",
-      "types": "./dist/webhook-events.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
-  "files": ["dist"],
-  "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "isnap",
+    "imessage",
+    "sms",
+    "rcs",
+    "p2p",
+    "telephony",
+    "messaging",
+    "sdk",
+    "typescript"
+  ],
+  "homepage": "https://github.com/WhatSnap/iSnap-App/tree/main/packages/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/WhatSnap/iSnap-App/issues"
   },
-  "author": "iSnap <hello@isnap.dev>",
-  "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/isnap-dev/isnap-node"
+    "url": "git+https://github.com/WhatSnap/iSnap-App.git",
+    "directory": "packages/sdk"
   },
-  "homepage": "https://github.com/isnap-dev/isnap-node#readme",
-  "bugs": {
-    "url": "https://github.com/isnap-dev/isnap-node/issues"
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun scripts/copy-generated.ts",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "generate": "openapi-typescript ../backend/openapi.json -o src/generated/openapi.d.ts",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build"
   },
-  "keywords": ["isnap", "messaging", "sms", "imessage", "p2p", "sdk"],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "openapi-typescript": "^7.13.0",
     "typescript": "^5.7.0",
+    "typescript-eslint": "^8.57.1",
     "vitest": "^3.0.0"
   }
 }

package/dist/paginate.d.ts

@@ -1,33 +0,0 @@
-/**
- * Generic async generator that paginates over any SDK list endpoint.
- *
- * Yields individual items from each page until all pages have been consumed.
- *
- * @param fetcher - A function that accepts `{ page, limit }` and returns a paginated response
- * @param params - Initial pagination parameters (defaults: `page = 1`, `limit = 100`)
- * @param dataKey - The key in the response object that holds the array of items
- *
- * @example
- * ```ts
- * import { init, paginate } from '@isnap/sdk';
- *
- * const client = init({ apiKey: 'isnap_your_key' });
- *
- * for await (const msg of paginate(
- *   (p) => client.messages.list(p),
- *   { status: 'delivered' },
- *   'messages',
- * )) {
- *   console.log(msg.id, msg.body);
- * }
- * ```
- */
-export declare function paginate<TItem, TParams extends {
-    page?: number;
-    limit?: number;
-}, TKey extends string>(fetcher: (params: TParams) => Promise<{
-    total: number;
-    page: number;
-    limit: number;
-} & Record<TKey, TItem[]>>, params: TParams, dataKey: TKey): AsyncGenerator<TItem, void, undefined>;
-//# sourceMappingURL=paginate.d.ts.map

package/dist/paginate.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"paginate.d.ts","sourceRoot":"","sources":["../src/paginate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAuB,QAAQ,CAC7B,KAAK,EACL,OAAO,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACjD,IAAI,SAAS,MAAM,EAEnB,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,EAC7G,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,IAAI,GACZ,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CAkBxC"}

package/dist/paginate.js

@@ -1,40 +0,0 @@
-/**
- * Generic async generator that paginates over any SDK list endpoint.
- *
- * Yields individual items from each page until all pages have been consumed.
- *
- * @param fetcher - A function that accepts `{ page, limit }` and returns a paginated response
- * @param params - Initial pagination parameters (defaults: `page = 1`, `limit = 100`)
- * @param dataKey - The key in the response object that holds the array of items
- *
- * @example
- * ```ts
- * import { init, paginate } from '@isnap/sdk';
- *
- * const client = init({ apiKey: 'isnap_your_key' });
- *
- * for await (const msg of paginate(
- *   (p) => client.messages.list(p),
- *   { status: 'delivered' },
- *   'messages',
- * )) {
- *   console.log(msg.id, msg.body);
- * }
- * ```
- */
-export async function* paginate(fetcher, params, dataKey) {
-    let page = params.page ?? 1;
-    const limit = params.limit ?? 100;
-    while (true) {
-        const response = await fetcher({ ...params, page, limit });
-        const items = response[dataKey];
-        for (const item of items) {
-            yield item;
-        }
-        if (items.length < limit || page * limit >= response.total) {
-            break;
-        }
-        page++;
-    }
-}
-//# sourceMappingURL=paginate.js.map

package/dist/paginate.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"paginate.js","sourceRoot":"","sources":["../src/paginate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,QAAQ,CAK7B,OAA6G,EAC7G,MAAe,EACf,OAAa;IAEb,IAAI,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,GAAG,CAAC;IAElC,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,KAAK,EAAa,CAAC,CAAC;QACtE,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QAEhC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,CAAC;QACb,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAC3D,MAAM;QACR,CAAC;QAED,IAAI,EAAE,CAAC;IACT,CAAC;AACH,CAAC"}

package/dist/webhook-events.d.ts

@@ -1,61 +0,0 @@
-import type { WebhookEvent } from './types.js';
-/**
- * Parameters for parsing an incoming webhook request.
- */
-export interface ParseWebhookOptions {
-    /** The webhook secret (from {@link Webhook.secret}). */
-    secret: string;
-    /** The `x-isnap-signature` header value. */
-    signature: string;
-    /** The `x-isnap-timestamp` header value (Unix seconds). */
-    timestamp: string;
-    /** The raw request body string. */
-    body: string;
-}
-/**
- * Result of parsing a webhook request.
- */
-export interface ParseWebhookResult {
-    /** Whether the signature was valid and the timestamp was fresh. */
-    verified: boolean;
-    /** The parsed and typed webhook event. Only meaningful when `verified` is `true`. */
-    event: WebhookEvent;
-}
-/**
- * Verify and parse an incoming webhook request in a single call.
- *
- * Combines signature verification with JSON parsing to produce a typed
- * {@link WebhookEvent} that supports discriminated-union narrowing.
- *
- * @param options - Signature, timestamp, secret, and raw body
- * @returns Object with `verified` flag and the parsed `event`
- *
- * @example
- * ```ts
- * import { parseWebhook } from '@isnap/sdk';
- *
- * app.post('/webhooks/isnap', (req, res) => {
- *   const { verified, event } = parseWebhook({
- *     secret: process.env.WEBHOOK_SECRET!,
- *     signature: req.headers['x-isnap-signature'] as string,
- *     timestamp: req.headers['x-isnap-timestamp'] as string,
- *     body: req.body, // raw string
- *   });
- *
- *   if (!verified) return res.status(401).send('Invalid signature');
- *
- *   switch (event.event) {
- *     case 'message.sent':
- *       console.log('Sent:', event.data.id);
- *       break;
- *     case 'message.received':
- *       console.log('Received:', event.data.body);
- *       break;
- *   }
- *
- *   res.sendStatus(200);
- * });
- * ```
- */
-export declare function parseWebhook(options: ParseWebhookOptions): ParseWebhookResult;
-//# sourceMappingURL=webhook-events.d.ts.map

package/dist/webhook-events.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"webhook-events.d.ts","sourceRoot":"","sources":["../src/webhook-events.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,QAAQ,EAAE,OAAO,CAAC;IAClB,qFAAqF;IACrF,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAK7E"}

package/dist/webhook-events.js

@@ -1,44 +0,0 @@
-import { verifyWebhookSignature } from './webhook-verify.js';
-/**
- * Verify and parse an incoming webhook request in a single call.
- *
- * Combines signature verification with JSON parsing to produce a typed
- * {@link WebhookEvent} that supports discriminated-union narrowing.
- *
- * @param options - Signature, timestamp, secret, and raw body
- * @returns Object with `verified` flag and the parsed `event`
- *
- * @example
- * ```ts
- * import { parseWebhook } from '@isnap/sdk';
- *
- * app.post('/webhooks/isnap', (req, res) => {
- *   const { verified, event } = parseWebhook({
- *     secret: process.env.WEBHOOK_SECRET!,
- *     signature: req.headers['x-isnap-signature'] as string,
- *     timestamp: req.headers['x-isnap-timestamp'] as string,
- *     body: req.body, // raw string
- *   });
- *
- *   if (!verified) return res.status(401).send('Invalid signature');
- *
- *   switch (event.event) {
- *     case 'message.sent':
- *       console.log('Sent:', event.data.id);
- *       break;
- *     case 'message.received':
- *       console.log('Received:', event.data.body);
- *       break;
- *   }
- *
- *   res.sendStatus(200);
- * });
- * ```
- */
-export function parseWebhook(options) {
-    const { secret, signature, timestamp, body } = options;
-    const event = JSON.parse(body);
-    const verified = verifyWebhookSignature(secret, signature, timestamp, body);
-    return { verified, event };
-}
-//# sourceMappingURL=webhook-events.js.map

package/dist/webhook-events.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"webhook-events.js","sourceRoot":"","sources":["../src/webhook-events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AA2B7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4B;IACvD,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IACvD,MAAM,KAAK,GAAiB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IAC5E,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC"}