@pacspace-io/sdk 0.1.0

package/dist/types/balance.d.ts

@@ -0,0 +1,218 @@
+import type { AnchorStatus, CheckpointType } from './common';
+import type { RequestOptions } from './config';
+/**
+ * Options for `balance.emit()`.
+ */
+export interface EmitOptions extends RequestOptions {
+    /** Your internal reference ID for correlation. */
+    referenceId?: string;
+    /** Arbitrary key-value metadata to store with the delta. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for `balance.emitAndWait()`.
+ */
+export interface EmitAndWaitOptions extends EmitOptions {
+    /**
+     * Maximum time (ms) to wait for verification before throwing.
+     * @default 60000
+     */
+    timeout?: number;
+    /**
+     * Interval (ms) between status polls.
+     * @default 2000
+     */
+    pollInterval?: number;
+}
+/**
+ * Response from `balance.emit()`.
+ */
+export interface EmitResponse {
+    /** Unique identifier for this anchor/delta record. */
+    anchorId: string;
+    /** The customer account this delta belongs to. */
+    customerId: string;
+    /** The recorded adjustment amount. */
+    delta: number;
+    /** Current processing status. */
+    status: AnchorStatus;
+    /** Proof root hash — store this for later verification. */
+    receiptId: string;
+    /** Root hash covering the items in this submission (same as receiptId). */
+    itemsRoot: string;
+    /** Individual content hashes for each item. */
+    itemHashes: string[];
+    /** Estimated number of verified deltas this submission will produce. */
+    estimatedVerifiedDeltas: number;
+    /** Estimated credits that will be consumed upon verification. */
+    estimatedCredits: number;
+    /** ISO 8601 timestamp of when the submission was received. */
+    receivedAt: string;
+    /** Human-readable status message. */
+    message: string;
+}
+/**
+ * Options for `balance.derive()`.
+ */
+export interface DeriveOptions extends RequestOptions {
+    /**
+     * Starting balance to derive from.
+     * @default 0
+     */
+    startingBalance?: number;
+    /**
+     * Checkpoint value to start derivation from (avoids replaying from genesis).
+     * Use the `latestReceiptId` from a previous derivation response.
+     */
+    startingCheckpoint?: string;
+    /**
+     * Type of checkpoint provided.
+     * @default 'itemsRoot'
+     */
+    startingCheckpointType?: CheckpointType;
+}
+/**
+ * A single verified delta in the derivation response.
+ */
+export interface VerifiedDelta {
+    anchorId: string;
+    itemHash: string;
+    itemsRoot: string;
+    receiptId: string;
+    delta: number;
+    reason: string | null;
+    referenceId: string | null;
+    window: string;
+    declaredTimestamp: string | null;
+    blockTimestamp: string | null;
+    dataPurged: boolean;
+    verified: true;
+}
+/**
+ * Summary of deltas within a time window.
+ */
+export interface WindowSummary {
+    window: string;
+    deltasCount: number;
+    netDelta: number;
+    firstBlockTimestamp: string | null;
+    lastBlockTimestamp: string | null;
+}
+/**
+ * Response from `balance.derive()`.
+ */
+export interface DeriveResponse {
+    customerId: string;
+    startingBalance: number;
+    startingCheckpoint: string;
+    startingCheckpointType: CheckpointType;
+    deltasCount: number;
+    computedBalance: number;
+    latestCheckpoint: string | null;
+    latestReceiptId: string | null;
+    deltas: VerifiedDelta[];
+    windowSummaries: WindowSummary[];
+    verificationProof: {
+        itemsRoot: string | null;
+        message: string;
+    };
+}
+/**
+ * Options for `balance.compare()`.
+ */
+export interface CompareOptions extends RequestOptions {
+    /**
+     * Starting balance for derivation.
+     * @default 0
+     */
+    startingBalance?: number;
+    /** Checkpoint to start comparison from. */
+    startingCheckpoint?: string;
+    /** Type of checkpoint provided. */
+    startingCheckpointType?: CheckpointType;
+}
+/**
+ * Balances to compare — your view vs. their view.
+ */
+export interface CompareBalances {
+    /** Your calculated balance. */
+    yours: number;
+    /** Customer's claimed balance. */
+    theirs: number;
+}
+/**
+ * Discrepancy details when balances don't match.
+ */
+export interface DiscrepancyReport {
+    amount: number;
+    resolution: string;
+    divergentParty: 'yours' | 'theirs' | 'both';
+    windowsToReview: Array<{
+        window: string;
+        netDelta: number;
+        deltasCount: number;
+        timeRange: string;
+    }>;
+    recommendation: string;
+}
+/**
+ * Response from `balance.compare()`.
+ */
+export interface CompareResponse {
+    customerId: string;
+    yourBalance: number;
+    theirBalance: number;
+    neutralBalance: number;
+    matchesYours: boolean;
+    matchesTheirs: boolean;
+    deltasVerified: number;
+    discrepancyReport: DiscrepancyReport | null;
+    proof: {
+        itemsRoot: string | null;
+        latestCheckpoint: string | null;
+        windowSummaries: WindowSummary[];
+    };
+}
+/**
+ * Response from `balance.receipt()`.
+ */
+export interface ReceiptResponse {
+    customerId: string;
+    generatedAt: string;
+    deltasCount: number;
+    finalBalance: number;
+    itemsRoot: string | null;
+    receiptId: string | null;
+    latestCheckpoint: string | null;
+    deltas: VerifiedDelta[];
+    windowSummaries: WindowSummary[];
+    verification: {
+        message: string;
+        itemHashes: string[];
+    };
+}
+/**
+ * Options for `balance.checkpoint()`.
+ */
+export interface CheckpointOptions extends RequestOptions {
+    /**
+     * Billing period in YYYY-MM format.
+     * Defaults to the current period.
+     */
+    period?: string;
+}
+/**
+ * Response from `balance.checkpoint()`.
+ */
+export interface CheckpointResponse {
+    checkpointId: string;
+    period: string;
+    merkleRoot: string;
+    deltaCount: number;
+    fromIndex: number;
+    toIndex: number;
+    customerId: string;
+    status: AnchorStatus;
+    message: string;
+}
+//# sourceMappingURL=balance.d.ts.map

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

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

package/dist/types/balance.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=balance.js.map

package/dist/types/balance.js.map

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

package/dist/types/common.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Raw API response envelope returned by all PacSpace endpoints.
+ * The SDK unwraps this automatically — users never see it.
+ * @internal
+ */
+export interface RawApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    message?: string;
+    error?: string;
+    statusCode?: number;
+}
+/**
+ * Anchor status lifecycle.
+ */
+export type AnchorStatus = 'QUEUED' | 'PROCESSING' | 'ANCHORING' | 'ANCHORED' | 'VERIFIED' | 'FAILED';
+/**
+ * Checkpoint type for balance derivation.
+ */
+export type CheckpointType = 'itemsRoot' | 'anchorId';
+//# sourceMappingURL=common.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/types/common.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,YAAY,GACZ,WAAW,GACX,UAAU,GACV,UAAU,GACV,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,UAAU,CAAC"}

