@pafi-dev/issuer 0.5.33 → 0.5.34

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Address, Hex, PublicClient, WalletClient } from 'viem';
-import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, UserOpTypedData } from '@pafi-dev/core';
+import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, ENTRY_POINT_V08, UserOpTypedData } from '@pafi-dev/core';
 export { PAFI_SUBGRAPH_URL } from '@pafi-dev/core';
 
 /**
@@ -1744,6 +1744,98 @@ declare class BalanceAggregator {
     getCombinedBalanceMulti(user: Address, pointTokens: Address[]): Promise<Map<Address, CombinedBalance>>;
 }
 
+/**
+ * Typed errors thrown by the helpers below — issuer controllers map
+ * these to the appropriate HTTP status. We don't depend on @nestjs/common
+ * here because the SDK is framework-agnostic; the consuming controller
+ * wraps each one in its preferred exception class.
+ */
+declare class BundlerNotConfiguredError extends Error {
+    readonly code = "BUNDLER_NOT_CONFIGURED";
+    constructor();
+}
+declare class BundlerRejectedError extends Error {
+    readonly code = "BUNDLER_REJECTED";
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+interface RequestPaymasterParams {
+    /** PAFI backend client. When `null` / `undefined` → returns `undefined`. */
+    client: PafiBackendClient | null | undefined;
+    chainId: number;
+    scenario: string;
+    /** UserOp skeleton — must have all gas + fee fields set. */
+    userOp: {
+        sender: Address;
+        nonce: bigint;
+        callData: Hex;
+        callGasLimit: bigint;
+        verificationGasLimit: bigint;
+        preVerificationGas: bigint;
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+    };
+    /** Target contract (typically the PointToken). */
+    pointTokenAddress: Address;
+    /**
+     * Function name to surface in audit / paymaster context. Defaults to
+     * a per-scenario sensible value (`mint` / `burn` / `swap` / generic
+     * scenario name).
+     */
+    functionName?: string;
+    /** Optional logger for the "sponsorship declined" warning. */
+    onWarning?: (msg: string) => void;
+}
+/**
+ * Thin wrapper around `PafiBackendClient.requestSponsorship` with the
+ * "non-fatal on failure" semantics every issuer wants:
+ *
+ * - When the client is missing → returns `undefined` (the caller falls
+ *   back to a self-funded UserOp).
+ * - When the network call throws OR PAFI declines (rate limit, intent
+ *   rejection, paymaster outage) → returns `undefined` after logging,
+ *   so the controller doesn't hard-fail. The caller's
+ *   `prepareMobileUserOp` / `mergePaymasterFields` will gracefully
+ *   produce the unsponsored variant.
+ *
+ * Replaces ~30 LoC of try/catch + scenario-to-function mapping every
+ * issuer would copy.
+ */
+declare function requestPaymaster(params: RequestPaymasterParams): Promise<Awaited<ReturnType<PafiBackendClient["requestSponsorship"]>> | undefined>;
+interface RelayUserOpParams {
+    client: PafiBackendClient | null | undefined;
+    /** EntryPoint address — typically `ENTRY_POINT_V08` from core. */
+    entryPoint: typeof ENTRY_POINT_V08 | string;
+    userOp: Record<string, string | null>;
+    /** EIP-7702 authorization (delegation UserOps only). */
+    eip7702Auth?: {
+        chainId: string;
+        address: string;
+        nonce: string;
+        r: string;
+        s: string;
+        yParity: string;
+    };
+}
+/**
+ * Submit a serialized UserOp to the Pimlico bundler via PAFI's
+ * sponsor-relayer. Handles the "client missing" / "bundler rejected"
+ * branches as typed errors so the controller can map to HTTP cleanly.
+ *
+ * Every issuer mobile flow has this exact wrapper — moved into SDK
+ * to drop ~30 LoC of try/catch + error-shape boilerplate per
+ * controller.
+ *
+ * Throws:
+ * - `BundlerNotConfiguredError` — caller didn't configure
+ *   `PafiBackendClient`. Map to 503.
+ * - `BundlerRejectedError` — bundler returned an error. Map to 422
+ *   (the FE can show the reason — usually `AA21` / `AA34` / etc.).
+ */
+declare function relayUserOp(params: RelayUserOpParams): Promise<{
+    userOpHash: Hex;
+}>;
+
 /**
  * Top-level configuration for `createIssuerService`.
  *
@@ -2177,4 +2269,4 @@ declare class IssuerStateValidator {
 /** SDK package version — bumped on every release */
 declare const PAFI_ISSUER_SDK_VERSION = "0.4.0";
 
-export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type NativePtQuoterConfig, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingCredit, type PendingUserOpEntry, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, RelayError, type RelayErrorCode, RelayService, type RelayUserOpRequest, type RelayUserOpResponse, type RetryConfig, type SerializedUserOpTypedData, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, serializeEntryToJsonRpc, serializeUserOpTypedData };
+export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, 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 CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type NativePtQuoterConfig, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingCredit, type PendingUserOpEntry, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type RetryConfig, type SerializedUserOpTypedData, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Address, Hex, PublicClient, WalletClient } from 'viem';
-import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, UserOpTypedData } from '@pafi-dev/core';
+import { PointTokenDomainConfig, PartialUserOperation, BurnRequest, PoolKey, ENTRY_POINT_V08, UserOpTypedData } from '@pafi-dev/core';
 export { PAFI_SUBGRAPH_URL } from '@pafi-dev/core';
 
 /**
@@ -1744,6 +1744,98 @@ declare class BalanceAggregator {
     getCombinedBalanceMulti(user: Address, pointTokens: Address[]): Promise<Map<Address, CombinedBalance>>;
 }
 
+/**
+ * Typed errors thrown by the helpers below — issuer controllers map
+ * these to the appropriate HTTP status. We don't depend on @nestjs/common
+ * here because the SDK is framework-agnostic; the consuming controller
+ * wraps each one in its preferred exception class.
+ */
+declare class BundlerNotConfiguredError extends Error {
+    readonly code = "BUNDLER_NOT_CONFIGURED";
+    constructor();
+}
+declare class BundlerRejectedError extends Error {
+    readonly code = "BUNDLER_REJECTED";
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+interface RequestPaymasterParams {
+    /** PAFI backend client. When `null` / `undefined` → returns `undefined`. */
+    client: PafiBackendClient | null | undefined;
+    chainId: number;
+    scenario: string;
+    /** UserOp skeleton — must have all gas + fee fields set. */
+    userOp: {
+        sender: Address;
+        nonce: bigint;
+        callData: Hex;
+        callGasLimit: bigint;
+        verificationGasLimit: bigint;
+        preVerificationGas: bigint;
+        maxFeePerGas: bigint;
+        maxPriorityFeePerGas: bigint;
+    };
+    /** Target contract (typically the PointToken). */
+    pointTokenAddress: Address;
+    /**
+     * Function name to surface in audit / paymaster context. Defaults to
+     * a per-scenario sensible value (`mint` / `burn` / `swap` / generic
+     * scenario name).
+     */
+    functionName?: string;
+    /** Optional logger for the "sponsorship declined" warning. */
+    onWarning?: (msg: string) => void;
+}
+/**
+ * Thin wrapper around `PafiBackendClient.requestSponsorship` with the
+ * "non-fatal on failure" semantics every issuer wants:
+ *
+ * - When the client is missing → returns `undefined` (the caller falls
+ *   back to a self-funded UserOp).
+ * - When the network call throws OR PAFI declines (rate limit, intent
+ *   rejection, paymaster outage) → returns `undefined` after logging,
+ *   so the controller doesn't hard-fail. The caller's
+ *   `prepareMobileUserOp` / `mergePaymasterFields` will gracefully
+ *   produce the unsponsored variant.
+ *
+ * Replaces ~30 LoC of try/catch + scenario-to-function mapping every
+ * issuer would copy.
+ */
+declare function requestPaymaster(params: RequestPaymasterParams): Promise<Awaited<ReturnType<PafiBackendClient["requestSponsorship"]>> | undefined>;
+interface RelayUserOpParams {
+    client: PafiBackendClient | null | undefined;
+    /** EntryPoint address — typically `ENTRY_POINT_V08` from core. */
+    entryPoint: typeof ENTRY_POINT_V08 | string;
+    userOp: Record<string, string | null>;
+    /** EIP-7702 authorization (delegation UserOps only). */
+    eip7702Auth?: {
+        chainId: string;
+        address: string;
+        nonce: string;
+        r: string;
+        s: string;
+        yParity: string;
+    };
+}
+/**
+ * Submit a serialized UserOp to the Pimlico bundler via PAFI's
+ * sponsor-relayer. Handles the "client missing" / "bundler rejected"
+ * branches as typed errors so the controller can map to HTTP cleanly.
+ *
+ * Every issuer mobile flow has this exact wrapper — moved into SDK
+ * to drop ~30 LoC of try/catch + error-shape boilerplate per
+ * controller.
+ *
+ * Throws:
+ * - `BundlerNotConfiguredError` — caller didn't configure
+ *   `PafiBackendClient`. Map to 503.
+ * - `BundlerRejectedError` — bundler returned an error. Map to 422
+ *   (the FE can show the reason — usually `AA21` / `AA34` / etc.).
+ */
+declare function relayUserOp(params: RelayUserOpParams): Promise<{
+    userOpHash: Hex;
+}>;
+
 /**
  * Top-level configuration for `createIssuerService`.
  *
@@ -2177,4 +2269,4 @@ declare class IssuerStateValidator {
 /** SDK package version — bumped on every release */
 declare const PAFI_ISSUER_SDK_VERSION = "0.4.0";
 
-export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type NativePtQuoterConfig, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingCredit, type PendingUserOpEntry, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, RelayError, type RelayErrorCode, RelayService, type RelayUserOpRequest, type RelayUserOpResponse, type RetryConfig, type SerializedUserOpTypedData, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, serializeEntryToJsonRpc, serializeUserOpTypedData };
+export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, 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 CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type NativePtQuoterConfig, NonceManager, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, type PendingCredit, type PendingUserOpEntry, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type RetryConfig, type SerializedUserOpTypedData, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };

package/dist/index.js

@@ -2315,6 +2315,76 @@ var PafiBackendClient = class {
   }
 };
 
+// src/pafi-backend/helpers.ts
+var BundlerNotConfiguredError = class extends Error {
+  code = "BUNDLER_NOT_CONFIGURED";
+  constructor() {
+    super(
+      "PAFI backend client not configured \u2014 set PAFI_BACKEND_URL, PAFI_ISSUER_ID, PAFI_API_KEY to enable mobile submit."
+    );
+    this.name = "BundlerNotConfiguredError";
+  }
+};
+var BundlerRejectedError = class extends Error {
+  code = "BUNDLER_REJECTED";
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "BundlerRejectedError";
+    this.cause = cause;
+  }
+};
+async function requestPaymaster(params) {
+  if (!params.client) return void 0;
+  const fn = params.functionName ?? defaultFunctionForScenario(params.scenario);
+  try {
+    return await params.client.requestSponsorship({
+      chainId: params.chainId,
+      scenario: params.scenario,
+      userOp: params.userOp,
+      target: {
+        contract: params.pointTokenAddress,
+        function: fn,
+        pointToken: params.pointTokenAddress
+      }
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    params.onWarning?.(`Paymaster sponsorship declined: ${msg}`);
+    return void 0;
+  }
+}
+function defaultFunctionForScenario(scenario) {
+  switch (scenario) {
+    case "mint":
+      return "mint";
+    case "burn":
+      return "burn";
+    case "swap":
+      return "swap";
+    case "perp-deposit":
+      return "deposit";
+    default:
+      return scenario;
+  }
+}
+async function relayUserOp(params) {
+  if (!params.client) {
+    throw new BundlerNotConfiguredError();
+  }
+  try {
+    const result = await params.client.relayUserOperation({
+      userOp: params.userOp,
+      entryPoint: params.entryPoint,
+      eip7702Auth: params.eip7702Auth
+    });
+    return { userOpHash: result.userOpHash };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new BundlerRejectedError(msg, err);
+  }
+}
+
 // src/config.ts
 import { getAddress as getAddress8 } from "viem";
 import { getContractAddresses as getContractAddresses2 } from "@pafi-dev/core";
@@ -2750,6 +2820,8 @@ export {
   AuthError,
   AuthService,
   BalanceAggregator,
+  BundlerNotConfiguredError,
+  BundlerRejectedError,
   BurnIndexer,
   DefaultPolicyEngine,
   FeeManager,
@@ -2780,6 +2852,8 @@ export {
   handleRedeemStatus,
   mergePaymasterFields,
   prepareMobileUserOp,
+  relayUserOp,
+  requestPaymaster,
   serializeEntryToJsonRpc,
   serializeUserOpTypedData
 };