@tokenbuddy/contracts 1.0.0

package/dist/src/crypto.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Encrypt a plaintext string using SM4-ECB with PKCS7 padding.
+ * Returns the ciphertext encoded as a base64 string.
+ */
+export declare function encryptSm4EcbPkcs7Base64(plaintext: string, sm4KeyBase64: string): string;
+/**
+ * Decrypt a base64 ciphertext string using SM4-ECB with PKCS7 padding.
+ * Returns the decrypted plaintext string.
+ */
+export declare function decryptSm4EcbPkcs7Base64(encryptedBase64: string, sm4KeyBase64: string): string;
+/**
+ * Compute md5 hex digest of a string (indicator).
+ */
+export declare function computeIndicator(slug: string): string;
+/**
+ * Generate a 32-character lowercase hex string as orderNo (UUID v4 without dashes).
+ */
+export declare function generateOrderNo(): string;
+/**
+ * Encrypt Clawtip order data: {"orderNo":..., "amount":..., "payTo":...}
+ * Returns the base64 encrypted data.
+ */
+export declare function encryptClawtipOrderData(orderNo: string, amount: number, payTo: string, sm4KeyBase64: string): string;
+export interface ClawtipPaymentParams {
+    orderNo: string;
+    amountFen: number;
+    payTo: string;
+    encryptedData: string;
+    indicator: string;
+    slug: string;
+    skillId: string;
+    description: string;
+    resourceUrl: string;
+}
+export interface ClawtipPaymentParamsInput {
+    payTo: string;
+    sm4KeyBase64: string;
+    skillSlug: string;
+    skillId: string;
+    description: string;
+    resourceUrl: string;
+    amountFen: number;
+}
+export declare function buildClawtipPaymentParams(input: ClawtipPaymentParamsInput): ClawtipPaymentParams;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/src/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/crypto.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAWxF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAU9F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GACnB,MAAM,CAOR;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,yBAAyB,GAAG,oBAAoB,CAiBhG"}

package/dist/src/crypto.js

@@ -0,0 +1,129 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encryptSm4EcbPkcs7Base64 = encryptSm4EcbPkcs7Base64;
+exports.decryptSm4EcbPkcs7Base64 = decryptSm4EcbPkcs7Base64;
+exports.computeIndicator = computeIndicator;
+exports.generateOrderNo = generateOrderNo;
+exports.encryptClawtipOrderData = encryptClawtipOrderData;
+exports.buildClawtipPaymentParams = buildClawtipPaymentParams;
+const crypto = __importStar(require("crypto"));
+const uuid_1 = require("uuid");
+/**
+ * Decode a base64 SM4 key to a 16-byte Buffer.
+ * Throws an error if the decoded key is not exactly 16 bytes.
+ */
+function decodeSm4Key(sm4KeyBase64) {
+    const key = Buffer.from(sm4KeyBase64, "base64");
+    if (key.length !== 16) {
+        throw new Error(`SM4 key must decode to 16 bytes, got ${key.length}`);
+    }
+    return key;
+}
+/**
+ * Encrypt a plaintext string using SM4-ECB with PKCS7 padding.
+ * Returns the ciphertext encoded as a base64 string.
+ */
+function encryptSm4EcbPkcs7Base64(plaintext, sm4KeyBase64) {
+    try {
+        const key = decodeSm4Key(sm4KeyBase64);
+        // Node.js crypto uses 'sm4-ecb' which defaults to PKCS7 padding for ECB
+        const cipher = crypto.createCipheriv("sm4-ecb", key, null);
+        let encrypted = cipher.update(plaintext, "utf8", "base64");
+        encrypted += cipher.final("base64");
+        return encrypted;
+    }
+    catch (error) {
+        throw new Error(`SM4 encryption failed: ${error.message}`);
+    }
+}
+/**
+ * Decrypt a base64 ciphertext string using SM4-ECB with PKCS7 padding.
+ * Returns the decrypted plaintext string.
+ */
+function decryptSm4EcbPkcs7Base64(encryptedBase64, sm4KeyBase64) {
+    try {
+        const key = decodeSm4Key(sm4KeyBase64);
+        const decipher = crypto.createDecipheriv("sm4-ecb", key, null);
+        let decrypted = decipher.update(encryptedBase64, "base64", "utf8");
+        decrypted += decipher.final("utf8");
+        return decrypted;
+    }
+    catch (error) {
+        throw new Error(`SM4 decryption failed: ${error.message}`);
+    }
+}
+/**
+ * Compute md5 hex digest of a string (indicator).
+ */
+function computeIndicator(slug) {
+    return crypto.createHash("md5").update(slug, "utf8").digest("hex");
+}
+/**
+ * Generate a 32-character lowercase hex string as orderNo (UUID v4 without dashes).
+ */
+function generateOrderNo() {
+    return (0, uuid_1.v4)().replace(/-/g, "");
+}
+/**
+ * Encrypt Clawtip order data: {"orderNo":..., "amount":..., "payTo":...}
+ * Returns the base64 encrypted data.
+ */
+function encryptClawtipOrderData(orderNo, amount, payTo, sm4KeyBase64) {
+    const plaintext = JSON.stringify({
+        orderNo,
+        amount,
+        payTo
+    });
+    return encryptSm4EcbPkcs7Base64(plaintext, sm4KeyBase64);
+}
+function buildClawtipPaymentParams(input) {
+    if (!Number.isInteger(input.amountFen) || input.amountFen < 1) {
+        throw new Error("amount_fen must be greater than zero");
+    }
+    const orderNo = generateOrderNo();
+    return {
+        orderNo,
+        amountFen: input.amountFen,
+        payTo: input.payTo,
+        encryptedData: encryptClawtipOrderData(orderNo, input.amountFen, input.payTo, input.sm4KeyBase64),
+        indicator: computeIndicator(input.skillSlug),
+        slug: input.skillSlug,
+        skillId: input.skillId,
+        description: input.description,
+        resourceUrl: input.resourceUrl
+    };
+}
+//# sourceMappingURL=crypto.js.map

