kawasekit 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -550,23 +550,29 @@ declare function createSponsoredKernelClient(params: CreateSponsoredKernelClient
  * Buy-list → ZeroDev policy bundle for a **disposable, scoped session key**
  * (the Agent Commerce Hub authorization flow).
  *
- * A user's resolved buy-list (its merchants + a per-transfer cap + a total
- * transfer count + a schedule window) is baked into a single-use session key by
- * composing three on-chain policies:
+ * A user's resolved buy-list (its merchants + a per-transfer cap + a schedule
+ * window) is baked into a single-use session key by composing two on-chain
+ * policies:
  * 1. **callPolicy** — `JPYC.transfer(to, value)` with `value ≤ maxPerTransfer`
  *    and `to ∈ merchants` (the allowlist; shared with
  *    {@link createJpycDailyLimitPolicies} via {@link buildJpycTransferCallPolicy}).
- * 2. **rateLimitPolicy** — a **total** cap of `maxTransfers` over the whole
- *    schedule window (the rate window is set to span `[validAfter, validUntil]`,
- *    so `count` does NOT reset within the session — it is a session total, not a
- *    per-day limit).
- * 3. **timestampPolicy** — the session key is only valid within
+ * 2. **timestampPolicy** — the session key is only valid within
  *    `[validAfter, validUntil]`.
  *
  * Cumulative budget ("spend ≤ ¥X total") is NOT a policy field — it is the
  * amount the user funds the account with (funding is the user's responsibility,
  * out of the SDK's scope). These policies bound *who* (allowlist), *how much per
- * transfer* (cap), *how many* (count), and *when* (window).
+ * transfer* (cap), and *when* (window).
+ *
+ * The transfer **count** / sponsored-op bound is intentionally NOT a session-key
+ * policy — total value is bounded by the funded balance, and an op-count / gas
+ * bound (if desired) belongs to the consumer's **sponsor-gas policy**, not this
+ * permission bundle. A prior version included a `rateLimitPolicy` for a
+ * `maxTransfers` count, but it was built on ZeroDev's **scheduled-release** rate-
+ * limit contract (`0xf63d4139…`, which gates op *i* at `startAt + i·interval`)
+ * with `interval` = the whole window, so the 2nd transfer was *not-due until
+ * `validUntil`* and the 3rd+ never — back-to-back multi-merchant payment reverted
+ * `AA22`. It was dropped in `0.10.0`; see `docs/rfc/0004-buylist-drop-scheduled-rate-limit.md`.
  *
  * @packageDocumentation
  */
@@ -583,11 +589,6 @@ interface CreateBuyListPoliciesParams {
     readonly merchants: readonly Address[];
     /** Maximum JPYC (raw units) per single transfer. Must be positive. */
     readonly maxPerTransfer: bigint;
-    /**
-     * Maximum number of transfers over the WHOLE window — a session total, not a
-     * per-day limit. Must be a positive integer.
-     */
-    readonly maxTransfers: number;
     /** Schedule-window end (unix seconds); the key is invalid after this. Must be a positive integer. */
     readonly validUntil: number;
     /**
@@ -613,13 +614,12 @@ interface CreateBuyListPoliciesParams {
  *   jpycAddress: getJpycAddress(polygonAmoy.id),
  *   merchants: [merchantA, merchantB],          // pay ONLY these (allowlist)
  *   maxPerTransfer: parseUnits("500", JPYC_DECIMALS),
- *   maxTransfers: 3,                             // at most 3 transfers, total
  *   validUntil: Math.floor(Date.now() / 1000) + 3 * 86_400, // valid 3 days
  * });
- * // user funds the account with their budget; the policies bound who/how-much/how-many/when.
+ * // user funds the account with their budget; the policies bound who/how-much/when.
  * ```
  */
-declare function createBuyListPolicies(params: CreateBuyListPoliciesParams): readonly [Policy, Policy, Policy];
+declare function createBuyListPolicies(params: CreateBuyListPoliciesParams): readonly [Policy, Policy];
 
 /**
  * JPYC stablecoin metadata, deployments, and ABI.

package/dist/index.d.ts

@@ -550,23 +550,29 @@ declare function createSponsoredKernelClient(params: CreateSponsoredKernelClient
  * Buy-list → ZeroDev policy bundle for a **disposable, scoped session key**
  * (the Agent Commerce Hub authorization flow).
  *
- * A user's resolved buy-list (its merchants + a per-transfer cap + a total
- * transfer count + a schedule window) is baked into a single-use session key by
- * composing three on-chain policies:
+ * A user's resolved buy-list (its merchants + a per-transfer cap + a schedule
+ * window) is baked into a single-use session key by composing two on-chain
+ * policies:
  * 1. **callPolicy** — `JPYC.transfer(to, value)` with `value ≤ maxPerTransfer`
  *    and `to ∈ merchants` (the allowlist; shared with
  *    {@link createJpycDailyLimitPolicies} via {@link buildJpycTransferCallPolicy}).
- * 2. **rateLimitPolicy** — a **total** cap of `maxTransfers` over the whole
- *    schedule window (the rate window is set to span `[validAfter, validUntil]`,
- *    so `count` does NOT reset within the session — it is a session total, not a
- *    per-day limit).
- * 3. **timestampPolicy** — the session key is only valid within
+ * 2. **timestampPolicy** — the session key is only valid within
  *    `[validAfter, validUntil]`.
  *
  * Cumulative budget ("spend ≤ ¥X total") is NOT a policy field — it is the
  * amount the user funds the account with (funding is the user's responsibility,
  * out of the SDK's scope). These policies bound *who* (allowlist), *how much per
- * transfer* (cap), *how many* (count), and *when* (window).
+ * transfer* (cap), and *when* (window).
+ *
+ * The transfer **count** / sponsored-op bound is intentionally NOT a session-key
+ * policy — total value is bounded by the funded balance, and an op-count / gas
+ * bound (if desired) belongs to the consumer's **sponsor-gas policy**, not this
+ * permission bundle. A prior version included a `rateLimitPolicy` for a
+ * `maxTransfers` count, but it was built on ZeroDev's **scheduled-release** rate-
+ * limit contract (`0xf63d4139…`, which gates op *i* at `startAt + i·interval`)
+ * with `interval` = the whole window, so the 2nd transfer was *not-due until
+ * `validUntil`* and the 3rd+ never — back-to-back multi-merchant payment reverted
+ * `AA22`. It was dropped in `0.10.0`; see `docs/rfc/0004-buylist-drop-scheduled-rate-limit.md`.
  *
  * @packageDocumentation
  */
@@ -583,11 +589,6 @@ interface CreateBuyListPoliciesParams {
     readonly merchants: readonly Address[];
     /** Maximum JPYC (raw units) per single transfer. Must be positive. */
     readonly maxPerTransfer: bigint;
-    /**
-     * Maximum number of transfers over the WHOLE window — a session total, not a
-     * per-day limit. Must be a positive integer.
-     */
-    readonly maxTransfers: number;
     /** Schedule-window end (unix seconds); the key is invalid after this. Must be a positive integer. */
     readonly validUntil: number;
     /**
@@ -613,13 +614,12 @@ interface CreateBuyListPoliciesParams {
  *   jpycAddress: getJpycAddress(polygonAmoy.id),
  *   merchants: [merchantA, merchantB],          // pay ONLY these (allowlist)
  *   maxPerTransfer: parseUnits("500", JPYC_DECIMALS),
- *   maxTransfers: 3,                             // at most 3 transfers, total
  *   validUntil: Math.floor(Date.now() / 1000) + 3 * 86_400, // valid 3 days
  * });
- * // user funds the account with their budget; the policies bound who/how-much/how-many/when.
+ * // user funds the account with their budget; the policies bound who/how-much/when.
  * ```
  */
-declare function createBuyListPolicies(params: CreateBuyListPoliciesParams): readonly [Policy, Policy, Policy];
+declare function createBuyListPolicies(params: CreateBuyListPoliciesParams): readonly [Policy, Policy];
 
 /**
  * JPYC stablecoin metadata, deployments, and ABI.

package/dist/index.js

@@ -1,4 +1,4 @@
-export { TransferJpycInputError, createBuyListPolicies, createSponsoredKernelClient, transferJpyc } from './chunk-DMP7YFGA.js';
+export { TransferJpycInputError, createBuyListPolicies, createSponsoredKernelClient, transferJpyc } from './chunk-OUCIKHS2.js';
 export { X402_DEFAULT_AUTHORIZATION_LIFETIME_SECONDS, X402_FACILITATOR_ERROR_CODES, createCoinbaseFacilitator, createHttpFacilitator, createSelfFacilitator, createX402PaymentSigner, deriveReceiptTimeoutMs, wrapFetch } from './chunk-P5563RGP.js';
 export { X402_DEFAULT_MAX_TIMEOUT_SECONDS, X402_HEADER_IDEMPOTENCY_KEY, X402_HEADER_PAYMENT_REQUIRED, X402_HEADER_PAYMENT_RESPONSE, X402_HEADER_PAYMENT_SIGNATURE, buildPaymentRequiredResponse, buildPaymentRequirements, createX402Handler, decodePaymentRequiredHeader, decodePaymentResponseHeader, decodePaymentSignatureHeader, encodePaymentRequiredHeader, encodePaymentResponseHeader, encodePaymentSignatureHeader } from './chunk-PVUKX6IF.js';
 export { extractAcceptedNetworks, invokeHookSafely } from './chunk-LEHWRDVS.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kawasekit",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "TypeScript SDK for stablecoin payments by AI agents. Japan-first, JPYC-native.",
   "license": "Apache-2.0",
   "author": "k0yote",

package/dist/chunk-DMP7YFGA.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/client/sponsored-kernel-client.ts","../src/client/transfer-jpyc.ts","../src/policy/buy-list.ts"],"names":[],"mappings":"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","file":"chunk-DMP7YFGA.js","sourcesContent":["/**\n * Build a gas-sponsored Kernel account client — a {@link ConfiguredKernelClient}\n * whose UserOp gas is paid by the ZeroDev paymaster. Pass the returned client\n * straight to {@link transferJpyc}; callers never construct a paymaster client or\n * cast to {@link ConfiguredKernelClient}.\n *\n * @packageDocumentation\n */\n\nimport {\n\ttype CreateKernelAccountReturnType,\n\tcreateKernelAccountClient,\n\tcreateZeroDevPaymasterClient,\n} from \"@zerodev/sdk\";\nimport { type Address, type Chain, http, type PublicClient, type Transport } from \"viem\";\nimport { invokeHookSafely } from \"../observability/hooks\";\nimport type { ConfiguredKernelClient } from \"./transfer-jpyc\";\n\n/**\n * Optional sponsorship observability. Hooks fire through {@link invokeHookSafely},\n * so a throwing hook never breaks sponsorship. The existing `ObservabilityHooks`\n * is x402-facilitator-shaped (verify/settle); this is the paymaster-seam surface.\n */\nexport interface SponsoredKernelClientObservability {\n\t/** Fired AFTER the paymaster GRANTS sponsorship for a userOp. */\n\treadonly onSponsor?: (event: { readonly account: Address }) => void;\n\t/** Fired when the paymaster DECLINES sponsorship (the raw error then propagates). */\n\treadonly onSponsorError?: (event: { readonly account: Address; readonly error: unknown }) => void;\n}\n\n/**\n * @internal Sponsor a userOp and fire the granted/declined observability hook.\n * The original paymaster error is re-thrown unchanged (no SDK wrapping). Exported\n * for unit testing the seam without a live chain; NOT part of the public API\n * (not re-exported from `src/index.ts`).\n */\nexport async function sponsorWithObservability<T>(\n\tsponsor: () => Promise<T>,\n\taccount: Address,\n\tobservability: SponsoredKernelClientObservability | undefined,\n): Promise<T> {\n\ttry {\n\t\tconst data = await sponsor();\n\t\tinvokeHookSafely(observability?.onSponsor, { account });\n\t\treturn data;\n\t} catch (error) {\n\t\tinvokeHookSafely(observability?.onSponsorError, { account, error });\n\t\tthrow error;\n\t}\n}\n\n/** Parameters for {@link createSponsoredKernelClient}. */\nexport interface CreateSponsoredKernelClientParams {\n\t/** A Kernel v0.7 account from `createAgentSmartAccount` or `restoreSessionAccount`. */\n\treadonly account: CreateKernelAccountReturnType<\"0.7\">;\n\t/** The viem chain the client operates on (e.g. `polygonAmoy`). */\n\treadonly chain: Chain;\n\t/**\n\t * The ZeroDev RPC URL — used for BOTH the bundler and the paymaster (ZeroDev\n\t * serves both from one project RPC). Build it from a project id with\n\t * `zerodevRpcUrl(chain, projectId)`, or paste the dashboard URL.\n\t */\n\treadonly zerodevRpc: string;\n\t/** Optional viem `PublicClient` for on-chain reads during userOp prep (recommended). */\n\treadonly publicClient?: PublicClient<Transport, Chain>;\n\t/** Optional sponsorship observability — granted / declined. */\n\treadonly observability?: SponsoredKernelClientObservability;\n}\n\n/**\n * Build a gas-sponsored Kernel account client. The returned\n * {@link ConfiguredKernelClient} pays UserOp gas via the ZeroDev paymaster and is\n * accepted directly by {@link transferJpyc} — no caller-side cast.\n *\n * @example\n * ```ts\n * import {\n *   createSponsoredKernelClient,\n *   polygonAmoy,\n *   restoreSessionAccount,\n *   transferJpyc,\n *   zerodevRpcUrl,\n * } from \"kawasekit\";\n *\n * const account = await restoreSessionAccount({ publicClient, envelope, sessionKeySigner });\n * const client = createSponsoredKernelClient({\n *   account,\n *   chain: polygonAmoy,\n *   zerodevRpc: zerodevRpcUrl(polygonAmoy, projectId),\n *   publicClient,\n * });\n * const { transactionHash } = await transferJpyc(client, { to, amount });\n * ```\n */\nexport function createSponsoredKernelClient(\n\tparams: CreateSponsoredKernelClientParams,\n): ConfiguredKernelClient {\n\tconst paymasterClient = createZeroDevPaymasterClient({\n\t\tchain: params.chain,\n\t\ttransport: http(params.zerodevRpc),\n\t});\n\tconst client = createKernelAccountClient({\n\t\taccount: params.account,\n\t\tchain: params.chain,\n\t\t// exactOptionalPropertyTypes: only pass `client` when given (never `undefined`).\n\t\t...(params.publicClient !== undefined ? { client: params.publicClient } : {}),\n\t\tbundlerTransport: http(params.zerodevRpc),\n\t\tpaymaster: {\n\t\t\tgetPaymasterData: (userOperation) =>\n\t\t\t\tsponsorWithObservability(\n\t\t\t\t\t() => paymasterClient.sponsorUserOperation({ userOperation }),\n\t\t\t\t\tparams.account.address,\n\t\t\t\t\tparams.observability,\n\t\t\t\t),\n\t\t},\n\t});\n\t// createKernelAccountClient's deep generics don't unify with the exported\n\t// ConfiguredKernelClient alias; the runtime client is identical. One cast here\n\t// means callers never cast (closing gap G4).\n\treturn client as unknown as ConfiguredKernelClient;\n}\n","/**\n * High-level helper: transfer JPYC from a Kernel smart account via a sponsored\n * UserOp.\n *\n * This is the canonical \"agent payment\" path for M2. The flow:\n * 1. Resolve the JPYC contract address for `kernelClient.chain`.\n * 2. Encode `JPYC.transfer(to, amount)` calldata.\n * 3. Wrap it as a Kernel call and submit via `sendUserOperation`.\n * 4. Wait for the bundler receipt and return both hashes.\n *\n * EIP-3009 `transferWithAuthorization` cannot be used here: JPYC's signature\n * verification is pure `ecrecover`, so a smart account cannot be `from`. See\n * `src/tokens/eip3009.ts` for the EOA-payer path.\n *\n * @packageDocumentation\n */\n\nimport type { KernelAccountClient } from \"@zerodev/sdk\";\nimport type { Address, Chain, Hex, Transport } from \"viem\";\nimport { encodeFunctionData, isAddress } from \"viem\";\nimport type { SmartAccount } from \"viem/account-abstraction\";\nimport { isSupportedChainId, type SupportedChainId } from \"../chains\";\nimport { getJpycAddress, jpycAbi } from \"../tokens/jpyc\";\n\n/** A {@link KernelAccountClient} that is fully configured (chain + account). */\nexport type ConfiguredKernelClient = KernelAccountClient<Transport, Chain, SmartAccount>;\n\n/** Parameters for {@link transferJpyc}. */\nexport interface TransferJpycParams {\n\t/** Recipient address. */\n\treadonly to: Address;\n\t/**\n\t * Raw token amount in the token's smallest unit (JPYC has 18 decimals).\n\t *\n\t * @example\n\t * ```ts\n\t * import { parseUnits } from \"viem\";\n\t * import { JPYC_DECIMALS } from \"kawasekit\";\n\t *\n\t * parseUnits(\"100\", JPYC_DECIMALS); // 100 JPYC\n\t * ```\n\t */\n\treadonly amount: bigint;\n\t/**\n\t * Optional. Defaults to waiting for the bundler receipt before returning.\n\t * Set to `false` to return after the UserOp is submitted but before it\n\t * lands on chain — useful when the caller wants to do its own polling.\n\t */\n\treadonly waitForReceipt?: boolean;\n}\n\n/** Result of a {@link transferJpyc} call. */\nexport interface TransferJpycResult {\n\treadonly userOpHash: Hex;\n\t/** `null` when `waitForReceipt: false` was requested. */\n\treadonly transactionHash: Hex | null;\n\t/** `true` if the bundler receipt reported success; `null` if not awaited. */\n\treadonly success: boolean | null;\n}\n\n/** Thrown when {@link transferJpyc} is called with invalid arguments. */\nexport class TransferJpycInputError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(`transferJpyc: ${message}`);\n\t\tthis.name = \"TransferJpycInputError\";\n\t}\n}\n\n/**\n * Transfer JPYC from the Kernel smart account to `to` via a sponsored UserOp.\n *\n * @example\n * ```ts\n * import { parseUnits } from \"viem\";\n * import { JPYC_DECIMALS, transferJpyc } from \"kawasekit\";\n *\n * const { userOpHash, transactionHash } = await transferJpyc(kernelClient, {\n *   to: \"0xBeef0000000000000000000000000000DEADBEEF\",\n *   amount: parseUnits(\"100\", JPYC_DECIMALS),\n * });\n * ```\n */\nexport async function transferJpyc(\n\tkernelClient: ConfiguredKernelClient,\n\tparams: TransferJpycParams,\n): Promise<TransferJpycResult> {\n\tif (!isAddress(params.to, { strict: false })) {\n\t\tthrow new TransferJpycInputError(`\\`to\\` is not a valid address: ${params.to}`);\n\t}\n\tif (params.amount <= 0n) {\n\t\tthrow new TransferJpycInputError(`\\`amount\\` must be positive, got ${params.amount}.`);\n\t}\n\n\tconst chainId = kernelClient.chain.id;\n\tif (!isSupportedChainId(chainId)) {\n\t\tthrow new TransferJpycInputError(`Chain ID ${chainId} is not a kawasekit-supported chain.`);\n\t}\n\tconst jpycAddress = getJpycAddress(chainId satisfies SupportedChainId);\n\n\tconst data = encodeFunctionData({\n\t\tabi: jpycAbi,\n\t\tfunctionName: \"transfer\",\n\t\targs: [params.to, params.amount],\n\t});\n\n\tconst callData = await kernelClient.account.encodeCalls([{ to: jpycAddress, value: 0n, data }]);\n\n\tconst userOpHash = await kernelClient.sendUserOperation({ callData });\n\n\tif (params.waitForReceipt === false) {\n\t\treturn { userOpHash, transactionHash: null, success: null };\n\t}\n\n\tconst receipt = await kernelClient.waitForUserOperationReceipt({ hash: userOpHash });\n\treturn {\n\t\tuserOpHash,\n\t\ttransactionHash: receipt.receipt.transactionHash,\n\t\tsuccess: receipt.success,\n\t};\n}\n","/**\n * Buy-list → ZeroDev policy bundle for a **disposable, scoped session key**\n * (the Agent Commerce Hub authorization flow).\n *\n * A user's resolved buy-list (its merchants + a per-transfer cap + a total\n * transfer count + a schedule window) is baked into a single-use session key by\n * composing three on-chain policies:\n * 1. **callPolicy** — `JPYC.transfer(to, value)` with `value ≤ maxPerTransfer`\n *    and `to ∈ merchants` (the allowlist; shared with\n *    {@link createJpycDailyLimitPolicies} via {@link buildJpycTransferCallPolicy}).\n * 2. **rateLimitPolicy** — a **total** cap of `maxTransfers` over the whole\n *    schedule window (the rate window is set to span `[validAfter, validUntil]`,\n *    so `count` does NOT reset within the session — it is a session total, not a\n *    per-day limit).\n * 3. **timestampPolicy** — the session key is only valid within\n *    `[validAfter, validUntil]`.\n *\n * Cumulative budget (\"spend ≤ ¥X total\") is NOT a policy field — it is the\n * amount the user funds the account with (funding is the user's responsibility,\n * out of the SDK's scope). These policies bound *who* (allowlist), *how much per\n * transfer* (cap), *how many* (count), and *when* (window).\n *\n * @packageDocumentation\n */\n\nimport type { Policy } from \"@zerodev/permissions\";\nimport {\n\ttype CallPolicyVersion,\n\ttoRateLimitPolicy,\n\ttoTimestampPolicy,\n} from \"@zerodev/permissions/policies\";\nimport type { Address } from \"viem\";\nimport { buildJpycTransferCallPolicy } from \"./jpyc-call-policy\";\n\n/** Parameters for {@link createBuyListPolicies}. */\nexport interface CreateBuyListPoliciesParams {\n\t/** JPYC contract address on the target chain. */\n\treadonly jpycAddress: Address;\n\t/**\n\t * The buy-list's resolved merchant recipient addresses — the allowlist the\n\t * session key may pay. **Required and non-empty** (a buy-list always targets\n\t * specific merchants); checksum-normalized + de-duplicated.\n\t */\n\treadonly merchants: readonly Address[];\n\t/** Maximum JPYC (raw units) per single transfer. Must be positive. */\n\treadonly maxPerTransfer: bigint;\n\t/**\n\t * Maximum number of transfers over the WHOLE window — a session total, not a\n\t * per-day limit. Must be a positive integer.\n\t */\n\treadonly maxTransfers: number;\n\t/** Schedule-window end (unix seconds); the key is invalid after this. Must be a positive integer. */\n\treadonly validUntil: number;\n\t/**\n\t * Optional schedule-window start (unix seconds); the key is invalid before\n\t * this. Defaults to 0 (valid immediately). Must be `< validUntil`.\n\t */\n\treadonly validAfter?: number;\n\t/** ZeroDev callPolicy on-chain version. Defaults to V0_0_4. */\n\treadonly callPolicyVersion?: CallPolicyVersion;\n}\n\n/**\n * Build the ZeroDev policy bundle for a buy-list-scoped, single-use session key.\n *\n * Plug the returned policies into `toPermissionValidator({ policies, … })` and\n * issue the session key via {@link issueSessionKey}.\n *\n * @example\n * ```ts\n * import { parseUnits } from \"viem\";\n * import { createBuyListPolicies, getJpycAddress, JPYC_DECIMALS, polygonAmoy } from \"kawasekit\";\n *\n * const policies = createBuyListPolicies({\n *   jpycAddress: getJpycAddress(polygonAmoy.id),\n *   merchants: [merchantA, merchantB],          // pay ONLY these (allowlist)\n *   maxPerTransfer: parseUnits(\"500\", JPYC_DECIMALS),\n *   maxTransfers: 3,                             // at most 3 transfers, total\n *   validUntil: Math.floor(Date.now() / 1000) + 3 * 86_400, // valid 3 days\n * });\n * // user funds the account with their budget; the policies bound who/how-much/how-many/when.\n * ```\n */\nexport function createBuyListPolicies(\n\tparams: CreateBuyListPoliciesParams,\n): readonly [Policy, Policy, Policy] {\n\tif (params.merchants.length === 0) {\n\t\tthrow new Error(\n\t\t\t\"createBuyListPolicies: merchants must not be empty — a buy-list must target at least one merchant.\",\n\t\t);\n\t}\n\tif (!Number.isInteger(params.maxTransfers) || params.maxTransfers < 1) {\n\t\tthrow new Error(\n\t\t\t`createBuyListPolicies: maxTransfers must be a positive integer, got ${params.maxTransfers}.`,\n\t\t);\n\t}\n\tif (!Number.isInteger(params.validUntil) || params.validUntil <= 0) {\n\t\tthrow new Error(\n\t\t\t`createBuyListPolicies: validUntil must be a positive unix-seconds integer, got ${params.validUntil}.`,\n\t\t);\n\t}\n\tconst validAfter = params.validAfter ?? 0;\n\tif (!Number.isInteger(validAfter) || validAfter < 0) {\n\t\tthrow new Error(\n\t\t\t`createBuyListPolicies: validAfter must be a non-negative unix-seconds integer, got ${params.validAfter}.`,\n\t\t);\n\t}\n\tif (validAfter >= params.validUntil) {\n\t\tthrow new Error(\n\t\t\t`createBuyListPolicies: validAfter (${validAfter}) must be before validUntil (${params.validUntil}).`,\n\t\t);\n\t}\n\n\t// callPolicy: amount cap + merchant allowlist (shared with daily-limit).\n\tconst callPolicy = buildJpycTransferCallPolicy({\n\t\tjpycAddress: params.jpycAddress,\n\t\tmaxPerTransfer: params.maxPerTransfer,\n\t\trecipientAllowlist: params.merchants,\n\t\tcallPolicyVersion: params.callPolicyVersion,\n\t});\n\n\t// rateLimitPolicy: a TOTAL cap of maxTransfers over the window. Setting the\n\t// rate window to span exactly [validAfter, validUntil] (interval = the window\n\t// length, startAt = validAfter) keeps the whole session in one rate bucket, so\n\t// `count` is a session total — NOT a per-day limit that could reset and let\n\t// more than maxTransfers through over a multi-day window.\n\tconst rateLimitPolicy = toRateLimitPolicy({\n\t\tinterval: params.validUntil - validAfter,\n\t\tcount: params.maxTransfers,\n\t\tstartAt: validAfter,\n\t});\n\n\t// timestampPolicy: the key is only valid within the schedule window. Omit\n\t// validAfter when not given (exactOptionalPropertyTypes: don't pass undefined).\n\tconst timestampPolicy = toTimestampPolicy(\n\t\tparams.validAfter === undefined\n\t\t\t? { validUntil: params.validUntil }\n\t\t\t: { validAfter: params.validAfter, validUntil: params.validUntil },\n\t);\n\n\treturn [callPolicy, rateLimitPolicy, timestampPolicy] as const;\n}\n"]}