@chipi-stack/types 14.14.0 → 14.15.1

package/dist/index.d.mts

@@ -87,9 +87,15 @@ type WalletType = "CHIPI" | "READY" | "SHHH" | (string & {});
 type ShhhSignerKind = "STARK" | "ED25519" | "SECP256K1" | "EIP191_SECP256K1" | "EIP712_SECP256K1" | "P256" | "WEBAUTHN_P256" | "JWT_ES256" | "JWT_ES256_APPLE_SUB" | "BLS12_381";
 /**
  * Authentication method used for wallet encryption.
- * - "passkey": passkey only (no PIN backup — legacy, not recommended)
- * - "pin": PIN only (current default)
- * - "passkey+pin": passkey primary + PIN backup (recommended default)
+ * - "passkey": passkey only. On the web the wrap key is the WebAuthn PRF
+ *   output, derived on the device; the passkey's platform sync (iCloud
+ *   Keychain, Google Password Manager) is the recovery path. The recommended
+ *   choice for self-custodial web apps. On Expo the key is a random key kept
+ *   in this device's secure storage only, so pair it with a PIN backup there.
+ * - "pin": PIN only (legacy). A short PIN can be brute-forced offline against
+ *   the stored ciphertext.
+ * - "passkey+pin": passkey primary + PIN backup. The backup is only as strong
+ *   as the PIN (same offline brute-force exposure as "pin").
  */
 type AuthMethod = "passkey" | "pin" | "passkey+pin";
 interface WalletData {
@@ -114,6 +120,12 @@ interface DeploymentData {
     calldata: string[];
 }
 interface CreateWalletParams {
+    /**
+     * Key that encrypts the private key. A PIN, or a passkey-derived key.
+     * With `useCreateWallet` and `usePasskey: true` it is optional: omit it for a
+     * passkey-only wallet, or pass a PIN to keep it as a backup.
+     * Required on the server SDK.
+     */
     encryptKey?: string;
     externalUserId: string;
     userId?: string;
@@ -155,10 +167,18 @@ interface CreateWalletParams {
      * itself.
      */
     ownerPubkeyFelts?: string[];
+    /**
+     * Browser/Expo hooks only (`useCreateWallet`): create a passkey and use the
+     * key it yields as `encryptKey`. The server SDK does not create passkeys.
+     */
     usePasskey?: boolean;
-    /** PIN for backup encryption (dual-key wrapping). Required when usePasskey: true. */
+    /**
+     * Optional PIN for a backup copy of the private key (dual-key wrapping).
+     * `useCreateWallet` fills it from `encryptKey` when `usePasskey: true` and a
+     * PIN is given; omit both for a passkey-only wallet.
+     */
     encryptKeyBackup?: string;
-    /** Auth method: "passkey+pin" for dual-key, "pin" for PIN-only */
+    /** Auth method: "passkey" (passkey only), "passkey+pin" (dual-key) or "pin" (PIN only) */
     authMethod?: AuthMethod;
     /** WebAuthn credential ID stored in backend for recovery */
     credentialId?: string;
@@ -1149,6 +1169,7 @@ interface X402PaymentConfig {
  * `@chipi-stack/backend`. Every call is billed to the organization's credits
  * and needs a secret key (`sk_`), so these are server-side only.
  */
+
 /** Actions `/v1/ai/think` may decide. */
 type ThinkAction = "swap" | "supply" | "withdraw" | "hold";
 /**
@@ -1219,6 +1240,38 @@ interface ThinkResponse {
     latencyMs: number;
     /** `true` only for `sk_dev_` keys: canned response, no model was called. */
     sandbox?: boolean;
+    /** Present when the call was paid over x402 instead of credits (`cost.charged` is 0). */
+    x402Payment?: ThinkX402Payment;
+}
+/** The x402 payment that paid a think call. */
+interface ThinkX402Payment {
+    /** Hash of the USDC transfer that paid the call. */
+    transactionHash: string;
+    payer: string;
+    /** USDC base units (6 decimals). */
+    amount: string;
+    asset: string;
+}
+/**
+ * Pay a think call over x402 with a session key when the API asks for it
+ * (402 with a `session-transfer` offer, e.g. when credits are short).
+ */
+interface ThinkSessionPayment extends Omit<ExecuteWithSessionParams, "calls"> {
+    /**
+     * The most one call may cost, in USDC base units (6 decimals). A higher
+     * price is refused before anything is paid. Also cap USDC in the session's
+     * spending policy: this is a client-side guard, the policy is the on-chain one.
+     */
+    maxAmount: bigint | string;
+}
+interface ThinkOptions {
+    /** Pay with this session key when the API answers 402 with an x402 offer. */
+    payWithSession?: ThinkSessionPayment;
+    /**
+     * A ready `X-PAYMENT` header value, to retry a call with a payment that was
+     * made but not served (the hash is in `error.details.x402PaymentHash`).
+     */
+    xPayment?: string;
 }
 interface AiChatMessage {
     role: "system" | "user" | "assistant";
@@ -1421,4 +1474,4 @@ interface PlanSnapshot {
     planPaymentProvider: PlanPaymentProvider | null;
 }
 
-export { type AddSessionKeyParams, type AiChatMessage, type AiChatParams, type AiChatResponse, type AiCost, type AiExecuteCall, type AiExecuteParams, type AiExecuteResponse, type AiModel, type AiModelsResponse, type AiPrices, type AiPricesParams, type AiSignals, type AiSignalsParams, type AiSwapQuote, type AiTokenPrice, type AiTokenSignals, type AiUsage, type ApiError, type ApiKey, type ApiResponse, type ApproveHookInput, type ApproveParams, type AsyncReturnType, type AuthContext, type AuthMethod, type CallAnyContractParams, Chain, ChainToken, type ChipiBrowserSDKConfig, type ChipiSDKConfig, type ChipiServerSDKConfig, type Country, type CreateCustodialWalletParams, type CreateSessionKeyParams, type CreateSkuPurchaseBody, type CreateSkuPurchaseParams, type CreateUserParams, type CreateWalletParams, type CreateWalletResponse, Currency, type DeepPartial, type DeploymentData, type ErrorWithCode, type ExecuteSponsoredTransactionParams, type ExecuteSponsoredTransactionResponse, type ExecuteTransactionParams, type ExecuteWalletUpgradeParams, type ExecuteWalletUpgradeResponse, type ExecuteWithSessionParams, type GetMerchantWalletParams, type GetSessionDataParams, type GetSkuListQuery, type GetSpendingPolicyParams, type GetTokenBalanceParams, type GetTokenBalanceResponse, type GetTransactionListQuery, type GetTransactionParams, type GetTransactionStatusParams, type GetTransactionsParams, type GetUserParams, type GetWalletParams, type GetWalletResponse, type JwtPayload, type MaybePromise, type MigrateWalletToPasskeyParams, type NonEmptyArray, type NonceStore, OnChainTxStatus, type Optional, type PaginatedResponse, type PaginationQuery, type PasskeyMetadata, type PaymasterAccount, type PaymasterAdapter, type PaymentPayload, type PaymentRequirement, type Plan, type PlanPaymentProvider, type PlanSnapshot, type PrepareTypedDataParams, type PrepareTypedDataResponse, type PrepareWalletCreationParams, type PrepareWalletCreationResponse, type PrepareWalletUpgradeParams, type PrepareWalletUpgradeResponse, type Prettify, type RecordSendTransactionParams, type RemoveSpendingPolicyParams, type RequireAtLeastOne, type RevokeSessionKeyParams, STARKNET_CONTRACTS, type SessionConfig, type SessionDataResponse, type SessionKeyData, type SessionSpendingPolicy, type SessionWalletData, type SetSpendingPolicyParams, type SettleResponse, type SetupSessionParams, type ShhhPaymentExtension, type ShhhSignerKind, type SignTypedDataParams, type SignTypedDataResult, type Sku, type SkuCategory, type SkuProvider, type SpendingPolicyConfig, type SpendingPolicyData, type StakeVesuUsdcHookInputParams, type StakeVesuUsdcParams, type SyncOnChainTransfersParams, type SyncOnChainTransfersResponse, type ThinkAction, type ThinkDecision, type ThinkParams, type ThinkRawDecision, type ThinkResponse, type ThinkRiskParams, type Transaction, type TransactionStatusResponse, type TransferHookInput, type TransferParams, type TxStatus, type TxType, type UpdateWalletEncryptionParams, type UpdateWalletEncryptionResponse, type User, type ValueOrFunction, type VerifyResponse, type WalletData, type WalletType, type WithdrawVesuUsdcHookInputParams, type WithdrawVesuUsdcParams, type X402ClientConfig, type X402FacilitatorConfig, type X402PaymentConfig, type alphaUrl };
+export { type AddSessionKeyParams, type AiChatMessage, type AiChatParams, type AiChatResponse, type AiCost, type AiExecuteCall, type AiExecuteParams, type AiExecuteResponse, type AiModel, type AiModelsResponse, type AiPrices, type AiPricesParams, type AiSignals, type AiSignalsParams, type AiSwapQuote, type AiTokenPrice, type AiTokenSignals, type AiUsage, type ApiError, type ApiKey, type ApiResponse, type ApproveHookInput, type ApproveParams, type AsyncReturnType, type AuthContext, type AuthMethod, type CallAnyContractParams, Chain, ChainToken, type ChipiBrowserSDKConfig, type ChipiSDKConfig, type ChipiServerSDKConfig, type Country, type CreateCustodialWalletParams, type CreateSessionKeyParams, type CreateSkuPurchaseBody, type CreateSkuPurchaseParams, type CreateUserParams, type CreateWalletParams, type CreateWalletResponse, Currency, type DeepPartial, type DeploymentData, type ErrorWithCode, type ExecuteSponsoredTransactionParams, type ExecuteSponsoredTransactionResponse, type ExecuteTransactionParams, type ExecuteWalletUpgradeParams, type ExecuteWalletUpgradeResponse, type ExecuteWithSessionParams, type GetMerchantWalletParams, type GetSessionDataParams, type GetSkuListQuery, type GetSpendingPolicyParams, type GetTokenBalanceParams, type GetTokenBalanceResponse, type GetTransactionListQuery, type GetTransactionParams, type GetTransactionStatusParams, type GetTransactionsParams, type GetUserParams, type GetWalletParams, type GetWalletResponse, type JwtPayload, type MaybePromise, type MigrateWalletToPasskeyParams, type NonEmptyArray, type NonceStore, OnChainTxStatus, type Optional, type PaginatedResponse, type PaginationQuery, type PasskeyMetadata, type PaymasterAccount, type PaymasterAdapter, type PaymentPayload, type PaymentRequirement, type Plan, type PlanPaymentProvider, type PlanSnapshot, type PrepareTypedDataParams, type PrepareTypedDataResponse, type PrepareWalletCreationParams, type PrepareWalletCreationResponse, type PrepareWalletUpgradeParams, type PrepareWalletUpgradeResponse, type Prettify, type RecordSendTransactionParams, type RemoveSpendingPolicyParams, type RequireAtLeastOne, type RevokeSessionKeyParams, STARKNET_CONTRACTS, type SessionConfig, type SessionDataResponse, type SessionKeyData, type SessionSpendingPolicy, type SessionWalletData, type SetSpendingPolicyParams, type SettleResponse, type SetupSessionParams, type ShhhPaymentExtension, type ShhhSignerKind, type SignTypedDataParams, type SignTypedDataResult, type Sku, type SkuCategory, type SkuProvider, type SpendingPolicyConfig, type SpendingPolicyData, type StakeVesuUsdcHookInputParams, type StakeVesuUsdcParams, type SyncOnChainTransfersParams, type SyncOnChainTransfersResponse, type ThinkAction, type ThinkDecision, type ThinkOptions, type ThinkParams, type ThinkRawDecision, type ThinkResponse, type ThinkRiskParams, type ThinkSessionPayment, type ThinkX402Payment, type Transaction, type TransactionStatusResponse, type TransferHookInput, type TransferParams, type TxStatus, type TxType, type UpdateWalletEncryptionParams, type UpdateWalletEncryptionResponse, type User, type ValueOrFunction, type VerifyResponse, type WalletData, type WalletType, type WithdrawVesuUsdcHookInputParams, type WithdrawVesuUsdcParams, type X402ClientConfig, type X402FacilitatorConfig, type X402PaymentConfig, type alphaUrl };

package/dist/index.d.ts

@@ -87,9 +87,15 @@ type WalletType = "CHIPI" | "READY" | "SHHH" | (string & {});
 type ShhhSignerKind = "STARK" | "ED25519" | "SECP256K1" | "EIP191_SECP256K1" | "EIP712_SECP256K1" | "P256" | "WEBAUTHN_P256" | "JWT_ES256" | "JWT_ES256_APPLE_SUB" | "BLS12_381";
 /**
  * Authentication method used for wallet encryption.
- * - "passkey": passkey only (no PIN backup — legacy, not recommended)
- * - "pin": PIN only (current default)
- * - "passkey+pin": passkey primary + PIN backup (recommended default)
+ * - "passkey": passkey only. On the web the wrap key is the WebAuthn PRF
+ *   output, derived on the device; the passkey's platform sync (iCloud
+ *   Keychain, Google Password Manager) is the recovery path. The recommended
+ *   choice for self-custodial web apps. On Expo the key is a random key kept
+ *   in this device's secure storage only, so pair it with a PIN backup there.
+ * - "pin": PIN only (legacy). A short PIN can be brute-forced offline against
+ *   the stored ciphertext.
+ * - "passkey+pin": passkey primary + PIN backup. The backup is only as strong
+ *   as the PIN (same offline brute-force exposure as "pin").
  */
 type AuthMethod = "passkey" | "pin" | "passkey+pin";
 interface WalletData {
@@ -114,6 +120,12 @@ interface DeploymentData {
     calldata: string[];
 }
 interface CreateWalletParams {
+    /**
+     * Key that encrypts the private key. A PIN, or a passkey-derived key.
+     * With `useCreateWallet` and `usePasskey: true` it is optional: omit it for a
+     * passkey-only wallet, or pass a PIN to keep it as a backup.
+     * Required on the server SDK.
+     */
     encryptKey?: string;
     externalUserId: string;
     userId?: string;
@@ -155,10 +167,18 @@ interface CreateWalletParams {
      * itself.
      */
     ownerPubkeyFelts?: string[];
+    /**
+     * Browser/Expo hooks only (`useCreateWallet`): create a passkey and use the
+     * key it yields as `encryptKey`. The server SDK does not create passkeys.
+     */
     usePasskey?: boolean;
-    /** PIN for backup encryption (dual-key wrapping). Required when usePasskey: true. */
+    /**
+     * Optional PIN for a backup copy of the private key (dual-key wrapping).
+     * `useCreateWallet` fills it from `encryptKey` when `usePasskey: true` and a
+     * PIN is given; omit both for a passkey-only wallet.
+     */
     encryptKeyBackup?: string;
-    /** Auth method: "passkey+pin" for dual-key, "pin" for PIN-only */
+    /** Auth method: "passkey" (passkey only), "passkey+pin" (dual-key) or "pin" (PIN only) */
     authMethod?: AuthMethod;
     /** WebAuthn credential ID stored in backend for recovery */
     credentialId?: string;
@@ -1149,6 +1169,7 @@ interface X402PaymentConfig {
  * `@chipi-stack/backend`. Every call is billed to the organization's credits
  * and needs a secret key (`sk_`), so these are server-side only.
  */
+
 /** Actions `/v1/ai/think` may decide. */
 type ThinkAction = "swap" | "supply" | "withdraw" | "hold";
 /**
@@ -1219,6 +1240,38 @@ interface ThinkResponse {
     latencyMs: number;
     /** `true` only for `sk_dev_` keys: canned response, no model was called. */
     sandbox?: boolean;
+    /** Present when the call was paid over x402 instead of credits (`cost.charged` is 0). */
+    x402Payment?: ThinkX402Payment;
+}
+/** The x402 payment that paid a think call. */
+interface ThinkX402Payment {
+    /** Hash of the USDC transfer that paid the call. */
+    transactionHash: string;
+    payer: string;
+    /** USDC base units (6 decimals). */
+    amount: string;
+    asset: string;
+}
+/**
+ * Pay a think call over x402 with a session key when the API asks for it
+ * (402 with a `session-transfer` offer, e.g. when credits are short).
+ */
+interface ThinkSessionPayment extends Omit<ExecuteWithSessionParams, "calls"> {
+    /**
+     * The most one call may cost, in USDC base units (6 decimals). A higher
+     * price is refused before anything is paid. Also cap USDC in the session's
+     * spending policy: this is a client-side guard, the policy is the on-chain one.
+     */
+    maxAmount: bigint | string;
+}
+interface ThinkOptions {
+    /** Pay with this session key when the API answers 402 with an x402 offer. */
+    payWithSession?: ThinkSessionPayment;
+    /**
+     * A ready `X-PAYMENT` header value, to retry a call with a payment that was
+     * made but not served (the hash is in `error.details.x402PaymentHash`).
+     */
+    xPayment?: string;
 }
 interface AiChatMessage {
     role: "system" | "user" | "assistant";
@@ -1421,4 +1474,4 @@ interface PlanSnapshot {
     planPaymentProvider: PlanPaymentProvider | null;
 }
 
-export { type AddSessionKeyParams, type AiChatMessage, type AiChatParams, type AiChatResponse, type AiCost, type AiExecuteCall, type AiExecuteParams, type AiExecuteResponse, type AiModel, type AiModelsResponse, type AiPrices, type AiPricesParams, type AiSignals, type AiSignalsParams, type AiSwapQuote, type AiTokenPrice, type AiTokenSignals, type AiUsage, type ApiError, type ApiKey, type ApiResponse, type ApproveHookInput, type ApproveParams, type AsyncReturnType, type AuthContext, type AuthMethod, type CallAnyContractParams, Chain, ChainToken, type ChipiBrowserSDKConfig, type ChipiSDKConfig, type ChipiServerSDKConfig, type Country, type CreateCustodialWalletParams, type CreateSessionKeyParams, type CreateSkuPurchaseBody, type CreateSkuPurchaseParams, type CreateUserParams, type CreateWalletParams, type CreateWalletResponse, Currency, type DeepPartial, type DeploymentData, type ErrorWithCode, type ExecuteSponsoredTransactionParams, type ExecuteSponsoredTransactionResponse, type ExecuteTransactionParams, type ExecuteWalletUpgradeParams, type ExecuteWalletUpgradeResponse, type ExecuteWithSessionParams, type GetMerchantWalletParams, type GetSessionDataParams, type GetSkuListQuery, type GetSpendingPolicyParams, type GetTokenBalanceParams, type GetTokenBalanceResponse, type GetTransactionListQuery, type GetTransactionParams, type GetTransactionStatusParams, type GetTransactionsParams, type GetUserParams, type GetWalletParams, type GetWalletResponse, type JwtPayload, type MaybePromise, type MigrateWalletToPasskeyParams, type NonEmptyArray, type NonceStore, OnChainTxStatus, type Optional, type PaginatedResponse, type PaginationQuery, type PasskeyMetadata, type PaymasterAccount, type PaymasterAdapter, type PaymentPayload, type PaymentRequirement, type Plan, type PlanPaymentProvider, type PlanSnapshot, type PrepareTypedDataParams, type PrepareTypedDataResponse, type PrepareWalletCreationParams, type PrepareWalletCreationResponse, type PrepareWalletUpgradeParams, type PrepareWalletUpgradeResponse, type Prettify, type RecordSendTransactionParams, type RemoveSpendingPolicyParams, type RequireAtLeastOne, type RevokeSessionKeyParams, STARKNET_CONTRACTS, type SessionConfig, type SessionDataResponse, type SessionKeyData, type SessionSpendingPolicy, type SessionWalletData, type SetSpendingPolicyParams, type SettleResponse, type SetupSessionParams, type ShhhPaymentExtension, type ShhhSignerKind, type SignTypedDataParams, type SignTypedDataResult, type Sku, type SkuCategory, type SkuProvider, type SpendingPolicyConfig, type SpendingPolicyData, type StakeVesuUsdcHookInputParams, type StakeVesuUsdcParams, type SyncOnChainTransfersParams, type SyncOnChainTransfersResponse, type ThinkAction, type ThinkDecision, type ThinkParams, type ThinkRawDecision, type ThinkResponse, type ThinkRiskParams, type Transaction, type TransactionStatusResponse, type TransferHookInput, type TransferParams, type TxStatus, type TxType, type UpdateWalletEncryptionParams, type UpdateWalletEncryptionResponse, type User, type ValueOrFunction, type VerifyResponse, type WalletData, type WalletType, type WithdrawVesuUsdcHookInputParams, type WithdrawVesuUsdcParams, type X402ClientConfig, type X402FacilitatorConfig, type X402PaymentConfig, type alphaUrl };
+export { type AddSessionKeyParams, type AiChatMessage, type AiChatParams, type AiChatResponse, type AiCost, type AiExecuteCall, type AiExecuteParams, type AiExecuteResponse, type AiModel, type AiModelsResponse, type AiPrices, type AiPricesParams, type AiSignals, type AiSignalsParams, type AiSwapQuote, type AiTokenPrice, type AiTokenSignals, type AiUsage, type ApiError, type ApiKey, type ApiResponse, type ApproveHookInput, type ApproveParams, type AsyncReturnType, type AuthContext, type AuthMethod, type CallAnyContractParams, Chain, ChainToken, type ChipiBrowserSDKConfig, type ChipiSDKConfig, type ChipiServerSDKConfig, type Country, type CreateCustodialWalletParams, type CreateSessionKeyParams, type CreateSkuPurchaseBody, type CreateSkuPurchaseParams, type CreateUserParams, type CreateWalletParams, type CreateWalletResponse, Currency, type DeepPartial, type DeploymentData, type ErrorWithCode, type ExecuteSponsoredTransactionParams, type ExecuteSponsoredTransactionResponse, type ExecuteTransactionParams, type ExecuteWalletUpgradeParams, type ExecuteWalletUpgradeResponse, type ExecuteWithSessionParams, type GetMerchantWalletParams, type GetSessionDataParams, type GetSkuListQuery, type GetSpendingPolicyParams, type GetTokenBalanceParams, type GetTokenBalanceResponse, type GetTransactionListQuery, type GetTransactionParams, type GetTransactionStatusParams, type GetTransactionsParams, type GetUserParams, type GetWalletParams, type GetWalletResponse, type JwtPayload, type MaybePromise, type MigrateWalletToPasskeyParams, type NonEmptyArray, type NonceStore, OnChainTxStatus, type Optional, type PaginatedResponse, type PaginationQuery, type PasskeyMetadata, type PaymasterAccount, type PaymasterAdapter, type PaymentPayload, type PaymentRequirement, type Plan, type PlanPaymentProvider, type PlanSnapshot, type PrepareTypedDataParams, type PrepareTypedDataResponse, type PrepareWalletCreationParams, type PrepareWalletCreationResponse, type PrepareWalletUpgradeParams, type PrepareWalletUpgradeResponse, type Prettify, type RecordSendTransactionParams, type RemoveSpendingPolicyParams, type RequireAtLeastOne, type RevokeSessionKeyParams, STARKNET_CONTRACTS, type SessionConfig, type SessionDataResponse, type SessionKeyData, type SessionSpendingPolicy, type SessionWalletData, type SetSpendingPolicyParams, type SettleResponse, type SetupSessionParams, type ShhhPaymentExtension, type ShhhSignerKind, type SignTypedDataParams, type SignTypedDataResult, type Sku, type SkuCategory, type SkuProvider, type SpendingPolicyConfig, type SpendingPolicyData, type StakeVesuUsdcHookInputParams, type StakeVesuUsdcParams, type SyncOnChainTransfersParams, type SyncOnChainTransfersResponse, type ThinkAction, type ThinkDecision, type ThinkOptions, type ThinkParams, type ThinkRawDecision, type ThinkResponse, type ThinkRiskParams, type ThinkSessionPayment, type ThinkX402Payment, type Transaction, type TransactionStatusResponse, type TransferHookInput, type TransferParams, type TxStatus, type TxType, type UpdateWalletEncryptionParams, type UpdateWalletEncryptionResponse, type User, type ValueOrFunction, type VerifyResponse, type WalletData, type WalletType, type WithdrawVesuUsdcHookInputParams, type WithdrawVesuUsdcParams, type X402ClientConfig, type X402FacilitatorConfig, type X402PaymentConfig, type alphaUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chipi-stack/types",
-  "version": "14.14.0",
+  "version": "14.15.1",
   "description": "Type definitions for Chipi SDK packages",
   "keywords": [
     "chipi",