@pafi-dev/issuer 0.8.0 → 0.9.0

package/dist/http/index.d.ts

@@ -0,0 +1,112 @@
+import { PafiErrorType, PafiSdkError } from '@pafi-dev/core';
+
+/**
+ * Stripe-style HTTP error envelope shared by every PAFI service and
+ * issuer backend. The framework-agnostic `normalizeErrorToEnvelope`
+ * helper produces this from any thrown value; framework-specific
+ * filters (`@pafi-dev/issuer/nestjs`) call into it and write the
+ * result to their response object.
+ *
+ * Wire format:
+ *
+ * ```json
+ * {
+ *   "success": false,
+ *   "statusCode": 422,
+ *   "error": {
+ *     "type": "business_logic_error",
+ *     "code": "REDEMPTION_POLICY_DENIED",
+ *     "message": "redemption denied: amount 1 below per-tx minimum",
+ *     "param": null,
+ *     "metadata": { "policyDenialCode": "PER_TX_MIN" },
+ *     "safeToRetry": false,
+ *     "details": null
+ *   },
+ *   "meta": {
+ *     "timestamp": "2026-05-07T...",
+ *     "requestId": "...",
+ *     "path": "/pt/redeem"
+ *   }
+ * }
+ * ```
+ */
+
+/** Inner `error` block of the envelope. */
+interface PafiErrorPayload {
+    type: PafiErrorType;
+    code: string;
+    message: string;
+    param?: string;
+    metadata?: Record<string, unknown>;
+    details?: unknown;
+    safeToRetry: boolean;
+}
+/** Outer envelope returned for any non-2xx response. */
+interface PafiErrorEnvelope {
+    success: false;
+    statusCode: number;
+    error: PafiErrorPayload;
+    meta: {
+        timestamp: string;
+        requestId: string;
+        path: string;
+    };
+}
+/** Per-call request context the filter must collect from the host framework. */
+interface NormalizeContext {
+    /** `req.url` or equivalent. */
+    path: string;
+    /** Resolved request id (header or generated). */
+    requestId: string;
+    /** Optional `now()` injection for deterministic tests. */
+    now?: () => Date;
+}
+/**
+ * Generic error duck-type. The filter passes a small descriptor for
+ * any framework exception so the normalizer doesn't depend on
+ * `@nestjs/common` or any specific HTTP library.
+ */
+interface GenericHttpExceptionDescriptor {
+    /** HTTP status code carried by the exception. */
+    statusCode: number;
+    /**
+     * The body the framework would have serialized. For NestJS this is
+     * `exception.getResponse()`. May be a string or a record with
+     * `code`/`error`/`message`/`details`/`safeToRetry`/`type`/etc.
+     */
+    responseBody: unknown;
+    /** Exception class name, used as a last-resort `code` fallback. */
+    exceptionName: string;
+    /** Original `error.message`, used as a last-resort `message` fallback. */
+    fallbackMessage: string;
+}
+/**
+ * Convert a `PafiSdkError` directly to the inner `error` payload —
+ * skipping any framework exception wrapper. Used by frameworks that
+ * surface SDK errors without going through `createSdkErrorMapper`.
+ */
+declare function payloadFromPafiSdkError(err: PafiSdkError): PafiErrorPayload;
+/**
+ * Build the full envelope for any thrown value. The caller resolves
+ * `HttpException`-shaped exceptions and passes a descriptor; plain
+ * `Error` instances and unknown throws are handled directly.
+ */
+declare function buildErrorEnvelope(input: {
+    status: number;
+    payload: PafiErrorPayload;
+    ctx: NormalizeContext;
+}): PafiErrorEnvelope;
+/**
+ * Normalize a known `HttpException`-shaped exception into a payload.
+ * Framework filters supply the descriptor; the rest is shape-agnostic.
+ */
+declare function payloadFromHttpException(desc: GenericHttpExceptionDescriptor): PafiErrorPayload;
+/**
+ * Normalize a generic `Error` (not an HttpException) — TypeORM
+ * `QueryFailedError`, viem revert errors, etc. Returns a redacted
+ * 500-class payload with no message bleed-through unless the error
+ * is recognizably benign.
+ */
+declare function payloadFromGenericError(err: Error): PafiErrorPayload;
+
+export { type GenericHttpExceptionDescriptor, type NormalizeContext, type PafiErrorEnvelope, type PafiErrorPayload, buildErrorEnvelope, payloadFromGenericError, payloadFromHttpException, payloadFromPafiSdkError };

package/dist/http/index.js

@@ -0,0 +1,14 @@
+import "../chunk-R4FYJZ2N.js";
+import {
+  buildErrorEnvelope,
+  payloadFromGenericError,
+  payloadFromHttpException,
+  payloadFromPafiSdkError
+} from "../chunk-U3WMORJG.js";
+export {
+  buildErrorEnvelope,
+  payloadFromGenericError,
+  payloadFromHttpException,
+  payloadFromPafiSdkError
+};
+//# sourceMappingURL=index.js.map

package/dist/http/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.cjs

@@ -62,14 +62,18 @@ __export(index_exports, {
   RedemptionService: () => RedemptionService,
   RelayError: () => RelayError,
   RelayService: () => RelayService,
+  SDK_ERROR_HTTP_STATUS_CODE: () => import_core.SDK_ERROR_HTTP_STATUS_CODE,
   SettlementClient: () => SettlementClient,
   ValidationError: () => import_core3.ValidationError,
   authenticateRequest: () => authenticateRequest,
+  buildErrorEnvelope: () => buildErrorEnvelope,
+  buildSdkErrorBody: () => buildSdkErrorBody,
   createIssuerService: () => createIssuerService,
   createNativePtQuoter: () => createNativePtQuoter,
   createSdkErrorMapper: () => createSdkErrorMapper,
   createSubgraphNativeUsdtQuoter: () => createSubgraphNativeUsdtQuoter,
   createSubgraphPoolsProvider: () => createSubgraphPoolsProvider,
+  defaultErrorTypeForStatus: () => import_core.defaultErrorTypeForStatus,
   defaultPolicyFor: () => defaultPolicyFor,
   evaluateRedemption: () => evaluateRedemption,
   handleClaimStatus: () => handleClaimStatus,
@@ -78,6 +82,9 @@ __export(index_exports, {
   handleMobileSubmit: () => handleMobileSubmit,
   handleRedeemStatus: () => handleRedeemStatus,
   mergePaymasterFields: () => mergePaymasterFields,
+  payloadFromGenericError: () => payloadFromGenericError,
+  payloadFromHttpException: () => payloadFromHttpException,
+  payloadFromPafiSdkError: () => payloadFromPafiSdkError,
   prepareMobileUserOp: () => prepareMobileUserOp,
   relayUserOp: () => relayUserOp,
   requestPaymaster: () => requestPaymaster,
@@ -101,6 +108,152 @@ var ConfigurationError = class extends import_core2.PafiSdkError {
   }
 };
 
+// src/api/errorMapper.ts
+function buildSdkErrorBody(err) {
+  const type = err.type ?? (0, import_core.defaultErrorTypeForStatus)(import_core.SDK_ERROR_HTTP_STATUS_CODE[err.httpStatus]);
+  const body = {
+    type,
+    code: err.code,
+    message: err.message,
+    safeToRetry: err.safeToRetry
+  };
+  if (err.param) body.param = err.param;
+  if (err.metadata) body.metadata = err.metadata;
+  if (err.details !== void 0) body.details = err.details;
+  return body;
+}
+function createSdkErrorMapper(factories) {
+  return (err) => {
+    if (!(err instanceof import_core.PafiSdkError)) {
+      throw err;
+    }
+    const body = buildSdkErrorBody(err);
+    switch (err.httpStatus) {
+      case "not_found":
+        throw factories.notFound(body);
+      case "forbidden":
+        throw factories.forbidden(body);
+      case "unprocessable":
+        throw factories.unprocessable(body);
+      case "service_unavailable":
+        throw factories.serviceUnavailable(body);
+    }
+  };
+}
+
+// src/http/errorEnvelope.ts
+function isValidationPipeBody(body) {
+  return Array.isArray(body["message"]) && typeof body["error"] === "string" && body["error"] === "Bad Request";
+}
+function extractParamFromValidatorMessage(message) {
+  const idx = message.indexOf(" ");
+  if (idx <= 0) return void 0;
+  const candidate = message.slice(0, idx);
+  return /^[A-Za-z_][\w.]*$/.test(candidate) ? candidate : void 0;
+}
+function normalizeValidationPipeBody(body) {
+  const fields = {};
+  for (const msg of body.message) {
+    const param2 = extractParamFromValidatorMessage(msg);
+    const key = param2 ?? "_";
+    (fields[key] ??= []).push(msg);
+  }
+  const fieldKeys = Object.keys(fields).filter((k) => k !== "_");
+  const param = fieldKeys.length === 1 ? fieldKeys[0] : void 0;
+  const payload = {
+    type: "validation_error",
+    code: "VALIDATION_FAILED",
+    message: body.message.join("; "),
+    safeToRetry: false,
+    metadata: { fieldErrors: fields }
+  };
+  if (param) payload.param = param;
+  return payload;
+}
+function normalizeHttpExceptionBody(desc) {
+  const { statusCode, responseBody, exceptionName, fallbackMessage } = desc;
+  const defaultType = (0, import_core.defaultErrorTypeForStatus)(statusCode);
+  if (typeof responseBody === "string") {
+    return {
+      type: defaultType,
+      code: exceptionName,
+      message: responseBody,
+      safeToRetry: false
+    };
+  }
+  if (responseBody && typeof responseBody === "object") {
+    const body = responseBody;
+    if (isValidationPipeBody(body)) {
+      return normalizeValidationPipeBody(body);
+    }
+    const code = typeof body["code"] === "string" && body["code"] || typeof body["error"] === "string" && body["error"] || exceptionName;
+    const message = typeof body["message"] === "string" && body["message"] || (Array.isArray(body["message"]) ? body["message"].join("; ") : "") || fallbackMessage;
+    const type = typeof body["type"] === "string" && body["type"] || defaultType;
+    const safeToRetry = typeof body["safeToRetry"] === "boolean" ? body["safeToRetry"] : false;
+    const payload = {
+      type,
+      code,
+      message,
+      safeToRetry
+    };
+    if (typeof body["param"] === "string") payload.param = body["param"];
+    if (body["metadata"] && typeof body["metadata"] === "object") {
+      payload.metadata = body["metadata"];
+    }
+    if (body["details"] !== void 0) payload.details = body["details"];
+    return payload;
+  }
+  return {
+    type: defaultType,
+    code: exceptionName || "INTERNAL_SERVER_ERROR",
+    message: fallbackMessage || "An unexpected error occurred",
+    safeToRetry: false
+  };
+}
+function payloadFromPafiSdkError(err) {
+  const body = buildSdkErrorBody(err);
+  const payload = {
+    type: body.type,
+    code: body.code,
+    message: body.message,
+    safeToRetry: body.safeToRetry
+  };
+  if (body.param) payload.param = body.param;
+  if (body.metadata) payload.metadata = body.metadata;
+  if (body.details !== void 0) payload.details = body.details;
+  return payload;
+}
+function sanitizeDbErrorMessage(message) {
+  if (/^[A-Z_]+: /.test(message) && message.length < 256) return message;
+  return "Internal database error";
+}
+function buildErrorEnvelope(input) {
+  const now = (input.ctx.now ?? (() => /* @__PURE__ */ new Date()))();
+  return {
+    success: false,
+    statusCode: input.status,
+    error: input.payload,
+    meta: {
+      timestamp: now.toISOString(),
+      requestId: input.ctx.requestId,
+      path: input.ctx.path
+    }
+  };
+}
+function payloadFromHttpException(desc) {
+  return normalizeHttpExceptionBody(desc);
+}
+function payloadFromGenericError(err) {
+  const name = err.name || "INTERNAL_SERVER_ERROR";
+  const isDbError = name === "QueryFailedError" || name === "EntityNotFoundError";
+  return {
+    type: "server_error",
+    code: name,
+    message: isDbError ? sanitizeDbErrorMessage(err.message) : err.message || "An unexpected error occurred",
+    safeToRetry: false
+  };
+}
+
 // src/policy/defaultPolicy.ts
 var DefaultPolicyEngine = class {
   ledger;
@@ -2781,31 +2934,6 @@ async function handleDelegateSubmit(params) {
   return { userOpHash: result.userOpHash };
 }
 
-// src/api/errorMapper.ts
-function createSdkErrorMapper(factories) {
-  return (err) => {
-    if (!(err instanceof import_core.PafiSdkError)) {
-      throw err;
-    }
-    const body = {
-      code: err.code,
-      message: err.message,
-      details: err.details,
-      safeToRetry: err.safeToRetry
-    };
-    switch (err.httpStatus) {
-      case "not_found":
-        throw factories.notFound(body);
-      case "forbidden":
-        throw factories.forbidden(body);
-      case "unprocessable":
-        throw factories.unprocessable(body);
-      case "service_unavailable":
-        throw factories.serviceUnavailable(body);
-    }
-  };
-}
-
 // src/api/issuerApiAdapter.ts
 var import_node_crypto3 = require("crypto");
 var import_viem11 = require("viem");
@@ -4444,7 +4572,7 @@ var MemoryRedemptionHistoryStore = class {
 };
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = true ? "0.8.0" : "dev";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.9.0" : "dev";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AdapterMisconfiguredError,
@@ -4489,14 +4617,18 @@ var PAFI_ISSUER_SDK_VERSION = true ? "0.8.0" : "dev";
   RedemptionService,
   RelayError,
   RelayService,
+  SDK_ERROR_HTTP_STATUS_CODE,
   SettlementClient,
   ValidationError,
   authenticateRequest,
+  buildErrorEnvelope,
+  buildSdkErrorBody,
   createIssuerService,
   createNativePtQuoter,
   createSdkErrorMapper,
   createSubgraphNativeUsdtQuoter,
   createSubgraphPoolsProvider,
+  defaultErrorTypeForStatus,
   defaultPolicyFor,
   evaluateRedemption,
   handleClaimStatus,
@@ -4505,6 +4637,9 @@ var PAFI_ISSUER_SDK_VERSION = true ? "0.8.0" : "dev";
   handleMobileSubmit,
   handleRedeemStatus,
   mergePaymasterFields,
+  payloadFromGenericError,
+  payloadFromHttpException,
+  payloadFromPafiSdkError,
   prepareMobileUserOp,
   relayUserOp,
   requestPaymaster,