@ghostgate/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ghost Protocol
+
+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

@@ -0,0 +1,45 @@
+# @ghostgate/sdk
+
+Node.js SDK for Ghost Protocol gate access, fulfillment, telemetry, and canary helpers.
+
+## Install
+
+```bash
+npm install @ghostgate/sdk
+```
+
+Until the package is published to npm, you can also test locally from this repo:
+
+```bash
+npm run build:sdk
+npm install ../GHOST_PROTOCOL/packages/sdk
+```
+
+## Surface
+
+- `GhostAgent`
+  - `connect()`
+  - `pulse()`
+  - `outcome()`
+  - `startHeartbeat()`
+- `GhostFulfillmentConsumer`
+- `GhostFulfillmentMerchant`
+- `GhostMerchant`
+- `buildCanaryPayload()`
+- `createCanaryHandler()`
+
+## Example
+
+```ts
+import { GhostAgent, GhostMerchant } from "@ghostgate/sdk";
+
+const sdk = new GhostAgent({
+  apiKey: process.env.GHOST_API_KEY,
+  privateKey: process.env.GHOST_SIGNER_PRIVATE_KEY as `0x${string}`,
+  baseUrl: process.env.GHOST_BASE_URL,
+  serviceSlug: "agent-18755",
+});
+
+await sdk.connect();
+await sdk.pulse();
+```

package/dist/fulfillment-eip712.d.ts

