@faremeter/types 0.16.0 → 0.17.1

package/dist/src/x402-adapters.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Shared conversion functions between x402 v1 and v2 protocol types.
+ *
+ * All packages that need to convert between v1 and v2 types should import
+ * from this module to avoid duplicating conversion logic.
+ */
+import type { x402PaymentRequirements as x402PaymentRequirementsV1, x402PaymentPayload as x402PaymentPayloadV1, x402PaymentRequiredResponse as x402PaymentRequiredResponseV1, x402PaymentRequiredResponseLenient, x402VerifyResponse as x402VerifyResponseV1, x402VerifyResponseLenient, x402SettleResponse as x402SettleResponseV1, x402SettleResponseLegacy, x402SettleResponseLenient, x402SupportedKind as x402SupportedKindV1 } from "./x402.js";
+import type { x402PaymentRequirements, x402PaymentPayload, x402PaymentRequiredResponse, x402ResourceInfo, x402VerifyResponse, x402SettleResponse, x402SupportedKind, x402SupportedKindAny } from "./x402v2.js";
+/**
+ * Callback for translating network identifiers between formats.
+ *
+ * For v1→v2 adapters: translates legacy network names to CAIP-2 identifiers.
+ * For v2→v1 adapters: translates CAIP-2 identifiers to legacy network names.
+ *
+ * Returns the translated network identifier, or the input unchanged if
+ * no translation is available.
+ */
+export type NetworkTranslator = (network: string) => string;
+/**
+ * Converts v1 payment requirements to v2 format.
+ *
+ * @param req - The v1 payment requirements
+ * @param translateNetwork - Function to translate legacy network IDs to CAIP-2
+ * @returns The v2 payment requirements
+ */
+export declare function adaptRequirementsV1ToV2(req: x402PaymentRequirementsV1, translateNetwork: NetworkTranslator): x402PaymentRequirements;
+/**
+ * Converts v2 payment requirements to v1 format.
+ *
+ * @param req - The v2 payment requirements
+ * @param resource - Resource information to populate v1 fields
+ * @param translateNetwork - Optional function to translate CAIP-2 to legacy IDs
+ * @returns The v1 payment requirements with mimeType guaranteed
+ */
+export declare function adaptRequirementsV2ToV1(req: x402PaymentRequirements, resource: x402ResourceInfo, translateNetwork?: NetworkTranslator): x402PaymentRequirementsV1 & {
+    mimeType: string;
+};
+/**
+ * Extracts resource information from v1 payment requirements.
+ *
+ * @param req - The v1 payment requirements containing resource fields
+ * @returns The extracted resource information
+ */
+export declare function extractResourceInfoV1(req: x402PaymentRequirementsV1): x402ResourceInfo;
+/**
+ * Converts a v1 payment payload to v2 format.
+ *
+ * @param payload - The v1 payment payload
+ * @param requirements - The v1 requirements used for resource extraction
+ * @param translateNetwork - Function to translate legacy network IDs to CAIP-2
+ * @returns The v2 payment payload
+ */
+export declare function adaptPayloadV1ToV2(payload: x402PaymentPayloadV1, requirements: x402PaymentRequirementsV1, translateNetwork: NetworkTranslator): x402PaymentPayload;
+/**
+ * Converts a v1 payment required response to v2 format.
+ *
+ * @param v1Response - The v1 payment required response
+ * @param resourceURL - The URL of the protected resource
+ * @param translateNetwork - Function to translate legacy network IDs to CAIP-2
+ * @returns The v2 payment required response
+ */
+export declare function adaptPaymentRequiredResponseV1ToV2(v1Response: x402PaymentRequiredResponseLenient, resourceURL: string, translateNetwork: NetworkTranslator): x402PaymentRequiredResponse;
+/**
+ * Converts a v2 payment required response to v1 format.
+ *
+ * @param v2Response - The v2 payment required response
+ * @param translateNetwork - Optional function to translate CAIP-2 to legacy IDs
+ * @returns The v1 payment required response
+ */
+export declare function adaptPaymentRequiredResponseV2ToV1(v2Response: x402PaymentRequiredResponse, translateNetwork?: NetworkTranslator): x402PaymentRequiredResponseV1;
+/**
+ * Converts a v2 verify response to v1 format.
+ *
+ * @param res - The v2 verify response
+ * @returns The v1 verify response
+ */
+export declare function adaptVerifyResponseV2ToV1(res: x402VerifyResponse): x402VerifyResponseV1;
+/**
+ * Converts a v1 verify response to v2 format.
+ *
+ * @param res - The v1 verify response (lenient)
+ * @returns The v2 verify response
+ */
+export declare function adaptVerifyResponseV1ToV2(res: x402VerifyResponseLenient): x402VerifyResponse;
+/**
+ * Adapt v2 settle response to spec-compliant v1 format.
+ * Since v1 spec uses the same field names as v2 (transaction, network, errorReason),
+ * this is primarily a network translation pass.
+ */
+export declare function adaptSettleResponseV2ToV1(res: x402SettleResponse, translateNetwork?: NetworkTranslator): x402SettleResponseV1;
+/**
+ * Adapt v2 settle response to legacy v1 format with old field names.
+ * Use this only for backward compatibility with clients expecting
+ * txHash/networkId/error field names.
+ * @deprecated Prefer adaptSettleResponseV2ToV1 for spec-compliant output
+ */
+export declare function adaptSettleResponseV2ToV1Legacy(res: x402SettleResponse, translateNetwork?: NetworkTranslator): x402SettleResponseLegacy;
+/**
+ * Adapt v1 settle response to v2 format.
+ * Accepts lenient input that may have optional/nullable fields from older handlers.
+ */
+export declare function adaptSettleResponseV1ToV2(res: x402SettleResponseLenient): x402SettleResponse;
+/**
+ * Adapt legacy v1 settle response (with txHash/networkId/error) to v2 format.
+ * Use this when receiving data from older clients that use legacy field names.
+ */
+export declare function adaptSettleResponseLegacyToV2(res: x402SettleResponseLegacy): x402SettleResponse;
+/**
+ * Adapt a lenient v1 settle response (accepting either legacy or spec-compliant
+ * field names) to v2 format. This is the most flexible adapter for parsing
+ * incoming settle responses from unknown sources.
+ */
+export declare function adaptSettleResponseLenientToV2(res: x402SettleResponseLenient): x402SettleResponse;
+/**
+ * Converts a v2 supported kind to v1 format.
+ *
+ * @param kind - The v2 supported kind
+ * @param translateNetwork - Optional function to translate CAIP-2 to legacy IDs
+ * @returns The v1 supported kind
+ */
+export declare function adaptSupportedKindV2ToV1(kind: x402SupportedKind, translateNetwork?: NetworkTranslator): x402SupportedKindAny;
+/**
+ * Converts a v1 supported kind to v2 format.
+ *
+ * @param kind - The v1 supported kind
+ * @param translateNetwork - Function to translate legacy network IDs to CAIP-2
+ * @returns The v2 supported kind
+ */
+export declare function adaptSupportedKindV1ToV2(kind: x402SupportedKindV1, translateNetwork: NetworkTranslator): x402SupportedKind;
+//# sourceMappingURL=x402-adapters.d.ts.map