package/dist/src/crypto.js.map

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

package/dist/src/errors.d.ts

@@ -0,0 +1,47 @@
+export declare enum RetryClass {
+    FailClosed = "fail_closed",
+    RetryableWithBackoff = "retryable_with_backoff",
+    NotRetryable = "not_retryable"
+}
+export declare enum ErrorCode {
+    BusyCapacity = "busy_capacity",
+    PaymentRequired = "payment_required",
+    PaymentAccountInsufficient = "payment_account_insufficient",
+    PaymentMethodNotReady = "payment_method_not_ready",
+    PaymentAuthorizationRequired = "payment_authorization_required",
+    PaymentCancelled = "payment_cancelled",
+    PaymentTimeout = "payment_timeout",
+    PaymentProviderFailed = "payment_provider_failed",
+    InvalidPurchaseRequest = "invalid_purchase_request",
+    ClawtipCredentialInvalid = "clawtip_credential_invalid",
+    ClawtipOrderMismatch = "clawtip_order_mismatch",
+    InsufficientFunds = "insufficient_funds",
+    InvalidOrExpiredToken = "invalid_or_expired_token",
+    TokenClassRevoked = "token_class_revoked",
+    RequestIdRequired = "request_id_required",
+    StreamingNotSupported = "streaming_not_supported",
+    IdempotencyConflict = "idempotency_conflict",
+    PurchaseNotFound = "purchase_not_found",
+    RequestNotFound = "request_not_found",
+    ModelNotAvailable = "model_not_available",
+    UpstreamNotConfigured = "upstream_not_configured",
+    ProtocolNotAvailable = "protocol_not_available",
+    LedgerFailClosed = "ledger_fail_closed",
+    UpstreamTimeout = "upstream_timeout",
+    ContractVersionDrift = "contract_version_drift"
+}
+export declare function getRetryClass(code: ErrorCode): RetryClass;
+export declare function getHttpStatus(code: ErrorCode): number;
+export declare function getDefaultMessage(code: ErrorCode): string;
+export interface ErrorBody {
+    code: ErrorCode;
+    retryClass: RetryClass;
+    message: string;
+    httpStatus: number;
+    retryAfterSeconds?: number;
+}
+export interface ErrorEnvelope {
+    error: ErrorBody;
+}
+export declare function createErrorEnvelope(code: ErrorCode, message?: string, retryAfterSeconds?: number): ErrorEnvelope;
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,oBAAY,UAAU;IACpB,UAAU,gBAAgB;IAC1B,oBAAoB,2BAA2B;IAC/C,YAAY,kBAAkB;CAC/B;AAED,oBAAY,SAAS;IACnB,YAAY,kBAAkB;IAC9B,eAAe,qBAAqB;IACpC,0BAA0B,iCAAiC;IAC3D,qBAAqB,6BAA6B;IAClD,4BAA4B,mCAAmC;IAC/D,gBAAgB,sBAAsB;IACtC,cAAc,oBAAoB;IAClC,qBAAqB,4BAA4B;IACjD,sBAAsB,6BAA6B;IACnD,wBAAwB,+BAA+B;IACvD,oBAAoB,2BAA2B;IAC/C,iBAAiB,uBAAuB;IACxC,qBAAqB,6BAA6B;IAClD,iBAAiB,wBAAwB;IACzC,iBAAiB,wBAAwB;IACzC,qBAAqB,4BAA4B;IACjD,mBAAmB,yBAAyB;IAC5C,gBAAgB,uBAAuB;IACvC,eAAe,sBAAsB;IACrC,iBAAiB,wBAAwB;IACzC,qBAAqB,4BAA4B;IACjD,oBAAoB,2BAA2B;IAC/C,gBAAgB,uBAAuB;IACvC,eAAe,qBAAqB;IACpC,oBAAoB,2BAA2B;CAChD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,CAYzD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAuCrD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAuDzD;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,EACf,OAAO,CAAC,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,MAAM,GACzB,aAAa,CAUf"}

