@pafi-dev/issuer 0.7.0 → 0.7.1

package/dist/index.cjs

@@ -20,12 +20,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AdapterMisconfiguredError: () => AdapterMisconfiguredError,
   AuthError: () => AuthError,
   AuthService: () => AuthService,
   BalanceAggregator: () => BalanceAggregator,
   BundlerNotConfiguredError: () => BundlerNotConfiguredError,
   BundlerRejectedError: () => BundlerRejectedError,
   BurnIndexer: () => BurnIndexer,
+  ConfigurationError: () => ConfigurationError,
   DefaultPolicyEngine: () => DefaultPolicyEngine,
   FeeManager: () => FeeManager,
   InMemoryCursorStore: () => InMemoryCursorStore,
@@ -53,6 +55,7 @@ __export(index_exports, {
   PointIndexer: () => PointIndexer,
   RelayError: () => RelayError,
   RelayService: () => RelayService,
+  ValidationError: () => ValidationError,
   authenticateRequest: () => authenticateRequest,
   createIssuerService: () => createIssuerService,
   createNativePtQuoter: () => createNativePtQuoter,
@@ -88,6 +91,26 @@ var PafiSdkError = class extends Error {
     this.name = new.target.name;
   }
 };
+var ValidationError = class extends PafiSdkError {
+  httpStatus = "unprocessable";
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+};
+var ConfigurationError = class extends PafiSdkError {
+  httpStatus = "service_unavailable";
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+};
 
 // src/policy/defaultPolicy.ts
 var DefaultPolicyEngine = class {
@@ -258,12 +281,32 @@ var import_viem2 = require("viem");
 var import_core = require("@pafi-dev/core");
 
 // src/auth/errors.ts
-var AuthError = class extends Error {
+function statusForCode(code) {
+  switch (code) {
+    case "INVALID_MESSAGE":
+    case "DOMAIN_MISMATCH":
+    case "CHAIN_MISMATCH":
+    case "MESSAGE_EXPIRED":
+    case "MESSAGE_NOT_YET_VALID":
+    case "MALFORMED_TOKEN":
+      return "unprocessable";
+    case "NONCE_INVALID":
+    case "SIGNATURE_INVALID":
+    case "MISSING_TOKEN":
+    case "TOKEN_INVALID":
+    case "TOKEN_EXPIRED":
+      return "forbidden";
+    case "SESSION_REVOKED":
+      return "not_found";
+  }
+}
+var AuthError = class extends PafiSdkError {
   code;
+  httpStatus;
   constructor(code, message) {
     super(message);
-    this.name = "AuthError";
     this.code = code;
+    this.httpStatus = statusForCode(code);
   }
 };
 
@@ -460,14 +503,15 @@ async function authenticateRequest(authHeader, authService) {
 }
 
 // src/relay/types.ts
-var RelayError = class extends Error {
+var RelayError = class extends PafiSdkError {
+  httpStatus = "unprocessable";
   code;
-  cause;
   constructor(code, message, cause) {
     super(message);
-    this.name = "RelayError";
     this.code = code;
-    if (cause !== void 0) this.cause = cause;
+    if (cause !== void 0) {
+      this.cause = cause;
+    }
   }
 };
 
@@ -1168,13 +1212,16 @@ var IssuerApiHandlers = class {
   /** `POST /auth/login` */
   async handleLogin(body) {
     if (!body || typeof body.message !== "string" || body.message.length === 0 || typeof body.signature !== "string" || body.signature.length <= 2) {
-      throw new Error("handleLogin: message and signature are required");
+      throw new ValidationError(
+        "INVALID_LOGIN_BODY",
+        "handleLogin: message and signature are required"
+      );
     }
     if (body.message.length > 4096) {
-      throw new Error("message too long");
+      throw new ValidationError("MESSAGE_TOO_LONG", "message too long");
     }
     if (body.signature.length > 260) {
-      throw new Error("signature too long");
+      throw new ValidationError("SIGNATURE_TOO_LONG", "signature too long");
     }
     const result = await this.authService.login(body.message, body.signature);
     return {
@@ -1191,11 +1238,15 @@ var IssuerApiHandlers = class {
    */
   async handleConfig(chainId) {
     if (!Number.isInteger(chainId) || chainId <= 0) {
-      throw new Error("invalid chainId");
+      throw new ValidationError("INVALID_CHAIN_ID", "invalid chainId", {
+        chainId
+      });
     }
     if (chainId !== this.chainId) {
-      throw new Error(
-        `handleConfig: unsupported chainId ${chainId}`
+      throw new ValidationError(
+        "UNSUPPORTED_CHAIN_ID",
+        `handleConfig: unsupported chainId ${chainId}`,
+        { requested: chainId, supported: this.chainId }
       );
     }
     const contracts = {
@@ -1212,7 +1263,8 @@ var IssuerApiHandlers = class {
   /** `GET /gas-fee` — quoted in USDT (6-decimal base units). */
   async handleGasFee() {
     if (!this.feeManager) {
-      throw new Error(
+      throw new ConfigurationError(
+        "FEE_MANAGER_NOT_CONFIGURED",
         "handleGasFee: feeManager is not configured on this issuer"
       );
     }
@@ -1234,13 +1286,16 @@ var IssuerApiHandlers = class {
    */
   async handlePools(_userAddress, request) {
     if (!this.poolsProvider) {
-      throw new Error(
+      throw new ConfigurationError(
+        "POOLS_PROVIDER_NOT_CONFIGURED",
         "handlePools: poolsProvider is not configured on this issuer"
       );
     }
     if (request.chainId !== this.chainId) {
-      throw new Error(
-        `handlePools: unsupported chainId ${request.chainId}`
+      throw new ValidationError(
+        "UNSUPPORTED_CHAIN_ID",
+        `handlePools: unsupported chainId ${request.chainId}`,
+        { requested: request.chainId, supported: this.chainId }
       );
     }
     return this.poolsProvider(request);
@@ -1254,21 +1309,27 @@ var IssuerApiHandlers = class {
    */
   async handleUser(userAddress, request) {
     if (request.chainId !== this.chainId) {
-      throw new Error(
-        `handleUser: unsupported chainId ${request.chainId}`
+      throw new ValidationError(
+        "UNSUPPORTED_CHAIN_ID",
+        `handleUser: unsupported chainId ${request.chainId}`,
+        { requested: request.chainId, supported: this.chainId }
       );
     }
     const normalizedAuthed = (0, import_viem6.getAddress)(userAddress);
     const normalizedRequest = (0, import_viem6.getAddress)(request.userAddress);
     if (normalizedAuthed !== normalizedRequest) {
-      throw new Error(
-        "handleUser: request userAddress must match authenticated user"
+      throw new ValidationError(
+        "USER_ADDRESS_MISMATCH",
+        "handleUser: request userAddress must match authenticated user",
+        { authenticated: normalizedAuthed, requested: normalizedRequest }
       );
     }
     const pointToken = (0, import_viem6.getAddress)(request.pointTokenAddress);
     if (!this.supportedTokens.has(pointToken)) {
-      throw new Error(
-        `handleUser: unsupported pointToken ${pointToken}`
+      throw new ValidationError(
+        "UNSUPPORTED_POINT_TOKEN",
+        `handleUser: unsupported pointToken ${pointToken}`,
+        { requested: pointToken }
       );
     }
     const [mintRequestNonce, receiverConsentNonce, offChainBalance, onChainBalance, minter] = await Promise.all([
@@ -1464,69 +1525,82 @@ var PTRedeemHandler = class {
       this.redeemLockDurationMs,
       this.pointTokenAddress
     );
-    const sponsoredUserOp = await this.relayService.prepareBurn({
-      mode: "burnWithSig",
-      userAddress: request.userAddress,
-      aaNonce: request.aaNonce,
-      pointTokenAddress: this.pointTokenAddress,
-      batchExecutorAddress: this.batchExecutorAddress,
-      burnRequest: sponsoredBurnRequest,
-      burnerSignature: sponsoredSig,
-      feeAmount: fee,
-      feeRecipient
-    });
-    let fallback = void 0;
-    if (fee > 0n) {
-      const fallbackBurnRequest = {
-        from: request.userAddress,
-        amount: request.amount,
-        nonce: burnNonce,
-        deadline
-      };
-      let fallbackSig;
-      try {
-        fallbackSig = (await (0, import_core4.signBurnRequest)(this.burnerSignerWallet, domain, fallbackBurnRequest)).serialized;
-      } catch (err) {
-        throw new PTRedeemError(
-          "SIGNING_FAILED",
-          `failed to sign fallback BurnRequest: ${err instanceof Error ? err.message : String(err)}`
-        );
-      }
-      const fallbackLockId = await this.ledger.reservePendingCredit(
-        request.userAddress,
-        request.amount,
-        this.redeemLockDurationMs,
-        this.pointTokenAddress
-      );
-      const fallbackUserOp = await this.relayService.prepareBurn({
+    try {
+      const sponsoredUserOp = await this.relayService.prepareBurn({
         mode: "burnWithSig",
         userAddress: request.userAddress,
         aaNonce: request.aaNonce,
         pointTokenAddress: this.pointTokenAddress,
         batchExecutorAddress: this.batchExecutorAddress,
-        burnRequest: fallbackBurnRequest,
-        burnerSignature: fallbackSig,
-        // Explicit 0n — fallback is fee-free regardless of how
-        // RelayService is configured. Without this, an
-        // auto-quoting RelayService would try to quote a fee here
-        // and re-add the PT.transfer we're trying to strip.
-        feeAmount: 0n
+        burnRequest: sponsoredBurnRequest,
+        burnerSignature: sponsoredSig,
+        feeAmount: fee,
+        feeRecipient
       });
-      fallback = {
-        lockId: fallbackLockId,
-        userOp: fallbackUserOp,
-        netCreditAmount: request.amount
+      let fallback = void 0;
+      if (fee > 0n) {
+        const fallbackBurnRequest = {
+          from: request.userAddress,
+          amount: request.amount,
+          nonce: burnNonce,
+          deadline
+        };
+        let fallbackSig;
+        try {
+          fallbackSig = (await (0, import_core4.signBurnRequest)(this.burnerSignerWallet, domain, fallbackBurnRequest)).serialized;
+        } catch (err) {
+          throw new PTRedeemError(
+            "SIGNING_FAILED",
+            `failed to sign fallback BurnRequest: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+        const fallbackLockId = await this.ledger.reservePendingCredit(
+          request.userAddress,
+          request.amount,
+          this.redeemLockDurationMs,
+          this.pointTokenAddress
+        );
+        let fallbackUserOp;
+        try {
+          fallbackUserOp = await this.relayService.prepareBurn({
+            mode: "burnWithSig",
+            userAddress: request.userAddress,
+            aaNonce: request.aaNonce,
+            pointTokenAddress: this.pointTokenAddress,
+            batchExecutorAddress: this.batchExecutorAddress,
+            burnRequest: fallbackBurnRequest,
+            burnerSignature: fallbackSig,
+            // Explicit 0n — fallback is fee-free regardless of how
+            // RelayService is configured. Without this, an
+            // auto-quoting RelayService would try to quote a fee here
+            // and re-add the PT.transfer we're trying to strip.
+            feeAmount: 0n
+          });
+        } catch (err) {
+          await this.ledger.releaseLock(fallbackLockId).catch(() => {
+          });
+          throw err;
+        }
+        fallback = {
+          lockId: fallbackLockId,
+          userOp: fallbackUserOp,
+          netCreditAmount: request.amount
+        };
+      }
+      return {
+        lockId: sponsoredLockId,
+        userOp: sponsoredUserOp,
+        netCreditAmount: sponsoredBurnAmount,
+        feeAmount: fee,
+        fallback,
+        expiresInSeconds: Math.floor(this.redeemLockDurationMs / 1e3),
+        signatureDeadline: deadline
       };
+    } catch (err) {
+      await this.ledger.releaseLock(sponsoredLockId).catch(() => {
+      });
+      throw err;
     }
-    return {
-      lockId: sponsoredLockId,
-      userOp: sponsoredUserOp,
-      netCreditAmount: sponsoredBurnAmount,
-      feeAmount: fee,
-      fallback,
-      expiresInSeconds: Math.floor(this.redeemLockDurationMs / 1e3),
-      signatureDeadline: deadline
-    };
   }
 };
 
@@ -1794,6 +1868,41 @@ async function prepareMobileUserOp(params) {
   };
 }
 
+// src/pafi-backend/types.ts
+var PafiBackendError = class extends Error {
+  constructor(code, message, httpStatus, details, opts) {
+    super(message);
+    this.code = code;
+    this.httpStatus = httpStatus;
+    this.details = details;
+    this.name = "PafiBackendError";
+    if (opts?.retryAfter !== void 0) this.retryAfter = opts.retryAfter;
+    if (opts?.safeToRetry !== void 0) this.serverSafeToRetry = opts.safeToRetry;
+  }
+  code;
+  httpStatus;
+  details;
+  retryAfter;
+  serverSafeToRetry;
+  get safeToRetry() {
+    if (this.serverSafeToRetry !== void 0) return this.serverSafeToRetry;
+    switch (this.code) {
+      case "RATE_LIMITER_UNAVAILABLE":
+      case "INTERNAL_ERROR":
+      case "TIMEOUT":
+      case "NETWORK_ERROR":
+        return true;
+      case "RATE_LIMIT_EXCEEDED":
+      case "RATE_LIMIT_EXCEEDED_DAILY":
+      case "RATE_LIMIT_EXCEEDED_PER_USER":
+      case "ISSUER_BUDGET_EXCEEDED":
+        return true;
+      default:
+        return false;
+    }
+  }
+};
+
 // src/pafi-backend/helpers.ts
 var BundlerNotConfiguredError = class extends PafiSdkError {
   code = "BUNDLER_NOT_CONFIGURED";
@@ -1829,8 +1938,23 @@ async function requestPaymaster(params) {
     });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    params.onWarning?.(`Paymaster sponsorship declined: ${msg}`);
-    return void 0;
+    if (err instanceof PafiBackendError && isTransientPaymasterError(err.code)) {
+      params.onWarning?.(`Paymaster sponsorship declined (transient): ${msg}`);
+      return void 0;
+    }
+    throw err;
+  }
+}
+function isTransientPaymasterError(code) {
+  switch (code) {
+    case "NETWORK_ERROR":
+    case "TIMEOUT":
+    case "PAYMASTER_UNAVAILABLE":
+    case "RATE_LIMITER_UNAVAILABLE":
+    case "INTERNAL_ERROR":
+      return true;
+    default:
+      return false;
   }
 }
 function defaultFunctionForScenario(scenario) {
@@ -2011,39 +2135,19 @@ var PTClaimHandler = class {
       this.cfg.lockDurationMs,
       request.pointTokenAddress
     );
-    const signatureDeadline = BigInt(
-      Math.floor(this.cfg.now() / 1e3) + this.cfg.signatureDeadlineSeconds
-    );
-    const feeAmount = this.cfg.feeService ? await this.cfg.feeService.estimateGasFee() : 0n;
-    const domain = {
-      name: this.cfg.pointTokenDomainName,
-      chainId: request.chainId,
-      verifyingContract: request.pointTokenAddress
-    };
-    let userOp;
     try {
-      userOp = await this.cfg.relayService.prepareMint({
-        userAddress: request.userAddress,
-        aaNonce: request.aaNonce,
-        batchExecutorAddress,
-        pointTokenAddress: request.pointTokenAddress,
-        amount: request.amount,
-        issuerSignerWallet: this.cfg.issuerSignerWallet,
-        domain,
-        mintRequestNonce: request.mintRequestNonce,
-        deadline: signatureDeadline
-        // No feeAmount/feeRecipient — RelayService auto-resolves.
-      });
-    } catch (err) {
-      throw new PTClaimError(
-        "BUILD_FAILED",
-        `prepareMint failed: ${err instanceof Error ? err.message : String(err)}`
+      const signatureDeadline = BigInt(
+        Math.floor(this.cfg.now() / 1e3) + this.cfg.signatureDeadlineSeconds
       );
-    }
-    let fallback;
-    if (feeAmount > 0n) {
+      const feeAmount = this.cfg.feeService ? await this.cfg.feeService.estimateGasFee() : 0n;
+      const domain = {
+        name: this.cfg.pointTokenDomainName,
+        chainId: request.chainId,
+        verifyingContract: request.pointTokenAddress
+      };
+      let userOp;
       try {
-        fallback = await this.cfg.relayService.prepareMint({
+        userOp = await this.cfg.relayService.prepareMint({
           userAddress: request.userAddress,
           aaNonce: request.aaNonce,
           batchExecutorAddress,
@@ -2052,28 +2156,54 @@ var PTClaimHandler = class {
           issuerSignerWallet: this.cfg.issuerSignerWallet,
           domain,
           mintRequestNonce: request.mintRequestNonce,
-          deadline: signatureDeadline,
-          feeAmount: 0n
+          deadline: signatureDeadline
+          // No feeAmount/feeRecipient — RelayService auto-resolves.
         });
       } catch (err) {
         throw new PTClaimError(
           "BUILD_FAILED",
-          `prepareMint (fallback) failed: ${err instanceof Error ? err.message : String(err)}`
+          `prepareMint failed: ${err instanceof Error ? err.message : String(err)}`
         );
       }
+      let fallback;
+      if (feeAmount > 0n) {
+        try {
+          fallback = await this.cfg.relayService.prepareMint({
+            userAddress: request.userAddress,
+            aaNonce: request.aaNonce,
+            batchExecutorAddress,
+            pointTokenAddress: request.pointTokenAddress,
+            amount: request.amount,
+            issuerSignerWallet: this.cfg.issuerSignerWallet,
+            domain,
+            mintRequestNonce: request.mintRequestNonce,
+            deadline: signatureDeadline,
+            feeAmount: 0n
+          });
+        } catch (err) {
+          throw new PTClaimError(
+            "BUILD_FAILED",
+            `prepareMint (fallback) failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+      const calls = (0, import_core8.decodeBatchExecuteCalls)(userOp.callData);
+      const callsFallback = fallback ? (0, import_core8.decodeBatchExecuteCalls)(fallback.callData) : void 0;
+      return {
+        userOp,
+        fallback,
+        lockId,
+        feeAmount,
+        signatureDeadline,
+        expiresInSeconds: Math.floor(this.cfg.lockDurationMs / 1e3),
+        calls,
+        callsFallback
+      };
+    } catch (err) {
+      await this.cfg.ledger.releaseLock(lockId).catch(() => {
+      });
+      throw err;
     }
-    const calls = (0, import_core8.decodeBatchExecuteCalls)(userOp.callData);
-    const callsFallback = fallback ? (0, import_core8.decodeBatchExecuteCalls)(fallback.callData) : void 0;
-    return {
-      userOp,
-      fallback,
-      lockId,
-      feeAmount,
-      signatureDeadline,
-      expiresInSeconds: Math.floor(this.cfg.lockDurationMs / 1e3),
-      calls,
-      callsFallback
-    };
   }
 };
 
@@ -2303,9 +2433,45 @@ function createSdkErrorMapper(factories) {
 // src/api/issuerApiAdapter.ts
 var import_viem10 = require("viem");
 var import_core11 = require("@pafi-dev/core");
+var AdapterMisconfiguredError = class extends Error {
+  code = "ADAPTER_MISCONFIGURED";
+  constructor(message) {
+    super(message);
+    this.name = "AdapterMisconfiguredError";
+  }
+};
 var IssuerApiAdapter = class {
   cfg;
   constructor(config) {
+    if (config.ptClaimHandler) {
+      if (typeof config.ledger.bindMintUserOpHash !== "function") {
+        throw new AdapterMisconfiguredError(
+          "ledger.bindMintUserOpHash is required when ptClaimHandler is wired (mobile claim flow). Implement it on your IPointLedger or omit ptClaimHandler from IssuerApiAdapter config."
+        );
+      }
+      if (typeof config.ledger.getMintLock !== "function") {
+        throw new AdapterMisconfiguredError(
+          "ledger.getMintLock is required when ptClaimHandler is wired \u2014 claimStatus uses it to look up the lock."
+        );
+      }
+    }
+    if (config.ptRedeemHandler) {
+      if (typeof config.ledger.reservePendingCredit !== "function") {
+        throw new AdapterMisconfiguredError(
+          "ledger.reservePendingCredit is required when ptRedeemHandler is wired (burn/redeem reverse flow). PTRedeemHandler also enforces this at construction; see ledger/types.ts comments."
+        );
+      }
+      if (typeof config.ledger.bindCreditUserOpHash !== "function") {
+        throw new AdapterMisconfiguredError(
+          "ledger.bindCreditUserOpHash is required when ptRedeemHandler is wired (mobile redeem flow)."
+        );
+      }
+      if (typeof config.ledger.getPendingCredit !== "function") {
+        throw new AdapterMisconfiguredError(
+          "ledger.getPendingCredit is required when ptRedeemHandler is wired \u2014 redeemStatus uses it to look up the credit."
+        );
+      }
+    }
     this.cfg = config;
   }
   // ------------------------------ Read endpoints ---------------------------
@@ -2606,6 +2772,11 @@ var IssuerApiAdapter = class {
   /**
    * Build + sign a SponsorAuth payload. Returns `undefined` when no
    * issuer id is configured, so the controller can skip the field.
+   *
+   * v0.7.1 — `scenario` typed as `SponsorshipScenario` (was `string`).
+   * Previously a typo (`"perp_deposit"` vs `"perp-deposit"`) compiled
+   * fine but rejected at L1 by sponsor-relayer's IntentValidator. See
+   * SDK_ISSUER_AUDIT.md N5.
    */
   async buildSponsorAuth(authenticatedAddress, callData, chainId, scenario) {
     if (!this.cfg.pafiIssuerId) return void 0;
@@ -3066,41 +3237,6 @@ var BalanceAggregator = class {
   }
 };
 
-// src/pafi-backend/types.ts
-var PafiBackendError = class extends Error {
-  constructor(code, message, httpStatus, details, opts) {
-    super(message);
-    this.code = code;
-    this.httpStatus = httpStatus;
-    this.details = details;
-    this.name = "PafiBackendError";
-    if (opts?.retryAfter !== void 0) this.retryAfter = opts.retryAfter;
-    if (opts?.safeToRetry !== void 0) this.serverSafeToRetry = opts.safeToRetry;
-  }
-  code;
-  httpStatus;
-  details;
-  retryAfter;
-  serverSafeToRetry;
-  get safeToRetry() {
-    if (this.serverSafeToRetry !== void 0) return this.serverSafeToRetry;
-    switch (this.code) {
-      case "RATE_LIMITER_UNAVAILABLE":
-      case "INTERNAL_ERROR":
-      case "TIMEOUT":
-      case "NETWORK_ERROR":
-        return true;
-      case "RATE_LIMIT_EXCEEDED":
-      case "RATE_LIMIT_EXCEEDED_DAILY":
-      case "RATE_LIMIT_EXCEEDED_PER_USER":
-      case "ISSUER_BUDGET_EXCEEDED":
-        return true;
-      default:
-        return false;
-    }
-  }
-};
-
 // src/pafi-backend/client.ts
 function serializeBigInt(_key, value) {
   return typeof value === "bigint" ? value.toString(10) : value;
@@ -3541,15 +3677,17 @@ var IssuerStateValidator = class _IssuerStateValidator {
 };
 
 // src/index.ts
-var PAFI_ISSUER_SDK_VERSION = "0.4.0";
+var PAFI_ISSUER_SDK_VERSION = true ? "0.7.1" : "dev";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AdapterMisconfiguredError,
   AuthError,
   AuthService,
   BalanceAggregator,
   BundlerNotConfiguredError,
   BundlerRejectedError,
   BurnIndexer,
+  ConfigurationError,
   DefaultPolicyEngine,
   FeeManager,
   InMemoryCursorStore,
@@ -3577,6 +3715,7 @@ var PAFI_ISSUER_SDK_VERSION = "0.4.0";
   PointIndexer,
   RelayError,
   RelayService,
+  ValidationError,
   authenticateRequest,
   createIssuerService,
   createNativePtQuoter,