@@ -0,0 +1,302 @@
+import { type Hex } from "viem";
+import { FULFILLMENT_EIP712_DOMAIN_NAME, FULFILLMENT_EIP712_DOMAIN_VERSION, FULFILLMENT_EIP712_VERIFIYING_CONTRACT_SENTINEL, type FulfillmentDeliveryProofEnvelope, type FulfillmentDeliveryProofMessage, type FulfillmentTicketEnvelope, type FulfillmentTicketHeaderRecord, type FulfillmentTicketMessage, type FulfillmentTicketRequestAuthMessage, type Hex32 } from "./fulfillment-types.js";
+type UintLike = bigint | number | string;
+type MaybeString = string | null | undefined;
+export declare const FULFILLMENT_EIP712_TYPES: {
+    readonly FulfillmentTicket: readonly [{
+        readonly name: "ticketId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "consumer";
+        readonly type: "address";
+    }, {
+        readonly name: "merchantOwner";
+        readonly type: "address";
+    }, {
+        readonly name: "gatewayConfigIdHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "serviceSlug";
+        readonly type: "string";
+    }, {
+        readonly name: "method";
+        readonly type: "string";
+    }, {
+        readonly name: "path";
+        readonly type: "string";
+    }, {
+        readonly name: "queryHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "bodyHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "cost";
+        readonly type: "uint256";
+    }, {
+        readonly name: "issuedAt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "expiresAt";
+        readonly type: "uint256";
+    }];
+    readonly FulfillmentDeliveryProof: readonly [{
+        readonly name: "ticketId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "deliveryProofId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "merchantSigner";
+        readonly type: "address";
+    }, {
+        readonly name: "serviceSlug";
+        readonly type: "string";
+    }, {
+        readonly name: "completedAt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "statusCode";
+        readonly type: "uint256";
+    }, {
+        readonly name: "latencyMs";
+        readonly type: "uint256";
+    }, {
+        readonly name: "responseHash";
+        readonly type: "bytes32";
+    }];
+    readonly FulfillmentTicketRequestAuth: readonly [{
+        readonly name: "action";
+        readonly type: "string";
+    }, {
+        readonly name: "serviceSlug";
+        readonly type: "string";
+    }, {
+        readonly name: "method";
+        readonly type: "string";
+    }, {
+        readonly name: "path";
+        readonly type: "string";
+    }, {
+        readonly name: "queryHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "bodyHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "cost";
+        readonly type: "uint256";
+    }, {
+        readonly name: "issuedAt";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "string";
+    }];
+};
+export declare const buildFulfillmentEip712Domain: (chainId?: number) => {
+    name: typeof FULFILLMENT_EIP712_DOMAIN_NAME;
+    version: typeof FULFILLMENT_EIP712_DOMAIN_VERSION;
+    chainId: number;
+    verifyingContract: typeof FULFILLMENT_EIP712_VERIFIYING_CONTRACT_SENTINEL;
+};
+export declare const normalizeFulfillmentTicketMessage: (input: {
+    ticketId: string;
+    consumer: string;
+    merchantOwner: string;
+    gatewayConfigIdHash: string;
+    serviceSlug: string;
+    method: string;
+    path: string;
+    queryHash: string;
+    bodyHash: string;
+    cost: UintLike;
+    issuedAt: UintLike;
+    expiresAt: UintLike;
+}) => FulfillmentTicketMessage;
+export declare const normalizeFulfillmentDeliveryProofMessage: (input: {
+    ticketId: string;
+    deliveryProofId: string;
+    merchantSigner: string;
+    serviceSlug: string;
+    completedAt: UintLike;
+    statusCode: UintLike;
+    latencyMs: UintLike;
+    responseHash?: string | null;
+}) => FulfillmentDeliveryProofMessage;
+export declare const normalizeFulfillmentTicketRequestAuthMessage: (input: {
+    action?: string;
+    serviceSlug: string;
+    method: string;
+    path: string;
+    queryHash: string;
+    bodyHash: string;
+    cost: UintLike;
+    issuedAt: UintLike;
+    nonce: string;
+}) => FulfillmentTicketRequestAuthMessage;
+export declare const buildFulfillmentTicketTypedData: (message: FulfillmentTicketMessage, options?: {
+    chainId?: number;
+}) => {
+    domain: {
+        name: typeof FULFILLMENT_EIP712_DOMAIN_NAME;
+        version: typeof FULFILLMENT_EIP712_DOMAIN_VERSION;
+        chainId: number;
+        verifyingContract: typeof FULFILLMENT_EIP712_VERIFIYING_CONTRACT_SENTINEL;
+    };
+    types: {
+        FulfillmentTicket: readonly [{
+            readonly name: "ticketId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "consumer";
+            readonly type: "address";
+        }, {
+            readonly name: "merchantOwner";
+            readonly type: "address";
+        }, {
+            readonly name: "gatewayConfigIdHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "serviceSlug";
+            readonly type: "string";
+        }, {
+            readonly name: "method";
+            readonly type: "string";
+        }, {
+            readonly name: "path";
+            readonly type: "string";
+        }, {
+            readonly name: "queryHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "bodyHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "cost";
+            readonly type: "uint256";
+        }, {
+            readonly name: "issuedAt";
+            readonly type: "uint256";
+        }, {
+            readonly name: "expiresAt";
+            readonly type: "uint256";
+        }];
+    };
+    primaryType: "FulfillmentTicket";
+    message: FulfillmentTicketMessage;
+};
+export declare const buildFulfillmentDeliveryProofTypedData: (message: FulfillmentDeliveryProofMessage, options?: {
+    chainId?: number;
+}) => {
+    domain: {
+        name: typeof FULFILLMENT_EIP712_DOMAIN_NAME;
+        version: typeof FULFILLMENT_EIP712_DOMAIN_VERSION;
+        chainId: number;
+        verifyingContract: typeof FULFILLMENT_EIP712_VERIFIYING_CONTRACT_SENTINEL;
+    };
+    types: {
+        FulfillmentDeliveryProof: readonly [{
+            readonly name: "ticketId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "deliveryProofId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "merchantSigner";
+            readonly type: "address";
+        }, {
+            readonly name: "serviceSlug";
+            readonly type: "string";
+        }, {
+            readonly name: "completedAt";
+            readonly type: "uint256";
+        }, {
+            readonly name: "statusCode";
+            readonly type: "uint256";
+        }, {
+            readonly name: "latencyMs";
+            readonly type: "uint256";
+        }, {
+            readonly name: "responseHash";
+            readonly type: "bytes32";
+        }];
+    };
+    primaryType: "FulfillmentDeliveryProof";
+    message: FulfillmentDeliveryProofMessage;
+};
+export declare const buildFulfillmentTicketRequestAuthTypedData: (message: FulfillmentTicketRequestAuthMessage, options?: {
+    chainId?: number;
+}) => {
+    domain: {
+        name: typeof FULFILLMENT_EIP712_DOMAIN_NAME;
+        version: typeof FULFILLMENT_EIP712_DOMAIN_VERSION;
+        chainId: number;
+        verifyingContract: typeof FULFILLMENT_EIP712_VERIFIYING_CONTRACT_SENTINEL;
+    };
+    types: {
+        FulfillmentTicketRequestAuth: readonly [{
+            readonly name: "action";
+            readonly type: "string";
+        }, {
+            readonly name: "serviceSlug";
+            readonly type: "string";
+        }, {
+            readonly name: "method";
+            readonly type: "string";
+        }, {
+            readonly name: "path";
+            readonly type: "string";
+        }, {
+            readonly name: "queryHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "bodyHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "cost";
+            readonly type: "uint256";
+        }, {
+            readonly name: "issuedAt";
+            readonly type: "uint256";
+        }, {
+            readonly name: "nonce";
+            readonly type: "string";
+        }];
+    };
+    primaryType: "FulfillmentTicketRequestAuth";
+    message: FulfillmentTicketRequestAuthMessage;
+};
+export declare const hashFulfillmentTicketTypedData: (message: FulfillmentTicketMessage, options?: {
+    chainId?: number;
+}) => Hex32;
+export declare const hashFulfillmentDeliveryProofTypedData: (message: FulfillmentDeliveryProofMessage, options?: {
+    chainId?: number;
+}) => Hex32;
+export declare const hashFulfillmentTicketRequestAuthTypedData: (message: FulfillmentTicketRequestAuthMessage, options?: {
+    chainId?: number;
+}) => Hex32;
+export declare const encodeTypedPayloadBase64Url: <T extends object>(payload: T) => string;
+export declare const decodeTypedPayloadBase64Url: <T = unknown>(encoded: string) => T;
+export declare const buildFulfillmentTicketEnvelope: (payload: FulfillmentTicketMessage, signature: string) => FulfillmentTicketEnvelope;
+export declare const buildFulfillmentDeliveryProofEnvelope: (payload: FulfillmentDeliveryProofMessage, signature: string) => FulfillmentDeliveryProofEnvelope;
+export declare const buildFulfillmentTicketHeaders: (input: {
+    ticketId: string;
+    ticket: FulfillmentTicketEnvelope;
+    clientRequestId?: MaybeString;
+}) => FulfillmentTicketHeaderRecord;
+type HeadersLike = Pick<Headers, "get"> | Record<string, string | undefined | null>;
+export declare const parseFulfillmentTicketHeaders: (headers: HeadersLike) => {
+    ticketId: Hex32;
+    ticket: FulfillmentTicketEnvelope;
+    clientRequestId: string | null;
+} | null;
+export declare const redactFulfillmentTicketEnvelopeDebug: (envelope: FulfillmentTicketEnvelope) => Record<string, unknown>;
+export declare const redactFulfillmentDeliveryProofEnvelopeDebug: (envelope: FulfillmentDeliveryProofEnvelope) => Record<string, unknown>;
+export declare const parseWireFulfillmentTicketMessage: (encodedPayload: string) => FulfillmentTicketMessage;
+export declare const parseWireFulfillmentDeliveryProofMessage: (encodedPayload: string) => FulfillmentDeliveryProofMessage;
+export declare const parseWireFulfillmentTicketRequestAuthMessage: (encodedPayload: string) => FulfillmentTicketRequestAuthMessage;
+export type FulfillmentFixtureDomain = ReturnType<typeof buildFulfillmentEip712Domain>;
+export type FulfillmentTicketTypedHash = Hex;
+export {};
+//# sourceMappingURL=fulfillment-eip712.d.ts.map

