@pafi-dev/issuer 0.31.0 → 0.32.0

package/dist/index.d.cts

@@ -1551,9 +1551,18 @@ interface SettlementClientConfig {
     /**
      * chainId — used to derive the issuer-api base URL via
      * `getPafiServiceUrls(chainId).issuerApi`. SDK ships with the URL
-     * per chainId; bump SDK version to retarget.
+     * per chainId; bump SDK version to retarget — OR pass `baseUrl`
+     * to override per-deployment.
      */
     chainId: number;
+    /**
+     * Optional override for the issuer-api base URL. Audit PACI5-17 —
+     * production issuer backends should set this from an env var
+     * (e.g. `PAFI_ISSUER_API_URL`) so the deployed binary doesn't
+     * depend on the SDK ship-default that may target dev infrastructure.
+     * Undefined / empty → use the ship-default for `chainId`.
+     */
+    baseUrl?: string;
     /** PAFI-assigned issuer id used in `X-Issuer-Id` header. */
     issuerId: string;
     /** Raw API key sent as `Authorization: Bearer <apiKey>`. */
@@ -1566,6 +1575,34 @@ interface SettlementClientConfig {
 interface PolicyProviderConfig extends SettlementClientConfig {
     /** Cache TTL in milliseconds. Default 5 * 60 * 1000 (5min). */
     cacheTtlMs?: number;
+    /**
+     * Behavior khi settlement-api fetch fail (network blip, 5xx, timeout).
+     *
+     * Audit PACI5-17 — the pre-flight redeem limit is the SOLE gate
+     * before the issuer signer mints a BurnRequest. Silently degrading
+     * to a permissive default during settlement outages let users
+     * exceed their configured limit until the outage cleared.
+     *
+     *  - `'fail-closed'` (DEFAULT, recommended): throw
+     *    `PolicyProviderUnavailableError`. Caller maps to HTTP 503 so
+     *    the FE can retry; redemptions are blocked until policy fetch
+     *    succeeds.
+     *
+     *  - `'permissive-default'`: return `defaultPolicyFor(issuerId)` and
+     *    fire `onWarning`. Pre-fix behavior. Operators who genuinely
+     *    prefer availability over enforcement (e.g. test issuers, low-
+     *    risk PT) MUST opt in explicitly AND wire `onWarning` to a
+     *    pager / Slack / Sentry alert. Silent permissive fallback is no
+     *    longer the default.
+     */
+    onFetchFailure?: "fail-closed" | "permissive-default";
+    /**
+     * Observability hook for non-fatal events: permissive-default
+     * fallbacks (when explicitly opted in). Wire to your logger /
+     * Sentry / Datadog so the `policy_provider_fallback` event reaches
+     * the on-call dashboard.
+     */
+    onWarning?: (msg: string, ctx: Record<string, unknown>) => void;
     /**
      * Optional clock for testability. Returns unix milliseconds.
      * Defaults to () => Date.now().
@@ -1596,6 +1633,8 @@ declare class PolicyProvider {
     private readonly client;
     private readonly issuerId;
     private readonly cacheTtlMs;
+    private readonly onFetchFailure;
+    private readonly onWarning?;
     private readonly now;
     private cache;
     private inflight;
@@ -1987,7 +2026,7 @@ interface PTRedeemResponse {
     /** The BurnRequest deadline (unix seconds) — FE uses this to surface a countdown. */
     signatureDeadline: bigint;
 }
-type PTRedeemErrorCode = "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED" | "REDEMPTION_POLICY_DENIED" | "UNSUPPORTED_POINT_TOKEN";
+type PTRedeemErrorCode = "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED" | "REDEMPTION_POLICY_DENIED" | "REDEMPTION_POLICY_UNAVAILABLE" | "UNSUPPORTED_POINT_TOKEN";
 declare class PTRedeemError extends PafiSdkError {
     readonly httpStatus: "unprocessable";
     readonly code: PTRedeemErrorCode;
@@ -2039,9 +2078,18 @@ interface PafiBackendConfig {
     /**
      * chainId — used to derive the sponsor-relayer base URL via
      * `getPafiServiceUrls(chainId).sponsorRelayer`. SDK ships with the
-     * URL per chainId; bump SDK version to retarget.
+     * URL per chainId; bump SDK version to retarget — OR pass
+     * `baseUrl` to override per-deployment.
      */
     chainId: number;
+    /**
+     * Optional override for the sponsor-relayer base URL. Audit
+     * PACI5-17 — production issuer backends should set this from an env
+     * var (e.g. `PAFI_SPONSOR_RELAYER_URL`) so the binary doesn't depend
+     * on the SDK ship-default that may target dev infrastructure.
+     * Undefined / empty → use the ship-default for `chainId`.
+     */
+    baseUrl?: string;
     issuerId: string;
     apiKey: string;
     fetchImpl?: typeof fetch;
@@ -3185,6 +3233,30 @@ interface IssuerServiceConfig {
         issuerId: string;
         apiKey: string;
         historyStore: IRedemptionHistoryStore;
+        /**
+         * Optional override for the PAFI issuer-api base URL. Audit
+         * PACI5-17 — production issuer backends should set this from an
+         * env var (e.g. `PAFI_ISSUER_API_URL`) so policy fetch hits the
+         * canonical environment for the deploy. Undefined → SDK
+         * ship-default per chainId.
+         */
+        baseUrl?: string;
+        /**
+         * Behavior khi settlement-api fetch fail. Default `'fail-closed'`
+         * (audit PACI5-17 — pre-flight redeem limit is the sole gate; do
+         * not silently degrade to a permissive default).
+         *
+         * Opt in to `'permissive-default'` ONLY when paired with an alert
+         * on the `policy_provider_fallback` event surfaced via
+         * `onPolicyWarning`.
+         */
+        onFetchFailure?: "fail-closed" | "permissive-default";
+        /**
+         * Observability hook for `policy_provider_fallback` events. Wire
+         * to your logger / Sentry / Datadog so the on-call dashboard sees
+         * settlement-api degradation.
+         */
+        onPolicyWarning?: (msg: string, ctx: Record<string, unknown>) => void;
         /** Override fetch (testing). */
         fetchImpl?: typeof fetch;
         /** Per-fetch timeout in ms. Default 1000. */
@@ -3354,12 +3426,6 @@ interface RedeemPrepareDto extends MobilePrepareDto {
      * Lock id reserved for the FALLBACK redeem path (= full `amount`).
      * Mobile FE polls `/redeem/status/:lockIdFallback` when it submits
      * the fallback variant (`variant: 'fallback'` on `/redeem/submit`).
-     *
-     * Audit PACI5-21 — pre-fix the adapter exposed only the sponsored
-     * `lockId` (= `amount - fee`), so the bundler-receipt fallback in
-     * `handleRedeemStatus` resolved the smaller credit against the
-     * on-chain burn of the full amount → user under-credited by exactly
-     * the fee on every fallback redeem.
      */
     lockIdFallback?: string;
 }

package/dist/index.d.ts

@@ -1551,9 +1551,18 @@ interface SettlementClientConfig {
     /**
      * chainId — used to derive the issuer-api base URL via
      * `getPafiServiceUrls(chainId).issuerApi`. SDK ships with the URL
-     * per chainId; bump SDK version to retarget.
+     * per chainId; bump SDK version to retarget — OR pass `baseUrl`
+     * to override per-deployment.
      */
     chainId: number;
+    /**
+     * Optional override for the issuer-api base URL. Audit PACI5-17 —
+     * production issuer backends should set this from an env var
+     * (e.g. `PAFI_ISSUER_API_URL`) so the deployed binary doesn't
+     * depend on the SDK ship-default that may target dev infrastructure.
+     * Undefined / empty → use the ship-default for `chainId`.
+     */
+    baseUrl?: string;
     /** PAFI-assigned issuer id used in `X-Issuer-Id` header. */
     issuerId: string;
     /** Raw API key sent as `Authorization: Bearer <apiKey>`. */
@@ -1566,6 +1575,34 @@ interface SettlementClientConfig {
 interface PolicyProviderConfig extends SettlementClientConfig {
     /** Cache TTL in milliseconds. Default 5 * 60 * 1000 (5min). */
     cacheTtlMs?: number;
+    /**
+     * Behavior khi settlement-api fetch fail (network blip, 5xx, timeout).
+     *
+     * Audit PACI5-17 — the pre-flight redeem limit is the SOLE gate
+     * before the issuer signer mints a BurnRequest. Silently degrading
+     * to a permissive default during settlement outages let users
+     * exceed their configured limit until the outage cleared.
+     *
+     *  - `'fail-closed'` (DEFAULT, recommended): throw
+     *    `PolicyProviderUnavailableError`. Caller maps to HTTP 503 so
+     *    the FE can retry; redemptions are blocked until policy fetch
+     *    succeeds.
+     *
+     *  - `'permissive-default'`: return `defaultPolicyFor(issuerId)` and
+     *    fire `onWarning`. Pre-fix behavior. Operators who genuinely
+     *    prefer availability over enforcement (e.g. test issuers, low-
+     *    risk PT) MUST opt in explicitly AND wire `onWarning` to a
+     *    pager / Slack / Sentry alert. Silent permissive fallback is no
+     *    longer the default.
+     */
+    onFetchFailure?: "fail-closed" | "permissive-default";
+    /**
+     * Observability hook for non-fatal events: permissive-default
+     * fallbacks (when explicitly opted in). Wire to your logger /
+     * Sentry / Datadog so the `policy_provider_fallback` event reaches
+     * the on-call dashboard.
+     */
+    onWarning?: (msg: string, ctx: Record<string, unknown>) => void;
     /**
      * Optional clock for testability. Returns unix milliseconds.
      * Defaults to () => Date.now().
@@ -1596,6 +1633,8 @@ declare class PolicyProvider {
     private readonly client;
     private readonly issuerId;
     private readonly cacheTtlMs;
+    private readonly onFetchFailure;
+    private readonly onWarning?;
     private readonly now;
     private cache;
     private inflight;
@@ -1987,7 +2026,7 @@ interface PTRedeemResponse {
     /** The BurnRequest deadline (unix seconds) — FE uses this to surface a countdown. */
     signatureDeadline: bigint;
 }
-type PTRedeemErrorCode = "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED" | "REDEMPTION_POLICY_DENIED" | "UNSUPPORTED_POINT_TOKEN";
+type PTRedeemErrorCode = "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED" | "REDEMPTION_POLICY_DENIED" | "REDEMPTION_POLICY_UNAVAILABLE" | "UNSUPPORTED_POINT_TOKEN";
 declare class PTRedeemError extends PafiSdkError {
     readonly httpStatus: "unprocessable";
     readonly code: PTRedeemErrorCode;
@@ -2039,9 +2078,18 @@ interface PafiBackendConfig {
     /**
      * chainId — used to derive the sponsor-relayer base URL via
      * `getPafiServiceUrls(chainId).sponsorRelayer`. SDK ships with the
-     * URL per chainId; bump SDK version to retarget.
+     * URL per chainId; bump SDK version to retarget — OR pass
+     * `baseUrl` to override per-deployment.
      */
     chainId: number;
+    /**
+     * Optional override for the sponsor-relayer base URL. Audit
+     * PACI5-17 — production issuer backends should set this from an env
+     * var (e.g. `PAFI_SPONSOR_RELAYER_URL`) so the binary doesn't depend
+     * on the SDK ship-default that may target dev infrastructure.
+     * Undefined / empty → use the ship-default for `chainId`.
+     */
+    baseUrl?: string;
     issuerId: string;
     apiKey: string;
     fetchImpl?: typeof fetch;
@@ -3185,6 +3233,30 @@ interface IssuerServiceConfig {
         issuerId: string;
         apiKey: string;
         historyStore: IRedemptionHistoryStore;
+        /**
+         * Optional override for the PAFI issuer-api base URL. Audit
+         * PACI5-17 — production issuer backends should set this from an
+         * env var (e.g. `PAFI_ISSUER_API_URL`) so policy fetch hits the
+         * canonical environment for the deploy. Undefined → SDK
+         * ship-default per chainId.
+         */
+        baseUrl?: string;
+        /**
+         * Behavior khi settlement-api fetch fail. Default `'fail-closed'`
+         * (audit PACI5-17 — pre-flight redeem limit is the sole gate; do
+         * not silently degrade to a permissive default).
+         *
+         * Opt in to `'permissive-default'` ONLY when paired with an alert
+         * on the `policy_provider_fallback` event surfaced via
+         * `onPolicyWarning`.
+         */
+        onFetchFailure?: "fail-closed" | "permissive-default";
+        /**
+         * Observability hook for `policy_provider_fallback` events. Wire
+         * to your logger / Sentry / Datadog so the on-call dashboard sees
+         * settlement-api degradation.
+         */
+        onPolicyWarning?: (msg: string, ctx: Record<string, unknown>) => void;
         /** Override fetch (testing). */
         fetchImpl?: typeof fetch;
         /** Per-fetch timeout in ms. Default 1000. */
@@ -3354,12 +3426,6 @@ interface RedeemPrepareDto extends MobilePrepareDto {
      * Lock id reserved for the FALLBACK redeem path (= full `amount`).
      * Mobile FE polls `/redeem/status/:lockIdFallback` when it submits
      * the fallback variant (`variant: 'fallback'` on `/redeem/submit`).
-     *
-     * Audit PACI5-21 — pre-fix the adapter exposed only the sponsored
-     * `lockId` (= `amount - fee`), so the bundler-receipt fallback in
-     * `handleRedeemStatus` resolved the smaller credit against the
-     * on-chain burn of the full amount → user under-credited by exactly
-     * the fee on every fallback redeem.
      */
     lockIdFallback?: string;
 }

package/dist/index.js

@@ -2190,11 +2190,23 @@ var PTRedeemHandler = class {
       );
     }
     if (this.redemptionService) {
-      const decision = await this.redemptionService.evaluate(
-        request.userAddress,
-        request.amount,
-        pointTokenAddress
-      );
+      let decision;
+      try {
+        decision = await this.redemptionService.evaluate(
+          request.userAddress,
+          request.amount,
+          pointTokenAddress
+        );
+      } catch (err) {
+        const code = err && typeof err === "object" && "code" in err ? err.code : void 0;
+        if (code === "POLICY_PROVIDER_UNAVAILABLE") {
+          throw new PTRedeemError(
+            "REDEMPTION_POLICY_UNAVAILABLE",
+            "Redemption policy temporarily unavailable \u2014 please try again shortly."
+          );
+        }
+        throw err;
+      }
       if (!decision.allowed) {
         const denial = decision.denial;
         throw new PTRedeemError(
@@ -3682,10 +3694,6 @@ var IssuerApiAdapter = class {
       pointTokenAddress,
       redeemResponse.expiresInSeconds,
       input.eip7702Auth,
-      // Audit PACI5-21 — fallback path reserves a separate
-      // PendingCredit row for the full `amount`. Surface its lockId so
-      // mobile FE can poll the correct row + `handleMobileSubmit`
-      // routes the userOpHash bind to it on fallback submit.
       redeemResponse.fallback?.lockId
     );
     return {
@@ -4264,7 +4272,9 @@ var PafiBackendClient = class {
     if (!config.issuerId) throw new Error("PafiBackendClient: issuerId is required");
     if (!config.apiKey) throw new Error("PafiBackendClient: apiKey is required");
     this.config = config;
-    this.baseUrl = getPafiServiceUrls(config.chainId).sponsorRelayer;
+    this.baseUrl = getPafiServiceUrls(config.chainId, {
+      sponsorRelayer: config.baseUrl
+    }).sponsorRelayer;
   }
   async requestSponsorship(request) {
     const maxAttempts = this.config.retry?.maxAttempts ?? 1;
@@ -4529,6 +4539,9 @@ function nextBlackoutEndAfter(windows, nowUnixSec) {
 }
 var REDEMPTION_HISTORY_WINDOW_SEC = SECONDS_PER_DAY;
 
+// src/redemption/policyProvider.ts
+import { PafiSdkError as PafiSdkError2 } from "@pafi-dev/core";
+
 // src/redemption/settlementClient.ts
 import {
   getPafiServiceUrls as getPafiServiceUrls2
@@ -4541,7 +4554,12 @@ var SettlementClient = class {
     if (!config.issuerId) throw new Error("SettlementClient: issuerId is required");
     if (!config.apiKey) throw new Error("SettlementClient: apiKey is required");
     this.config = {
-      baseUrl: getPafiServiceUrls2(config.chainId).issuerApi.replace(/\/+$/, ""),
+      // Audit PACI5-17 — honor optional baseUrl override wired from
+      // an env var (e.g. PAFI_ISSUER_API_URL). Empty / undefined →
+      // ship-default for chainId.
+      baseUrl: getPafiServiceUrls2(config.chainId, {
+        issuerApi: config.baseUrl
+      }).issuerApi.replace(/\/+$/, ""),
       issuerId: config.issuerId,
       apiKey: config.apiKey,
       fetchTimeoutMs: config.fetchTimeoutMs ?? DEFAULT_TIMEOUT_MS,
@@ -4645,10 +4663,23 @@ function defaultPolicyFor(issuerId) {
 
 // src/redemption/policyProvider.ts
 var DEFAULT_CACHE_TTL_MS3 = 5 * 60 * 1e3;
+var PolicyProviderUnavailableError = class extends PafiSdkError2 {
+  code = "POLICY_PROVIDER_UNAVAILABLE";
+  httpStatus = "service_unavailable";
+  details;
+  constructor(issuerId, reason) {
+    super(
+      `Redemption policy provider unavailable for issuer ${issuerId}: ${reason}. Pre-flight redeem limit cannot be enforced \u2014 refusing to sign BurnRequest. Mobile FE: surface "try again shortly" and retry with backoff.`
+    );
+    this.details = { issuerId, reason };
+  }
+};
 var PolicyProvider = class {
   client;
   issuerId;
   cacheTtlMs;
+  onFetchFailure;
+  onWarning;
   now;
   cache = null;
   inflight = null;
@@ -4656,6 +4687,8 @@ var PolicyProvider = class {
     this.client = new SettlementClient(config);
     this.issuerId = config.issuerId;
     this.cacheTtlMs = config.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS3;
+    this.onFetchFailure = config.onFetchFailure ?? "fail-closed";
+    this.onWarning = config.onWarning;
     this.now = config.now ?? (() => Date.now());
   }
   async getPolicy() {
@@ -4688,7 +4721,19 @@ var PolicyProvider = class {
       };
       return { policy: result.policy, source: "settlement" };
     }
-    return { policy: defaultPolicyFor(this.issuerId), source: "default" };
+    const reason = "reason" in result && typeof result.reason === "string" ? result.reason : "unknown";
+    if (this.onFetchFailure === "permissive-default") {
+      this.onWarning?.(
+        "PolicyProvider: settlement-api unreachable, falling back to permissive default. Pre-flight redeem limit is DEGRADED until settlement-api recovers.",
+        {
+          event: "policy_provider_fallback",
+          issuerId: this.issuerId,
+          reason
+        }
+      );
+      return { policy: defaultPolicyFor(this.issuerId), source: "default" };
+    }
+    throw new PolicyProviderUnavailableError(this.issuerId, reason);
   }
 };
 
@@ -4835,6 +4880,15 @@ async function createIssuerService(config) {
       issuerId: config.redemption.issuerId,
       apiKey: config.redemption.apiKey
     };
+    if (config.redemption.baseUrl) {
+      policyConfig.baseUrl = config.redemption.baseUrl;
+    }
+    if (config.redemption.onFetchFailure) {
+      policyConfig.onFetchFailure = config.redemption.onFetchFailure;
+    }
+    if (config.redemption.onPolicyWarning) {
+      policyConfig.onWarning = config.redemption.onPolicyWarning;
+    }
     if (config.redemption.fetchImpl) policyConfig.fetchImpl = config.redemption.fetchImpl;
     if (config.redemption.fetchTimeoutMs !== void 0) {
       policyConfig.fetchTimeoutMs = config.redemption.fetchTimeoutMs;
@@ -5099,7 +5153,7 @@ var MemoryRedemptionHistoryStore = class {
 };
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = true ? "0.31.0" : "dev";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.32.0" : "dev";
 export {
   AdapterMisconfiguredError,
   AuthError,