package/dist/src/x402-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-adapters.d.ts","sourceRoot":"","sources":["../../src/x402-adapters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,uBAAuB,IAAI,yBAAyB,EACpD,kBAAkB,IAAI,oBAAoB,EAC1C,2BAA2B,IAAI,6BAA6B,EAC5D,kCAAkC,EAClC,kBAAkB,IAAI,oBAAoB,EAC1C,yBAAyB,EACzB,kBAAkB,IAAI,oBAAoB,EAC1C,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,IAAI,mBAAmB,EACzC,MAAM,QAAQ,CAAC;AAIhB,OAAO,KAAK,EACV,uBAAuB,EACvB,kBAAkB,EAClB,2BAA2B,EAC3B,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,UAAU,CAAC;AAElB;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,yBAAyB,EAC9B,gBAAgB,EAAE,iBAAiB,GAClC,uBAAuB,CAazB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,uBAAuB,EAC5B,QAAQ,EAAE,gBAAgB,EAC1B,gBAAgB,CAAC,EAAE,iBAAiB,GACnC,yBAAyB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAgBlD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,yBAAyB,GAC7B,gBAAgB,CAWlB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,oBAAoB,EAC7B,YAAY,EAAE,yBAAyB,EACvC,gBAAgB,EAAE,iBAAiB,GAClC,kBAAkB,CAOpB;AAED;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,kCAAkC,EAC9C,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,iBAAiB,GAClC,2BAA2B,CAyB7B;AAED;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,2BAA2B,EACvC,gBAAgB,CAAC,EAAE,iBAAiB,GACnC,6BAA6B,CAQ/B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,kBAAkB,GACtB,oBAAoB,CAStB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,yBAAyB,GAC7B,kBAAkB,CAWpB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,kBAAkB,EACvB,gBAAgB,CAAC,EAAE,iBAAiB,GACnC,oBAAoB,CAWtB;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,GAAG,EAAE,kBAAkB,EACvB,gBAAgB,CAAC,EAAE,iBAAiB,GACnC,wBAAwB,CAa1B;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,yBAAyB,GAC7B,kBAAkB,CAwBpB;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,wBAAwB,GAC5B,kBAAkB,CAqBpB;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,yBAAyB,GAC7B,kBAAkB,CAGpB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,iBAAiB,EACvB,gBAAgB,CAAC,EAAE,iBAAiB,GACnC,oBAAoB,CAUtB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,mBAAmB,EACzB,gBAAgB,EAAE,iBAAiB,GAClC,iBAAiB,CAUnB"}