package/dist/src/errors.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCode = exports.RetryClass = void 0;
+exports.getRetryClass = getRetryClass;
+exports.getHttpStatus = getHttpStatus;
+exports.getDefaultMessage = getDefaultMessage;
+exports.createErrorEnvelope = createErrorEnvelope;
+var RetryClass;
+(function (RetryClass) {
+    RetryClass["FailClosed"] = "fail_closed";
+    RetryClass["RetryableWithBackoff"] = "retryable_with_backoff";
+    RetryClass["NotRetryable"] = "not_retryable";
+})(RetryClass || (exports.RetryClass = RetryClass = {}));
+var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["BusyCapacity"] = "busy_capacity";
+    ErrorCode["PaymentRequired"] = "payment_required";
+    ErrorCode["PaymentAccountInsufficient"] = "payment_account_insufficient";
+    ErrorCode["PaymentMethodNotReady"] = "payment_method_not_ready";
+    ErrorCode["PaymentAuthorizationRequired"] = "payment_authorization_required";
+    ErrorCode["PaymentCancelled"] = "payment_cancelled";
+    ErrorCode["PaymentTimeout"] = "payment_timeout";
+    ErrorCode["PaymentProviderFailed"] = "payment_provider_failed";
+    ErrorCode["InvalidPurchaseRequest"] = "invalid_purchase_request";
+    ErrorCode["ClawtipCredentialInvalid"] = "clawtip_credential_invalid";
+    ErrorCode["ClawtipOrderMismatch"] = "clawtip_order_mismatch";
+    ErrorCode["InsufficientFunds"] = "insufficient_funds";
+    ErrorCode["InvalidOrExpiredToken"] = "invalid_or_expired_token";
+    ErrorCode["TokenClassRevoked"] = "token_class_revoked";
+    ErrorCode["RequestIdRequired"] = "request_id_required";
+    ErrorCode["StreamingNotSupported"] = "streaming_not_supported";
+    ErrorCode["IdempotencyConflict"] = "idempotency_conflict";
+    ErrorCode["PurchaseNotFound"] = "purchase_not_found";
+    ErrorCode["RequestNotFound"] = "request_not_found";
+    ErrorCode["ModelNotAvailable"] = "model_not_available";
+    ErrorCode["UpstreamNotConfigured"] = "upstream_not_configured";
+    ErrorCode["ProtocolNotAvailable"] = "protocol_not_available";
+    ErrorCode["LedgerFailClosed"] = "ledger_fail_closed";
+    ErrorCode["UpstreamTimeout"] = "upstream_timeout";
+    ErrorCode["ContractVersionDrift"] = "contract_version_drift";
+})(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
+function getRetryClass(code) {
+    switch (code) {
+        case ErrorCode.BusyCapacity:
+        case ErrorCode.UpstreamTimeout:
+            return RetryClass.RetryableWithBackoff;
+        case ErrorCode.LedgerFailClosed:
+        case ErrorCode.ClawtipCredentialInvalid:
+        case ErrorCode.ClawtipOrderMismatch:
+            return RetryClass.FailClosed;
+        default:
+            return RetryClass.NotRetryable;
+    }
+}
+function getHttpStatus(code) {
+    switch (code) {
+        case ErrorCode.BusyCapacity:
+            return 429;
+        case ErrorCode.PaymentRequired:
+        case ErrorCode.PaymentAccountInsufficient:
+        case ErrorCode.PaymentMethodNotReady:
+        case ErrorCode.PaymentAuthorizationRequired:
+        case ErrorCode.PaymentCancelled:
+        case ErrorCode.PaymentTimeout:
+        case ErrorCode.PaymentProviderFailed:
+        case ErrorCode.ClawtipCredentialInvalid:
+        case ErrorCode.ClawtipOrderMismatch:
+        case ErrorCode.InsufficientFunds:
+            return 402;
+        case ErrorCode.InvalidPurchaseRequest:
+            return 400;
+        case ErrorCode.InvalidOrExpiredToken:
+        case ErrorCode.TokenClassRevoked:
+            return 401;
+        case ErrorCode.RequestIdRequired:
+        case ErrorCode.StreamingNotSupported:
+        case ErrorCode.ModelNotAvailable:
+        case ErrorCode.UpstreamNotConfigured:
+        case ErrorCode.ProtocolNotAvailable:
+        case ErrorCode.ContractVersionDrift:
+            return 400;
+        case ErrorCode.IdempotencyConflict:
+            return 409;
+        case ErrorCode.PurchaseNotFound:
+        case ErrorCode.RequestNotFound:
+            return 404;
+        case ErrorCode.LedgerFailClosed:
+            return 500;
+        case ErrorCode.UpstreamTimeout:
+            return 504;
+        default:
+            return 500;
+    }
+}
+function getDefaultMessage(code) {
+    switch (code) {
+        case ErrorCode.BusyCapacity:
+            return "Seller capacity is currently exhausted.";
+        case ErrorCode.PaymentRequired:
+            return "Additional credit is required before this operation can proceed.";
+        case ErrorCode.PaymentAccountInsufficient:
+            return "Payment account balance is insufficient. Add funds to the selected payment method and retry.";
+        case ErrorCode.PaymentMethodNotReady:
+            return "Selected payment method is not ready. Configure or enable a payment method and retry.";
+        case ErrorCode.PaymentAuthorizationRequired:
+            return "Selected payment method requires authorization before payment can proceed.";
+        case ErrorCode.PaymentCancelled:
+            return "Payment was cancelled before completion.";
+        case ErrorCode.PaymentTimeout:
+            return "Payment did not complete before the timeout.";
+        case ErrorCode.PaymentProviderFailed:
+            return "Selected payment provider could not complete the payment.";
+        case ErrorCode.ClawtipCredentialInvalid:
+            return "Clawtip payment credential is invalid.";
+        case ErrorCode.InvalidPurchaseRequest:
+            return "Purchase request is invalid.";
+        case ErrorCode.ClawtipOrderMismatch:
+            return "Clawtip payment does not match the expected order.";
+        case ErrorCode.InsufficientFunds:
+            return "Purchase balance is exhausted.";
+        case ErrorCode.InvalidOrExpiredToken:
+            return "Bearer token is invalid or expired.";
+        case ErrorCode.TokenClassRevoked:
+            return "Token class has been revoked by seller operator.";
+        case ErrorCode.RequestIdRequired:
+            return "Chat requests must include requestId.";
+        case ErrorCode.StreamingNotSupported:
+            return "Streaming responses are not supported in P0.";
+        case ErrorCode.IdempotencyConflict:
+            return "Idempotency key was reused with a different request payload.";
+        case ErrorCode.PurchaseNotFound:
+            return "Purchase could not be found.";
+        case ErrorCode.RequestNotFound:
+            return "Request could not be found.";
+        case ErrorCode.ModelNotAvailable:
+            return "Requested model is not available on this seller.";
+        case ErrorCode.UpstreamNotConfigured:
+            return "Seller upstream is not configured. Ask the seller operator to configure upstreams.";
+        case ErrorCode.ProtocolNotAvailable:
+            return "Requested protocol is not available for this seller upstream.";
+        case ErrorCode.LedgerFailClosed:
+            return "Ledger entered fail-closed mode.";
+        case ErrorCode.UpstreamTimeout:
+            return "Upstream model request timed out.";
+        case ErrorCode.ContractVersionDrift:
+            return "Contract version drift detected.";
+        default:
+            return "An unknown error occurred.";
+    }
+}
+function createErrorEnvelope(code, message, retryAfterSeconds) {
+    return {
+        error: {
+            code,
+            retryClass: getRetryClass(code),
+            message: message || getDefaultMessage(code),
+            httpStatus: getHttpStatus(code),
+            ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {})
+        }
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./errors.js";
+export * from "./crypto.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./crypto.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,8CAA4B"}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@tokenbuddy/contracts",
+  "version": "1.0.0",
+  "description": "Shared contract models and crypto functions",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "private": false,
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/uuid": "^9.0.8"
+  }
+}

