@pafi-dev/issuer 0.3.0-beta.9 → 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 } 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;
@@ -1451,7 +1409,7 @@ interface PafiBackendConfig {
     timeoutMs?: number;
     retry?: RetryConfig;
 }
-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" | "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;
@@ -1465,6 +1423,41 @@ declare class PafiBackendError extends Error {
     get safeToRetry(): boolean;
 }
 
+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 config;
+    constructor(config: PafiBackendConfig);
+    requestSponsorship(request: SponsorshipRequest): Promise<SponsorshipResponse>;
+    private _doRequest;
+}
+
 /**
  * Top-level configuration for `createIssuerService`.
  *
@@ -1501,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
@@ -1514,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;
@@ -1547,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)
@@ -1561,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, 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 RetryConfig, type Session, 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 };