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

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Address, Hex, PublicClient, Chain, WalletClient } from 'viem';
-import { PointTokenDomainConfig, MintRequest, EIP712Signature, PartialUserOperation, BurnRequest, ReceiverConsent, PathKey, PoolKey, SponsorshipScenario } from '@pafi-dev/core';
+import { PointTokenDomainConfig, MintRequest, EIP712Signature, PartialUserOperation, BurnRequest, ReceiverConsent, PathKey, PoolKey, SponsorAuthScenario, SponsorAuthPayload, SponsorshipScenario } from '@pafi-dev/core';
 
 /**
  * Lifecycle of a minting request as tracked by the issuer's point ledger.
@@ -1486,35 +1486,83 @@ interface PafiBackendConfig {
      */
     retry?: RetryConfig;
 }
-/** Paired with `POST /paymaster/sponsor`. See SPONSORED_PATH_FLOW.md §4.1 */
+/**
+ * @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: {
-        /** The allowlisted contract this batch call targets. */
         contract: Address;
-        /** Function selector / name — validated against allowlist. */
         function: string;
-        /** The PointToken involved (for scenario context). */
         pointToken?: Address;
     };
 }
+/** @deprecated See `SponsorshipRequest`. Use `SponsorAuthResponse` in beta.8+. */
 interface SponsorshipResponse {
     paymaster: Address;
     paymasterData: Hex;
     paymasterVerificationGasLimit: bigint;
     paymasterPostOpGasLimit: bigint;
-    /** Unix seconds when this sponsorship expires. Re-request after. */
     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;
+    };
+}
 /**
- * Machine-readable error codes returned by PAFI Backend.
+ * Response from `POST /sponsor-auth`.
  *
- * Source of truth: `apps/paymaster-proxy` `CalldataValidationError`,
- * `RateLimitError`, `CoinbaseClientError`. Keep in sync.
+ * `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`.
  */
-type PafiBackendErrorCode = "MISSING_ISSUER_ID" | "MISSING_API_KEY" | "ISSUER_UNAUTHORIZED" | "CALLDATA_INVALID" | "CALLDATA_EMPTY_BATCH" | "TARGET_NOT_ALLOWLISTED" | "FUNCTION_NOT_ALLOWED" | "SCENARIO_MISMATCH" | "SCENARIO_DISABLED" | "RATE_LIMIT_EXCEEDED" | "RATE_LIMIT_EXCEEDED_DAILY" | "RATE_LIMIT_EXCEEDED_PER_USER" | "RATE_LIMITER_UNAVAILABLE" | "PAYMASTER_REJECTED" | "PAYMASTER_UNAVAILABLE" | "PAYMASTER_TIMEOUT" | "BAD_REQUEST" | "INTERNAL_ERROR" | "TIMEOUT" | "NETWORK_ERROR";
+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";
 declare class PafiBackendError extends Error {
     code: PafiBackendErrorCode;
     httpStatus: number;
@@ -1560,15 +1608,31 @@ declare class PafiBackendClient {
     private readonly retry;
     constructor(config: PafiBackendConfig);
     /**
-     * Request paymaster sponsorship for a pre-built UserOperation.
-     * See [SPONSORED_PATH_FLOW.md §4.1] for the API contract.
+     * 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.
      *
-     * Retries automatically on transient failures (5xx, timeouts, network
-     * errors, and errors the server flags with `safeToRetry: true`) up to
-     * `retry.maxAttempts`. 4xx errors 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;
     /**

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, SponsorshipScenario } from '@pafi-dev/core';
+import { PointTokenDomainConfig, MintRequest, EIP712Signature, PartialUserOperation, BurnRequest, ReceiverConsent, PathKey, PoolKey, SponsorAuthScenario, SponsorAuthPayload, SponsorshipScenario } from '@pafi-dev/core';
 
 /**
  * Lifecycle of a minting request as tracked by the issuer's point ledger.
@@ -1486,35 +1486,83 @@ interface PafiBackendConfig {
      */
     retry?: RetryConfig;
 }
-/** Paired with `POST /paymaster/sponsor`. See SPONSORED_PATH_FLOW.md §4.1 */
+/**
+ * @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: {
-        /** The allowlisted contract this batch call targets. */
         contract: Address;
-        /** Function selector / name — validated against allowlist. */
         function: string;
-        /** The PointToken involved (for scenario context). */
         pointToken?: Address;
     };
 }
+/** @deprecated See `SponsorshipRequest`. Use `SponsorAuthResponse` in beta.8+. */
 interface SponsorshipResponse {
     paymaster: Address;
     paymasterData: Hex;
     paymasterVerificationGasLimit: bigint;
     paymasterPostOpGasLimit: bigint;
-    /** Unix seconds when this sponsorship expires. Re-request after. */
     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;
+    };
+}
 /**
- * Machine-readable error codes returned by PAFI Backend.
+ * Response from `POST /sponsor-auth`.
  *
- * Source of truth: `apps/paymaster-proxy` `CalldataValidationError`,
- * `RateLimitError`, `CoinbaseClientError`. Keep in sync.
+ * `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`.
  */
-type PafiBackendErrorCode = "MISSING_ISSUER_ID" | "MISSING_API_KEY" | "ISSUER_UNAUTHORIZED" | "CALLDATA_INVALID" | "CALLDATA_EMPTY_BATCH" | "TARGET_NOT_ALLOWLISTED" | "FUNCTION_NOT_ALLOWED" | "SCENARIO_MISMATCH" | "SCENARIO_DISABLED" | "RATE_LIMIT_EXCEEDED" | "RATE_LIMIT_EXCEEDED_DAILY" | "RATE_LIMIT_EXCEEDED_PER_USER" | "RATE_LIMITER_UNAVAILABLE" | "PAYMASTER_REJECTED" | "PAYMASTER_UNAVAILABLE" | "PAYMASTER_TIMEOUT" | "BAD_REQUEST" | "INTERNAL_ERROR" | "TIMEOUT" | "NETWORK_ERROR";
+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";
 declare class PafiBackendError extends Error {
     code: PafiBackendErrorCode;
     httpStatus: number;
@@ -1560,15 +1608,31 @@ declare class PafiBackendClient {
     private readonly retry;
     constructor(config: PafiBackendConfig);
     /**
-     * Request paymaster sponsorship for a pre-built UserOperation.
-     * See [SPONSORED_PATH_FLOW.md §4.1] for the API contract.
+     * 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.
      *
-     * Retries automatically on transient failures (5xx, timeouts, network
-     * errors, and errors the server flags with `safeToRetry: true`) up to
-     * `retry.maxAttempts`. 4xx errors 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;
     /**

package/dist/index.js

@@ -1827,18 +1827,22 @@ var PafiBackendError = class extends Error {
   get safeToRetry() {
     if (this.serverSafeToRetry !== void 0) return this.serverSafeToRetry;
     switch (this.code) {
+      // Transient infra
       case "PAYMASTER_UNAVAILABLE":
       case "PAYMASTER_TIMEOUT":
       case "RATE_LIMITER_UNAVAILABLE":
+      case "KMS_UNAVAILABLE":
+      case "SPONSOR_AUTH_SIGNING_FAILED":
       case "INTERNAL_ERROR":
       case "TIMEOUT":
       case "NETWORK_ERROR":
         return true;
+      // Rate-limited — safe to retry after retryAfter window
       case "RATE_LIMIT_EXCEEDED":
       case "RATE_LIMIT_EXCEEDED_DAILY":
       case "RATE_LIMIT_EXCEEDED_PER_USER":
+      case "ISSUER_BUDGET_EXCEEDED":
         return true;
-      // after retryAfter
       default:
         return false;
     }
@@ -1886,15 +1890,36 @@ var PafiBackendClient = class {
     }
   }
   /**
-   * Request paymaster sponsorship for a pre-built UserOperation.
-   * See [SPONSORED_PATH_FLOW.md §4.1] for the API contract.
+   * Request a SponsorAuth signature from PAFI sponsor-relayer (beta.8+).
    *
-   * Retries automatically on transient failures (5xx, timeouts, network
-   * errors, and errors the server flags with `safeToRetry: true`) up to
-   * `retry.maxAttempts`. 4xx errors that are not `safeToRetry` fail fast.
+   * 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
    */
+  async requestSponsorAuth(req) {
+    return this.postWithRetry(
+      "/sponsor-auth",
+      req
+    );
+  }
+  /**
+   * @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
+   */
   async requestSponsorship(req) {
     return this.postWithRetry(
       "/paymaster/sponsor",