@pafi-dev/issuer 0.5.37 → 0.5.38

package/dist/index.d.cts

@@ -2156,6 +2156,68 @@ interface QuotePointTokenToUsdtResult {
 }
 declare function quotePointTokenToUsdt(params: QuotePointTokenToUsdtParams): Promise<QuotePointTokenToUsdtResult>;
 
+/**
+ * Normalized HTTP status the issuer controller should surface for a
+ * given SDK error. Kept to the three statuses every issuer needs —
+ * `400/500/etc.` are not used because every SDK error already maps
+ * cleanly into one of these three buckets.
+ */
+type SdkErrorStatus = "not_found" | "unprocessable" | "service_unavailable";
+/**
+ * Structured body the issuer controller passes to its
+ * framework-specific exception class. Mirrors the shape every PAFI
+ * issuer surfaces over HTTP today.
+ */
+interface SdkErrorBody {
+    code: string;
+    message: string;
+    details?: unknown;
+    safeToRetry: boolean;
+}
+/**
+ * Per-status exception factories. The issuer's controller wires one
+ * factory per status to its preferred framework's exception class
+ * (NestJS `UnprocessableEntityException`, Fastify `httpErrors.badData`,
+ * etc). The factory must throw or return an Error — `createSdkErrorMapper`
+ * uses `throw factory(body)` so either form is fine.
+ */
+interface SdkErrorMapperFactories {
+    notFound: (body: SdkErrorBody) => Error;
+    unprocessable: (body: SdkErrorBody) => Error;
+    serviceUnavailable: (body: SdkErrorBody) => Error;
+}
+/**
+ * Build a single error-mapping function that converts any typed SDK
+ * error into the issuer's framework-specific HTTP exception.
+ *
+ *   - `PendingUserOpNotFoundError`   → 404 (lock expired / already submitted)
+ *   - `BundlerNotConfiguredError`    → 503 (PAFI backend client missing)
+ *   - `IssuerStateError`             → 422 (cap exceeded / inactive)
+ *   - `PerpDepositError`             → 422 (Orderly relay quote / broker)
+ *   - `PTClaimError`, `PTRedeemError`, `SwapError`, `BundlerRejectedError` → 422
+ *   - any other error                → re-thrown as-is
+ *
+ * `safeToRetry` is `true` only for transient cases:
+ *   - `MINT_CAP_EXCEEDED` (cap may free up between requests)
+ *   - `RELAY_FEE_EXCEEDS_AMOUNT` (Orderly fee may drop)
+ *
+ * Usage (NestJS):
+ *
+ * ```ts
+ * const mapSdkError = createSdkErrorMapper({
+ *   notFound: (body) => new NotFoundException(body),
+ *   unprocessable: (body) => new UnprocessableEntityException(body),
+ *   serviceUnavailable: (body) => new ServiceUnavailableException(body),
+ * });
+ *
+ * try { ... } catch (err) { mapSdkError(err); }
+ * ```
+ *
+ * Returns `never` so call sites in `try/catch` propagate the throw
+ * without a redundant `throw` keyword.
+ */
+declare function createSdkErrorMapper(factories: SdkErrorMapperFactories): (err: unknown) => never;
+
 /**
  * Config for `createSubgraphPoolsProvider`.
  */
@@ -2680,4 +2742,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, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, 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, 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, PendingUserOpNotFoundError, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, 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, type QuotePointTokenToUsdtParams, type QuotePointTokenToUsdtResult, 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, SwapError, SwapHandler, type SwapHandlerConfig, type SwapRequest, type SwapResponse, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, quotePointTokenToUsdt, relayUserOp, requestPaymaster, 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 HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, 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, 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, PendingUserOpNotFoundError, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, 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, type QuotePointTokenToUsdtParams, type QuotePointTokenToUsdtResult, 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, SwapError, SwapHandler, type SwapHandlerConfig, type SwapRequest, type SwapResponse, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, quotePointTokenToUsdt, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };

package/dist/index.d.ts

@@ -2156,6 +2156,68 @@ interface QuotePointTokenToUsdtResult {
 }
 declare function quotePointTokenToUsdt(params: QuotePointTokenToUsdtParams): Promise<QuotePointTokenToUsdtResult>;
 
+/**
+ * Normalized HTTP status the issuer controller should surface for a
+ * given SDK error. Kept to the three statuses every issuer needs —
+ * `400/500/etc.` are not used because every SDK error already maps
+ * cleanly into one of these three buckets.
+ */
+type SdkErrorStatus = "not_found" | "unprocessable" | "service_unavailable";
+/**
+ * Structured body the issuer controller passes to its
+ * framework-specific exception class. Mirrors the shape every PAFI
+ * issuer surfaces over HTTP today.
+ */
+interface SdkErrorBody {
+    code: string;
+    message: string;
+    details?: unknown;
+    safeToRetry: boolean;
+}
+/**
+ * Per-status exception factories. The issuer's controller wires one
+ * factory per status to its preferred framework's exception class
+ * (NestJS `UnprocessableEntityException`, Fastify `httpErrors.badData`,
+ * etc). The factory must throw or return an Error — `createSdkErrorMapper`
+ * uses `throw factory(body)` so either form is fine.
+ */
+interface SdkErrorMapperFactories {
+    notFound: (body: SdkErrorBody) => Error;
+    unprocessable: (body: SdkErrorBody) => Error;
+    serviceUnavailable: (body: SdkErrorBody) => Error;
+}
+/**
+ * Build a single error-mapping function that converts any typed SDK
+ * error into the issuer's framework-specific HTTP exception.
+ *
+ *   - `PendingUserOpNotFoundError`   → 404 (lock expired / already submitted)
+ *   - `BundlerNotConfiguredError`    → 503 (PAFI backend client missing)
+ *   - `IssuerStateError`             → 422 (cap exceeded / inactive)
+ *   - `PerpDepositError`             → 422 (Orderly relay quote / broker)
+ *   - `PTClaimError`, `PTRedeemError`, `SwapError`, `BundlerRejectedError` → 422
+ *   - any other error                → re-thrown as-is
+ *
+ * `safeToRetry` is `true` only for transient cases:
+ *   - `MINT_CAP_EXCEEDED` (cap may free up between requests)
+ *   - `RELAY_FEE_EXCEEDS_AMOUNT` (Orderly fee may drop)
+ *
+ * Usage (NestJS):
+ *
+ * ```ts
+ * const mapSdkError = createSdkErrorMapper({
+ *   notFound: (body) => new NotFoundException(body),
+ *   unprocessable: (body) => new UnprocessableEntityException(body),
+ *   serviceUnavailable: (body) => new ServiceUnavailableException(body),
+ * });
+ *
+ * try { ... } catch (err) { mapSdkError(err); }
+ * ```
+ *
+ * Returns `never` so call sites in `try/catch` propagate the throw
+ * without a redundant `throw` keyword.
+ */
+declare function createSdkErrorMapper(factories: SdkErrorMapperFactories): (err: unknown) => never;
+
 /**
  * Config for `createSubgraphPoolsProvider`.
  */
@@ -2680,4 +2742,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, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, 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, 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, PendingUserOpNotFoundError, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, 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, type QuotePointTokenToUsdtParams, type QuotePointTokenToUsdtResult, 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, SwapError, SwapHandler, type SwapHandlerConfig, type SwapRequest, type SwapResponse, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, quotePointTokenToUsdt, relayUserOp, requestPaymaster, 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 HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, 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, 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, PendingUserOpNotFoundError, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, 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, type QuotePointTokenToUsdtParams, type QuotePointTokenToUsdtResult, 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, SwapError, SwapHandler, type SwapHandlerConfig, type SwapRequest, type SwapResponse, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createNativePtQuoter, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, quotePointTokenToUsdt, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };

package/dist/index.js

@@ -2519,6 +2519,50 @@ async function quotePointTokenToUsdt(params) {
   };
 }
 
+// src/api/errorMapper.ts
+function createSdkErrorMapper(factories) {
+  return (err) => {
+    if (err instanceof PendingUserOpNotFoundError) {
+      throw factories.notFound({
+        code: err.code,
+        message: err.message,
+        safeToRetry: false
+      });
+    }
+    if (err instanceof BundlerNotConfiguredError) {
+      throw factories.serviceUnavailable({
+        code: err.code,
+        message: err.message,
+        safeToRetry: false
+      });
+    }
+    if (err instanceof IssuerStateError) {
+      throw factories.unprocessable({
+        code: err.code,
+        message: err.message,
+        details: err.details,
+        safeToRetry: err.code === "MINT_CAP_EXCEEDED"
+      });
+    }
+    if (err instanceof PerpDepositError) {
+      throw factories.unprocessable({
+        code: err.code,
+        message: err.message,
+        safeToRetry: err.code === "RELAY_FEE_EXCEEDS_AMOUNT"
+      });
+    }
+    if (err instanceof PTClaimError || err instanceof PTRedeemError || err instanceof SwapError || err instanceof BundlerRejectedError) {
+      throw factories.unprocessable({
+        code: err.code,
+        message: err.message,
+        details: "details" in err ? err.details : void 0,
+        safeToRetry: false
+      });
+    }
+    throw err;
+  };
+}
+
 // src/pools/subgraphPoolsProvider.ts
 import { isAddress } from "viem";
 import { PAFI_SUBGRAPH_URL } from "@pafi-dev/core";
@@ -3454,6 +3498,7 @@ export {
   authenticateRequest,
   createIssuerService,
   createNativePtQuoter,
+  createSdkErrorMapper,
   createSubgraphNativeUsdtQuoter,
   createSubgraphPoolsProvider,
   handleClaimStatus,