package/dist/src/x402-adapters.js

@@ -0,0 +1,297 @@
+/**
+ * Shared conversion functions between x402 v1 and v2 protocol types.
+ *
+ * All packages that need to convert between v1 and v2 types should import
+ * from this module to avoid duplicating conversion logic.
+ */
+import { normalizeSettleResponse } from "./x402.js";
+/**
+ * Converts v1 payment requirements to v2 format.
+ *
+ * @param req - The v1 payment requirements
+ * @param translateNetwork - Function to translate legacy network IDs to CAIP-2
+ * @returns The v2 payment requirements
+ */
+export function adaptRequirementsV1ToV2(req, translateNetwork) {
+    const result = {
+        scheme: req.scheme,
+        network: translateNetwork(req.network),
+        amount: req.maxAmountRequired,
+        asset: req.asset,
+        payTo: req.payTo,
+        maxTimeoutSeconds: req.maxTimeoutSeconds,
+    };
+    if (req.extra !== undefined) {
+        result.extra = req.extra;
+    }
+    return result;
+}
+/**
+ * Converts v2 payment requirements to v1 format.
+ *
+ * @param req - The v2 payment requirements
+ * @param resource - Resource information to populate v1 fields
+ * @param translateNetwork - Optional function to translate CAIP-2 to legacy IDs
+ * @returns The v1 payment requirements with mimeType guaranteed
+ */
+export function adaptRequirementsV2ToV1(req, resource, translateNetwork) {
+    const result = {
+        scheme: req.scheme,
+        network: translateNetwork ? translateNetwork(req.network) : req.network,
+        maxAmountRequired: req.amount,
+        resource: resource.url,
+        description: resource.description ?? "",
+        mimeType: resource.mimeType ?? "",
+        payTo: req.payTo,
+        maxTimeoutSeconds: req.maxTimeoutSeconds,
+        asset: req.asset,
+    };
+    if (req.extra !== undefined) {
+        result.extra = req.extra;
+    }
+    return result;
+}
+/**
+ * Extracts resource information from v1 payment requirements.
+ *
+ * @param req - The v1 payment requirements containing resource fields
+ * @returns The extracted resource information
+ */
+export function extractResourceInfoV1(req) {
+    const result = {
+        url: req.resource,
+    };
+    if (req.description) {
+        result.description = req.description;
+    }
+    if (req.mimeType) {
+        result.mimeType = req.mimeType;
+    }
+    return result;
+}
+/**
+ * Converts a v1 payment payload to v2 format.
+ *
+ * @param payload - The v1 payment payload
+ * @param requirements - The v1 requirements used for resource extraction
+ * @param translateNetwork - Function to translate legacy network IDs to CAIP-2
+ * @returns The v2 payment payload
+ */
+export function adaptPayloadV1ToV2(payload, requirements, translateNetwork) {
+    return {
+        x402Version: 2,
+        accepted: adaptRequirementsV1ToV2(requirements, translateNetwork),
+        payload: payload.payload,
+        resource: extractResourceInfoV1(requirements),
+    };
+}
+/**
+ * Converts a v1 payment required response to v2 format.
+ *
+ * @param v1Response - The v1 payment required response
+ * @param resourceURL - The URL of the protected resource
+ * @param translateNetwork - Function to translate legacy network IDs to CAIP-2
+ * @returns The v2 payment required response
+ */
+export function adaptPaymentRequiredResponseV1ToV2(v1Response, resourceURL, translateNetwork) {
+    const firstAccept = v1Response.accepts[0];
+    const resourceInfo = {
+        url: resourceURL,
+    };
+    if (firstAccept?.description) {
+        resourceInfo.description = firstAccept.description;
+    }
+    if (firstAccept?.mimeType) {
+        resourceInfo.mimeType = firstAccept.mimeType;
+    }
+    const result = {
+        x402Version: 2,
+        resource: resourceInfo,
+        accepts: v1Response.accepts.map((req) => adaptRequirementsV1ToV2(req, translateNetwork)),
+    };
+    if (v1Response.error) {
+        result.error = v1Response.error;
+    }
+    return result;
+}
+/**
+ * Converts a v2 payment required response to v1 format.
+ *
+ * @param v2Response - The v2 payment required response
+ * @param translateNetwork - Optional function to translate CAIP-2 to legacy IDs
+ * @returns The v1 payment required response
+ */
+export function adaptPaymentRequiredResponseV2ToV1(v2Response, translateNetwork) {
+    return {
+        x402Version: 1,
+        accepts: v2Response.accepts.map((req) => adaptRequirementsV2ToV1(req, v2Response.resource, translateNetwork)),
+        error: v2Response.error ?? "",
+    };
+}
+/**
+ * Converts a v2 verify response to v1 format.
+ *
+ * @param res - The v2 verify response
+ * @returns The v1 verify response
+ */
+export function adaptVerifyResponseV2ToV1(res) {
+    const result = {
+        isValid: res.isValid,
+        payer: res.payer ?? "",
+    };
+    if (res.invalidReason !== undefined) {
+        result.invalidReason = res.invalidReason;
+    }
+    return result;
+}
+/**
+ * Converts a v1 verify response to v2 format.
+ *
+ * @param res - The v1 verify response (lenient)
+ * @returns The v2 verify response
+ */
+export function adaptVerifyResponseV1ToV2(res) {
+    const result = {
+        isValid: res.isValid,
+    };
+    if (res.invalidReason !== undefined && res.invalidReason !== null) {
+        result.invalidReason = res.invalidReason;
+    }
+    if (res.payer) {
+        result.payer = res.payer;
+    }
+    return result;
+}
+/**
+ * Adapt v2 settle response to spec-compliant v1 format.
+ * Since v1 spec uses the same field names as v2 (transaction, network, errorReason),
+ * this is primarily a network translation pass.
+ */
+export function adaptSettleResponseV2ToV1(res, translateNetwork) {
+    const result = {
+        success: res.success,
+        transaction: res.transaction,
+        network: translateNetwork ? translateNetwork(res.network) : res.network,
+        payer: res.payer ?? "",
+    };
+    if (res.errorReason !== undefined) {
+        result.errorReason = res.errorReason;
+    }
+    return result;
+}
+/**
+ * Adapt v2 settle response to legacy v1 format with old field names.
+ * Use this only for backward compatibility with clients expecting
+ * txHash/networkId/error field names.
+ * @deprecated Prefer adaptSettleResponseV2ToV1 for spec-compliant output
+ */
+export function adaptSettleResponseV2ToV1Legacy(res, translateNetwork) {
+    const result = {
+        success: res.success,
+        txHash: res.transaction,
+        networkId: translateNetwork ? translateNetwork(res.network) : res.network,
+    };
+    if (res.errorReason !== undefined) {
+        result.error = res.errorReason;
+    }
+    if (res.payer !== undefined) {
+        result.payer = res.payer;
+    }
+    return result;
+}
+/**
+ * Adapt v1 settle response to v2 format.
+ * Accepts lenient input that may have optional/nullable fields from older handlers.
+ */
+export function adaptSettleResponseV1ToV2(res) {
+    const network = res.network ?? res.networkId;
+    const transaction = res.transaction ?? res.txHash;
+    if (network == null) {
+        throw new Error("v1 settle response is missing network");
+    }
+    if (res.success && transaction == null) {
+        throw new Error("v1 settle response has success: true but missing transaction");
+    }
+    const result = {
+        success: res.success,
+        transaction: transaction ?? "",
+        network: network,
+    };
+    const errorReason = res.errorReason ?? res.error;
+    if (errorReason !== undefined && errorReason !== null) {
+        result.errorReason = errorReason;
+    }
+    if (res.payer) {
+        result.payer = res.payer;
+    }
+    return result;
+}
+/**
+ * Adapt legacy v1 settle response (with txHash/networkId/error) to v2 format.
+ * Use this when receiving data from older clients that use legacy field names.
+ */
+export function adaptSettleResponseLegacyToV2(res) {
+    if (res.networkId == null) {
+        throw new Error("legacy v1 settle response is missing networkId");
+    }
+    if (res.success && res.txHash == null) {
+        throw new Error("legacy v1 settle response has success: true but missing txHash");
+    }
+    const result = {
+        success: res.success,
+        transaction: res.txHash ?? "",
+        network: res.networkId,
+    };
+    if (res.error !== undefined && res.error !== null) {
+        result.errorReason = res.error;
+    }
+    if (res.payer !== undefined) {
+        result.payer = res.payer;
+    }
+    return result;
+}
+/**
+ * Adapt a lenient v1 settle response (accepting either legacy or spec-compliant
+ * field names) to v2 format. This is the most flexible adapter for parsing
+ * incoming settle responses from unknown sources.
+ */
+export function adaptSettleResponseLenientToV2(res) {
+    const normalized = normalizeSettleResponse(res);
+    return adaptSettleResponseV1ToV2(normalized);
+}
+/**
+ * Converts a v2 supported kind to v1 format.
+ *
+ * @param kind - The v2 supported kind
+ * @param translateNetwork - Optional function to translate CAIP-2 to legacy IDs
+ * @returns The v1 supported kind
+ */
+export function adaptSupportedKindV2ToV1(kind, translateNetwork) {
+    const result = {
+        x402Version: 1,
+        scheme: kind.scheme,
+        network: translateNetwork ? translateNetwork(kind.network) : kind.network,
+    };
+    if (kind.extra !== undefined) {
+        result.extra = kind.extra;
+    }
+    return result;
+}
+/**
+ * Converts a v1 supported kind to v2 format.
+ *
+ * @param kind - The v1 supported kind
+ * @param translateNetwork - Function to translate legacy network IDs to CAIP-2
+ * @returns The v2 supported kind
+ */
+export function adaptSupportedKindV1ToV2(kind, translateNetwork) {
+    const result = {
+        x402Version: 2,
+        scheme: kind.scheme,
+        network: translateNetwork(kind.network),
+    };
+    if (kind.extra !== undefined) {
+        result.extra = kind.extra;
+    }
+    return result;
+}

package/dist/src/x402-adapters.test.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env pnpm tsx
+export {};
+//# sourceMappingURL=x402-adapters.test.d.ts.map

package/dist/src/x402-adapters.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-adapters.test.d.ts","sourceRoot":"","sources":["../../src/x402-adapters.test.ts"],"names":[],"mappings":""}