@pafi-dev/core 0.7.7 → 0.8.0

package/dist/index.d.cts

@@ -1,11 +1,11 @@
 import { Address, Hex, TypedDataDomain, PublicClient, WalletClient, TransactionReceipt, HttpTransport } from 'viem';
-import { P as PoolKey, C as ChainConfig, a as PafiSDKConfig, b as PointTokenDomainConfig, M as MintRequest, R as ReceiverConsent, E as EIP712Signature, S as SignatureVerification } from './types-BAkmxgVo.cjs';
-export { B as BestQuote, c as BurnRequest, I as Issuer, d as PathKey, Q as QuoteResult } from './types-BAkmxgVo.cjs';
-export { pointTokenAbi as POINT_TOKEN_V2_ABI, erc20Abi, issuerRegistryAbi, mintingOracleAbi, permit2Abi, pointTokenAbi, pointTokenFactoryAbi, universalRouterAbi, v4QuoterAbi } from './abi/index.cjs';
-export { buildBurnRequestTypedData, buildDomain, buildMintRequestTypedData, buildReceiverConsentTypedData, signBurnRequest, signMintRequest, signReceiverConsent, verifyBurnRequest, verifyMintRequest, verifyReceiverConsent } from './eip712/index.cjs';
+import { P as PoolKey, C as ChainConfig, a as PafiSDKConfig, b as PointTokenDomainConfig, M as MintRequest, R as ReceiverConsent, E as EIP712Signature, S as SignatureVerification } from './types-BS4kpO4Z.cjs';
+export { B as BestQuote, c as BlackoutWindow, d as BurnRequest, I as Issuer, e as PathKey, Q as QuoteResult, f as Recipient, g as RedemptionDecision, h as RedemptionDenial, i as RedemptionDenialCode, j as RedemptionPolicy, k as RedemptionPolicySource, l as RedemptionPreview } from './types-BS4kpO4Z.cjs';
+export { pointTokenAbi as POINT_TOKEN_V2_ABI, erc20Abi, issuerRegistryAbi, mintFeeWrapperAbi, mintingOracleAbi, permit2Abi, pointTokenAbi, pointTokenFactoryAbi, universalRouterAbi, v4QuoterAbi } from './abi/index.cjs';
+export { Eip712DomainMismatchError, assertDomainMatchesContract, buildBurnRequestTypedData, buildDomain, buildMintRequestTypedData, buildReceiverConsentTypedData, signBurnRequest, signMintRequest, signReceiverConsent, verifyBurnRequest, verifyMintRequest, verifyReceiverConsent } from './eip712/index.cjs';
 export { getBurnRequestNonce, getIssuer, getMintRequestNonce, getPointTokenBalance, getPointTokenIssuer, getPointTokenIssuerAddress, getReceiverConsentNonce, getTokenName, isActiveIssuer, isMinter, issuerRegistryGetIssuerFlatAbi, verifyMintCap } from './contract/index.cjs';
 import { LoginMessageParams } from './auth/index.cjs';
-export { BuildSponsorAuthParams, BuiltSponsorAuth, SPONSOR_AUTH_DOMAIN_NAME, SPONSOR_AUTH_TYPES, SponsorAuthPayload, SponsorAuthVerifyResult, VerifyLoginResult, buildAndSignSponsorAuth, buildSponsorAuthDomain, buildSponsorAuthTypedData, computeCallDataHash, createLoginMessage, generateSponsorAuthNonce, parseLoginMessage, signSponsorAuth, verifyLoginMessage, verifySponsorAuth } from './auth/index.cjs';
+export { BuildSponsorAuthParams, BuiltSponsorAuth, SPONSOR_AUTH_DOMAIN_ANCHOR_BASE_MAINNET, SPONSOR_AUTH_DOMAIN_NAME, SPONSOR_AUTH_TYPES, SponsorAuthPayload, SponsorAuthVerifyResult, VerifyLoginResult, buildAndSignSponsorAuth, buildSponsorAuthDomain, buildSponsorAuthTypedData, computeCallDataHash, createLoginMessage, generateSponsorAuthNonce, getSponsorAuthDomainAnchor, parseLoginMessage, signSponsorAuth, verifyLoginMessage, verifySponsorAuth } from './auth/index.cjs';
 
 declare const mintRequestTypes: {
     readonly MintRequest: readonly [{
@@ -83,17 +83,25 @@ declare const ENTRY_POINT_V08: Address;
 declare const PERMIT2_ADDRESS: Address;
 
 /**
- * v0.7.1 — unified error base for the entire SDK (core + issuer +
- * trading). Subclasses declare `code` (machine-readable) and
- * `httpStatus` (recommended HTTP status for issuer's controller).
+ * Unified error base for the entire SDK (core + issuer + trading).
+ * Subclasses declare `code` (machine-readable) and `httpStatus`
+ * (recommended HTTP status for issuer's controller).
  *
  * Issuer's `createSdkErrorMapper` routes any `PafiSdkError` instance
  * through framework-specific exception factories; non-PafiSdkError
  * still becomes 500.
- *
- * See SDK_CORE_TRADING_AUDIT.md H3.
  */
 type SdkErrorHttpStatus = "not_found" | "forbidden" | "unprocessable" | "service_unavailable";
+/**
+ * Stripe-style error taxonomy. The SDK emits one of these on every
+ * error so consumers can branch UI behavior on `type` (toast vs modal
+ * vs retry banner) without whitelisting individual `code` values.
+ */
+type PafiErrorType = "validation_error" | "authentication_error" | "authorization_error" | "not_found_error" | "business_logic_error" | "rate_limit_error" | "server_error" | "service_unavailable_error";
+/** Numeric HTTP status implied by an `SdkErrorHttpStatus` slot. */
+declare const SDK_ERROR_HTTP_STATUS_CODE: Record<SdkErrorHttpStatus, number>;
+/** Default `type` slot for a numeric HTTP status. */
+declare function defaultErrorTypeForStatus(status: number): PafiErrorType;
 declare abstract class PafiSdkError extends Error {
     abstract readonly code: string;
     /**
@@ -103,14 +111,32 @@ declare abstract class PafiSdkError extends Error {
     readonly safeToRetry: boolean;
     readonly details?: unknown;
     abstract readonly httpStatus: SdkErrorHttpStatus;
+    /**
+     * Optional Stripe-style taxonomy override. Defaults to the type
+     * implied by `httpStatus` (forbidden→authorization_error,
+     * unprocessable→business_logic_error, etc).
+     */
+    readonly type?: PafiErrorType;
+    /**
+     * Optional name of the request field that triggered the error (e.g.
+     * `"amount"`, `"chainId"`). Surfaced on validation failures so the
+     * client can highlight the offending field.
+     */
+    readonly param?: string;
+    /**
+     * Optional structured context (e.g. `{ available, requested }` for a
+     * cap denial). Distinct from `details` — `metadata` is meant for
+     * UI consumption; `details` carries raw debug info.
+     */
+    readonly metadata?: Record<string, unknown>;
     constructor(message: string);
 }
 /**
- * @deprecated v0.7.1 — use `PafiSdkError` (capital S, lowercase dk).
+ * @deprecated Use `PafiSdkError` (capital S, lowercase dk).
  * The two classes existed in parallel ("PafiSDKError" in core,
  * "PafiSdkError" in issuer) due to historical drift; consolidating
  * here. Kept as alias for back-compat through v0.7.x; will be removed
- * in v0.8. See SDK_CORE_TRADING_AUDIT.md H3.
+ * in v0.8.
  */
 declare class PafiSDKError extends Error {
     constructor(message: string);
@@ -133,11 +159,8 @@ declare class ApiError extends PafiSDKError {
 /**
  * Thrown by `quoteOperatorFee*` when an upstream price source
  * (Chainlink ETH/USD, PAFI subgraph) is unavailable or stale and the
- * caller did not opt in to the hardcoded fallback prices.
- *
- * v0.7.1 — previously `quoteOperatorFeePt` silently fell back to
- * ETH=$3000 / PT=$0.10 with `console.warn`. Now opt-in via
- * `allowStaleFallback: true`. See SDK_CORE_TRADING_AUDIT.md C2.
+ * caller did not opt in to the hardcoded fallback prices via
+ * `allowStaleFallback: true`.
  *
  * Extends the unified `PafiSdkError` so issuer's `createSdkErrorMapper`
  * routes it to 503 instead of leaking as a 500.
@@ -156,14 +179,18 @@ declare class OracleStaleError extends PafiSdkError {
  *
  * Uses an instance `details` field so subclasses can override the
  * declaration; matches the issuer-side shape that pre-existed here.
- *
- * v0.7.4 — added per SDK_CORE_TRADING_AUDIT.md H2/H13.
  */
 declare class ValidationError extends PafiSdkError {
     readonly httpStatus: "unprocessable";
+    readonly type: "validation_error";
     readonly code: string;
     readonly details?: Record<string, unknown>;
-    constructor(code: string, message: string, details?: Record<string, unknown>);
+    readonly param?: string;
+    readonly metadata?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>, options?: {
+        param?: string;
+        metadata?: Record<string, unknown>;
+    });
 }
 
 /**
@@ -1392,10 +1419,6 @@ interface SmartAccountSender {
  *
  * Use this to decide whether retrying without a paymaster makes sense.
  * Contract reverts (AA23, AA24, AA25) and bundler errors are NOT matched.
- *
- * v0.7.1 — replaced naive substring matching that false-positived on
- * arbitrary text containing "503"/"403"/"429" (e.g. address/transit ID).
- * See SDK_CORE_TRADING_AUDIT.md C3.
  */
 declare function isPaymasterError(err: unknown): boolean;
 interface SendWithPaymasterFallbackParams {
@@ -1459,8 +1482,7 @@ declare function sendWithPaymasterFallback(params: SendWithPaymasterFallbackPara
  *   perp-deposit — `buildPerpDepositViaRelay` 800k (LayerZero msg)
  *   delegate     — minimal no-op self-call, 200k margin
  *
- * Pass an explicit `gasUnits` to override. v0.7.4 — added per
- * SDK_CORE_TRADING_AUDIT.md H12.
+ * Pass an explicit `gasUnits` to override.
  */
 type FeeScenario = "mint" | "burn" | "swap" | "perp-deposit" | "delegate";
 interface QuoteOperatorFeePtConfig {
@@ -1497,17 +1519,38 @@ interface QuoteOperatorFeePtConfig {
      * `true` AND configure `fallbackEthPriceUsd` / `fallbackPtPriceUsdt`
      * to absorb oracle outages instead of surfacing them.
      *
-     * v0.7.1 — previously fallback was always-on with hardcoded
-     * defaults (ETH=$3000, PT=$0.10), causing under-priced fees during
-     * incidents. See SDK_CORE_TRADING_AUDIT.md C2.
+     * When fallback fires, callers SHOULD observe via `onFallback` so
+     * production can flag the under-priced quote (e.g. show "fee priced
+     * against stale oracle" banner in FE; alert on-call).
      */
     allowStaleFallback?: boolean;
     /** Fallback ETH price (USD) when Chainlink is unreachable. Only used when `allowStaleFallback: true`. Default 3000. */
     fallbackEthPriceUsd?: number;
     /** Fallback PT price (USDT per 1 PT) when subgraph is unreachable. Only used when `allowStaleFallback: true`. Default 0.1. */
     fallbackPtPriceUsdt?: number;
+    /**
+     * Observability hook fired when the quoter falls back to stale
+     * prices. Callers SHOULD wire this to their alert pipeline (Sentry,
+     * Datadog, PagerDuty) so under-priced quotes don't go unnoticed.
+     * When omitted, falls back to `console.warn` (kept for back-compat
+     * but invisible in most prod log shippers).
+     */
+    onFallback?: (info: FallbackInfo) => void;
     fetchImpl?: typeof fetch;
 }
+/**
+ * Detail surfaced via `onFallback` when the quoter substitutes a
+ * stale-fallback price. Callers can format this into a UI banner or
+ * log line.
+ */
+interface FallbackInfo {
+    /** Which oracle failed. */
+    source: "chainlink" | "subgraph";
+    /** Underlying reason from the oracle call (e.g. RPC error message). */
+    reason: string;
+    /** The fallback value that was used (in source-native units). */
+    fallbackValue: number;
+}
 /**
  * Subset of `QuoteOperatorFeePtConfig` that doesn't need the V4 pool
  * step — used by `quoteOperatorFeeUsdt` (FE cashout-preview / `/gas-fee`
@@ -1525,10 +1568,12 @@ interface QuoteOperatorFeeUsdtConfig {
     usdtDecimals?: number;
     /**
      * Opt-in fallback price when Chainlink is unavailable. Default
-     * `false` — throw `OracleStaleError`. v0.7.1 — see C2.
+     * `false` — throw `OracleStaleError`.
      */
     allowStaleFallback?: boolean;
     fallbackEthPriceUsd?: number;
+    /** See QuoteOperatorFeePtConfig.onFallback. */
+    onFallback?: (info: FallbackInfo) => void;
 }
 /**
  * Operator fee quoted in USDT raw units (default 6 decimals). Returns
@@ -1634,6 +1679,42 @@ declare const POINT_TOKEN_IMPL_ADDRESSES: Record<number, Address>;
  */
 declare function getContractAddresses(chainId: number): ContractAddresses;
 
+/**
+ * PAFI HTTP service URLs by chainId. Mirrors the `getContractAddresses`
+ * pattern: SDK ships with the URL for each supported chain so issuers
+ * don't pass URLs as env vars / constructor args.
+ *
+ * When PAFI changes URLs (rebrand, re-host, environment migration),
+ * bump the SDK version and re-publish. Issuers pin a version, get the
+ * URLs that match.
+ *
+ * No env override is provided on purpose — different environments use
+ * different SDK versions (e.g. an `@pafi-dev/issuer-dev` channel for
+ * staging). This keeps issuer integration to chainId + creds only.
+ */
+interface PafiServiceUrls {
+    /**
+     * sponsor-relayer base URL (paymaster proxy). PafiBackendClient
+     * appends `/paymaster/sponsor`, `/bundler/receipt`, etc.
+     */
+    sponsorRelayer: string;
+    /**
+     * issuer-api base URL. SettlementClient appends
+     * `/issuers/:issuerId/redemption-policy`.
+     */
+    issuerApi: string;
+}
+/**
+ * Per-chain URL map. URLs follow the pattern
+ * `https://<host>/api/<service>` so Kong gateway can route by path.
+ *
+ * NOTE: placeholder URLs — Phi will swap in real prod/staging hosts
+ * once the deploy targets are finalized. SDK version bump captures
+ * the change.
+ */
+declare const PAFI_SERVICE_URLS: Record<number, PafiServiceUrls>;
+declare function getPafiServiceUrls(chainId: number): PafiServiceUrls;
+
 /**
  * Public contract surface for `@pafi-dev/core/contracts`.
  *
@@ -1971,4 +2052,4 @@ declare class PafiSDK {
     signLoginMessage(message: string): Promise<Hex>;
 }
 
-export { ApiError, BATCH_EXECUTOR_7702_IMPL, BATCH_EXECUTOR_ABI, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, BROKER_HASHES, type BuildDelegationUserOpParams, type BuildPartialUserOpParams, type BuildPerpDepositViaRelayParams, type BuildPerpDepositWithGasDeductionParams, COMMON_POOLS, COMMON_TOKENS, CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, DUMMY_SIGNATURE_V07, type DelegateDirectParams, type DelegateDirectResult, type DelegateImpl, EIP712Signature, ENTRY_POINT_V07, ENTRY_POINT_V08, type Eip7702AuthorizationJsonRpc, LoginMessageParams, MintRequest, type ModalOpenOptions, ORDERLY_RELAY_ABI, ORDERLY_VAULT_ABI, ORDERLY_VAULT_ADDRESSES, ORDERLY_VAULT_BASE_MAINNET, type Operation, OracleStaleError, type OrderlyRelayDepositRequest, PAFI_SUBGRAPH_URL, PERMIT2_ADDRESS, POINT_TOKEN_FACTORY_ADDRESSES, POINT_TOKEN_IMPL_ADDRESSES, POINT_TOKEN_POOLS, type PackedUserOperationMessage, type PafiProxyTransportParams, PafiSDK, PafiSDKConfig, PafiSDKError, PafiSdkError, type PafiWebModalAdapter, type PafiWebModalHandle, type PartialUserOperation, type PaymasterConfig, type PaymasterFields, PointTokenDomainConfig, PoolKey, type QuoteOperatorFeePtConfig, type QuoteOperatorFeeUsdtConfig, ReceiverConsent, SIMPLE_7702_IMPL_BASE_MAINNET, SUPPORTED_CHAINS, type SdkErrorHttpStatus, type SendWithPaymasterFallbackParams, type SignAuthorizationFn, type SignatureStruct, SignatureVerification, type SignedAuthorization, SigningError, SimulationError, type SmartAccountSender, type SponsorshipScenario, type SubmissionPath, TOKEN_HASHES, UNIVERSAL_ROUTER_ADDRESSES, type UserOpReceipt, type UserOpTypedData, type UserOperation, V4_QUOTER_ADDRESSES, ValidationError, type VaultDepositFE, ZERO_VALUE, _resetPaymasterConfigForTests, assembleUserOperation, buildDelegationUserOp, buildEip7702Authorization, buildPartialUserOperation, buildPerpDepositViaRelay, buildPerpDepositWithGasDeduction, buildUserOpTypedData, burnRequestTypes, checkDelegation, checkEthAndBranch, computeAccountId, computeAuthorizationHash, computeUserOpHash, createPafiProxyTransport, decodeBatchExecuteCalls, delegateDirect, detectDelegateImpl, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, fetchPafiPools, getAaNonce, getContractAddresses, getDummySignatureFor7702, getPafiWebModalAdapter, getPaymasterConfig, isDelegatedTo, isDelegatedToTarget, isPaymasterConfigured, isPaymasterError, mintRequestTypes, openPafiWebModal, openWebPopup, parseEip7702DelegatedAddress, quoteOperatorFeePt, quoteOperatorFeeUsdt, rawCallOp, receiverConsentTypes, sendWithPaymasterFallback, serializeUserOpToJsonRpc, setPafiWebModalAdapter, setPaymasterConfig, splitAuthorizationSig, webPopupAdapter };
+export { ApiError, BATCH_EXECUTOR_7702_IMPL, BATCH_EXECUTOR_ABI, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, BROKER_HASHES, type BuildDelegationUserOpParams, type BuildPartialUserOpParams, type BuildPerpDepositViaRelayParams, type BuildPerpDepositWithGasDeductionParams, COMMON_POOLS, COMMON_TOKENS, CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, DUMMY_SIGNATURE_V07, type DelegateDirectParams, type DelegateDirectResult, type DelegateImpl, EIP712Signature, ENTRY_POINT_V07, ENTRY_POINT_V08, type Eip7702AuthorizationJsonRpc, LoginMessageParams, MintRequest, type ModalOpenOptions, ORDERLY_RELAY_ABI, ORDERLY_VAULT_ABI, ORDERLY_VAULT_ADDRESSES, ORDERLY_VAULT_BASE_MAINNET, type Operation, OracleStaleError, type OrderlyRelayDepositRequest, PAFI_SERVICE_URLS, PAFI_SUBGRAPH_URL, PERMIT2_ADDRESS, POINT_TOKEN_FACTORY_ADDRESSES, POINT_TOKEN_IMPL_ADDRESSES, POINT_TOKEN_POOLS, type PackedUserOperationMessage, type PafiErrorType, type PafiProxyTransportParams, PafiSDK, PafiSDKConfig, PafiSDKError, PafiSdkError, type PafiServiceUrls, type PafiWebModalAdapter, type PafiWebModalHandle, type PartialUserOperation, type PaymasterConfig, type PaymasterFields, PointTokenDomainConfig, PoolKey, type QuoteOperatorFeePtConfig, type QuoteOperatorFeeUsdtConfig, ReceiverConsent, SDK_ERROR_HTTP_STATUS_CODE, SIMPLE_7702_IMPL_BASE_MAINNET, SUPPORTED_CHAINS, type SdkErrorHttpStatus, type SendWithPaymasterFallbackParams, type SignAuthorizationFn, type SignatureStruct, SignatureVerification, type SignedAuthorization, SigningError, SimulationError, type SmartAccountSender, type SponsorshipScenario, type SubmissionPath, TOKEN_HASHES, UNIVERSAL_ROUTER_ADDRESSES, type UserOpReceipt, type UserOpTypedData, type UserOperation, V4_QUOTER_ADDRESSES, ValidationError, type VaultDepositFE, ZERO_VALUE, _resetPaymasterConfigForTests, assembleUserOperation, buildDelegationUserOp, buildEip7702Authorization, buildPartialUserOperation, buildPerpDepositViaRelay, buildPerpDepositWithGasDeduction, buildUserOpTypedData, burnRequestTypes, checkDelegation, checkEthAndBranch, computeAccountId, computeAuthorizationHash, computeUserOpHash, createPafiProxyTransport, decodeBatchExecuteCalls, defaultErrorTypeForStatus, delegateDirect, detectDelegateImpl, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, fetchPafiPools, getAaNonce, getContractAddresses, getDummySignatureFor7702, getPafiServiceUrls, getPafiWebModalAdapter, getPaymasterConfig, isDelegatedTo, isDelegatedToTarget, isPaymasterConfigured, isPaymasterError, mintRequestTypes, openPafiWebModal, openWebPopup, parseEip7702DelegatedAddress, quoteOperatorFeePt, quoteOperatorFeeUsdt, rawCallOp, receiverConsentTypes, sendWithPaymasterFallback, serializeUserOpToJsonRpc, setPafiWebModalAdapter, setPaymasterConfig, splitAuthorizationSig, webPopupAdapter };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { Address, Hex, TypedDataDomain, PublicClient, WalletClient, TransactionReceipt, HttpTransport } from 'viem';
-import { P as PoolKey, C as ChainConfig, a as PafiSDKConfig, b as PointTokenDomainConfig, M as MintRequest, R as ReceiverConsent, E as EIP712Signature, S as SignatureVerification } from './types-BAkmxgVo.js';
-export { B as BestQuote, c as BurnRequest, I as Issuer, d as PathKey, Q as QuoteResult } from './types-BAkmxgVo.js';
-export { pointTokenAbi as POINT_TOKEN_V2_ABI, erc20Abi, issuerRegistryAbi, mintingOracleAbi, permit2Abi, pointTokenAbi, pointTokenFactoryAbi, universalRouterAbi, v4QuoterAbi } from './abi/index.js';
-export { buildBurnRequestTypedData, buildDomain, buildMintRequestTypedData, buildReceiverConsentTypedData, signBurnRequest, signMintRequest, signReceiverConsent, verifyBurnRequest, verifyMintRequest, verifyReceiverConsent } from './eip712/index.js';
+import { P as PoolKey, C as ChainConfig, a as PafiSDKConfig, b as PointTokenDomainConfig, M as MintRequest, R as ReceiverConsent, E as EIP712Signature, S as SignatureVerification } from './types-BS4kpO4Z.js';
+export { B as BestQuote, c as BlackoutWindow, d as BurnRequest, I as Issuer, e as PathKey, Q as QuoteResult, f as Recipient, g as RedemptionDecision, h as RedemptionDenial, i as RedemptionDenialCode, j as RedemptionPolicy, k as RedemptionPolicySource, l as RedemptionPreview } from './types-BS4kpO4Z.js';
+export { pointTokenAbi as POINT_TOKEN_V2_ABI, erc20Abi, issuerRegistryAbi, mintFeeWrapperAbi, mintingOracleAbi, permit2Abi, pointTokenAbi, pointTokenFactoryAbi, universalRouterAbi, v4QuoterAbi } from './abi/index.js';
+export { Eip712DomainMismatchError, assertDomainMatchesContract, buildBurnRequestTypedData, buildDomain, buildMintRequestTypedData, buildReceiverConsentTypedData, signBurnRequest, signMintRequest, signReceiverConsent, verifyBurnRequest, verifyMintRequest, verifyReceiverConsent } from './eip712/index.js';
 export { getBurnRequestNonce, getIssuer, getMintRequestNonce, getPointTokenBalance, getPointTokenIssuer, getPointTokenIssuerAddress, getReceiverConsentNonce, getTokenName, isActiveIssuer, isMinter, issuerRegistryGetIssuerFlatAbi, verifyMintCap } from './contract/index.js';
 import { LoginMessageParams } from './auth/index.js';
-export { BuildSponsorAuthParams, BuiltSponsorAuth, SPONSOR_AUTH_DOMAIN_NAME, SPONSOR_AUTH_TYPES, SponsorAuthPayload, SponsorAuthVerifyResult, VerifyLoginResult, buildAndSignSponsorAuth, buildSponsorAuthDomain, buildSponsorAuthTypedData, computeCallDataHash, createLoginMessage, generateSponsorAuthNonce, parseLoginMessage, signSponsorAuth, verifyLoginMessage, verifySponsorAuth } from './auth/index.js';
+export { BuildSponsorAuthParams, BuiltSponsorAuth, SPONSOR_AUTH_DOMAIN_ANCHOR_BASE_MAINNET, SPONSOR_AUTH_DOMAIN_NAME, SPONSOR_AUTH_TYPES, SponsorAuthPayload, SponsorAuthVerifyResult, VerifyLoginResult, buildAndSignSponsorAuth, buildSponsorAuthDomain, buildSponsorAuthTypedData, computeCallDataHash, createLoginMessage, generateSponsorAuthNonce, getSponsorAuthDomainAnchor, parseLoginMessage, signSponsorAuth, verifyLoginMessage, verifySponsorAuth } from './auth/index.js';
 
 declare const mintRequestTypes: {
     readonly MintRequest: readonly [{
@@ -83,17 +83,25 @@ declare const ENTRY_POINT_V08: Address;
 declare const PERMIT2_ADDRESS: Address;
 
 /**
- * v0.7.1 — unified error base for the entire SDK (core + issuer +
- * trading). Subclasses declare `code` (machine-readable) and
- * `httpStatus` (recommended HTTP status for issuer's controller).
+ * Unified error base for the entire SDK (core + issuer + trading).
+ * Subclasses declare `code` (machine-readable) and `httpStatus`
+ * (recommended HTTP status for issuer's controller).
  *
  * Issuer's `createSdkErrorMapper` routes any `PafiSdkError` instance
  * through framework-specific exception factories; non-PafiSdkError
  * still becomes 500.
- *
- * See SDK_CORE_TRADING_AUDIT.md H3.
  */
 type SdkErrorHttpStatus = "not_found" | "forbidden" | "unprocessable" | "service_unavailable";
+/**
+ * Stripe-style error taxonomy. The SDK emits one of these on every
+ * error so consumers can branch UI behavior on `type` (toast vs modal
+ * vs retry banner) without whitelisting individual `code` values.
+ */
+type PafiErrorType = "validation_error" | "authentication_error" | "authorization_error" | "not_found_error" | "business_logic_error" | "rate_limit_error" | "server_error" | "service_unavailable_error";
+/** Numeric HTTP status implied by an `SdkErrorHttpStatus` slot. */
+declare const SDK_ERROR_HTTP_STATUS_CODE: Record<SdkErrorHttpStatus, number>;
+/** Default `type` slot for a numeric HTTP status. */
+declare function defaultErrorTypeForStatus(status: number): PafiErrorType;
 declare abstract class PafiSdkError extends Error {
     abstract readonly code: string;
     /**
@@ -103,14 +111,32 @@ declare abstract class PafiSdkError extends Error {
     readonly safeToRetry: boolean;
     readonly details?: unknown;
     abstract readonly httpStatus: SdkErrorHttpStatus;
+    /**
+     * Optional Stripe-style taxonomy override. Defaults to the type
+     * implied by `httpStatus` (forbidden→authorization_error,
+     * unprocessable→business_logic_error, etc).
+     */
+    readonly type?: PafiErrorType;
+    /**
+     * Optional name of the request field that triggered the error (e.g.
+     * `"amount"`, `"chainId"`). Surfaced on validation failures so the
+     * client can highlight the offending field.
+     */
+    readonly param?: string;
+    /**
+     * Optional structured context (e.g. `{ available, requested }` for a
+     * cap denial). Distinct from `details` — `metadata` is meant for
+     * UI consumption; `details` carries raw debug info.
+     */
+    readonly metadata?: Record<string, unknown>;
     constructor(message: string);
 }
 /**
- * @deprecated v0.7.1 — use `PafiSdkError` (capital S, lowercase dk).
+ * @deprecated Use `PafiSdkError` (capital S, lowercase dk).
  * The two classes existed in parallel ("PafiSDKError" in core,
  * "PafiSdkError" in issuer) due to historical drift; consolidating
  * here. Kept as alias for back-compat through v0.7.x; will be removed
- * in v0.8. See SDK_CORE_TRADING_AUDIT.md H3.
+ * in v0.8.
  */
 declare class PafiSDKError extends Error {
     constructor(message: string);
@@ -133,11 +159,8 @@ declare class ApiError extends PafiSDKError {
 /**
  * Thrown by `quoteOperatorFee*` when an upstream price source
  * (Chainlink ETH/USD, PAFI subgraph) is unavailable or stale and the
- * caller did not opt in to the hardcoded fallback prices.
- *
- * v0.7.1 — previously `quoteOperatorFeePt` silently fell back to
- * ETH=$3000 / PT=$0.10 with `console.warn`. Now opt-in via
- * `allowStaleFallback: true`. See SDK_CORE_TRADING_AUDIT.md C2.
+ * caller did not opt in to the hardcoded fallback prices via
+ * `allowStaleFallback: true`.
  *
  * Extends the unified `PafiSdkError` so issuer's `createSdkErrorMapper`
  * routes it to 503 instead of leaking as a 500.
@@ -156,14 +179,18 @@ declare class OracleStaleError extends PafiSdkError {
  *
  * Uses an instance `details` field so subclasses can override the
  * declaration; matches the issuer-side shape that pre-existed here.
- *
- * v0.7.4 — added per SDK_CORE_TRADING_AUDIT.md H2/H13.
  */
 declare class ValidationError extends PafiSdkError {
     readonly httpStatus: "unprocessable";
+    readonly type: "validation_error";
     readonly code: string;
     readonly details?: Record<string, unknown>;
-    constructor(code: string, message: string, details?: Record<string, unknown>);
+    readonly param?: string;
+    readonly metadata?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>, options?: {
+        param?: string;
+        metadata?: Record<string, unknown>;
+    });
 }
 
 /**
@@ -1392,10 +1419,6 @@ interface SmartAccountSender {
  *
  * Use this to decide whether retrying without a paymaster makes sense.
  * Contract reverts (AA23, AA24, AA25) and bundler errors are NOT matched.
- *
- * v0.7.1 — replaced naive substring matching that false-positived on
- * arbitrary text containing "503"/"403"/"429" (e.g. address/transit ID).
- * See SDK_CORE_TRADING_AUDIT.md C3.
  */
 declare function isPaymasterError(err: unknown): boolean;
 interface SendWithPaymasterFallbackParams {
@@ -1459,8 +1482,7 @@ declare function sendWithPaymasterFallback(params: SendWithPaymasterFallbackPara
  *   perp-deposit — `buildPerpDepositViaRelay` 800k (LayerZero msg)
  *   delegate     — minimal no-op self-call, 200k margin
  *
- * Pass an explicit `gasUnits` to override. v0.7.4 — added per
- * SDK_CORE_TRADING_AUDIT.md H12.
+ * Pass an explicit `gasUnits` to override.
  */
 type FeeScenario = "mint" | "burn" | "swap" | "perp-deposit" | "delegate";
 interface QuoteOperatorFeePtConfig {
@@ -1497,17 +1519,38 @@ interface QuoteOperatorFeePtConfig {
      * `true` AND configure `fallbackEthPriceUsd` / `fallbackPtPriceUsdt`
      * to absorb oracle outages instead of surfacing them.
      *
-     * v0.7.1 — previously fallback was always-on with hardcoded
-     * defaults (ETH=$3000, PT=$0.10), causing under-priced fees during
-     * incidents. See SDK_CORE_TRADING_AUDIT.md C2.
+     * When fallback fires, callers SHOULD observe via `onFallback` so
+     * production can flag the under-priced quote (e.g. show "fee priced
+     * against stale oracle" banner in FE; alert on-call).
      */
     allowStaleFallback?: boolean;
     /** Fallback ETH price (USD) when Chainlink is unreachable. Only used when `allowStaleFallback: true`. Default 3000. */
     fallbackEthPriceUsd?: number;
     /** Fallback PT price (USDT per 1 PT) when subgraph is unreachable. Only used when `allowStaleFallback: true`. Default 0.1. */
     fallbackPtPriceUsdt?: number;
+    /**
+     * Observability hook fired when the quoter falls back to stale
+     * prices. Callers SHOULD wire this to their alert pipeline (Sentry,
+     * Datadog, PagerDuty) so under-priced quotes don't go unnoticed.
+     * When omitted, falls back to `console.warn` (kept for back-compat
+     * but invisible in most prod log shippers).
+     */
+    onFallback?: (info: FallbackInfo) => void;
     fetchImpl?: typeof fetch;
 }
+/**
+ * Detail surfaced via `onFallback` when the quoter substitutes a
+ * stale-fallback price. Callers can format this into a UI banner or
+ * log line.
+ */
+interface FallbackInfo {
+    /** Which oracle failed. */
+    source: "chainlink" | "subgraph";
+    /** Underlying reason from the oracle call (e.g. RPC error message). */
+    reason: string;
+    /** The fallback value that was used (in source-native units). */
+    fallbackValue: number;
+}
 /**
  * Subset of `QuoteOperatorFeePtConfig` that doesn't need the V4 pool
  * step — used by `quoteOperatorFeeUsdt` (FE cashout-preview / `/gas-fee`
@@ -1525,10 +1568,12 @@ interface QuoteOperatorFeeUsdtConfig {
     usdtDecimals?: number;
     /**
      * Opt-in fallback price when Chainlink is unavailable. Default
-     * `false` — throw `OracleStaleError`. v0.7.1 — see C2.
+     * `false` — throw `OracleStaleError`.
      */
     allowStaleFallback?: boolean;
     fallbackEthPriceUsd?: number;
+    /** See QuoteOperatorFeePtConfig.onFallback. */
+    onFallback?: (info: FallbackInfo) => void;
 }
 /**
  * Operator fee quoted in USDT raw units (default 6 decimals). Returns
@@ -1634,6 +1679,42 @@ declare const POINT_TOKEN_IMPL_ADDRESSES: Record<number, Address>;
  */
 declare function getContractAddresses(chainId: number): ContractAddresses;
 
+/**
+ * PAFI HTTP service URLs by chainId. Mirrors the `getContractAddresses`
+ * pattern: SDK ships with the URL for each supported chain so issuers
+ * don't pass URLs as env vars / constructor args.
+ *
+ * When PAFI changes URLs (rebrand, re-host, environment migration),
+ * bump the SDK version and re-publish. Issuers pin a version, get the
+ * URLs that match.
+ *
+ * No env override is provided on purpose — different environments use
+ * different SDK versions (e.g. an `@pafi-dev/issuer-dev` channel for
+ * staging). This keeps issuer integration to chainId + creds only.
+ */
+interface PafiServiceUrls {
+    /**
+     * sponsor-relayer base URL (paymaster proxy). PafiBackendClient
+     * appends `/paymaster/sponsor`, `/bundler/receipt`, etc.
+     */
+    sponsorRelayer: string;
+    /**
+     * issuer-api base URL. SettlementClient appends
+     * `/issuers/:issuerId/redemption-policy`.
+     */
+    issuerApi: string;
+}
+/**
+ * Per-chain URL map. URLs follow the pattern
+ * `https://<host>/api/<service>` so Kong gateway can route by path.
+ *
+ * NOTE: placeholder URLs — Phi will swap in real prod/staging hosts
+ * once the deploy targets are finalized. SDK version bump captures
+ * the change.
+ */
+declare const PAFI_SERVICE_URLS: Record<number, PafiServiceUrls>;
+declare function getPafiServiceUrls(chainId: number): PafiServiceUrls;
+
 /**
  * Public contract surface for `@pafi-dev/core/contracts`.
  *
@@ -1971,4 +2052,4 @@ declare class PafiSDK {
     signLoginMessage(message: string): Promise<Hex>;
 }
 
-export { ApiError, BATCH_EXECUTOR_7702_IMPL, BATCH_EXECUTOR_ABI, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, BROKER_HASHES, type BuildDelegationUserOpParams, type BuildPartialUserOpParams, type BuildPerpDepositViaRelayParams, type BuildPerpDepositWithGasDeductionParams, COMMON_POOLS, COMMON_TOKENS, CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, DUMMY_SIGNATURE_V07, type DelegateDirectParams, type DelegateDirectResult, type DelegateImpl, EIP712Signature, ENTRY_POINT_V07, ENTRY_POINT_V08, type Eip7702AuthorizationJsonRpc, LoginMessageParams, MintRequest, type ModalOpenOptions, ORDERLY_RELAY_ABI, ORDERLY_VAULT_ABI, ORDERLY_VAULT_ADDRESSES, ORDERLY_VAULT_BASE_MAINNET, type Operation, OracleStaleError, type OrderlyRelayDepositRequest, PAFI_SUBGRAPH_URL, PERMIT2_ADDRESS, POINT_TOKEN_FACTORY_ADDRESSES, POINT_TOKEN_IMPL_ADDRESSES, POINT_TOKEN_POOLS, type PackedUserOperationMessage, type PafiProxyTransportParams, PafiSDK, PafiSDKConfig, PafiSDKError, PafiSdkError, type PafiWebModalAdapter, type PafiWebModalHandle, type PartialUserOperation, type PaymasterConfig, type PaymasterFields, PointTokenDomainConfig, PoolKey, type QuoteOperatorFeePtConfig, type QuoteOperatorFeeUsdtConfig, ReceiverConsent, SIMPLE_7702_IMPL_BASE_MAINNET, SUPPORTED_CHAINS, type SdkErrorHttpStatus, type SendWithPaymasterFallbackParams, type SignAuthorizationFn, type SignatureStruct, SignatureVerification, type SignedAuthorization, SigningError, SimulationError, type SmartAccountSender, type SponsorshipScenario, type SubmissionPath, TOKEN_HASHES, UNIVERSAL_ROUTER_ADDRESSES, type UserOpReceipt, type UserOpTypedData, type UserOperation, V4_QUOTER_ADDRESSES, ValidationError, type VaultDepositFE, ZERO_VALUE, _resetPaymasterConfigForTests, assembleUserOperation, buildDelegationUserOp, buildEip7702Authorization, buildPartialUserOperation, buildPerpDepositViaRelay, buildPerpDepositWithGasDeduction, buildUserOpTypedData, burnRequestTypes, checkDelegation, checkEthAndBranch, computeAccountId, computeAuthorizationHash, computeUserOpHash, createPafiProxyTransport, decodeBatchExecuteCalls, delegateDirect, detectDelegateImpl, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, fetchPafiPools, getAaNonce, getContractAddresses, getDummySignatureFor7702, getPafiWebModalAdapter, getPaymasterConfig, isDelegatedTo, isDelegatedToTarget, isPaymasterConfigured, isPaymasterError, mintRequestTypes, openPafiWebModal, openWebPopup, parseEip7702DelegatedAddress, quoteOperatorFeePt, quoteOperatorFeeUsdt, rawCallOp, receiverConsentTypes, sendWithPaymasterFallback, serializeUserOpToJsonRpc, setPafiWebModalAdapter, setPaymasterConfig, splitAuthorizationSig, webPopupAdapter };
+export { ApiError, BATCH_EXECUTOR_7702_IMPL, BATCH_EXECUTOR_ABI, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, BROKER_HASHES, type BuildDelegationUserOpParams, type BuildPartialUserOpParams, type BuildPerpDepositViaRelayParams, type BuildPerpDepositWithGasDeductionParams, COMMON_POOLS, COMMON_TOKENS, CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, DUMMY_SIGNATURE_V07, type DelegateDirectParams, type DelegateDirectResult, type DelegateImpl, EIP712Signature, ENTRY_POINT_V07, ENTRY_POINT_V08, type Eip7702AuthorizationJsonRpc, LoginMessageParams, MintRequest, type ModalOpenOptions, ORDERLY_RELAY_ABI, ORDERLY_VAULT_ABI, ORDERLY_VAULT_ADDRESSES, ORDERLY_VAULT_BASE_MAINNET, type Operation, OracleStaleError, type OrderlyRelayDepositRequest, PAFI_SERVICE_URLS, PAFI_SUBGRAPH_URL, PERMIT2_ADDRESS, POINT_TOKEN_FACTORY_ADDRESSES, POINT_TOKEN_IMPL_ADDRESSES, POINT_TOKEN_POOLS, type PackedUserOperationMessage, type PafiErrorType, type PafiProxyTransportParams, PafiSDK, PafiSDKConfig, PafiSDKError, PafiSdkError, type PafiServiceUrls, type PafiWebModalAdapter, type PafiWebModalHandle, type PartialUserOperation, type PaymasterConfig, type PaymasterFields, PointTokenDomainConfig, PoolKey, type QuoteOperatorFeePtConfig, type QuoteOperatorFeeUsdtConfig, ReceiverConsent, SDK_ERROR_HTTP_STATUS_CODE, SIMPLE_7702_IMPL_BASE_MAINNET, SUPPORTED_CHAINS, type SdkErrorHttpStatus, type SendWithPaymasterFallbackParams, type SignAuthorizationFn, type SignatureStruct, SignatureVerification, type SignedAuthorization, SigningError, SimulationError, type SmartAccountSender, type SponsorshipScenario, type SubmissionPath, TOKEN_HASHES, UNIVERSAL_ROUTER_ADDRESSES, type UserOpReceipt, type UserOpTypedData, type UserOperation, V4_QUOTER_ADDRESSES, ValidationError, type VaultDepositFE, ZERO_VALUE, _resetPaymasterConfigForTests, assembleUserOperation, buildDelegationUserOp, buildEip7702Authorization, buildPartialUserOperation, buildPerpDepositViaRelay, buildPerpDepositWithGasDeduction, buildUserOpTypedData, burnRequestTypes, checkDelegation, checkEthAndBranch, computeAccountId, computeAuthorizationHash, computeUserOpHash, createPafiProxyTransport, decodeBatchExecuteCalls, defaultErrorTypeForStatus, delegateDirect, detectDelegateImpl, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, fetchPafiPools, getAaNonce, getContractAddresses, getDummySignatureFor7702, getPafiServiceUrls, getPafiWebModalAdapter, getPaymasterConfig, isDelegatedTo, isDelegatedToTarget, isPaymasterConfigured, isPaymasterError, mintRequestTypes, openPafiWebModal, openWebPopup, parseEip7702DelegatedAddress, quoteOperatorFeePt, quoteOperatorFeeUsdt, rawCallOp, receiverConsentTypes, sendWithPaymasterFallback, serializeUserOpToJsonRpc, setPafiWebModalAdapter, setPaymasterConfig, splitAuthorizationSig, webPopupAdapter };