package/dist/types/common.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=common.js.map

package/dist/types/common.js.map

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

package/dist/types/config.d.ts

@@ -0,0 +1,54 @@
+/**
+ * PacSpace SDK configuration options.
+ */
+export interface PacSpaceConfig {
+    /**
+     * Your PacSpace API key.
+     * Format: `pk_live_PUBLIC.SECRET` (production) or `pk_test_PUBLIC.SECRET` (sandbox).
+     */
+    apiKey: string;
+    /**
+     * Base URL for the PacSpace API.
+     * Defaults to `https://balance-api.pacspace.io`.
+     */
+    baseUrl?: string;
+    /**
+     * Default chain ID to use for all requests.
+     * Auto-detected from API key prefix when not set:
+     * - `pk_test_*` → 296 (Hedera Testnet)
+     * - `pk_live_*` → 295 (Hedera Mainnet)
+     */
+    chainId?: number;
+    /**
+     * Default credit pool ID for all requests.
+     */
+    creditPoolId?: number;
+    /**
+     * Maximum number of automatic retries on transient errors (5xx, network).
+     * @default 2
+     */
+    maxRetries?: number;
+    /**
+     * Request timeout in milliseconds.
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Custom fetch implementation. Uses global `fetch` by default (Node 18+).
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Per-request options that can override defaults.
+ */
+export interface RequestOptions {
+    /** Override the default chain ID for this request. */
+    chainId?: number;
+    /** Override the default credit pool ID for this request. */
+    creditPoolId?: number;
+    /** Idempotency key to prevent duplicate processing. */
+    idempotencyKey?: string;
+    /** AbortSignal for request cancellation. */
+    signal?: AbortSignal;
+}
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB"}

package/dist/types/config.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=config.js.map

package/dist/types/config.js.map

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

package/dist/utils/polling.d.ts

@@ -0,0 +1,32 @@
+import type { AnchorStatus } from '../types/common';
+/**
+ * Options for the poll utility.
+ */
+export interface PollOptions {
+    /**
+     * Maximum time (ms) to wait before throwing a TimeoutError.
+     * @default 60000
+     */
+    timeout?: number;
+    /**
+     * Interval (ms) between polls.
+     * @default 2000
+     */
+    pollInterval?: number;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Poll a status-returning function until a terminal status is reached.
+ *
+ * @param statusFn — Async function that returns the current status and full data.
+ * @param options — Timeout and interval configuration.
+ * @returns The full data object once a terminal status is reached.
+ * @throws TimeoutError if the timeout is exceeded.
+ *
+ * @internal
+ */
+export declare function pollUntilTerminal<T extends {
+    status: AnchorStatus;
+}>(statusFn: () => Promise<T>, options?: PollOptions): Promise<T>;
+//# sourceMappingURL=polling.d.ts.map

package/dist/utils/polling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polling.d.ts","sourceRoot":"","sources":["../../src/utils/polling.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAYpD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,EACxE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC1B,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,CAAC,CAAC,CA0CZ"}

package/dist/utils/polling.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pollUntilTerminal = pollUntilTerminal;
+const errors_1 = require("../errors");
+/**
+ * Terminal statuses — once an anchor reaches these, polling stops.
+ */
+const TERMINAL_STATUSES = new Set([
+    'ANCHORED',
+    'VERIFIED',
+    'FAILED',
+]);
+/**
+ * Poll a status-returning function until a terminal status is reached.
+ *
+ * @param statusFn — Async function that returns the current status and full data.
+ * @param options — Timeout and interval configuration.
+ * @returns The full data object once a terminal status is reached.
+ * @throws TimeoutError if the timeout is exceeded.
+ *
+ * @internal
+ */
+async function pollUntilTerminal(statusFn, options) {
+    const timeout = options?.timeout ?? 60000;
+    const pollInterval = options?.pollInterval ?? 2000;
+    const signal = options?.signal;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+        // Check cancellation
+        if (signal?.aborted) {
+            throw new errors_1.TimeoutError('Polling cancelled');
+        }
+        const result = await statusFn();
+        if (TERMINAL_STATUSES.has(result.status)) {
+            return result;
+        }
+        // Wait before next poll, but respect the deadline
+        const remaining = deadline - Date.now();
+        const delay = Math.min(pollInterval, remaining);
+        if (delay <= 0)
+            break;
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(resolve, delay);
+            // If cancelled during sleep, clean up and reject
+            if (signal) {
+                const onAbort = () => {
+                    clearTimeout(timer);
+                    reject(new errors_1.TimeoutError('Polling cancelled'));
+                };
+                signal.addEventListener('abort', onAbort, { once: true });
+            }
+        });
+    }
+    throw new errors_1.TimeoutError(`Operation did not reach a terminal status within ${timeout}ms`);
+}
+//# sourceMappingURL=polling.js.map

