@pafi-dev/issuer 0.7.9 → 0.9.0

package/dist/index.d.cts

@@ -1,16 +1,14 @@
-import { PafiSdkError, SdkErrorHttpStatus, PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, UserOpTypedData, decodeBatchExecuteCalls, BROKER_HASHES, BuiltSponsorAuth, ENTRY_POINT_V08 } from '@pafi-dev/core';
-export { PAFI_SUBGRAPH_URL, PafiSdkError, SdkErrorHttpStatus, ValidationError } from '@pafi-dev/core';
+import { PafiSdkError, SdkErrorHttpStatus, PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, RedemptionPolicy, RedemptionPolicySource, RedemptionPreview, RedemptionDecision, RedemptionDenialCode, UserOpTypedData, decodeBatchExecuteCalls, BROKER_HASHES, PafiErrorType, BuiltSponsorAuth, ENTRY_POINT_V08 } from '@pafi-dev/core';
+export { PAFI_SUBGRAPH_URL, PafiErrorType, PafiSdkError, SDK_ERROR_HTTP_STATUS_CODE, SdkErrorHttpStatus, ValidationError, defaultErrorTypeForStatus } from '@pafi-dev/core';
+export { GenericHttpExceptionDescriptor, NormalizeContext, PafiErrorEnvelope, PafiErrorPayload, buildErrorEnvelope, payloadFromGenericError, payloadFromHttpException, payloadFromPafiSdkError } from './http/index.cjs';
 import { Address, Hex, PublicClient, WalletClient } from 'viem';
 
 /**
- * v0.7.4 — `PafiSdkError` + `SdkErrorHttpStatus` were moved to
+ * `PafiSdkError` + `SdkErrorHttpStatus` are exported from
  * `@pafi-dev/core/errors` so core-level errors (e.g. `OracleStaleError`)
- * can extend the same base. Issuer re-exports the canonical types
- * here for back-compat. See SDK_CORE_TRADING_AUDIT.md H3.
- *
- * Effect: `instanceof PafiSdkError` from EITHER package now catches
- * errors thrown from EITHER package — no more silent fall-through to
- * 500 for core-thrown errors.
+ * can extend the same base. Issuer re-exports the canonical types here
+ * for back-compat — `instanceof PafiSdkError` from EITHER package
+ * catches errors thrown from EITHER package.
  */
 
 /**
@@ -19,8 +17,6 @@ import { Address, Hex, PublicClient, WalletClient } from 'viem';
  * `/pools` called but `poolsProvider` not configured). 503 because
  * the endpoint genuinely can't serve the request — caller's payload
  * is fine, the issuer's deployment is incomplete.
- *
- * v0.7.1 — added per SDK_ISSUER_AUDIT.md H1.
  */
 declare class ConfigurationError extends PafiSdkError {
     readonly httpStatus: "service_unavailable";
@@ -293,6 +289,15 @@ interface MemorySessionStoreOptions {
     nonceTtlMs?: number;
     /** Clock override for tests. */
     now?: () => number;
+    /**
+     * Bypass the production-safety guard. By default, instantiating
+     * `MemorySessionStore` when `process.env.NODE_ENV === "production"`
+     * THROWS — multi-pod K8s deploys do not share Map state, so sessions
+     * are not revocable across replicas, and tokens remain valid on pod
+     * B after `logout` on pod A. Only set this `true` for single-pod
+     * deployments where you've consciously accepted the trade-off.
+     */
+    dangerouslyAllowMemoryStoreInProduction?: boolean;
 }
 /**
  * In-memory `ISessionStore` — Map-backed nonces and sessions with lazy
@@ -351,6 +356,21 @@ interface AuthServiceConfig {
     domain: string;
     /** Expected chain id. */
     chainId: number;
+    /**
+     * Optional `iss` (issuer) claim baked into JWTs and validated on
+     * verify. Recommended for multi-issuer deployments to prevent
+     * cross-validation if a JWT secret is accidentally shared. Examples:
+     * `"gg56-issuer"`, `"issuer.gg56.com"`. When unset, no `iss` is
+     * written or required (back-compat).
+     */
+    issuer?: string;
+    /**
+     * Optional `aud` (audience) claim baked into JWTs and validated on
+     * verify. Recommended to bind tokens to a specific consumer, e.g.
+     * `"gg56-mobile"` or `"gg56-web"`. When unset, no `aud` is written
+     * or required (back-compat).
+     */
+    audience?: string;
     /** Clock override for tests. */
     now?: () => Date;
 }