package/src/crypto.ts

@@ -0,0 +1,120 @@
+import * as crypto from "crypto";
+import { v4 as uuidv4 } from "uuid";
+
+/**
+ * Decode a base64 SM4 key to a 16-byte Buffer.
+ * Throws an error if the decoded key is not exactly 16 bytes.
+ */
+function decodeSm4Key(sm4KeyBase64: string): Buffer {
+  const key = Buffer.from(sm4KeyBase64, "base64");
+  if (key.length !== 16) {
+    throw new Error(`SM4 key must decode to 16 bytes, got ${key.length}`);
+  }
+  return key;
+}
+
+/**
+ * Encrypt a plaintext string using SM4-ECB with PKCS7 padding.
+ * Returns the ciphertext encoded as a base64 string.
+ */
+export function encryptSm4EcbPkcs7Base64(plaintext: string, sm4KeyBase64: string): string {
+  try {
+    const key = decodeSm4Key(sm4KeyBase64);
+    // Node.js crypto uses 'sm4-ecb' which defaults to PKCS7 padding for ECB
+    const cipher = crypto.createCipheriv("sm4-ecb", key, null);
+    let encrypted = cipher.update(plaintext, "utf8", "base64");
+    encrypted += cipher.final("base64");
+    return encrypted;
+  } catch (error: any) {
+    throw new Error(`SM4 encryption failed: ${error.message}`);
+  }
+}
+
+/**
+ * Decrypt a base64 ciphertext string using SM4-ECB with PKCS7 padding.
+ * Returns the decrypted plaintext string.
+ */
+export function decryptSm4EcbPkcs7Base64(encryptedBase64: string, sm4KeyBase64: string): string {
+  try {
+    const key = decodeSm4Key(sm4KeyBase64);
+    const decipher = crypto.createDecipheriv("sm4-ecb", key, null);
+    let decrypted = decipher.update(encryptedBase64, "base64", "utf8");
+    decrypted += decipher.final("utf8");
+    return decrypted;
+  } catch (error: any) {
+    throw new Error(`SM4 decryption failed: ${error.message}`);
+  }
+}
+
+/**
+ * Compute md5 hex digest of a string (indicator).
+ */
+export function computeIndicator(slug: string): string {
+  return crypto.createHash("md5").update(slug, "utf8").digest("hex");
+}
+
+/**
+ * Generate a 32-character lowercase hex string as orderNo (UUID v4 without dashes).
+ */
+export function generateOrderNo(): string {
+  return uuidv4().replace(/-/g, "");
+}
+
+/**
+ * Encrypt Clawtip order data: {"orderNo":..., "amount":..., "payTo":...}
+ * Returns the base64 encrypted data.
+ */
+export function encryptClawtipOrderData(
+  orderNo: string,
+  amount: number,
+  payTo: string,
+  sm4KeyBase64: string
+): string {
+  const plaintext = JSON.stringify({
+    orderNo,
+    amount,
+    payTo
+  });
+  return encryptSm4EcbPkcs7Base64(plaintext, sm4KeyBase64);
+}
+
+export interface ClawtipPaymentParams {
+  orderNo: string;
+  amountFen: number;
+  payTo: string;
+  encryptedData: string;
+  indicator: string;
+  slug: string;
+  skillId: string;
+  description: string;
+  resourceUrl: string;
+}
+
+export interface ClawtipPaymentParamsInput {
+  payTo: string;
+  sm4KeyBase64: string;
+  skillSlug: string;
+  skillId: string;
+  description: string;
+  resourceUrl: string;
+  amountFen: number;
+}
+
+export function buildClawtipPaymentParams(input: ClawtipPaymentParamsInput): ClawtipPaymentParams {
+  if (!Number.isInteger(input.amountFen) || input.amountFen < 1) {
+    throw new Error("amount_fen must be greater than zero");
+  }
+
+  const orderNo = generateOrderNo();
+  return {
+    orderNo,
+    amountFen: input.amountFen,
+    payTo: input.payTo,
+    encryptedData: encryptClawtipOrderData(orderNo, input.amountFen, input.payTo, input.sm4KeyBase64),
+    indicator: computeIndicator(input.skillSlug),
+    slug: input.skillSlug,
+    skillId: input.skillId,
+    description: input.description,
+    resourceUrl: input.resourceUrl
+  };
+}