package/dist/utils/polling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polling.js","sourceRoot":"","sources":["../../src/utils/polling.ts"],"names":[],"mappings":";;AAwCA,8CA6CC;AApFD,sCAAyC;AAEzC;;GAEG;AACH,MAAM,iBAAiB,GAAsB,IAAI,GAAG,CAAC;IACnD,UAAU;IACV,UAAU;IACV,QAAQ;CACT,CAAC,CAAC;AAoBH;;;;;;;;;GASG;AACI,KAAK,UAAU,iBAAiB,CACrC,QAA0B,EAC1B,OAAqB;IAErB,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,KAAM,CAAC;IAC3C,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,IAAK,CAAC;IACpD,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAE/B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;IAEtC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,qBAAqB;QACrB,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,qBAAY,CAAC,mBAAmB,CAAC,CAAC;QAC9C,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,QAAQ,EAAE,CAAC;QAEhC,IAAI,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YACzC,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,kDAAkD;QAClD,MAAM,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QAEhD,IAAI,KAAK,IAAI,CAAC;YAAE,MAAM;QAEtB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1C,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YAEzC,iDAAiD;YACjD,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,OAAO,GAAG,GAAG,EAAE;oBACnB,YAAY,CAAC,KAAK,CAAC,CAAC;oBACpB,MAAM,CAAC,IAAI,qBAAY,CAAC,mBAAmB,CAAC,CAAC,CAAC;gBAChD,CAAC,CAAC;gBACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,qBAAY,CACpB,oDAAoD,OAAO,IAAI,CAChE,CAAC;AACJ,CAAC"}

package/dist/utils/retry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Utility for exponential backoff delay calculations.
+ * @internal — Used by the HttpClient; exported for advanced use cases.
+ */
+/**
+ * Calculate exponential backoff delay with jitter.
+ *
+ * @param attempt - The retry attempt number (1-indexed).
+ * @param baseDelay - Base delay in milliseconds.
+ * @param maxDelay - Maximum delay in milliseconds.
+ * @returns Delay in milliseconds.
+ */
+export declare function exponentialBackoff(attempt: number, baseDelay?: number, maxDelay?: number): number;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,SAAS,SAAM,EACf,QAAQ,SAAS,GAChB,MAAM,CAIR"}

package/dist/utils/retry.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Utility for exponential backoff delay calculations.
+ * @internal — Used by the HttpClient; exported for advanced use cases.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exponentialBackoff = exponentialBackoff;
+/**
+ * Calculate exponential backoff delay with jitter.
+ *
+ * @param attempt - The retry attempt number (1-indexed).
+ * @param baseDelay - Base delay in milliseconds.
+ * @param maxDelay - Maximum delay in milliseconds.
+ * @returns Delay in milliseconds.
+ */
+function exponentialBackoff(attempt, baseDelay = 500, maxDelay = 30000) {
+    const delay = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
+    const jitter = delay * 0.25 * Math.random();
+    return delay + jitter;
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAUH,gDAQC;AAhBD;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAChC,OAAe,EACf,SAAS,GAAG,GAAG,EACf,QAAQ,GAAG,KAAM;IAEjB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACvE,MAAM,MAAM,GAAG,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5C,OAAO,KAAK,GAAG,MAAM,CAAC;AACxB,CAAC"}

package/dist/webhooks/index.d.ts

@@ -0,0 +1,3 @@
+export { Webhooks, type VerifyOptions } from './verify';
+export type { WebhookEventType, WebhookEvent, WebhookEventMap, WebhookHeaders, DeltaVerifiedPayload, DeltaStoredPayload, CheckpointVerifiedPayload, FactVerifiedPayload, RecordTransferredPayload, } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webhooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AACxD,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,SAAS,CAAC"}

package/dist/webhooks/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Webhooks = void 0;
+var verify_1 = require("./verify");
+Object.defineProperty(exports, "Webhooks", { enumerable: true, get: function () { return verify_1.Webhooks; } });
+//# sourceMappingURL=index.js.map

package/dist/webhooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/webhooks/index.ts"],"names":[],"mappings":";;;AAAA,mCAAwD;AAA/C,kGAAA,QAAQ,OAAA"}

package/dist/webhooks/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * All supported webhook event types.
+ */
+export type WebhookEventType = 'delta.verified' | 'delta.stored' | 'checkpoint.verified' | 'fact.verified' | 'record.transferred';
+export interface DeltaVerifiedPayload {
+    receiptId: string;
+    deltaIndex: number | null;
+    status: 'verified';
+    verifiedAt: string;
+    verificationId: string;
+    delta: {
+        customerId: string | null;
+        amount: number | null;
+        reason: string | null;
+        referenceId: string | null;
+        metadata: Record<string, unknown>;
+        submittedAt: string | null;
+    };
+    proof: {
+        proofHash: string;
+        contentHash: string | null;
+        itemHashes: string[];
+        previousProofHash: string | null;
+    };
+    verification: {
+        verified: boolean;
+        latencyMs: number;
+        discrepancies: string[];
+    };
+    period?: {
+        id: string;
+        deltaCount: number;
+        netDelta: number;
+    };
+    usage?: {
+        plan: string;
+        includedDeltas: number;
+        consumedDeltas: number;
+        remainingDeltas: number;
+        overageRate: string;
+    };
+}
+export interface DeltaStoredPayload {
+    startIndex: string;
+    count: string;
+    verificationId: string;
+    verifiedAt: string;
+}
+export interface CheckpointVerifiedPayload {
+    fromIndex: string;
+    toIndex: string;
+    proofHash: string;
+    verifiedAt: string;
+    verificationId: string;
+    message: string;
+}
+export interface FactVerifiedPayload {
+    contentHash: string;
+    proofHash: string;
+    verifiedAt: string;
+    verificationId: string;
+}
+export interface RecordTransferredPayload {
+    receiptId: string;
+    verifiedAt: string;
+    verificationId: string;
+}
+/**
+ * Map from event type to its payload shape.
+ */
+export interface WebhookEventMap {
+    'delta.verified': DeltaVerifiedPayload;
+    'delta.stored': DeltaStoredPayload;
+    'checkpoint.verified': CheckpointVerifiedPayload;
+    'fact.verified': FactVerifiedPayload;
+    'record.transferred': RecordTransferredPayload;
+}
+/**
+ * A typed webhook event.
+ */
+export interface WebhookEvent<T extends WebhookEventType = WebhookEventType> {
+    /** The event type. */
+    event: T;
+    /** ISO 8601 timestamp of when the webhook was sent. */
+    timestamp: string;
+    /** Event-specific data. */
+    data: T extends keyof WebhookEventMap ? WebhookEventMap[T] : unknown;
+}
+/**
+ * Headers sent with every webhook delivery.
+ */
+export interface WebhookHeaders {
+    'x-pacspace-signature': string;
+    'x-pacspace-timestamp': string;
+    'x-webhook-event'?: string;
+    'x-event-id'?: string;
+    [key: string]: string | undefined;
+}
+//# 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,6 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Webhook Event Types
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+//# 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":";AAAA,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E"}