package/dist/fulfillment-eip712.d.ts.map

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

package/dist/fulfillment-eip712.js

@@ -0,0 +1,267 @@
+import { Buffer } from "node:buffer";
+import { hashTypedData } from "viem";
+import { assertFulfillmentPath, FULFILLMENT_API_VERSION, FULFILLMENT_DEFAULT_CHAIN_ID, FULFILLMENT_EIP712_DOMAIN_NAME, FULFILLMENT_EIP712_DOMAIN_VERSION, FULFILLMENT_EIP712_VERIFIYING_CONTRACT_SENTINEL, FULFILLMENT_TICKET_HEADER_CLIENT_REQUEST_ID, FULFILLMENT_TICKET_HEADER_PAYLOAD, FULFILLMENT_TICKET_HEADER_SIGNATURE, FULFILLMENT_TICKET_HEADER_TICKET_ID, FULFILLMENT_TICKET_HEADER_VERSION, FULFILLMENT_TICKET_REQUEST_ACTION, normalizeFulfillmentMethod, parseFulfillmentChainId, } from "./fulfillment-types.js";
+import { FULFILLMENT_ZERO_HASH_32 } from "./fulfillment-hash.js";
+const LOWER_HEX32_PATTERN = /^0x[a-f0-9]{64}$/;
+const LOWER_HEX_PATTERN = /^0x[a-f0-9]+$/;
+const ADDRESS_PATTERN = /^0x[a-f0-9]{40}$/;
+const parseUintLike = (value, field) => {
+    if (typeof value === "bigint") {
+        if (value < 0n)
+            throw new Error(`${field} must be non-negative.`);
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isInteger(value) || value < 0)
+            throw new Error(`${field} must be a non-negative integer.`);
+        return BigInt(value);
+    }
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed))
+        throw new Error(`${field} must be an unsigned integer string.`);
+    return BigInt(trimmed);
+};
+const normalizeLowerHex = (value, field) => {
+    const normalized = value.trim().toLowerCase();
+    if (!LOWER_HEX_PATTERN.test(normalized))
+        throw new Error(`${field} must be a lowercase 0x-prefixed hex string.`);
+    return normalized;
+};
+const normalizeAddress = (value, field) => {
+    const normalized = value.trim().toLowerCase();
+    if (!ADDRESS_PATTERN.test(normalized))
+        throw new Error(`${field} must be a lowercase 20-byte address.`);
+    return normalized;
+};
+const normalizeHex32 = (value, field) => {
+    const normalized = value.trim().toLowerCase();
+    if (!LOWER_HEX32_PATTERN.test(normalized))
+        throw new Error(`${field} must be a lowercase bytes32 hex string.`);
+    return normalized;
+};
+const normalizeAsciiString = (value, field, maxLen) => {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error(`${field} is required.`);
+    if (trimmed.length > maxLen)
+        throw new Error(`${field} exceeds max length ${maxLen}.`);
+    if (!/^[\x20-\x7E]+$/.test(trimmed))
+        throw new Error(`${field} must be printable ASCII.`);
+    return trimmed;
+};
+const serializeBigIntJson = (value) => JSON.stringify(value, (_key, entryValue) => (typeof entryValue === "bigint" ? entryValue.toString() : entryValue));
+const parseBase64UrlJson = (payload) => {
+    const text = Buffer.from(payload, "base64url").toString("utf8");
+    return JSON.parse(text);
+};
+export const FULFILLMENT_EIP712_TYPES = {
+    FulfillmentTicket: [
+        { name: "ticketId", type: "bytes32" },
+        { name: "consumer", type: "address" },
+        { name: "merchantOwner", type: "address" },
+        { name: "gatewayConfigIdHash", type: "bytes32" },
+        { name: "serviceSlug", type: "string" },
+        { name: "method", type: "string" },
+        { name: "path", type: "string" },
+        { name: "queryHash", type: "bytes32" },
+        { name: "bodyHash", type: "bytes32" },
+        { name: "cost", type: "uint256" },
+        { name: "issuedAt", type: "uint256" },
+        { name: "expiresAt", type: "uint256" },
+    ],
+    FulfillmentDeliveryProof: [
+        { name: "ticketId", type: "bytes32" },
+        { name: "deliveryProofId", type: "bytes32" },
+        { name: "merchantSigner", type: "address" },
+        { name: "serviceSlug", type: "string" },
+        { name: "completedAt", type: "uint256" },
+        { name: "statusCode", type: "uint256" },
+        { name: "latencyMs", type: "uint256" },
+        { name: "responseHash", type: "bytes32" },
+    ],
+    FulfillmentTicketRequestAuth: [
+        { name: "action", type: "string" },
+        { name: "serviceSlug", type: "string" },
+        { name: "method", type: "string" },
+        { name: "path", type: "string" },
+        { name: "queryHash", type: "bytes32" },
+        { name: "bodyHash", type: "bytes32" },
+        { name: "cost", type: "uint256" },
+        { name: "issuedAt", type: "uint256" },
+        { name: "nonce", type: "string" },
+    ],
+};
+export const buildFulfillmentEip712Domain = (chainId = parseFulfillmentChainId(undefined)) => ({
+    name: FULFILLMENT_EIP712_DOMAIN_NAME,
+    version: FULFILLMENT_EIP712_DOMAIN_VERSION,
+    chainId,
+    verifyingContract: FULFILLMENT_EIP712_VERIFIYING_CONTRACT_SENTINEL,
+});
+export const normalizeFulfillmentTicketMessage = (input) => ({
+    ticketId: normalizeHex32(input.ticketId, "ticketId"),
+    consumer: normalizeAddress(input.consumer, "consumer"),
+    merchantOwner: normalizeAddress(input.merchantOwner, "merchantOwner"),
+    gatewayConfigIdHash: normalizeHex32(input.gatewayConfigIdHash, "gatewayConfigIdHash"),
+    serviceSlug: normalizeAsciiString(input.serviceSlug, "serviceSlug", 256),
+    method: normalizeFulfillmentMethod(input.method),
+    path: assertFulfillmentPath(input.path),
+    queryHash: normalizeHex32(input.queryHash, "queryHash"),
+    bodyHash: normalizeHex32(input.bodyHash, "bodyHash"),
+    cost: parseUintLike(input.cost, "cost"),
+    issuedAt: parseUintLike(input.issuedAt, "issuedAt"),
+    expiresAt: parseUintLike(input.expiresAt, "expiresAt"),
+});
+export const normalizeFulfillmentDeliveryProofMessage = (input) => ({
+    ticketId: normalizeHex32(input.ticketId, "ticketId"),
+    deliveryProofId: normalizeHex32(input.deliveryProofId, "deliveryProofId"),
+    merchantSigner: normalizeAddress(input.merchantSigner, "merchantSigner"),
+    serviceSlug: normalizeAsciiString(input.serviceSlug, "serviceSlug", 256),
+    completedAt: parseUintLike(input.completedAt, "completedAt"),
+    statusCode: parseUintLike(input.statusCode, "statusCode"),
+    latencyMs: parseUintLike(input.latencyMs, "latencyMs"),
+    responseHash: input.responseHash == null ? FULFILLMENT_ZERO_HASH_32 : normalizeHex32(input.responseHash, "responseHash"),
+});
+export const normalizeFulfillmentTicketRequestAuthMessage = (input) => ({
+    action: FULFILLMENT_TICKET_REQUEST_ACTION,
+    serviceSlug: normalizeAsciiString(input.serviceSlug, "serviceSlug", 256),
+    method: normalizeFulfillmentMethod(input.method),
+    path: assertFulfillmentPath(input.path),
+    queryHash: normalizeHex32(input.queryHash, "queryHash"),
+    bodyHash: normalizeHex32(input.bodyHash, "bodyHash"),
+    cost: parseUintLike(input.cost, "cost"),
+    issuedAt: parseUintLike(input.issuedAt, "issuedAt"),
+    nonce: normalizeAsciiString(input.nonce, "nonce", 256),
+});
+export const buildFulfillmentTicketTypedData = (message, options) => ({
+    domain: buildFulfillmentEip712Domain(options?.chainId ?? FULFILLMENT_DEFAULT_CHAIN_ID),
+    types: { FulfillmentTicket: FULFILLMENT_EIP712_TYPES.FulfillmentTicket },
+    primaryType: "FulfillmentTicket",
+    message,
+});
+export const buildFulfillmentDeliveryProofTypedData = (message, options) => ({
+    domain: buildFulfillmentEip712Domain(options?.chainId ?? FULFILLMENT_DEFAULT_CHAIN_ID),
+    types: { FulfillmentDeliveryProof: FULFILLMENT_EIP712_TYPES.FulfillmentDeliveryProof },
+    primaryType: "FulfillmentDeliveryProof",
+    message,
+});
+export const buildFulfillmentTicketRequestAuthTypedData = (message, options) => ({
+    domain: buildFulfillmentEip712Domain(options?.chainId ?? FULFILLMENT_DEFAULT_CHAIN_ID),
+    types: { FulfillmentTicketRequestAuth: FULFILLMENT_EIP712_TYPES.FulfillmentTicketRequestAuth },
+    primaryType: "FulfillmentTicketRequestAuth",
+    message,
+});
+export const hashFulfillmentTicketTypedData = (message, options) => hashTypedData(buildFulfillmentTicketTypedData(message, options));
+export const hashFulfillmentDeliveryProofTypedData = (message, options) => hashTypedData(buildFulfillmentDeliveryProofTypedData(message, options));
+export const hashFulfillmentTicketRequestAuthTypedData = (message, options) => hashTypedData(buildFulfillmentTicketRequestAuthTypedData(message, options));
+export const encodeTypedPayloadBase64Url = (payload) => Buffer.from(serializeBigIntJson(payload), "utf8").toString("base64url");
+export const decodeTypedPayloadBase64Url = (encoded) => parseBase64UrlJson(encoded);
+export const buildFulfillmentTicketEnvelope = (payload, signature) => ({
+    version: FULFILLMENT_API_VERSION,
+    payload: encodeTypedPayloadBase64Url(payload),
+    signature: normalizeLowerHex(signature, "ticket.signature"),
+});
+export const buildFulfillmentDeliveryProofEnvelope = (payload, signature) => ({
+    payload: encodeTypedPayloadBase64Url(payload),
+    signature: normalizeLowerHex(signature, "deliveryProof.signature"),
+});
+export const buildFulfillmentTicketHeaders = (input) => {
+    const headers = {
+        [FULFILLMENT_TICKET_HEADER_VERSION]: String(input.ticket.version),
+        [FULFILLMENT_TICKET_HEADER_PAYLOAD]: input.ticket.payload,
+        [FULFILLMENT_TICKET_HEADER_SIGNATURE]: normalizeLowerHex(input.ticket.signature, "ticket.signature"),
+        [FULFILLMENT_TICKET_HEADER_TICKET_ID]: normalizeHex32(input.ticketId, "ticketId"),
+    };
+    const clientRequestId = input.clientRequestId?.trim();
+    if (clientRequestId) {
+        headers[FULFILLMENT_TICKET_HEADER_CLIENT_REQUEST_ID] = clientRequestId;
+    }
+    return headers;
+};
+const getHeaderValue = (headers, key) => {
+    if (typeof headers.get === "function") {
+        return headers.get(key);
+    }
+    const record = headers;
+    const direct = record[key];
+    if (typeof direct === "string")
+        return direct;
+    const fallback = record[key.toLowerCase()];
+    return typeof fallback === "string" ? fallback : null;
+};
+export const parseFulfillmentTicketHeaders = (headers) => {
+    const versionRaw = getHeaderValue(headers, FULFILLMENT_TICKET_HEADER_VERSION)?.trim();
+    const payloadRaw = getHeaderValue(headers, FULFILLMENT_TICKET_HEADER_PAYLOAD)?.trim();
+    const sigRaw = getHeaderValue(headers, FULFILLMENT_TICKET_HEADER_SIGNATURE)?.trim();
+    const ticketIdRaw = getHeaderValue(headers, FULFILLMENT_TICKET_HEADER_TICKET_ID)?.trim();
+    if (!versionRaw || !payloadRaw || !sigRaw || !ticketIdRaw)
+        return null;
+    if (versionRaw !== String(FULFILLMENT_API_VERSION))
+        return null;
+    try {
+        return {
+            ticketId: normalizeHex32(ticketIdRaw, "ticketId"),
+            ticket: {
+                version: FULFILLMENT_API_VERSION,
+                payload: payloadRaw,
+                signature: normalizeLowerHex(sigRaw, "ticket.signature"),
+            },
+            clientRequestId: getHeaderValue(headers, FULFILLMENT_TICKET_HEADER_CLIENT_REQUEST_ID)?.trim() ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+};
+export const redactFulfillmentTicketEnvelopeDebug = (envelope) => ({
+    version: envelope.version,
+    payloadLength: envelope.payload.length,
+    signaturePrefix: envelope.signature.slice(0, 10),
+});
+export const redactFulfillmentDeliveryProofEnvelopeDebug = (envelope) => ({
+    payloadLength: envelope.payload.length,
+    signaturePrefix: envelope.signature.slice(0, 10),
+});
+export const parseWireFulfillmentTicketMessage = (encodedPayload) => {
+    const decoded = decodeTypedPayloadBase64Url(encodedPayload);
+    return normalizeFulfillmentTicketMessage({
+        ticketId: String(decoded.ticketId ?? ""),
+        consumer: String(decoded.consumer ?? ""),
+        merchantOwner: String(decoded.merchantOwner ?? ""),
+        gatewayConfigIdHash: String(decoded.gatewayConfigIdHash ?? ""),
+        serviceSlug: String(decoded.serviceSlug ?? ""),
+        method: String(decoded.method ?? ""),
+        path: String(decoded.path ?? ""),
+        queryHash: String(decoded.queryHash ?? ""),
+        bodyHash: String(decoded.bodyHash ?? ""),
+        cost: decoded.cost,
+        issuedAt: decoded.issuedAt,
+        expiresAt: decoded.expiresAt,
+    });
+};
+export const parseWireFulfillmentDeliveryProofMessage = (encodedPayload) => {
+    const decoded = decodeTypedPayloadBase64Url(encodedPayload);
+    return normalizeFulfillmentDeliveryProofMessage({
+        ticketId: String(decoded.ticketId ?? ""),
+        deliveryProofId: String(decoded.deliveryProofId ?? ""),
+        merchantSigner: String(decoded.merchantSigner ?? ""),
+        serviceSlug: String(decoded.serviceSlug ?? ""),
+        completedAt: decoded.completedAt,
+        statusCode: decoded.statusCode,
+        latencyMs: decoded.latencyMs,
+        responseHash: typeof decoded.responseHash === "string" ? decoded.responseHash : undefined,
+    });
+};
+export const parseWireFulfillmentTicketRequestAuthMessage = (encodedPayload) => {
+    const decoded = decodeTypedPayloadBase64Url(encodedPayload);
+    return normalizeFulfillmentTicketRequestAuthMessage({
+        action: typeof decoded.action === "string" ? decoded.action : undefined,
+        serviceSlug: String(decoded.serviceSlug ?? ""),
+        method: String(decoded.method ?? ""),
+        path: String(decoded.path ?? ""),
+        queryHash: String(decoded.queryHash ?? ""),
+        bodyHash: String(decoded.bodyHash ?? ""),
+        cost: decoded.cost,
+        issuedAt: decoded.issuedAt,
+        nonce: String(decoded.nonce ?? ""),
+    });
+};

package/dist/fulfillment-hash.d.ts

@@ -0,0 +1,20 @@
+import type { Hex32 } from "./fulfillment-types.js";
+export declare class FulfillmentCanonicalizationError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare const FULFILLMENT_ZERO_HASH_32: "0x0000000000000000000000000000000000000000000000000000000000000000";
+export declare const canonicalizeJsonJcs: (value: unknown) => string;
+export declare const sha256HexUtf8: (value: string) => Hex32;
+export declare const hashCanonicalJsonJcs: (value: unknown) => Hex32;
+export type FulfillmentCanonicalQueryPair = {
+    key: string;
+    value: string;
+};
+export declare const canonicalizeFulfillmentQuery: (rawQuery: string | null | undefined) => {
+    canonical: string;
+    pairs: FulfillmentCanonicalQueryPair[];
+};
+export declare const hashCanonicalFulfillmentQuery: (rawQuery: string | null | undefined) => Hex32;
+export declare const hashCanonicalFulfillmentBodyJson: (payload: unknown) => Hex32;
+//# sourceMappingURL=fulfillment-hash.d.ts.map

package/dist/fulfillment-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fulfillment-hash.d.ts","sourceRoot":"","sources":["../src/fulfillment-hash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAEpD,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,IAAI,EAAE,MAAM,CAAC;gBAED,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,eAAO,MAAM,wBAAwB,sEAC0D,CAAC;AAuEhG,eAAO,MAAM,mBAAmB,GAAI,OAAO,OAAO,KAAG,MAAsC,CAAC;AAI5F,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,KAAG,KAAkD,CAAC;AAEjG,eAAO,MAAM,oBAAoB,GAAI,OAAO,OAAO,KAAG,KAAkD,CAAC;AA6BzG,MAAM,MAAM,6BAA6B,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E,eAAO,MAAM,4BAA4B,GACvC,UAAU,MAAM,GAAG,IAAI,GAAG,SAAS,KAClC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,6BAA6B,EAAE,CAAA;CAiD7D,CAAC;AAEF,eAAO,MAAM,6BAA6B,GAAI,UAAU,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,KAGnF,CAAC;AAEF,eAAO,MAAM,gCAAgC,GAAI,SAAS,OAAO,KAAG,KAAsC,CAAC"}