package/src/errors.ts

@@ -0,0 +1,173 @@
+export enum RetryClass {
+  FailClosed = "fail_closed",
+  RetryableWithBackoff = "retryable_with_backoff",
+  NotRetryable = "not_retryable"
+}
+
+export enum ErrorCode {
+  BusyCapacity = "busy_capacity",
+  PaymentRequired = "payment_required",
+  PaymentAccountInsufficient = "payment_account_insufficient",
+  PaymentMethodNotReady = "payment_method_not_ready",
+  PaymentAuthorizationRequired = "payment_authorization_required",
+  PaymentCancelled = "payment_cancelled",
+  PaymentTimeout = "payment_timeout",
+  PaymentProviderFailed = "payment_provider_failed",
+  InvalidPurchaseRequest = "invalid_purchase_request",
+  ClawtipCredentialInvalid = "clawtip_credential_invalid",
+  ClawtipOrderMismatch = "clawtip_order_mismatch",
+  InsufficientFunds = "insufficient_funds",
+  InvalidOrExpiredToken = "invalid_or_expired_token",
+  TokenClassRevoked = "token_class_revoked",
+  RequestIdRequired = "request_id_required",
+  StreamingNotSupported = "streaming_not_supported",
+  IdempotencyConflict = "idempotency_conflict",
+  PurchaseNotFound = "purchase_not_found",
+  RequestNotFound = "request_not_found",
+  ModelNotAvailable = "model_not_available",
+  UpstreamNotConfigured = "upstream_not_configured",
+  ProtocolNotAvailable = "protocol_not_available",
+  LedgerFailClosed = "ledger_fail_closed",
+  UpstreamTimeout = "upstream_timeout",
+  ContractVersionDrift = "contract_version_drift"
+}
+
+export function getRetryClass(code: ErrorCode): RetryClass {
+  switch (code) {
+    case ErrorCode.BusyCapacity:
+    case ErrorCode.UpstreamTimeout:
+      return RetryClass.RetryableWithBackoff;
+    case ErrorCode.LedgerFailClosed:
+    case ErrorCode.ClawtipCredentialInvalid:
+    case ErrorCode.ClawtipOrderMismatch:
+      return RetryClass.FailClosed;
+    default:
+      return RetryClass.NotRetryable;
+  }
+}
+
+export function getHttpStatus(code: ErrorCode): number {
+  switch (code) {
+    case ErrorCode.BusyCapacity:
+      return 429;
+    case ErrorCode.PaymentRequired:
+    case ErrorCode.PaymentAccountInsufficient:
+    case ErrorCode.PaymentMethodNotReady:
+    case ErrorCode.PaymentAuthorizationRequired:
+    case ErrorCode.PaymentCancelled:
+    case ErrorCode.PaymentTimeout:
+    case ErrorCode.PaymentProviderFailed:
+    case ErrorCode.ClawtipCredentialInvalid:
+    case ErrorCode.ClawtipOrderMismatch:
+    case ErrorCode.InsufficientFunds:
+      return 402;
+    case ErrorCode.InvalidPurchaseRequest:
+      return 400;
+    case ErrorCode.InvalidOrExpiredToken:
+    case ErrorCode.TokenClassRevoked:
+      return 401;
+    case ErrorCode.RequestIdRequired:
+    case ErrorCode.StreamingNotSupported:
+    case ErrorCode.ModelNotAvailable:
+    case ErrorCode.UpstreamNotConfigured:
+    case ErrorCode.ProtocolNotAvailable:
+    case ErrorCode.ContractVersionDrift:
+      return 400;
+    case ErrorCode.IdempotencyConflict:
+      return 409;
+    case ErrorCode.PurchaseNotFound:
+    case ErrorCode.RequestNotFound:
+      return 404;
+    case ErrorCode.LedgerFailClosed:
+      return 500;
+    case ErrorCode.UpstreamTimeout:
+      return 504;
+    default:
+      return 500;
+  }
+}
+
+export function getDefaultMessage(code: ErrorCode): string {
+  switch (code) {
+    case ErrorCode.BusyCapacity:
+      return "Seller capacity is currently exhausted.";
+    case ErrorCode.PaymentRequired:
+      return "Additional credit is required before this operation can proceed.";
+    case ErrorCode.PaymentAccountInsufficient:
+      return "Payment account balance is insufficient. Add funds to the selected payment method and retry.";
+    case ErrorCode.PaymentMethodNotReady:
+      return "Selected payment method is not ready. Configure or enable a payment method and retry.";
+    case ErrorCode.PaymentAuthorizationRequired:
+      return "Selected payment method requires authorization before payment can proceed.";
+    case ErrorCode.PaymentCancelled:
+      return "Payment was cancelled before completion.";
+    case ErrorCode.PaymentTimeout:
+      return "Payment did not complete before the timeout.";
+    case ErrorCode.PaymentProviderFailed:
+      return "Selected payment provider could not complete the payment.";
+    case ErrorCode.ClawtipCredentialInvalid:
+      return "Clawtip payment credential is invalid.";
+    case ErrorCode.InvalidPurchaseRequest:
+      return "Purchase request is invalid.";
+    case ErrorCode.ClawtipOrderMismatch:
+      return "Clawtip payment does not match the expected order.";
+    case ErrorCode.InsufficientFunds:
+      return "Purchase balance is exhausted.";
+    case ErrorCode.InvalidOrExpiredToken:
+      return "Bearer token is invalid or expired.";
+    case ErrorCode.TokenClassRevoked:
+      return "Token class has been revoked by seller operator.";
+    case ErrorCode.RequestIdRequired:
+      return "Chat requests must include requestId.";
+    case ErrorCode.StreamingNotSupported:
+      return "Streaming responses are not supported in P0.";
+    case ErrorCode.IdempotencyConflict:
+      return "Idempotency key was reused with a different request payload.";
+    case ErrorCode.PurchaseNotFound:
+      return "Purchase could not be found.";
+    case ErrorCode.RequestNotFound:
+      return "Request could not be found.";
+    case ErrorCode.ModelNotAvailable:
+      return "Requested model is not available on this seller.";
+    case ErrorCode.UpstreamNotConfigured:
+      return "Seller upstream is not configured. Ask the seller operator to configure upstreams.";
+    case ErrorCode.ProtocolNotAvailable:
+      return "Requested protocol is not available for this seller upstream.";
+    case ErrorCode.LedgerFailClosed:
+      return "Ledger entered fail-closed mode.";
+    case ErrorCode.UpstreamTimeout:
+      return "Upstream model request timed out.";
+    case ErrorCode.ContractVersionDrift:
+      return "Contract version drift detected.";
+    default:
+      return "An unknown error occurred.";
+  }
+}
+
+export interface ErrorBody {
+  code: ErrorCode;
+  retryClass: RetryClass;
+  message: string;
+  httpStatus: number;
+  retryAfterSeconds?: number;
+}
+
+export interface ErrorEnvelope {
+  error: ErrorBody;
+}
+
+export function createErrorEnvelope(
+  code: ErrorCode,
+  message?: string,
+  retryAfterSeconds?: number
+): ErrorEnvelope {
+  return {
+    error: {
+      code,
+      retryClass: getRetryClass(code),
+      message: message || getDefaultMessage(code),
+      httpStatus: getHttpStatus(code),
+      ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {})
+    }
+  };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./errors.js";
+export * from "./crypto.js";

package/tests/crypto.test.ts

@@ -0,0 +1,91 @@
+import {
+  encryptSm4EcbPkcs7Base64,
+  decryptSm4EcbPkcs7Base64,
+  computeIndicator,
+  generateOrderNo,
+  encryptClawtipOrderData,
+  buildClawtipPaymentParams
+} from "../src/crypto.js";
+
+// base64("0123456789ABCDEF") — exactly 16 bytes
+const KEY = "MDEyMzQ1Njc4OUFCQ0RFRg==";
+
+describe("SM4 Cryptography and Helpers Tests", () => {
+  test("sm4 ecb pkcs7 roundtrip", () => {
+    const plaintext = '{"orderNo":"abc123","amount":100,"payTo":"payto-test"}';
+    const encrypted = encryptSm4EcbPkcs7Base64(plaintext, KEY);
+    const decrypted = decryptSm4EcbPkcs7Base64(encrypted, KEY);
+    
+    expect(encrypted).not.toBe(plaintext);
+    expect(decrypted).toBe(plaintext);
+  });
+
+  test("sm4 invalid base64 key throws error", () => {
+    expect(() => {
+      encryptSm4EcbPkcs7Base64("hello", "!!!not-base64!!!");
+    }).toThrow();
+  });
+
+  test("sm4 short key throws error", () => {
+    // base64("short") = 8 bytes
+    expect(() => {
+      encryptSm4EcbPkcs7Base64("hello", "c2hvcnQ=");
+    }).toThrow("16 bytes");
+  });
+
+  test("compute_indicator is md5 hex of slug", () => {
+    // echo -n "test" | md5sum => 098f6bcd4621d373cade4e832627b4f6
+    expect(computeIndicator("test")).toBe("098f6bcd4621d373cade4e832627b4f6");
+  });
+
+  test("generate_order_no is 32 lowercase hex chars", () => {
+    const no = generateOrderNo();
+    expect(no.length).toBe(32);
+    expect(/^[0-9a-f]{32}$/.test(no)).toBe(true);
+  });
+
+  test("encryptClawtipOrderData produces valid json after decrypt", () => {
+    const enc = encryptClawtipOrderData("ord001", 500, "pay-to-addr", KEY);
+    const dec = decryptSm4EcbPkcs7Base64(enc, KEY);
+    const val = JSON.parse(dec);
+    expect(val.orderNo).toBe("ord001");
+    expect(val.amount).toBe(500);
+    expect(val.payTo).toBe("pay-to-addr");
+  });
+
+  test("buildClawtipPaymentParams produces the shared wallet bootstrap shape", () => {
+    const params = buildClawtipPaymentParams({
+      payTo: "pay-to-addr",
+      sm4KeyBase64: KEY,
+      skillSlug: "tb-wallet-bootstrap",
+      skillId: "si-tb-wallet-bootstrap",
+      description: "Activate",
+      resourceUrl: "https://example.com",
+      amountFen: 1
+    });
+
+    expect(params.amountFen).toBe(1);
+    expect(params.payTo).toBe("pay-to-addr");
+    expect(params.slug).toBe("tb-wallet-bootstrap");
+    expect(params.skillId).toBe("si-tb-wallet-bootstrap");
+    expect(params.orderNo).toMatch(/^[0-9a-f]{32}$/);
+    expect(params.indicator).toBe(computeIndicator("tb-wallet-bootstrap"));
+
+    const decoded = JSON.parse(decryptSm4EcbPkcs7Base64(params.encryptedData, KEY));
+    expect(decoded.orderNo).toBe(params.orderNo);
+    expect(decoded.amount).toBe(1);
+    expect(decoded.payTo).toBe("pay-to-addr");
+  });
+
+  test("buildClawtipPaymentParams rejects non-positive amountFen", () => {
+    expect(() => buildClawtipPaymentParams({
+      payTo: "pay-to-addr",
+      sm4KeyBase64: KEY,
+      skillSlug: "tb-wallet-bootstrap",
+      skillId: "si-tb-wallet-bootstrap",
+      description: "Activate",
+      resourceUrl: "https://example.com",
+      amountFen: 0
+    })).toThrow("amount_fen");
+  });
+});

package/tests/errors.test.ts

@@ -0,0 +1,34 @@
+import {
+  ErrorCode,
+  RetryClass,
+  getRetryClass,
+  getHttpStatus,
+  getDefaultMessage,
+  createErrorEnvelope
+} from "../src/errors.js";
+
+describe("ErrorCode and RetryClass Mapping Tests", () => {
+  test("retry class maps correctly", () => {
+    expect(getRetryClass(ErrorCode.BusyCapacity)).toBe(RetryClass.RetryableWithBackoff);
+    expect(getRetryClass(ErrorCode.UpstreamTimeout)).toBe(RetryClass.RetryableWithBackoff);
+    expect(getRetryClass(ErrorCode.LedgerFailClosed)).toBe(RetryClass.FailClosed);
+    expect(getRetryClass(ErrorCode.ClawtipCredentialInvalid)).toBe(RetryClass.FailClosed);
+    expect(getRetryClass(ErrorCode.PaymentRequired)).toBe(RetryClass.NotRetryable);
+  });
+
+  test("http status maps correctly", () => {
+    expect(getHttpStatus(ErrorCode.BusyCapacity)).toBe(429);
+    expect(getHttpStatus(ErrorCode.PaymentRequired)).toBe(402);
+    expect(getHttpStatus(ErrorCode.InvalidOrExpiredToken)).toBe(401);
+    expect(getHttpStatus(ErrorCode.LedgerFailClosed)).toBe(500);
+    expect(getHttpStatus(ErrorCode.UpstreamTimeout)).toBe(504);
+  });
+
+  test("createErrorEnvelope produces standard wire structure", () => {
+    const envelope = createErrorEnvelope(ErrorCode.BusyCapacity);
+    expect(envelope.error.code).toBe(ErrorCode.BusyCapacity);
+    expect(envelope.error.retryClass).toBe(RetryClass.RetryableWithBackoff);
+    expect(envelope.error.httpStatus).toBe(429);
+    expect(envelope.error.message).toContain("capacity");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./"
+  },
+  "include": ["src/**/*"]
+}