@@ -384,6 +404,8 @@ declare class AuthService {
     private readonly jwtExpiresIn;
     private readonly domain;
     private readonly chainId;
+    private readonly issuer?;
+    private readonly audience?;
     private readonly nonceManager;
     private readonly now;
     constructor(config: AuthServiceConfig);
@@ -396,6 +418,7 @@ declare class AuthService {
     login(message: string, signature: Hex): Promise<LoginResult>;
     /** Revoke the session backing the given JWT (logout). */
     logout(token: string): Promise<void>;
+    private logSessionStoreError;
     /**
      * Verify a JWT and return the authenticated user context. Throws an
      * `AuthError` if the token is missing, malformed, expired, revoked, or
@@ -421,10 +444,9 @@ declare function authenticateRequest(authHeader: string | undefined, authService
  */
 type AuthErrorCode = "INVALID_MESSAGE" | "DOMAIN_MISMATCH" | "CHAIN_MISMATCH" | "NONCE_INVALID" | "MESSAGE_EXPIRED" | "MESSAGE_NOT_YET_VALID" | "SIGNATURE_INVALID" | "MISSING_TOKEN" | "MALFORMED_TOKEN" | "TOKEN_INVALID" | "TOKEN_EXPIRED" | "SESSION_REVOKED";
 /**
- * v0.7.1 — extends `PafiSdkError` so issuer controllers can route auth
- * failures through the same `createSdkErrorMapper` as everything else.
- * Previously caller had to wire `instanceof AuthError` separately. See
- * SDK_ISSUER_AUDIT.md H2.
+ * Extends `PafiSdkError` so issuer controllers can route auth failures
+ * through the same `createSdkErrorMapper` as everything else (no
+ * separate `instanceof AuthError` check needed).
  */
 declare class AuthError extends PafiSdkError {
     readonly code: AuthErrorCode;
@@ -432,6 +454,88 @@ declare class AuthError extends PafiSdkError {
     constructor(code: AuthErrorCode, message: string);
 }
 
+/**
+ * Per-key rate limiting for unauthenticated public endpoints.
+ *
+ * `/auth/nonce` and `/auth/login` are unauthenticated and CPU-bound
+ * (SIWE message parsing + ECDSA `recover`), so without rate limiting
+ * an attacker can saturate the issuer at low cost. Worse, on
+ * `/auth/nonce` they can flood the session store with single-use
+ * nonces; with `MemorySessionStore` this is a pure DoS.
+ *
+ * Issuers wire a `IRateLimiter` impl in `IssuerApiHandlersConfig` —
+ * `MemoryRateLimiter` is the default reference impl (single-pod, dev).
+ * Production deployments use a Redis-backed impl that shares state
+ * across replicas (similar pattern to `ISessionStore`).
+ *
+ * The "key" is up to the caller — typically the client IP, but the
+ * issuer's HTTP layer chooses (could be userAddress on POST /login).
+ */
+interface IRateLimiter {
+    /**
+     * Check + increment a counter under `key`. Returns `{ allowed: false,
+     * retryAfterMs }` when the caller has exceeded its quota for this
+     * window. Default config is action-specific (see
+     * `RateLimiterConfig`).
+     *
+     * Idempotent in the sense that successive calls with the same `key`
+     * within the same window count toward the limit; a separate window
+     * starts after `windowMs` elapses.
+     */
+    consume(key: string, action: RateLimitAction): Promise<{
+        allowed: boolean;
+        retryAfterMs?: number;
+    }>;
+}
+type RateLimitAction = "auth_nonce" | "auth_login";
+interface RateLimiterConfig {
+    /**
+     * Per-key max requests per `windowMs`. Defaults:
+     *   - auth_nonce:  1 per 2s (30/min)
+     *   - auth_login:  5 per minute
+     *
+     * Issuers can tune per their threat model.
+     */
+    limits?: Partial<Record<RateLimitAction, {
+        max: number;
+        windowMs: number;
+    }>>;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+/**
+ * In-memory `IRateLimiter` — Map of `{key, action}` → count + window
+ * start. Lazy expiry on read. Single-process: NOT safe for multi-pod
+ * deployments. Use a Redis impl in production.
+ */
+declare class MemoryRateLimiter implements IRateLimiter {
+    private buckets;
+    private readonly limits;
+    private readonly now;
+    constructor(config?: RateLimiterConfig);
+    consume(key: string, action: RateLimitAction): Promise<{
+        allowed: boolean;
+        retryAfterMs?: number;
+    }>;
+    /**
+     * Test helper — clear all buckets. Not part of `IRateLimiter`; only
+     * exposed on the in-memory impl for unit tests.
+     */
+    reset(): void;
+}
+/**
+ * Convenience: a no-op `IRateLimiter` that lets every request through.
+ * Useful as a default in `IssuerApiHandlersConfig` when the issuer
+ * hasn't wired a rate limiter yet (back-compat) — emits a one-time
+ * warning at construction so consumers notice.
+ */
+declare class NoopRateLimiter implements IRateLimiter {
+    private warned;
+    consume(): Promise<{
+        allowed: boolean;
+    }>;
+}
+
 type RelayErrorCode = "ENCODE_FAILED";
 declare class RelayError extends PafiSdkError {
     readonly httpStatus: "unprocessable";
@@ -724,6 +828,16 @@ interface PointIndexerConfig {
     pollIntervalMs?: number;
     /** Clock override for tests. */
     now?: () => number;
+    /**
+     * Observability hook fired on EVERY tick error (RPC failure, ledger
+     * write failure, etc). Issuers MUST wire this to their alert
+     * pipeline (Sentry / Datadog / PagerDuty) — without it, the indexer
+     * silently swallows errors via `console.error`, and indexer outage
+     * means PENDING mint locks never resolve (user balances stuck).
+     *
+     * When omitted, falls back to `console.error` for back-compat.
+     */
+    onTickError?: (err: unknown) => void;
 }
 /**
  * Watches `PointToken.Transfer(from=0x0 → to)` events and finalizes the
@@ -755,6 +869,7 @@ declare class PointIndexer {
     private readonly confirmations;
     private readonly batchSize;
     private readonly pollIntervalMs;
+    private readonly onTickError?;
     private running;
     private timer;
     constructor(config: PointIndexerConfig);
@@ -768,6 +883,7 @@ declare class PointIndexer {
      * schedules the next tick. Visible for test harnesses via a public name.
      */
     tick(): Promise<void>;
+    private handleTickError;
     private scheduleNext;
     /**
      * Scan `[from, to]` inclusive for mint events in `batchSize` chunks.
@@ -816,6 +932,13 @@ interface BurnIndexerConfig {
      * ledger uses a lookup by lockId supplied out-of-band from the claim flow.
      */
     matchLockId: (event: BurnEvent) => Promise<string | undefined>;
+    /**
+     * Observability hook — see PointIndexerConfig.onTickError for full
+     * rationale. Critical for burn indexer too: silent failure means
+     * pending credits never resolve, user reports "I burned my PT but
+     * never got my off-chain credit".
+     */
+    onTickError?: (err: unknown) => void;
 }
 /**
  * Mirror of `PointIndexer` for the reverse direction — watches
@@ -846,6 +969,7 @@ declare class BurnIndexer {
     private readonly confirmations;
     private readonly batchSize;
     private readonly pollIntervalMs;
+    private readonly onTickError?;
     matchLockId: (event: BurnEvent) => Promise<string | undefined>;
     private running;
     private timer;
@@ -853,6 +977,7 @@ declare class BurnIndexer {
     start(): void;
     stop(): void;
     tick(): Promise<void>;
+    private handleTickError;
     private scheduleNext;
     /**
      * Scan `[from, to]` inclusive for burn events. Callers can drive this
@@ -975,8 +1100,161 @@ interface ApiUserResponse {
     balance: bigint;
     isMinter: boolean;
 }
+interface ApiRedemptionPreviewRequest {
+    pointTokenAddress?: Address;
+}
+interface ApiRedemptionPreviewResponse {
+    availableAmountPt: bigint;
+    dailyRemainingPt: bigint;
+    cooldownUntilUnixSec: number | null;
+    nextBlackoutEndsAtUnixSec: number | null;
+    perTxMinPt: bigint;
+    perTxMaxPt: bigint;
+    policyVersion: string;
+    policySource: "settlement" | "cache" | "default";
+}
+interface ApiRedemptionEvaluateRequest {
+    amountPt: bigint;
+    pointTokenAddress?: Address;
+}
+interface ApiRedemptionEvaluateResponse {
+    allowed: boolean;
+    denial?: {
+        code: "AMOUNT_BELOW_MIN" | "AMOUNT_ABOVE_MAX" | "DAILY_LIMIT_EXCEEDED" | "COOLDOWN_ACTIVE" | "BLACKOUT_WINDOW";
+        message: string;
+    };
+    preview: ApiRedemptionPreviewResponse;
+}
 type PoolsProvider = (request: ApiPoolsRequest) => Promise<ApiPoolsResponse>;
 
+/**
+ * Per-user redemption history needed by the evaluator. The issuer can
+ * implement this with their existing burn audit table (preferred) or
+ * use the bundled MemoryRedemptionHistoryStore for tests.
+ */
+interface IRedemptionHistoryStore {
+    /**
+     * Sum of PT redeemed by `user` from `sinceUnixSec` onwards. Used for
+     * the rolling 24h daily-limit check. MUST count both confirmed burns
+     * and currently-reserved-pending entries — the policy treats reserved
+     * burns as "spent" so a flood of pending requests can't bypass the cap.
+     */
+    sumRedeemedSince(user: Address, sinceUnixSec: number, pointTokenAddress?: Address): Promise<bigint>;
+    /**
+     * Unix-second timestamp of the user's last redemption attempt
+     * (confirmed or reserved). null if never. Used for cooldown.
+     */
+    getLastRedeemedAtUnixSec(user: Address, pointTokenAddress?: Address): Promise<number | null>;
+    /**
+     * Record a new redemption attempt. Called by handleRedemptionInitiate
+     * AFTER policy.evaluate() returns ALLOW and the BurnRequest is signed.
+     * Implementations may persist this row in a redemption_history table or
+     * derive from existing pending-credit reservations.
+     */
+    recordRedemption(entry: {
+        user: Address;
+        amountPt: bigint;
+        pointTokenAddress?: Address;
+        unixSec: number;
+        /** Optional pointer back to the reservation lock id. */
+        reservationId?: string;
+    }): Promise<void>;
+}
+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.
+     */
+    chainId: number;
+    /** PAFI-assigned issuer id used in `X-Issuer-Id` header. */
+    issuerId: string;
+    /** Raw API key sent as `Authorization: Bearer <apiKey>`. */
+    apiKey: string;
+    /** Per-request timeout in milliseconds. Default 1000. */
+    fetchTimeoutMs?: number;
+    /** Override fetch (testing). */
+    fetchImpl?: typeof fetch;
+}
+interface PolicyProviderConfig extends SettlementClientConfig {
+    /** Cache TTL in milliseconds. Default 5 * 60 * 1000 (5min). */
+    cacheTtlMs?: number;
+    /**
+     * Optional clock for testability. Returns unix milliseconds.
+     * Defaults to () => Date.now().
+     */
+    now?: () => number;
+}
+
+interface ResolvedPolicy {
+    policy: RedemptionPolicy;
+    source: RedemptionPolicySource;
+}
+/**
+ * Wraps SettlementClient with a 5-minute TTL cache and a hardcoded
+ * default fallback. Single-flight: concurrent getPolicy() calls during
+ * a cache miss share the same in-flight request.
+ *
+ * Resolution order:
+ *   1. fresh cache hit            → return cached
+ *   2. cache miss → fetch ok      → cache + return (source=settlement)
+ *   3. cache miss → fetch failed  → DEFAULT_REDEMPTION_POLICY (source=default)
+ *
+ * Stale cache is NEVER returned — once the TTL expires we either fetch
+ * fresh data or fall through to default. This keeps behavior predictable:
+ * "default" means "we couldn't talk to settlement RIGHT NOW", not "we got
+ * lucky with a stale entry".
+ */
+declare class PolicyProvider {
+    private readonly client;
+    private readonly issuerId;
+    private readonly cacheTtlMs;
+    private readonly now;
+    private cache;
+    private inflight;
+    constructor(config: PolicyProviderConfig);
+    getPolicy(): Promise<ResolvedPolicy>;
+    /** Drop cached policy. Next getPolicy() will refetch. */
+    invalidate(): void;
+    private readCache;
+    private fetchAndStore;
+}
+
+interface RedemptionServiceConfig {
+    policyProvider: PolicyProvider | PolicyProviderConfig;
+    historyStore: IRedemptionHistoryStore;
+    /** Defaults to () => Math.floor(Date.now() / 1000). */
+    nowUnixSec?: () => number;
+}
+/**
+ * High-level facade used by HTTP handlers. Combines PolicyProvider +
+ * IRedemptionHistoryStore into preview/evaluate operations.
+ *
+ *   preview(user)                → RedemptionPreview (no amount required)
+ *   evaluate(user, amount)       → RedemptionDecision
+ *   recordSuccessfulInitiate(..) → call AFTER signing the BurnRequest
+ *
+ * Note: this service does NOT mutate anything during evaluate(). The
+ * caller must call recordSuccessfulInitiate() after the BurnRequest is
+ * signed and the pending credit is reserved on the ledger. Splitting
+ * "decide" from "record" lets the handler atomically reserve + record
+ * under one DB transaction if it wants.
+ */
+declare class RedemptionService {
+    private readonly policyProvider;
+    private readonly historyStore;
+    private readonly nowUnixSec;
+    constructor(config: RedemptionServiceConfig);
+    preview(user: Address, pointTokenAddress?: Address): Promise<RedemptionPreview>;
+    evaluate(user: Address, amountPt: bigint, pointTokenAddress?: Address): Promise<RedemptionDecision>;
+    recordSuccessfulInitiate(entry: {
+        user: Address;
+        amountPt: bigint;
+        pointTokenAddress?: Address;
+        reservationId?: string;
+    }): Promise<void>;
+}
+
 interface IssuerApiHandlersConfig {
     authService: AuthService;
     ledger: IPointLedger;
@@ -1004,6 +1282,19 @@ interface IssuerApiHandlersConfig {
     feeManager?: FeeManager;
     /** Required by `handlePools`; omit to disable the endpoint. */
     poolsProvider?: PoolsProvider;
+    /**
+     * Required by `handleRedemptionPreview` / `handleRedemptionEvaluate`;
+     * omit to disable both. Wired by createIssuerService when the top-level
+     * `redemption` config is provided.
+     */
+    redemption?: RedemptionService;
+    /**
+     * Rate limiter for `/auth/nonce` and `/auth/login` (both unauthenticated +
+     * CPU-bound). When omitted, defaults to a `NoopRateLimiter` that lets
+     * every request through (with a one-time prod warning) — issuers MUST
+     * wire a real impl in production.
+     */
+    rateLimiter?: IRateLimiter;
 }
 /**
  * Framework-agnostic HTTP handlers that match the endpoints a `PafiSDK`
@@ -1030,11 +1321,27 @@ declare class IssuerApiHandlers {
     private readonly pafiWebUrl?;
     private readonly feeManager?;
     private readonly poolsProvider?;
+    private readonly redemption?;
+    private readonly rateLimiter;
     constructor(config: IssuerApiHandlersConfig);
-    /** `GET /auth/nonce` */
-    handleGetNonce(): Promise<ApiNonceResponse>;
-    /** `POST /auth/login` */
-    handleLogin(body: ApiLoginRequest): Promise<ApiLoginResponse>;
+    /**
+     * `GET /auth/nonce`
+     *
+     * @param rateLimitKey  Caller-side rate-limit key (typically client IP).
+     *                      The HTTP layer (controller/middleware) extracts
+     *                      this from the request and passes it through.
+     *                      When omitted, no rate limit applies — production
+     *                      callers SHOULD always pass a key.
+     */
+    handleGetNonce(rateLimitKey?: string): Promise<ApiNonceResponse>;
+    /**
+     * `POST /auth/login`
+     *
+     * @param body          Login message + signature.
+     * @param rateLimitKey  Caller-side rate-limit key (typically client IP
+     *                      or `body.userAddress` if known). See `handleGetNonce`.
+     */
+    handleLogin(body: ApiLoginRequest, rateLimitKey?: string): Promise<ApiLoginResponse>;
     /**
      * `GET /config?chainId=<id>`
      *
@@ -1061,6 +1368,26 @@ declare class IssuerApiHandlers {
      * balance.
      */
     handleUser(userAddress: Address, request: ApiUserRequest): Promise<ApiUserResponse>;
+    /**
+     * `GET /redemption/preview?pointToken=<addr>`
+     *
+     * Returns the headroom currently available to `userAddress` under the
+     * configured RedemptionPolicy. Pure read — does not record anything.
+     * Use this for UI to render "X PT redeemable now / next available at …".
+     */
+    handleRedemptionPreview(userAddress: Address, request: ApiRedemptionPreviewRequest): Promise<ApiRedemptionPreviewResponse>;
+    /**
+     * `POST /redemption/evaluate`
+     *
+     * Pre-flight check before the issuer signs a BurnRequest. Returns
+     * { allowed, denial?, preview }. Caller (the burn-orchestrator) MUST
+     * re-check on the actual initiate path — evaluate is read-only and a
+     * caller could race two requests under the same headroom. The intended
+     * write path is: evaluate → sign BurnRequest → reserve pending credit
+     * → call `service.redemption.recordSuccessfulInitiate()`.
+     */
+    handleRedemptionEvaluate(userAddress: Address, request: ApiRedemptionEvaluateRequest): Promise<ApiRedemptionEvaluateResponse>;
+    private requireSupportedToken;
 }
 
 /**
@@ -1134,6 +1461,16 @@ interface PTRedeemHandlerConfig {
     signatureDeadlineSeconds?: number;
     /** Clock injection for tests; defaults to `Date.now`. */
     now?: () => number;
+    /**
+     * Optional — when wired, the handler enforces the per-issuer
+     * RedemptionPolicy (daily limit / cooldown / blackout / per-tx range)
+     * BEFORE signing the BurnRequest. On denial it throws
+     * PTRedeemError("REDEMPTION_POLICY_DENIED", ...) with the policy
+     * denial code in `policyDenialCode`. After a successful sign+reserve,
+     * the handler records the redemption against the user's history so
+     * the next preview reflects the spend.
+     */
+    redemptionService?: RedemptionService;
 }
 interface PTRedeemRequest {
     /** Address extracted from the verified JWT — must match `userAddress`. */
@@ -1193,11 +1530,14 @@ 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";
+type PTRedeemErrorCode = "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "NONCE_IN_FLIGHT" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED" | "REDEMPTION_POLICY_DENIED";
 declare class PTRedeemError extends PafiSdkError {
     readonly httpStatus: "unprocessable";
     readonly code: PTRedeemErrorCode;
-    constructor(code: PTRedeemErrorCode, message: string);
+    readonly policyDenialCode?: RedemptionDenialCode;
+    constructor(code: PTRedeemErrorCode, message: string, options?: {
+        policyDenialCode?: RedemptionDenialCode;
+    });
 }
 declare class PTRedeemHandler {
     private readonly ledger;
@@ -1212,6 +1552,7 @@ declare class PTRedeemHandler {
     private readonly redeemLockDurationMs;
     private readonly signatureDeadlineSeconds;
     private readonly now;
+    private readonly redemptionService?;
     /**
      * Per-user in-flight nonce guard (single-process only).
      *
@@ -1238,7 +1579,12 @@ interface RetryConfig {
     maxRetryAfterMs?: number;
 }
 interface PafiBackendConfig {
-    url: string;
+    /**
+     * 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.
+     */
+    chainId: number;
     issuerId: string;
     apiKey: string;
     fetchImpl?: typeof fetch;
@@ -1343,6 +1689,7 @@ interface SponsorshipResponse {
 }
 declare class PafiBackendClient {
     private readonly config;
+    private readonly baseUrl;
     constructor(config: PafiBackendConfig);
     requestSponsorship(request: SponsorshipRequest): Promise<SponsorshipResponse>;
     /**
@@ -2021,13 +2368,36 @@ declare function handleDelegateSubmit(params: HandleDelegateSubmitParams): Promi
 type SdkErrorStatus = SdkErrorHttpStatus;
 /**
  * Structured body the issuer controller passes to its
- * framework-specific exception class. Mirrors the shape every PAFI
- * issuer surfaces over HTTP today.
+ * framework-specific exception class. Stripe-style envelope:
+ *
+ * ```json
+ * {
+ *   "type": "business_logic_error",
+ *   "code": "REDEMPTION_POLICY_DENIED",
+ *   "message": "...",
+ *   "param": null,
+ *   "metadata": { "policyDenialCode": "PER_TX_MIN" },
+ *   "safeToRetry": false
+ * }
+ * ```
+ *
+ * Carries enough fields for the global HTTP filter to emit the final
+ * envelope without losing any SDK-side context.
  */
 interface SdkErrorBody {
+    /** Stripe-style taxonomy slot — drives UI branching. */
+    type: PafiErrorType;
+    /** Machine-readable code, e.g. `"REDEMPTION_POLICY_DENIED"`. */
     code: string;
+    /** Human-readable message. */
     message: string;
+    /** Field name that triggered the error, when applicable. */
+    param?: string;
+    /** UI-facing structured context. */
+    metadata?: Record<string, unknown>;
+    /** Raw debug context. */
     details?: unknown;
+    /** True when retry is safe (no side effects yet). */
     safeToRetry: boolean;
 }
 /**
@@ -2043,6 +2413,12 @@ interface SdkErrorMapperFactories {
     unprocessable: (body: SdkErrorBody) => Error;
     serviceUnavailable: (body: SdkErrorBody) => Error;
 }
+/**
+ * Build the Stripe-style body from any `PafiSdkError`. Exposed for
+ * frameworks that don't fit the four-factory shape (e.g. a Hono error
+ * handler that builds its own response object).
+ */
+declare function buildSdkErrorBody(err: PafiSdkError): SdkErrorBody;
 /**
  * Build a single error-mapping function that converts any `PafiSdkError`
  * into the issuer's framework-specific HTTP exception. Status, code,
@@ -2145,6 +2521,28 @@ interface IssuerServiceConfig {
          */
         autoStart?: boolean;
     };
+    /**
+     * Redemption restriction config. When provided, the SDK fetches the
+     * per-issuer policy from PAFI issuer-api (with 5min cache + default
+     * fallback) and exposes preview/evaluate via `service.redemption`.
+     * The handler endpoints `handleRedemptionPreview` / `handleRedemptionEvaluate`
+     * are wired only when this is configured.
+     *
+     * `chainId` is taken from the top-level config; the issuer-api URL
+     * is looked up via `getPafiServiceUrls(chainId)`. Only credentials
+     * + the history store are required here.
+     */
+    redemption?: {
+        issuerId: string;
+        apiKey: string;
+        historyStore: IRedemptionHistoryStore;
+        /** Override fetch (testing). */
+        fetchImpl?: typeof fetch;
+        /** Per-fetch timeout in ms. Default 1000. */
+        fetchTimeoutMs?: number;
+        /** Cache TTL in ms. Default 5 * 60 * 1000. */
+        cacheTtlMs?: number;
+    };
 }
 interface IssuerService {
     /** AuthService — login, logout, nonce management. */
@@ -2166,6 +2564,12 @@ interface IssuerService {
     indexer: PointIndexer;
     /** Framework-agnostic HTTP handlers — wire into Express / Fastify / Hono. */
     api: IssuerApiHandlers;
+    /**
+     * Redemption restriction service. Undefined when `redemption` is not
+     * configured — the corresponding handlers throw "not configured" at
+     * request time.
+     */
+    redemption: RedemptionService | undefined;
 }
 /**
  * Wire a fully-functional issuer service from a single config object.
@@ -2866,6 +3270,79 @@ declare class IssuerStateValidator {
     private fetchIssuerState;
 }
 
+/**
+ * SDK-side fallback used when settlement-api is unreachable, returns
+ * 404, or returns 5xx. Keep it permissive enough that an outage doesn't
+ * lock all users out, but tight enough that it's not an abuse vector.
+ */
+declare const DEFAULT_REDEMPTION_POLICY: RedemptionPolicy;
+declare function defaultPolicyFor(issuerId: string): RedemptionPolicy;
+
+/**
+ * Either a successful policy fetch or a structured failure. We never
+ * throw from `fetchPolicy()` — callers fall back to cache/default on
+ * any failure mode, so a thrown error would just force every caller
+ * to wrap in try/catch.
+ */
+type FetchResult = {
+    ok: true;
+    policy: RedemptionPolicy;
+} | {
+    ok: false;
+    reason: FetchFailureReason;
+    status?: number;
+};
+type FetchFailureReason = "TIMEOUT" | "NETWORK" | "NOT_FOUND" | "UNAUTHORIZED" | "SERVER_ERROR" | "INVALID_RESPONSE";
+declare class SettlementClient {
+    private readonly config;
+    constructor(config: SettlementClientConfig);
+    fetchPolicy(): Promise<FetchResult>;
+}
+
+interface UserHistory {
+    /** Total PT redeemed by user in the rolling 24h window. */
+    redeemedLast24hPt: bigint;
+    /** Last redemption timestamp (unix seconds), or null if never. */
+    lastRedeemedAtUnixSec: number | null;
+}
+interface EvaluateInput {
+    policy: RedemptionPolicy;
+    policySource: RedemptionPolicySource;
+    history: UserHistory;
+    /** Amount being requested. Pass 0n for a pure preview. */
+    amountPt: bigint;
+    /** Current unix time in seconds (caller-controlled for testability). */
+    nowUnixSec: number;
+}
+/**
+ * Pure evaluator. Given a policy + user history snapshot + requested
+ * amount, returns either ALLOW + a preview of the user's remaining
+ * headroom, or DENY + the first failing rule.
+ *
+ * Preview is always populated, even on denial — UI uses it to render
+ * "X PT redeemable now" / "next available at HH:MM" regardless.
+ */
+declare function evaluateRedemption(input: EvaluateInput): RedemptionDecision;
+declare const REDEMPTION_HISTORY_WINDOW_SEC: number;
+
+/**
+ * In-memory IRedemptionHistoryStore for tests + the bundled NestJS
+ * example. Production issuers should implement this against their
+ * existing burn/audit table — sumRedeemedSince is hot path on every
+ * redemption preview.
+ */
+declare class MemoryRedemptionHistoryStore implements IRedemptionHistoryStore {
+    private readonly entries;
+    sumRedeemedSince(user: Address, sinceUnixSec: number, pointTokenAddress?: Address): Promise<bigint>;
+    getLastRedeemedAtUnixSec(user: Address, pointTokenAddress?: Address): Promise<number | null>;
+    recordRedemption(entry: {
+        user: Address;
+        amountPt: bigint;
+        pointTokenAddress?: Address;
+        unixSec: number;
+    }): Promise<void>;
+}
+
 declare const PAFI_ISSUER_SDK_VERSION: string;
 
-export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type CombinedBalance, type ConfigDto, ConfigurationError, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, FeeManager, type FeeManagerConfig, type GasFeeDto, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsDto, type PoolsProvider, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, type RedeemDto, type RedeemPrepareDto, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, authenticateRequest, createIssuerService, createNativePtQuoter, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };
+export { AdapterMisconfiguredError, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedemptionEvaluateRequest, type ApiRedemptionEvaluateResponse, type ApiRedemptionPreviewRequest, type ApiRedemptionPreviewResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type CombinedBalance, type ConfigDto, ConfigurationError, DEFAULT_REDEMPTION_POLICY, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, type EvaluateInput, FeeManager, type FeeManagerConfig, type FetchFailureReason, type FetchResult, type GasFeeDto, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type IRateLimiter, type IRedemptionHistoryStore, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemoryRateLimiter, MemoryRedemptionHistoryStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, NoopRateLimiter, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, PolicyProvider, type PolicyProviderConfig, type PoolsDto, type PoolsProvider, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, REDEMPTION_HISTORY_WINDOW_SEC, type RateLimitAction, type RateLimiterConfig, type RedeemDto, type RedeemPrepareDto, RedemptionService, type RedemptionServiceConfig, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type ResolvedPolicy, type RetryConfig, type SdkErrorBody, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, SettlementClient, type SettlementClientConfig, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type UserDto, type UserHistory, authenticateRequest, buildSdkErrorBody, createIssuerService, createNativePtQuoter, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, defaultPolicyFor, evaluateRedemption, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };