@pafi-dev/issuer 0.3.0-beta.8 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Address, Hex, PublicClient, Chain, WalletClient } from 'viem';
-import { PointTokenDomainConfig, MintRequest, EIP712Signature, PartialUserOperation, BurnRequest, ReceiverConsent, PathKey, PoolKey, SponsorAuthScenario, SponsorAuthPayload, SponsorshipScenario } from '@pafi-dev/core';
+import { Address, Hex, PublicClient, WalletClient } from 'viem';
+import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, ReceiverConsent, PathKey, PoolKey } from '@pafi-dev/core';
 
 /**
  * Lifecycle of a minting request as tracked by the issuer's point ledger.
@@ -62,11 +62,7 @@ interface IPointLedger {
     lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number, tokenAddress?: Address): Promise<string>;
     /** Release a previously created lock (e.g. on tx failure / cancel). */
     releaseLock(lockId: string): Promise<void>;
-    /**
-     * Permanently deduct an amount from a user's balance after the on-chain
-     * mint has been observed by the indexer. Should also resolve any matching
-     * lock so the funds aren't double-counted.
-     */
+    /** Deduct balance after a confirmed on-chain mint. Idempotent on `txHash`. */
     deductBalance(userAddress: Address, amount: bigint, txHash: Hex, tokenAddress?: Address): Promise<void>;
     /** Credit points to a user's balance (e.g. from merchant activity). */
     creditBalance(userAddress: Address, amount: bigint, reason: string, tokenAddress?: Address): Promise<void>;
@@ -97,47 +93,6 @@ interface IPointLedger {
     resolveCreditByBurnTx?(lockId: string, txHash: Hex): Promise<void>;
 }
 
-/**
- * In-memory IPointLedger implementation for development and tests.
- *
- * NOT for production — state is lost on restart. Issuers should ship their
- * own database-backed implementation.
- *
- * Concurrency model: single-process, single-threaded (Node.js event loop).
- * The lock check + insert is atomic within a tick because no awaits sit
- * between balance read and lock write.
- *
- * **Multi-token (0.2.0):** Balances are keyed by `(user, token)`. If callers
- * omit `tokenAddress`, the literal string "default" is used — that keeps
- * single-token usage working exactly like 0.1.x.
- */
-declare class MemoryPointLedger implements IPointLedger {
-    private balances;
-    private locks;
-    private nextLockId;
-    private now;
-    constructor(opts?: {
-        now?: () => number;
-    });
-    getBalance(userAddress: Address, tokenAddress?: Address): Promise<bigint>;
-    getLockedRequests(userAddress: Address, tokenAddress?: Address): Promise<LockedMintRequest[]>;
-    creditBalance(userAddress: Address, amount: bigint, _reason: string, tokenAddress?: Address): Promise<void>;
-    lockForMinting(userAddress: Address, amount: bigint, lockDurationMs: number, tokenAddress?: Address): Promise<string>;
-    releaseLock(lockId: string): Promise<void>;
-    deductBalance(userAddress: Address, amount: bigint, txHash: Hex, tokenAddress?: Address): Promise<void>;
-    updateMintStatus(lockId: string, status: MintingStatus, txHash?: Hex): Promise<void>;
-    private pendingCredits;
-    private nextCreditId;
-    reservePendingCredit(userAddress: Address, amount: bigint, durationMs: number, tokenAddress?: Address): Promise<string>;
-    resolveCreditByBurnTx(lockId: string, txHash: Hex): Promise<void>;
-    /**
-     * Auto-expire any PENDING lock past its expiry. Called lazily on every
-     * read/write so the in-memory state stays self-cleaning without a timer.
-     */
-    private purgeExpired;
-    private lockedTotalFor;
-}
-
 /**
  * Input to a policy evaluation. Policy engines use this to decide whether
  * a user's mint request should be approved.
@@ -213,56 +168,6 @@ declare class DefaultPolicyEngine implements IPolicyEngine {
     evaluate(request: PolicyEvalRequest): Promise<PolicyDecision>;
 }
 
-/**
- * Issuer signer — produces the MintRequest EIP-712 signature that the Relay
- * contract verifies against the issuer's on-chain authorized minter.
- *
- * This is a trust boundary: the default `PrivateKeySigner` holds the key in
- * process memory and is intended for local development only. Production
- * issuers replace this with an HSM/KMS/MPC integration.
- */
-interface IIssuerSigner {
-    /**
-     * Sign a `MintRequest` message against the point token's EIP-712 domain.
-     * The returned signature is what the Relay contract passes to
-     * `PointToken.verify` during `mintAndSwap`.
-     */
-    signMintRequest(domain: PointTokenDomainConfig, message: MintRequest): Promise<EIP712Signature>;
-    /** Get the signer's on-chain address (used for verification / logging). */
-    getAddress(): Promise<Address>;
-}
-
-interface PrivateKeySignerOptions {
-    /** 0x-prefixed 32-byte hex private key */
-    privateKey: Hex;
-    /**
-     * Chain metadata for the viem WalletClient. Only the chain id is actually
-     * used for signing; a minimal stub is acceptable (it does not need to
-     * match the deployed chain config beyond id).
-     */
-    chain: Chain;
-    /**
-     * Optional RPC URL. `signTypedData` is offline, so this can usually be
-     * left unset — viem only requires a transport to construct the client.
-     */
-    rpcUrl?: string;
-}
-/**
- * Local-key implementation of `IIssuerSigner`. Wraps viem's `signTypedData`
- * via the shared `@pafi/core` `signMintRequest` helper.
- *
- * ⚠️ **NOT for production use.** The private key lives in process memory
- * and is trivially extractable from a compromised host. Replace with an
- * HSM/KMS/MPC-backed `IIssuerSigner` before deployment.
- */
-declare class PrivateKeySigner implements IIssuerSigner {
-    private readonly account;
-    private readonly walletClient;
-    constructor(opts: PrivateKeySignerOptions);
-    signMintRequest(domain: PointTokenDomainConfig, message: MintRequest): Promise<EIP712Signature>;
-    getAddress(): Promise<Address>;
-}
-
 /**
  * A server-issued session created after a successful wallet login. The
  * token id is embedded in the JWT so sessions can be revoked without
@@ -609,6 +514,9 @@ declare class FeeManager {
     private readonly gasUnits;
     private readonly gasPremiumBps;
     private readonly quoteNativeToFee;
+    private cachedFee;
+    private cacheExpiresAt;
+    private static readonly CACHE_TTL_MS;
     constructor(config: FeeManagerConfig);
     /**
      * Estimate the fee (in the caller's fee currency) to charge for the
@@ -784,6 +692,15 @@ interface BurnIndexerConfig {
     /** Polling interval (ms). Default: 5000. */
     pollIntervalMs?: number;
     now?: () => number;
+    /**
+     * Map a burn event to the pending credit lockId that should be resolved.
+     * Return `undefined` to skip this burn event (no credit granted).
+     *
+     * REQUIRED — there is no default implementation. Issuers with a Postgres
+     * ledger typically JOIN on `(from, amount, status=PENDING)`. The in-memory
+     * ledger uses a lookup by lockId supplied out-of-band from the claim flow.
+     */
+    matchLockId: (event: BurnEvent) => Promise<string | undefined>;
 }
 /**
  * Mirror of `PointIndexer` for the reverse direction — watches
@@ -814,17 +731,6 @@ declare class BurnIndexer {
     private readonly confirmations;
     private readonly batchSize;
     private readonly pollIntervalMs;
-    /**
-     * Caller-supplied matcher. Return the lockId to resolve for a given
-     * burn event, or `undefined` to skip. Runs synchronously via the
-     * ledger's query path.
-     *
-     * Default: try `ledger.resolveCreditByBurnTx` keyed on a synthetic
-     * lock id `burn-${from}-${amount}` — the in-memory ledger assigns
-     * incrementing IDs so callers with the memory ledger must provide a
-     * custom matcher. Real DB-backed ledgers override this to JOIN on
-     * their `pending_credits` table.
-     */
     matchLockId: (event: BurnEvent) => Promise<string | undefined>;
     private running;
     private timer;
@@ -974,6 +880,27 @@ interface ApiClaimAndSwapResponse {
     blockNumber?: bigint;
     gasUsed?: bigint;
 }
+interface ApiClaimRequest {
+    chainId: number;
+    pointTokenAddress: Address;
+    /** PT amount to mint. */
+    amount: bigint;
+    /** ERC-4337 account nonce for the user's EOA (from EntryPoint). */
+    aaNonce: bigint;
+    /** Unix seconds — when the MintRequest signature expires. */
+    deadline: bigint;
+    /** Optional operator fee (PT) deducted inside the same UserOp batch. */
+    feeAmount?: bigint;
+    feeRecipient?: Address;
+}
+interface ApiClaimResponse {
+    /** Off-chain lock id — poll `/user` to track PENDING → MINTED. */
+    lockId: string;
+    /** Unsigned UserOp — attach paymaster data + user signature, then submit. */
+    userOp: PartialUserOperation;
+    /** Seconds until the off-chain lock expires if the UserOp is not submitted. */
+    expiresInSeconds: number;
+}
 interface ApiBuildConsentTypedDataRequest {
     chainId: number;
     pointTokenAddress: Address;
@@ -1024,6 +951,20 @@ interface IssuerApiHandlersConfig {
     feeManager?: FeeManager;
     /** Required by `handlePools`; omit to disable the endpoint. */
     poolsProvider?: PoolsProvider;
+    /**
+     * Required by `handleClaim`; omit to disable the endpoint.
+     * Wires policy evaluation + ledger locking + MintRequest signing
+     * into a single atomic handler so callers cannot accidentally skip
+     * the policy check.
+     */
+    claim?: {
+        policy: IPolicyEngine;
+        relayService: RelayService;
+        issuerSignerWallet: WalletClient;
+        batchExecutorAddress: Address;
+        /** How long to hold the off-chain lock while the UserOp is in flight. Default: 15 min. */
+        lockDurationMs?: number;
+    };
 }
 /**
  * Framework-agnostic HTTP handlers that match the endpoints a `PafiSDK`
@@ -1045,15 +986,12 @@ declare class IssuerApiHandlers {
      * validate the request's `pointTokenAddress` against this set.
      */
     private readonly supportedTokens;
-    /** First supported token — used as default when a handler doesn't
-     * receive a `pointTokenAddress` in the request (shouldn't happen in
-     * practice, but keeps type-narrowing happy). */
-    private readonly defaultToken;
     private readonly chainId;
     private readonly contracts;
     private readonly pafiWebUrl?;
     private readonly feeManager?;
     private readonly poolsProvider?;
+    private readonly claim?;
     constructor(config: IssuerApiHandlersConfig);
     /** `GET /auth/nonce` */
     handleGetNonce(): Promise<ApiNonceResponse>;
@@ -1099,6 +1037,22 @@ declare class IssuerApiHandlers {
      * mobile apps — no app store review needed.
      */
     handleBuildConsentTypedData(userAddress: Address, request: ApiBuildConsentTypedDataRequest): Promise<ApiBuildConsentTypedDataResponse>;
+    /**
+     * `POST /claim`
+     *
+     * Policy gate + ledger lock + MintRequest signing in a single atomic
+     * step. Returns an unsigned UserOp the frontend attaches paymaster data
+     * to and submits via EIP-7702 + Bundler.
+     *
+     * Order of operations:
+     *   1. Validate request fields.
+     *   2. policy.evaluate() — throws if denied; cannot be bypassed.
+     *   3. ledger.lockForMinting() — reserves the balance.
+     *   4. Read on-chain mintRequestNonce + token name in parallel.
+     *   5. relayService.prepareMint() — sign MintRequest + encode UserOp.
+     *   6. On any error after step 3, release the lock before re-throwing.
+     */
+    handleClaim(userAddress: Address, request: ApiClaimRequest): Promise<ApiClaimResponse>;
 }
 
 /**
@@ -1167,6 +1121,8 @@ interface PTRedeemHandlerConfig {
     now?: () => number;
 }
 interface PTRedeemRequest {
+    /** Address extracted from the verified JWT — must match `userAddress`. */
+    authenticatedAddress: Address;
     userAddress: Address;
     amount: bigint;
     /** ERC-4337 account nonce for the user's EOA. */
@@ -1183,8 +1139,8 @@ interface PTRedeemResponse {
     signatureDeadline: bigint;
 }
 declare class PTRedeemError extends Error {
-    code: "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED";
-    constructor(code: "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED", message: string);
+    code: "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED";
+    constructor(code: "UNAUTHORIZED" | "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED", message: string);
 }
 declare class PTRedeemHandler {
     private readonly ledger;
@@ -1232,6 +1188,8 @@ interface TopUpRedemptionHandlerConfig {
     pointTokenAddress: Address;
 }
 interface TopUpRedemptionRequest {
+    /** Address extracted from the verified JWT — must match `userAddress`. */
+    authenticatedAddress: Address;
     userAddress: Address;
     /** Total points the voucher redemption requires off-chain. */
     requiredAmount: bigint;
@@ -1252,8 +1210,8 @@ type TopUpRedemptionResponse = {
     redeem: PTRedeemResponse;
 };
 declare class TopUpRedemptionError extends Error {
-    code: "INSUFFICIENT_ONCHAIN_BALANCE" | "LEDGER_NOT_SUPPORTED";
-    constructor(code: "INSUFFICIENT_ONCHAIN_BALANCE" | "LEDGER_NOT_SUPPORTED", message: string);
+    code: "UNAUTHORIZED" | "INSUFFICIENT_ONCHAIN_BALANCE" | "LEDGER_NOT_SUPPORTED";
+    constructor(code: "UNAUTHORIZED" | "INSUFFICIENT_ONCHAIN_BALANCE" | "LEDGER_NOT_SUPPORTED", message: string);
 }
 declare class TopUpRedemptionHandler {
     private readonly ledger;
@@ -1438,221 +1396,66 @@ declare class BalanceAggregator {
 }
 
 interface RetryConfig {
-    /**
-     * Max total attempts including the first try. Default: 1 (no retry).
-     * Set to 3 to get 2 retries after the initial call.
-     *
-     * Only applies when the server error body carries `safeToRetry: true`
-     * or the failure is a transient network/timeout error.
-     */
     maxAttempts?: number;
-    /**
-     * Initial backoff delay in ms. Default: 500. Each subsequent retry
-     * doubles this (exponential backoff) and adds ±20% jitter.
-     */
     initialDelayMs?: number;
-    /**
-     * Hard ceiling for a single backoff (ms). Default: 10_000.
-     */
     maxDelayMs?: number;
-    /**
-     * Upper bound on `retryAfter` from the server. If the server asks us
-     * to wait longer than this (e.g. rate limit until UTC midnight), the
-     * client gives up rather than blocking. Default: 30_000.
-     */
     maxRetryAfterMs?: number;
 }
 interface PafiBackendConfig {
-    /**
-     * PAFI Backend API base URL. Example:
-     *   https://api.pacificfinance.org
-     *   https://staging-api.pacificfinance.org
-     */
     url: string;
-    /** PAFI-assigned issuer ID (e.g., "gg56"). Sent in X-Issuer-Id header. */
     issuerId: string;
-    /** Per-issuer API key (or JWT) for the Authorization header. */
     apiKey: string;
-    /** Optional fetch override for tests. */
     fetchImpl?: typeof fetch;
-    /**
-     * Timeout (ms) for each request. Default: 10_000. PAFI Backend should
-     * respond in <1s for the happy path; this is just the sanity bound.
-     */
     timeoutMs?: number;
-    /**
-     * Retry policy for transient failures (5xx, 429, timeouts, network).
-     * Omit or pass `{ maxAttempts: 1 }` to disable retry entirely.
-     */
     retry?: RetryConfig;
 }
-/**
- * @deprecated Coinbase paymaster path — replaced by SponsorAuth in beta.8.
- * Kept for back-compat with consumers still on Coinbase. Will be removed
- * in 1.0.
- */
-interface SponsorshipRequest {
-    chainId: number;
-    scenario: SponsorshipScenario;
-    userOp: PartialUserOperation;
-    target: {
-        contract: Address;
-        function: string;
-        pointToken?: Address;
-    };
-}
-/** @deprecated See `SponsorshipRequest`. Use `SponsorAuthResponse` in beta.8+. */
-interface SponsorshipResponse {
-    paymaster: Address;
-    paymasterData: Hex;
-    paymasterVerificationGasLimit: bigint;
-    paymasterPostOpGasLimit: bigint;
-    expiresAt: number;
-}
-
-/**
- * Request body for `POST /sponsor-auth` against PAFI sponsor-relayer.
- * See `pafi-backend/docs/SPONSOR_AUTH_DESIGN.md` for the full spec.
- *
- * The endpoint:
- *   1. Authenticates user (JWT) + issuer (API key)
- *   2. Per-(user, scenario) rate-limits
- *   3. Per-issuer daily budget check
- *   4. Scenario-specific intent validation (mint cap, KYC, etc.)
- *   5. Allocates a unique nonce
- *   6. Signs the SponsorAuth payload via KMS-backed PAFI key
- *   7. Returns `{ sponsorAuth, payload }` for FE to forward to Privy
- */
-interface SponsorAuthRequest {
-    chainId: number;
-    scenario: SponsorAuthScenario;
-    /** The exact UserOp the FE intends to submit. callDataHash binds to this. */
-    userOp: PartialUserOperation;
-    /** Issuer ID this sponsorship is billed against (e.g. "gg56"). */
-    issuerId: string;
-    /**
-     * Scenario-specific context for intent validation. The relayer reads
-     * these to apply scenario rules — e.g. preValidateMint reads
-     * pointToken + amount to check the issuer cap.
-     */
-    context?: {
-        pointToken?: Address;
-        /** Decimal string representation (handles bigint over JSON). */
-        amount?: string;
-        brokerHash?: Hex;
-    };
-}
-/**
- * Response from `POST /sponsor-auth`.
- *
- * `payload` is returned alongside `sponsorAuth` so the FE doesn't have
- * to reconstruct the message — just forwards both to Privy. Privy
- * verifier checks `signature` recovers to PAFI's registered pubkey
- * over `payload`.
- */
-interface SponsorAuthResponse {
-    /** EIP-712 signature, hex-encoded 65 bytes. */
-    sponsorAuth: Hex;
-    /** The payload that was signed. Pass to Privy alongside the signature. */
-    payload: SponsorAuthPayload;
-}
-/**
- * Machine-readable error codes returned by PAFI sponsor-relayer.
- *
- * Source of truth: `apps/sponsor-relayer/src/**` (renamed from
- * paymaster-proxy in beta.8). Keep in sync.
- */
-type PafiBackendErrorCode = "MISSING_ISSUER_ID" | "MISSING_API_KEY" | "ISSUER_UNAUTHORIZED" | "USER_UNAUTHORIZED" | "INTENT_REJECTED" | "MINT_CAP_EXCEEDED" | "ISSUER_INACTIVE" | "BROKER_NOT_WHITELISTED" | "RATE_LIMIT_EXCEEDED" | "RATE_LIMIT_EXCEEDED_DAILY" | "RATE_LIMIT_EXCEEDED_PER_USER" | "ISSUER_BUDGET_EXCEEDED" | "RATE_LIMITER_UNAVAILABLE" | "KMS_UNAVAILABLE" | "SPONSOR_AUTH_SIGNING_FAILED" | "PAYMASTER_REJECTED" | "PAYMASTER_UNAVAILABLE" | "PAYMASTER_TIMEOUT" | "CALLDATA_INVALID" | "CALLDATA_EMPTY_BATCH" | "TARGET_NOT_ALLOWLISTED" | "FUNCTION_NOT_ALLOWED" | "SCENARIO_MISMATCH" | "SCENARIO_DISABLED" | "BAD_REQUEST" | "INTERNAL_ERROR" | "TIMEOUT" | "NETWORK_ERROR";
+type PafiBackendErrorCode = "MISSING_ISSUER_ID" | "MISSING_API_KEY" | "ISSUER_UNAUTHORIZED" | "USER_UNAUTHORIZED" | "INTENT_REJECTED" | "MINT_CAP_EXCEEDED" | "ISSUER_INACTIVE" | "BROKER_NOT_WHITELISTED" | "RATE_LIMIT_EXCEEDED" | "RATE_LIMIT_EXCEEDED_DAILY" | "RATE_LIMIT_EXCEEDED_PER_USER" | "ISSUER_BUDGET_EXCEEDED" | "RATE_LIMITER_UNAVAILABLE" | "PAYMASTER_UNAVAILABLE" | "TARGET_NOT_ALLOWLISTED" | "BAD_REQUEST" | "INTERNAL_ERROR" | "TIMEOUT" | "NETWORK_ERROR" | (string & {});
 declare class PafiBackendError extends Error {
     code: PafiBackendErrorCode;
     httpStatus: number;
     details?: unknown | undefined;
-    /**
-     * Seconds to wait before retry. Populated from the server body
-     * (e.g. rate limit returns the number of seconds until UTC midnight).
-     */
     readonly retryAfter?: number;
-    /**
-     * `safeToRetry` as reported by the server body. Prefer this over the
-     * code-based heuristic when available — the server knows more about
-     * whether the same request will succeed on retry.
-     */
     private readonly serverSafeToRetry?;
     constructor(code: PafiBackendErrorCode, message: string, httpStatus: number, details?: unknown | undefined, opts?: {
         retryAfter?: number;
         safeToRetry?: boolean;
     });
-    /**
-     * Whether the caller can safely retry the same request.
-     *
-     * If the server provided `safeToRetry` in the body, trust that.
-     * Otherwise fall back to a code-based heuristic.
-     */
     get safeToRetry(): boolean;
 }
 
-/**
- * HTTP client for the PAFI Backend paymaster proxy service. See
- * [SPONSORED_PATH_FLOW.md] for the full flow + API contract.
- *
- * This client sits between `@pafi/issuer`'s RelayService and the
- * PAFI Backend. It does NOT talk to Coinbase Paymaster directly —
- * PAFI Backend holds that integration.
- */
+interface SponsorshipUserOp {
+    sender: Address;
+    nonce: bigint;
+    callData: Hex;
+    callGasLimit: bigint;
+    verificationGasLimit: bigint;
+    preVerificationGas: bigint;
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+}
+interface SponsorshipTarget {
+    contract: Address;
+    function: string;
+    pointToken: Address;
+}
+interface SponsorshipRequest {
+    chainId: number;
+    scenario: string;
+    userOp: SponsorshipUserOp;
+    target: SponsorshipTarget;
+}
+interface SponsorshipResponse {
+    paymaster: Address;
+    paymasterData: Hex;
+    paymasterVerificationGasLimit: bigint;
+    paymasterPostOpGasLimit: bigint;
+    expiresAt: number;
+}
 declare class PafiBackendClient {
-    private readonly url;
-    private readonly issuerId;
-    private readonly apiKey;
-    private readonly fetchImpl;
-    private readonly timeoutMs;
-    private readonly retry;
+    private readonly config;
     constructor(config: PafiBackendConfig);
-    /**
-     * Request a SponsorAuth signature from PAFI sponsor-relayer (beta.8+).
-     *
-     * The relayer:
-     *   1. Authenticates user (JWT) + issuer (API key)
-     *   2. Per-(user, scenario) rate limit + per-issuer daily budget
-     *   3. Scenario-specific intent validation (mint cap, KYC, etc.)
-     *   4. Allocates nonce + signs SponsorAuth payload via KMS PAFI key
-     *   5. Returns `{ sponsorAuth, payload }` for the FE to forward to
-     *      Privy's `signUserOperation({ sponsorAuth, payload })`.
-     *
-     * Retries on transient failures (5xx, timeouts, KMS unavailable,
-     * rate-limit-with-retryAfter). 4xx that are not `safeToRetry` fail fast.
-     *
-     * See `pafi-backend/docs/SPONSOR_AUTH_DESIGN.md` for the full spec.
-     *
-     * @throws PafiBackendError on final failure after exhausting retries
-     */
-    requestSponsorAuth(req: SponsorAuthRequest): Promise<SponsorAuthResponse>;
-    /**
-     * @deprecated Coinbase paymaster path — replaced by `requestSponsorAuth`
-     * in beta.8. Will be removed in 1.0. Migrate by:
-     *   1. Switch to `requestSponsorAuth` returning `{ sponsorAuth, payload }`
-     *   2. Pass both to Privy `signUserOperation` instead of merging
-     *      paymasterData into the UserOp callData
-     */
-    requestSponsorship(req: SponsorshipRequest): Promise<SponsorshipResponse>;
-    private postWithRetry;
-    /**
-     * Pick the delay before the next retry.
-     * - If the server sent `retryAfter` (seconds), honor it (capped by
-     *   `maxRetryAfterMs`) — returns null if the server wait exceeds the
-     *   cap, signalling the caller should give up.
-     * - Otherwise: exponential backoff with ±20% jitter, capped at
-     *   `maxDelayMs`.
-     */
-    private computeBackoff;
-    private sleep;
-    private post;
-    /** JSON replacer that stringifies bigints. Paired with bigintReviver. */
-    private bigintReplacer;
-    /**
-     * JSON reviver that coerces specific numeric-string fields back to
-     * bigint. The server must send these fields as decimal strings.
-     */
-    private bigintReviver;
+    requestSponsorship(request: SponsorshipRequest): Promise<SponsorshipResponse>;
+    private _doRequest;
 }
 
 /**
@@ -1691,8 +1494,20 @@ interface IssuerServiceConfig {
         /** Passed straight to `jose` (`"24h"`, `"7d"`, …). Default `"24h"`. */
         jwtExpiresIn?: string;
     };
-    ledger?: IPointLedger;
+    /**
+     * Off-chain point ledger — the source of truth for user balances and
+     * in-flight minting locks. Every issuer provides their own database-backed
+     * implementation (Postgres, Redis, etc.) that implements `IPointLedger`.
+     * The SDK does not ship a production ledger; each issuer's data model and
+     * infrastructure are different.
+     */
+    ledger: IPointLedger;
+    /**
+     * Policy engine — optional, defaults to `DefaultPolicyEngine` which checks
+     * off-chain balance. Extend or replace to add KYC, volume caps, etc.
+     */
     policy?: IPolicyEngine;
+    /** Session store — optional, defaults to `MemorySessionStore` (dev/test only). */
     sessionStore?: ISessionStore;
     /**
      * Fee management config. If omitted the `handleGasFee` endpoint will
@@ -1704,6 +1519,16 @@ interface IssuerServiceConfig {
      * throws "not configured" at request time.
      */
     poolsProvider?: PoolsProvider;
+    /**
+     * Enables `handleClaim`. The factory combines these with the shared
+     * `policy` + `relayService` instances already wired by the factory.
+     * Omit to disable the `/claim` endpoint.
+     */
+    claim?: {
+        issuerSignerWallet: WalletClient;
+        batchExecutorAddress: Address;
+        lockDurationMs?: number;
+    };
     indexer?: {
         fromBlock?: bigint;
         cursorStore?: IIndexerCursorStore;
@@ -1737,8 +1562,7 @@ interface IssuerService {
  * Wire a fully-functional issuer service from a single config object.
  *
  * Defaults:
- *  - `ledger`          → `MemoryPointLedger`
- *  - `sessionStore`    → `MemorySessionStore`
+ *  - `sessionStore`    → `MemorySessionStore` (dev/test only — replace in prod)
  *  - `policy`          → `DefaultPolicyEngine({ ledger })`
  *  - `feeManager`      → undefined (handleGasFee throws until configured)
  *  - `poolsProvider`   → undefined (handlePools throws until configured)
@@ -1751,4 +1575,4 @@ declare function createIssuerService(config: IssuerServiceConfig): IssuerService
 /** SDK package version — bumped on every release */
 declare const PAFI_ISSUER_SDK_VERSION = "0.1.0";
 
-export { type ApiBuildConsentTypedDataRequest, type ApiBuildConsentTypedDataResponse, type ApiClaimAndSwapRequest, type ApiClaimAndSwapResponse, 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, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IIssuerSigner, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerService, type IssuerServiceConfig, type LockedMintRequest, type LoginResult, MemoryPointLedger, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintingStatus, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, PrivateKeySigner, type PrivateKeySignerOptions, RelayError, type RelayErrorCode, RelayService, type Session, type SponsorshipRequest, type SponsorshipResponse, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };
+export { type ApiBuildConsentTypedDataRequest, type ApiBuildConsentTypedDataResponse, type ApiClaimAndSwapRequest, type ApiClaimAndSwapResponse, type ApiClaimRequest, type ApiClaimResponse, 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, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerService, type IssuerServiceConfig, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintingStatus, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, RelayError, type RelayErrorCode, RelayService, type RetryConfig, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };