@pafi-dev/issuer 0.8.0 → 0.9.1

package/dist/chunk-R4FYJZ2N.js

@@ -0,0 +1 @@
+//# sourceMappingURL=chunk-R4FYJZ2N.js.map

package/dist/chunk-R4FYJZ2N.js.map

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

package/dist/chunk-U3WMORJG.js

@@ -0,0 +1,230 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== void 0 && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({ kind: __decoratorStrings[kind], name, metadata, addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null)) });
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length; i < n; i++) flags & 1 ? fns[i].call(self) : value = fns[i].call(self, value);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var fn, it, done, ctx, access, k = flags & 7, s = !!(flags & 8), p = !!(flags & 16);
+  var j = k > 3 ? array.length + 1 : k ? s ? 1 : 2 : 0, key = __decoratorStrings[k + 5];
+  var initializers = k > 3 && (array[j - 1] = []), extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (!p && !s && (target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(k < 4 ? target : { get [name]() {
+    return __privateGet(this, extra);
+  }, set [name](x) {
+    return __privateSet(this, extra, x);
+  } }, name));
+  k ? p && k < 4 && __name(extra, (k > 2 ? "set " : k > 1 ? "get " : "") + name) : __name(target, name);
+  for (var i = decorators.length - 1; i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    if (k) {
+      ctx.static = s, ctx.private = p, access = ctx.access = { has: p ? (x) => __privateIn(target, x) : (x) => name in x };
+      if (k ^ 3) access.get = p ? (x) => (k ^ 1 ? __privateGet : __privateMethod)(x, target, k ^ 4 ? extra : desc.get) : (x) => x[name];
+      if (k > 2) access.set = p ? (x, y) => __privateSet(x, target, y, k ^ 4 ? extra : desc.set) : (x, y) => x[name] = y;
+    }
+    it = (0, decorators[i])(k ? k < 4 ? p ? extra : desc[key] : k > 4 ? void 0 : { get: desc.get, set: desc.set } : target, ctx), done._ = 1;
+    if (k ^ 4 || it === void 0) __expectFn(it) && (k > 4 ? initializers.unshift(it) : k ? p ? extra = it : desc[key] = it : target = it);
+    else if (typeof it !== "object" || it === null) __typeError("Object expected");
+    else __expectFn(fn = it.get) && (desc.get = fn), __expectFn(fn = it.set) && (desc.set = fn), __expectFn(fn = it.init) && initializers.unshift(fn);
+  }
+  return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+// src/errors.ts
+import {
+  PafiSdkError,
+  SDK_ERROR_HTTP_STATUS_CODE,
+  defaultErrorTypeForStatus
+} from "@pafi-dev/core";
+import { PafiSdkError as PafiSdkError2 } from "@pafi-dev/core";
+import { ValidationError } from "@pafi-dev/core";
+var ConfigurationError = class extends PafiSdkError2 {
+  httpStatus = "service_unavailable";
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// src/api/errorMapper.ts
+function buildSdkErrorBody(err) {
+  const type = err.type ?? defaultErrorTypeForStatus(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 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 = 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
+  };
+}
+
+export {
+  __decoratorStart,
+  __runInitializers,
+  __decorateElement,
+  ConfigurationError,
+  PafiSdkError,
+  SDK_ERROR_HTTP_STATUS_CODE,
+  defaultErrorTypeForStatus,
+  ValidationError,
+  buildSdkErrorBody,
+  createSdkErrorMapper,
+  payloadFromPafiSdkError,
+  buildErrorEnvelope,
+  payloadFromHttpException,
+  payloadFromGenericError
+};
+//# sourceMappingURL=chunk-U3WMORJG.js.map

package/dist/chunk-U3WMORJG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/api/errorMapper.ts","../src/http/errorEnvelope.ts"],"sourcesContent":["/**\n * `PafiSdkError` + `SdkErrorHttpStatus` are exported from\n * `@pafi-dev/core/errors` so core-level errors (e.g. `OracleStaleError`)\n * can extend the same base. Issuer re-exports the canonical types here\n * for back-compat — `instanceof PafiSdkError` from EITHER package\n * catches errors thrown from EITHER package.\n */\nexport {\n  PafiSdkError,\n  SDK_ERROR_HTTP_STATUS_CODE,\n  defaultErrorTypeForStatus,\n  type SdkErrorHttpStatus,\n  type PafiErrorType,\n} from \"@pafi-dev/core\";\nimport { PafiSdkError } from \"@pafi-dev/core\";\n\n/**\n * `ValidationError` lives in `@pafi-dev/core` so core/trading helpers\n * throw the same typed class. Re-exported here for back-compat.\n */\nexport { ValidationError } from \"@pafi-dev/core\";\n\n/**\n * Issuer wired the SDK without a dependency the requested endpoint\n * needs (e.g. `/gas-fee` called but `feeManager` not configured;\n * `/pools` called but `poolsProvider` not configured). 503 because\n * the endpoint genuinely can't serve the request — caller's payload\n * is fine, the issuer's deployment is incomplete.\n */\nexport class ConfigurationError extends PafiSdkError {\n  readonly httpStatus = \"service_unavailable\" as const;\n  readonly code: string;\n  readonly details?: Record<string, unknown>;\n\n  constructor(\n    code: string,\n    message: string,\n    details?: Record<string, unknown>,\n  ) {\n    super(message);\n    this.code = code;\n    this.details = details;\n  }\n}\n","import {\n  PafiSdkError,\n  SDK_ERROR_HTTP_STATUS_CODE,\n  defaultErrorTypeForStatus,\n  type PafiErrorType,\n  type SdkErrorHttpStatus,\n} from \"../errors\";\n\n/**\n * Normalized HTTP status the issuer controller should surface for a\n * given SDK error. Mirrors `SdkErrorHttpStatus` on `PafiSdkError`.\n */\nexport type SdkErrorStatus = SdkErrorHttpStatus;\n\n/**\n * Structured body the issuer controller passes to its\n * framework-specific exception class. Stripe-style envelope:\n *\n * ```json\n * {\n *   \"type\": \"business_logic_error\",\n *   \"code\": \"REDEMPTION_POLICY_DENIED\",\n *   \"message\": \"...\",\n *   \"param\": null,\n *   \"metadata\": { \"policyDenialCode\": \"PER_TX_MIN\" },\n *   \"safeToRetry\": false\n * }\n * ```\n *\n * Carries enough fields for the global HTTP filter to emit the final\n * envelope without losing any SDK-side context.\n */\nexport interface SdkErrorBody {\n  /** Stripe-style taxonomy slot — drives UI branching. */\n  type: PafiErrorType;\n  /** Machine-readable code, e.g. `\"REDEMPTION_POLICY_DENIED\"`. */\n  code: string;\n  /** Human-readable message. */\n  message: string;\n  /** Field name that triggered the error, when applicable. */\n  param?: string;\n  /** UI-facing structured context. */\n  metadata?: Record<string, unknown>;\n  /** Raw debug context. */\n  details?: unknown;\n  /** True when retry is safe (no side effects yet). */\n  safeToRetry: boolean;\n}\n\n/**\n * Per-status exception factories. The issuer's controller wires one\n * factory per status to its preferred framework's exception class\n * (NestJS `UnprocessableEntityException`, Fastify `httpErrors.badData`,\n * etc). The factory must return an Error — `createSdkErrorMapper`\n * uses `throw factory(body)`.\n */\nexport interface SdkErrorMapperFactories {\n  notFound: (body: SdkErrorBody) => Error;\n  forbidden: (body: SdkErrorBody) => Error;\n  unprocessable: (body: SdkErrorBody) => Error;\n  serviceUnavailable: (body: SdkErrorBody) => Error;\n}\n\n/**\n * Build the Stripe-style body from any `PafiSdkError`. Exposed for\n * frameworks that don't fit the four-factory shape (e.g. a Hono error\n * handler that builds its own response object).\n */\nexport function buildSdkErrorBody(err: PafiSdkError): SdkErrorBody {\n  const type =\n    err.type ??\n    defaultErrorTypeForStatus(SDK_ERROR_HTTP_STATUS_CODE[err.httpStatus]);\n  const body: SdkErrorBody = {\n    type,\n    code: err.code,\n    message: err.message,\n    safeToRetry: err.safeToRetry,\n  };\n  if (err.param) body.param = err.param;\n  if (err.metadata) body.metadata = err.metadata;\n  if (err.details !== undefined) body.details = err.details;\n  return body;\n}\n\n/**\n * Build a single error-mapping function that converts any `PafiSdkError`\n * into the issuer's framework-specific HTTP exception. Status, code,\n * `safeToRetry`, and `details` come straight off the error class —\n * the mapper is a dumb funnel, no per-error business logic.\n *\n * Any non-`PafiSdkError` is re-thrown unchanged so unexpected runtime\n * errors propagate to the framework's default 500 handler.\n *\n * Usage (NestJS):\n *\n * ```ts\n * const mapSdkError = createSdkErrorMapper({\n *   notFound: (body) => new NotFoundException(body),\n *   forbidden: (body) => new ForbiddenException(body),\n *   unprocessable: (body) => new UnprocessableEntityException(body),\n *   serviceUnavailable: (body) => new ServiceUnavailableException(body),\n * });\n *\n * try { ... } catch (err) { mapSdkError(err); }\n * ```\n *\n * Returns `never` so call sites in `try/catch` propagate the throw\n * without a redundant `throw` keyword.\n */\nexport function createSdkErrorMapper(\n  factories: SdkErrorMapperFactories,\n): (err: unknown) => never {\n  return (err: unknown): never => {\n    if (!(err instanceof PafiSdkError)) {\n      throw err;\n    }\n    const body = buildSdkErrorBody(err);\n    switch (err.httpStatus) {\n      case \"not_found\":\n        throw factories.notFound(body);\n      case \"forbidden\":\n        throw factories.forbidden(body);\n      case \"unprocessable\":\n        throw factories.unprocessable(body);\n      case \"service_unavailable\":\n        throw factories.serviceUnavailable(body);\n    }\n  };\n}\n","/**\n * Stripe-style HTTP error envelope shared by every PAFI service and\n * issuer backend. The framework-agnostic `normalizeErrorToEnvelope`\n * helper produces this from any thrown value; framework-specific\n * filters (`@pafi-dev/issuer/nestjs`) call into it and write the\n * result to their response object.\n *\n * Wire format:\n *\n * ```json\n * {\n *   \"success\": false,\n *   \"statusCode\": 422,\n *   \"error\": {\n *     \"type\": \"business_logic_error\",\n *     \"code\": \"REDEMPTION_POLICY_DENIED\",\n *     \"message\": \"redemption denied: amount 1 below per-tx minimum\",\n *     \"param\": null,\n *     \"metadata\": { \"policyDenialCode\": \"PER_TX_MIN\" },\n *     \"safeToRetry\": false,\n *     \"details\": null\n *   },\n *   \"meta\": {\n *     \"timestamp\": \"2026-05-07T...\",\n *     \"requestId\": \"...\",\n *     \"path\": \"/pt/redeem\"\n *   }\n * }\n * ```\n */\n\nimport {\n  PafiSdkError,\n  SDK_ERROR_HTTP_STATUS_CODE,\n  defaultErrorTypeForStatus,\n  type PafiErrorType,\n} from \"../errors\";\nimport { buildSdkErrorBody, type SdkErrorBody } from \"../api/errorMapper\";\n\n/** Inner `error` block of the envelope. */\nexport interface PafiErrorPayload {\n  type: PafiErrorType;\n  code: string;\n  message: string;\n  param?: string;\n  metadata?: Record<string, unknown>;\n  details?: unknown;\n  safeToRetry: boolean;\n}\n\n/** Outer envelope returned for any non-2xx response. */\nexport interface PafiErrorEnvelope {\n  success: false;\n  statusCode: number;\n  error: PafiErrorPayload;\n  meta: {\n    timestamp: string;\n    requestId: string;\n    path: string;\n  };\n}\n\n/** Per-call request context the filter must collect from the host framework. */\nexport interface NormalizeContext {\n  /** `req.url` or equivalent. */\n  path: string;\n  /** Resolved request id (header or generated). */\n  requestId: string;\n  /** Optional `now()` injection for deterministic tests. */\n  now?: () => Date;\n}\n\n/**\n * Generic error duck-type. The filter passes a small descriptor for\n * any framework exception so the normalizer doesn't depend on\n * `@nestjs/common` or any specific HTTP library.\n */\nexport interface GenericHttpExceptionDescriptor {\n  /** HTTP status code carried by the exception. */\n  statusCode: number;\n  /**\n   * The body the framework would have serialized. For NestJS this is\n   * `exception.getResponse()`. May be a string or a record with\n   * `code`/`error`/`message`/`details`/`safeToRetry`/`type`/etc.\n   */\n  responseBody: unknown;\n  /** Exception class name, used as a last-resort `code` fallback. */\n  exceptionName: string;\n  /** Original `error.message`, used as a last-resort `message` fallback. */\n  fallbackMessage: string;\n}\n\n/** True when `value` looks like a NestJS `BadRequestException` from `ValidationPipe`. */\nfunction isValidationPipeBody(\n  body: Record<string, unknown>,\n): body is { message: string[]; error?: string; statusCode?: number } {\n  return (\n    Array.isArray(body[\"message\"]) &&\n    typeof body[\"error\"] === \"string\" &&\n    body[\"error\"] === \"Bad Request\"\n  );\n}\n\n/** Pull `param` out of a `class-validator` message like `\"amount must be a number string\"`. */\nfunction extractParamFromValidatorMessage(message: string): string | undefined {\n  const idx = message.indexOf(\" \");\n  if (idx <= 0) return undefined;\n  const candidate = message.slice(0, idx);\n  return /^[A-Za-z_][\\w.]*$/.test(candidate) ? candidate : undefined;\n}\n\nfunction normalizeValidationPipeBody(\n  body: { message: string[]; statusCode?: number },\n): PafiErrorPayload {\n  const fields: Record<string, string[]> = {};\n  for (const msg of body.message) {\n    const param = extractParamFromValidatorMessage(msg);\n    const key = param ?? \"_\";\n    (fields[key] ??= []).push(msg);\n  }\n  const fieldKeys = Object.keys(fields).filter((k) => k !== \"_\");\n  const param = fieldKeys.length === 1 ? fieldKeys[0] : undefined;\n\n  const payload: PafiErrorPayload = {\n    type: \"validation_error\",\n    code: \"VALIDATION_FAILED\",\n    message: body.message.join(\"; \"),\n    safeToRetry: false,\n    metadata: { fieldErrors: fields },\n  };\n  if (param) payload.param = param;\n  return payload;\n}\n\n/**\n * Pull a Stripe-style payload out of a structured exception body. The\n * filter has already determined this is an `HttpException` (or\n * duck-typed equivalent). Order:\n *\n * 1. SDK-shaped body (has `type` + `code`) — pass through verbatim.\n * 2. `ValidationPipe` body (`message: string[]`, `error: \"Bad Request\"`)\n *    — collapse into `validation_error` with `metadata.fieldErrors`.\n * 3. Plain object with `code` or `error` — best-effort extract.\n * 4. String body — just a message.\n */\nfunction normalizeHttpExceptionBody(\n  desc: GenericHttpExceptionDescriptor,\n): PafiErrorPayload {\n  const { statusCode, responseBody, exceptionName, fallbackMessage } = desc;\n  const defaultType = defaultErrorTypeForStatus(statusCode);\n\n  if (typeof responseBody === \"string\") {\n    return {\n      type: defaultType,\n      code: exceptionName,\n      message: responseBody,\n      safeToRetry: false,\n    };\n  }\n\n  if (responseBody && typeof responseBody === \"object\") {\n    const body = responseBody as Record<string, unknown>;\n\n    if (isValidationPipeBody(body)) {\n      return normalizeValidationPipeBody(body);\n    }\n\n    const code =\n      (typeof body[\"code\"] === \"string\" && body[\"code\"]) ||\n      (typeof body[\"error\"] === \"string\" && body[\"error\"]) ||\n      exceptionName;\n    const message =\n      (typeof body[\"message\"] === \"string\" && body[\"message\"]) ||\n      (Array.isArray(body[\"message\"])\n        ? (body[\"message\"] as string[]).join(\"; \")\n        : \"\") ||\n      fallbackMessage;\n    const type =\n      (typeof body[\"type\"] === \"string\" && (body[\"type\"] as PafiErrorType)) ||\n      defaultType;\n    const safeToRetry =\n      typeof body[\"safeToRetry\"] === \"boolean\" ? body[\"safeToRetry\"] : false;\n\n    const payload: PafiErrorPayload = {\n      type,\n      code,\n      message,\n      safeToRetry,\n    };\n    if (typeof body[\"param\"] === \"string\") payload.param = body[\"param\"];\n    if (body[\"metadata\"] && typeof body[\"metadata\"] === \"object\") {\n      payload.metadata = body[\"metadata\"] as Record<string, unknown>;\n    }\n    if (body[\"details\"] !== undefined) payload.details = body[\"details\"];\n    return payload;\n  }\n\n  return {\n    type: defaultType,\n    code: exceptionName || \"INTERNAL_SERVER_ERROR\",\n    message: fallbackMessage || \"An unexpected error occurred\",\n    safeToRetry: false,\n  };\n}\n\n/**\n * Convert a `PafiSdkError` directly to the inner `error` payload —\n * skipping any framework exception wrapper. Used by frameworks that\n * surface SDK errors without going through `createSdkErrorMapper`.\n */\nexport function payloadFromPafiSdkError(err: PafiSdkError): PafiErrorPayload {\n  const body: SdkErrorBody = buildSdkErrorBody(err);\n  const payload: PafiErrorPayload = {\n    type: body.type,\n    code: body.code,\n    message: body.message,\n    safeToRetry: body.safeToRetry,\n  };\n  if (body.param) payload.param = body.param;\n  if (body.metadata) payload.metadata = body.metadata;\n  if (body.details !== undefined) payload.details = body.details;\n  return payload;\n}\n\n/** Strip SQL fragments from raw DB driver errors before exposing them. */\nfunction sanitizeDbErrorMessage(message: string): string {\n  if (/^[A-Z_]+: /.test(message) && message.length < 256) return message;\n  return \"Internal database error\";\n}\n\n/**\n * Build the full envelope for any thrown value. The caller resolves\n * `HttpException`-shaped exceptions and passes a descriptor; plain\n * `Error` instances and unknown throws are handled directly.\n */\nexport function buildErrorEnvelope(input: {\n  status: number;\n  payload: PafiErrorPayload;\n  ctx: NormalizeContext;\n}): PafiErrorEnvelope {\n  const now = (input.ctx.now ?? (() => new Date()))();\n  return {\n    success: false,\n    statusCode: input.status,\n    error: input.payload,\n    meta: {\n      timestamp: now.toISOString(),\n      requestId: input.ctx.requestId,\n      path: input.ctx.path,\n    },\n  };\n}\n\n/**\n * Normalize a known `HttpException`-shaped exception into a payload.\n * Framework filters supply the descriptor; the rest is shape-agnostic.\n */\nexport function payloadFromHttpException(\n  desc: GenericHttpExceptionDescriptor,\n): PafiErrorPayload {\n  return normalizeHttpExceptionBody(desc);\n}\n\n/**\n * Normalize a generic `Error` (not an HttpException) — TypeORM\n * `QueryFailedError`, viem revert errors, etc. Returns a redacted\n * 500-class payload with no message bleed-through unless the error\n * is recognizably benign.\n */\nexport function payloadFromGenericError(err: Error): PafiErrorPayload {\n  const name = err.name || \"INTERNAL_SERVER_ERROR\";\n  const isDbError = name === \"QueryFailedError\" || name === \"EntityNotFoundError\";\n  return {\n    type: \"server_error\",\n    code: name,\n    message: isDbError\n      ? sanitizeDbErrorMessage(err.message)\n      : err.message || \"An unexpected error occurred\",\n    safeToRetry: false,\n  };\n}\n"],"mappings":"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","names":["PafiSdkError","param"]}

package/dist/http/index.cjs

@@ -0,0 +1,169 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/http/index.ts
+var http_exports = {};
+__export(http_exports, {
+  buildErrorEnvelope: () => buildErrorEnvelope,
+  payloadFromGenericError: () => payloadFromGenericError,
+  payloadFromHttpException: () => payloadFromHttpException,
+  payloadFromPafiSdkError: () => payloadFromPafiSdkError
+});
+module.exports = __toCommonJS(http_exports);
+
+// src/errors.ts
+var import_core = require("@pafi-dev/core");
+var import_core2 = require("@pafi-dev/core");
+var import_core3 = require("@pafi-dev/core");
+
+// 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;
+}
+
+// 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
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildErrorEnvelope,
+  payloadFromGenericError,
+  payloadFromHttpException,
+  payloadFromPafiSdkError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/http/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/http/index.ts","../../src/errors.ts","../../src/api/errorMapper.ts","../../src/http/errorEnvelope.ts"],"sourcesContent":["export {\n  buildErrorEnvelope,\n  payloadFromHttpException,\n  payloadFromGenericError,\n  payloadFromPafiSdkError,\n  type PafiErrorEnvelope,\n  type PafiErrorPayload,\n  type GenericHttpExceptionDescriptor,\n  type NormalizeContext,\n} from \"./errorEnvelope\";\n","/**\n * `PafiSdkError` + `SdkErrorHttpStatus` are exported from\n * `@pafi-dev/core/errors` so core-level errors (e.g. `OracleStaleError`)\n * can extend the same base. Issuer re-exports the canonical types here\n * for back-compat — `instanceof PafiSdkError` from EITHER package\n * catches errors thrown from EITHER package.\n */\nexport {\n  PafiSdkError,\n  SDK_ERROR_HTTP_STATUS_CODE,\n  defaultErrorTypeForStatus,\n  type SdkErrorHttpStatus,\n  type PafiErrorType,\n} from \"@pafi-dev/core\";\nimport { PafiSdkError } from \"@pafi-dev/core\";\n\n/**\n * `ValidationError` lives in `@pafi-dev/core` so core/trading helpers\n * throw the same typed class. Re-exported here for back-compat.\n */\nexport { ValidationError } from \"@pafi-dev/core\";\n\n/**\n * Issuer wired the SDK without a dependency the requested endpoint\n * needs (e.g. `/gas-fee` called but `feeManager` not configured;\n * `/pools` called but `poolsProvider` not configured). 503 because\n * the endpoint genuinely can't serve the request — caller's payload\n * is fine, the issuer's deployment is incomplete.\n */\nexport class ConfigurationError extends PafiSdkError {\n  readonly httpStatus = \"service_unavailable\" as const;\n  readonly code: string;\n  readonly details?: Record<string, unknown>;\n\n  constructor(\n    code: string,\n    message: string,\n    details?: Record<string, unknown>,\n  ) {\n    super(message);\n    this.code = code;\n    this.details = details;\n  }\n}\n","import {\n  PafiSdkError,\n  SDK_ERROR_HTTP_STATUS_CODE,\n  defaultErrorTypeForStatus,\n  type PafiErrorType,\n  type SdkErrorHttpStatus,\n} from \"../errors\";\n\n/**\n * Normalized HTTP status the issuer controller should surface for a\n * given SDK error. Mirrors `SdkErrorHttpStatus` on `PafiSdkError`.\n */\nexport type SdkErrorStatus = SdkErrorHttpStatus;\n\n/**\n * Structured body the issuer controller passes to its\n * framework-specific exception class. Stripe-style envelope:\n *\n * ```json\n * {\n *   \"type\": \"business_logic_error\",\n *   \"code\": \"REDEMPTION_POLICY_DENIED\",\n *   \"message\": \"...\",\n *   \"param\": null,\n *   \"metadata\": { \"policyDenialCode\": \"PER_TX_MIN\" },\n *   \"safeToRetry\": false\n * }\n * ```\n *\n * Carries enough fields for the global HTTP filter to emit the final\n * envelope without losing any SDK-side context.\n */\nexport interface SdkErrorBody {\n  /** Stripe-style taxonomy slot — drives UI branching. */\n  type: PafiErrorType;\n  /** Machine-readable code, e.g. `\"REDEMPTION_POLICY_DENIED\"`. */\n  code: string;\n  /** Human-readable message. */\n  message: string;\n  /** Field name that triggered the error, when applicable. */\n  param?: string;\n  /** UI-facing structured context. */\n  metadata?: Record<string, unknown>;\n  /** Raw debug context. */\n  details?: unknown;\n  /** True when retry is safe (no side effects yet). */\n  safeToRetry: boolean;\n}\n\n/**\n * Per-status exception factories. The issuer's controller wires one\n * factory per status to its preferred framework's exception class\n * (NestJS `UnprocessableEntityException`, Fastify `httpErrors.badData`,\n * etc). The factory must return an Error — `createSdkErrorMapper`\n * uses `throw factory(body)`.\n */\nexport interface SdkErrorMapperFactories {\n  notFound: (body: SdkErrorBody) => Error;\n  forbidden: (body: SdkErrorBody) => Error;\n  unprocessable: (body: SdkErrorBody) => Error;\n  serviceUnavailable: (body: SdkErrorBody) => Error;\n}\n\n/**\n * Build the Stripe-style body from any `PafiSdkError`. Exposed for\n * frameworks that don't fit the four-factory shape (e.g. a Hono error\n * handler that builds its own response object).\n */\nexport function buildSdkErrorBody(err: PafiSdkError): SdkErrorBody {\n  const type =\n    err.type ??\n    defaultErrorTypeForStatus(SDK_ERROR_HTTP_STATUS_CODE[err.httpStatus]);\n  const body: SdkErrorBody = {\n    type,\n    code: err.code,\n    message: err.message,\n    safeToRetry: err.safeToRetry,\n  };\n  if (err.param) body.param = err.param;\n  if (err.metadata) body.metadata = err.metadata;\n  if (err.details !== undefined) body.details = err.details;\n  return body;\n}\n\n/**\n * Build a single error-mapping function that converts any `PafiSdkError`\n * into the issuer's framework-specific HTTP exception. Status, code,\n * `safeToRetry`, and `details` come straight off the error class —\n * the mapper is a dumb funnel, no per-error business logic.\n *\n * Any non-`PafiSdkError` is re-thrown unchanged so unexpected runtime\n * errors propagate to the framework's default 500 handler.\n *\n * Usage (NestJS):\n *\n * ```ts\n * const mapSdkError = createSdkErrorMapper({\n *   notFound: (body) => new NotFoundException(body),\n *   forbidden: (body) => new ForbiddenException(body),\n *   unprocessable: (body) => new UnprocessableEntityException(body),\n *   serviceUnavailable: (body) => new ServiceUnavailableException(body),\n * });\n *\n * try { ... } catch (err) { mapSdkError(err); }\n * ```\n *\n * Returns `never` so call sites in `try/catch` propagate the throw\n * without a redundant `throw` keyword.\n */\nexport function createSdkErrorMapper(\n  factories: SdkErrorMapperFactories,\n): (err: unknown) => never {\n  return (err: unknown): never => {\n    if (!(err instanceof PafiSdkError)) {\n      throw err;\n    }\n    const body = buildSdkErrorBody(err);\n    switch (err.httpStatus) {\n      case \"not_found\":\n        throw factories.notFound(body);\n      case \"forbidden\":\n        throw factories.forbidden(body);\n      case \"unprocessable\":\n        throw factories.unprocessable(body);\n      case \"service_unavailable\":\n        throw factories.serviceUnavailable(body);\n    }\n  };\n}\n","/**\n * Stripe-style HTTP error envelope shared by every PAFI service and\n * issuer backend. The framework-agnostic `normalizeErrorToEnvelope`\n * helper produces this from any thrown value; framework-specific\n * filters (`@pafi-dev/issuer/nestjs`) call into it and write the\n * result to their response object.\n *\n * Wire format:\n *\n * ```json\n * {\n *   \"success\": false,\n *   \"statusCode\": 422,\n *   \"error\": {\n *     \"type\": \"business_logic_error\",\n *     \"code\": \"REDEMPTION_POLICY_DENIED\",\n *     \"message\": \"redemption denied: amount 1 below per-tx minimum\",\n *     \"param\": null,\n *     \"metadata\": { \"policyDenialCode\": \"PER_TX_MIN\" },\n *     \"safeToRetry\": false,\n *     \"details\": null\n *   },\n *   \"meta\": {\n *     \"timestamp\": \"2026-05-07T...\",\n *     \"requestId\": \"...\",\n *     \"path\": \"/pt/redeem\"\n *   }\n * }\n * ```\n */\n\nimport {\n  PafiSdkError,\n  SDK_ERROR_HTTP_STATUS_CODE,\n  defaultErrorTypeForStatus,\n  type PafiErrorType,\n} from \"../errors\";\nimport { buildSdkErrorBody, type SdkErrorBody } from \"../api/errorMapper\";\n\n/** Inner `error` block of the envelope. */\nexport interface PafiErrorPayload {\n  type: PafiErrorType;\n  code: string;\n  message: string;\n  param?: string;\n  metadata?: Record<string, unknown>;\n  details?: unknown;\n  safeToRetry: boolean;\n}\n\n/** Outer envelope returned for any non-2xx response. */\nexport interface PafiErrorEnvelope {\n  success: false;\n  statusCode: number;\n  error: PafiErrorPayload;\n  meta: {\n    timestamp: string;\n    requestId: string;\n    path: string;\n  };\n}\n\n/** Per-call request context the filter must collect from the host framework. */\nexport interface NormalizeContext {\n  /** `req.url` or equivalent. */\n  path: string;\n  /** Resolved request id (header or generated). */\n  requestId: string;\n  /** Optional `now()` injection for deterministic tests. */\n  now?: () => Date;\n}\n\n/**\n * Generic error duck-type. The filter passes a small descriptor for\n * any framework exception so the normalizer doesn't depend on\n * `@nestjs/common` or any specific HTTP library.\n */\nexport interface GenericHttpExceptionDescriptor {\n  /** HTTP status code carried by the exception. */\n  statusCode: number;\n  /**\n   * The body the framework would have serialized. For NestJS this is\n   * `exception.getResponse()`. May be a string or a record with\n   * `code`/`error`/`message`/`details`/`safeToRetry`/`type`/etc.\n   */\n  responseBody: unknown;\n  /** Exception class name, used as a last-resort `code` fallback. */\n  exceptionName: string;\n  /** Original `error.message`, used as a last-resort `message` fallback. */\n  fallbackMessage: string;\n}\n\n/** True when `value` looks like a NestJS `BadRequestException` from `ValidationPipe`. */\nfunction isValidationPipeBody(\n  body: Record<string, unknown>,\n): body is { message: string[]; error?: string; statusCode?: number } {\n  return (\n    Array.isArray(body[\"message\"]) &&\n    typeof body[\"error\"] === \"string\" &&\n    body[\"error\"] === \"Bad Request\"\n  );\n}\n\n/** Pull `param` out of a `class-validator` message like `\"amount must be a number string\"`. */\nfunction extractParamFromValidatorMessage(message: string): string | undefined {\n  const idx = message.indexOf(\" \");\n  if (idx <= 0) return undefined;\n  const candidate = message.slice(0, idx);\n  return /^[A-Za-z_][\\w.]*$/.test(candidate) ? candidate : undefined;\n}\n\nfunction normalizeValidationPipeBody(\n  body: { message: string[]; statusCode?: number },\n): PafiErrorPayload {\n  const fields: Record<string, string[]> = {};\n  for (const msg of body.message) {\n    const param = extractParamFromValidatorMessage(msg);\n    const key = param ?? \"_\";\n    (fields[key] ??= []).push(msg);\n  }\n  const fieldKeys = Object.keys(fields).filter((k) => k !== \"_\");\n  const param = fieldKeys.length === 1 ? fieldKeys[0] : undefined;\n\n  const payload: PafiErrorPayload = {\n    type: \"validation_error\",\n    code: \"VALIDATION_FAILED\",\n    message: body.message.join(\"; \"),\n    safeToRetry: false,\n    metadata: { fieldErrors: fields },\n  };\n  if (param) payload.param = param;\n  return payload;\n}\n\n/**\n * Pull a Stripe-style payload out of a structured exception body. The\n * filter has already determined this is an `HttpException` (or\n * duck-typed equivalent). Order:\n *\n * 1. SDK-shaped body (has `type` + `code`) — pass through verbatim.\n * 2. `ValidationPipe` body (`message: string[]`, `error: \"Bad Request\"`)\n *    — collapse into `validation_error` with `metadata.fieldErrors`.\n * 3. Plain object with `code` or `error` — best-effort extract.\n * 4. String body — just a message.\n */\nfunction normalizeHttpExceptionBody(\n  desc: GenericHttpExceptionDescriptor,\n): PafiErrorPayload {\n  const { statusCode, responseBody, exceptionName, fallbackMessage } = desc;\n  const defaultType = defaultErrorTypeForStatus(statusCode);\n\n  if (typeof responseBody === \"string\") {\n    return {\n      type: defaultType,\n      code: exceptionName,\n      message: responseBody,\n      safeToRetry: false,\n    };\n  }\n\n  if (responseBody && typeof responseBody === \"object\") {\n    const body = responseBody as Record<string, unknown>;\n\n    if (isValidationPipeBody(body)) {\n      return normalizeValidationPipeBody(body);\n    }\n\n    const code =\n      (typeof body[\"code\"] === \"string\" && body[\"code\"]) ||\n      (typeof body[\"error\"] === \"string\" && body[\"error\"]) ||\n      exceptionName;\n    const message =\n      (typeof body[\"message\"] === \"string\" && body[\"message\"]) ||\n      (Array.isArray(body[\"message\"])\n        ? (body[\"message\"] as string[]).join(\"; \")\n        : \"\") ||\n      fallbackMessage;\n    const type =\n      (typeof body[\"type\"] === \"string\" && (body[\"type\"] as PafiErrorType)) ||\n      defaultType;\n    const safeToRetry =\n      typeof body[\"safeToRetry\"] === \"boolean\" ? body[\"safeToRetry\"] : false;\n\n    const payload: PafiErrorPayload = {\n      type,\n      code,\n      message,\n      safeToRetry,\n    };\n    if (typeof body[\"param\"] === \"string\") payload.param = body[\"param\"];\n    if (body[\"metadata\"] && typeof body[\"metadata\"] === \"object\") {\n      payload.metadata = body[\"metadata\"] as Record<string, unknown>;\n    }\n    if (body[\"details\"] !== undefined) payload.details = body[\"details\"];\n    return payload;\n  }\n\n  return {\n    type: defaultType,\n    code: exceptionName || \"INTERNAL_SERVER_ERROR\",\n    message: fallbackMessage || \"An unexpected error occurred\",\n    safeToRetry: false,\n  };\n}\n\n/**\n * Convert a `PafiSdkError` directly to the inner `error` payload —\n * skipping any framework exception wrapper. Used by frameworks that\n * surface SDK errors without going through `createSdkErrorMapper`.\n */\nexport function payloadFromPafiSdkError(err: PafiSdkError): PafiErrorPayload {\n  const body: SdkErrorBody = buildSdkErrorBody(err);\n  const payload: PafiErrorPayload = {\n    type: body.type,\n    code: body.code,\n    message: body.message,\n    safeToRetry: body.safeToRetry,\n  };\n  if (body.param) payload.param = body.param;\n  if (body.metadata) payload.metadata = body.metadata;\n  if (body.details !== undefined) payload.details = body.details;\n  return payload;\n}\n\n/** Strip SQL fragments from raw DB driver errors before exposing them. */\nfunction sanitizeDbErrorMessage(message: string): string {\n  if (/^[A-Z_]+: /.test(message) && message.length < 256) return message;\n  return \"Internal database error\";\n}\n\n/**\n * Build the full envelope for any thrown value. The caller resolves\n * `HttpException`-shaped exceptions and passes a descriptor; plain\n * `Error` instances and unknown throws are handled directly.\n */\nexport function buildErrorEnvelope(input: {\n  status: number;\n  payload: PafiErrorPayload;\n  ctx: NormalizeContext;\n}): PafiErrorEnvelope {\n  const now = (input.ctx.now ?? (() => new Date()))();\n  return {\n    success: false,\n    statusCode: input.status,\n    error: input.payload,\n    meta: {\n      timestamp: now.toISOString(),\n      requestId: input.ctx.requestId,\n      path: input.ctx.path,\n    },\n  };\n}\n\n/**\n * Normalize a known `HttpException`-shaped exception into a payload.\n * Framework filters supply the descriptor; the rest is shape-agnostic.\n */\nexport function payloadFromHttpException(\n  desc: GenericHttpExceptionDescriptor,\n): PafiErrorPayload {\n  return normalizeHttpExceptionBody(desc);\n}\n\n/**\n * Normalize a generic `Error` (not an HttpException) — TypeORM\n * `QueryFailedError`, viem revert errors, etc. Returns a redacted\n * 500-class payload with no message bleed-through unless the error\n * is recognizably benign.\n */\nexport function payloadFromGenericError(err: Error): PafiErrorPayload {\n  const name = err.name || \"INTERNAL_SERVER_ERROR\";\n  const isDbError = name === \"QueryFailedError\" || name === \"EntityNotFoundError\";\n  return {\n    type: \"server_error\",\n    code: name,\n    message: isDbError\n      ? sanitizeDbErrorMessage(err.message)\n      : err.message || \"An unexpected error occurred\",\n    safeToRetry: false,\n  };\n}\n"],"mappings":"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","names":["import_core","param"]}

package/dist/http/index.d.cts

@@ -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 };