@ardrive/turbo-sdk 1.41.3 → 1.42.0-alpha.10

package/lib/cjs/utils/uuid.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uuidV4 = uuidV4;
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const crypto_1 = require("crypto");
+/**
+ * RFC 4122 version 4 UUID, derived from `randomBytes` (already used across the
+ * SDK in both the node and web builds). Avoids depending on
+ * `crypto.randomUUID`, whose availability varies by runtime/polyfill.
+ */
+function uuidV4() {
+    const bytes = (0, crypto_1.randomBytes)(16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 variant
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/lib/cjs/web/factory.js

@@ -37,7 +37,7 @@ class TurboFactory extends factory_js_1.TurboBaseFactory {
         // Import the TurboAuthenticatedUploadService class from the web upload module
         return new upload_js_1.TurboAuthenticatedUploadService(config);
     }
-    static authenticated({ privateKey, signer: providedSigner, paymentServiceConfig = {}, uploadServiceConfig = {}, token, gatewayUrl, tokenMap, tokenTools, walletAdapter, cuUrl, processId, }) {
+    static authenticated({ privateKey, signer: providedSigner, paymentServiceConfig = {}, uploadServiceConfig = {}, token, gatewayUrl, tokenMap, tokenTools, walletAdapter, }) {
         return new TurboFactory().getAuthenticatedTurbo({
             privateKey,
             signer: providedSigner,
@@ -49,8 +49,6 @@ class TurboFactory extends factory_js_1.TurboBaseFactory {
             tokenTools,
             logger: this.logger,
             walletAdapter,
-            cuUrl,
-            processId,
         });
     }
 }

package/lib/cjs/web/signer.js

@@ -64,9 +64,11 @@ class TurboWebArweaveSigner extends signer_js_1.TurboDataItemAbstractSigner {
             dataItemSizeFactory: () => signedDataItemSize,
         };
     }
-    async generateSignedRequestHeaders() {
+    async generateSignedRequestHeaders(nonce, additionalData) {
         await this.setPublicKey();
-        return super.generateSignedRequestHeaders();
+        // Pass through the caller's nonce + action-binding data (previously dropped,
+        // which would override a route-required UUID nonce and the H-2 binding).
+        return super.generateSignedRequestHeaders(nonce, additionalData);
     }
     async signData(dataToSign) {
         await this.setPublicKey();

package/lib/esm/cli/cli.js

@@ -20,14 +20,15 @@ import { DataItem } from '@dha-team/arbundles';
 import { program } from 'commander';
 import { readFileSync, readdirSync } from 'fs';
 import { version } from '../version.js';
+import { arnsFiatQuote, arnsPrice, arnsPurchaseStatus, buyArNSName, extendArNSLease, increaseArNSUndernames, removeArNSRecord, setArNSRecord, transferArNSAnt, upgradeArNSName, } from './commands/arns.js';
 import { fiatEstimate } from './commands/fiatEstimate.js';
-import { balance, cryptoFund, price, topUp, uploadFile, uploadFolder, } from './commands/index.js';
+import { balance, cryptoFund, freeStatus, paymentHistory, price, topUp, uploadFile, uploadFolder, } from './commands/index.js';
 import { listShares } from './commands/listShares.js';
 import { revokeCredits } from './commands/revokeCredits.js';
 import { shareCredits } from './commands/shareCredits.js';
 import { tokenPrice } from './commands/tokenPrice.js';
 import { x402UploadUnsignedFile } from './commands/x402UploadUnsignedData.js';
-import { globalOptions, listSharesOptions, optionMap, revokeCreditsOptions, shareCreditsOptions, uploadFileOptions, uploadFolderOptions, walletOptions, } from './options.js';
+import { arnsFiatQuoteOptions, arnsPriceOptions, arnsPurchaseStatusOptions, buyArNSNameOptions, extendArNSLeaseOptions, globalOptions, increaseArNSUndernamesOptions, listSharesOptions, optionMap, removeArNSRecordOptions, revokeCreditsOptions, setArNSRecordOptions, shareCreditsOptions, transferArNSAntOptions, upgradeArNSNameOptions, uploadFileOptions, uploadFolderOptions, walletOptions, } from './options.js';
 import { applyOptions, runCommand } from './utils.js';
 applyOptions(program
     .name('turbo')
@@ -37,6 +38,16 @@ applyOptions(program
 applyOptions(program.command('balance').description('Get balance of a Turbo address'), [optionMap.address, ...walletOptions]).action(async (_commandOptions, command) => {
     await runCommand(command, balance);
 });
+applyOptions(program
+    .command('free-status')
+    .description('Get the free-tier upload allowance remaining for a Turbo address'), [optionMap.address, ...walletOptions]).action(async (_commandOptions, command) => {
+    await runCommand(command, freeStatus);
+});
+applyOptions(program
+    .command('payment-history')
+    .description("Get the signing wallet's own top-up (payment) history"), [...walletOptions, optionMap.limit, optionMap.cursor]).action(async (_commandOptions, command) => {
+    await runCommand(command, paymentHistory);
+});
 applyOptions(program.command('top-up').description('Top up a Turbo address with Fiat'), [...walletOptions, optionMap.address, optionMap.value, optionMap.currency]).action(async (_commandOptions, command) => {
     await runCommand(command, topUp);
 });
@@ -84,6 +95,56 @@ applyOptions(program
     .description('Lists all given or received Turbo credit share approvals for specified address or connected wallet'), listSharesOptions).action(async (_commandOptions, command) => {
     await runCommand(command, listShares);
 });
+applyOptions(program
+    .command('arns-price')
+    .description('Get the Turbo Credit (winc + mARIO) price to buy, extend, increase undernames, or upgrade an ArNS name'), arnsPriceOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, arnsPrice);
+});
+applyOptions(program
+    .command('arns-fiat-quote')
+    .description('Quote an ArNS purchase paid by credit card (Stripe) - no credits needed'), arnsFiatQuoteOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, arnsFiatQuote);
+});
+applyOptions(program
+    .command('buy-arns-name')
+    .description('Buy an ArNS name (lease or permabuy) with Turbo Credits'), buyArNSNameOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, buyArNSName);
+});
+applyOptions(program
+    .command('extend-arns-lease')
+    .description('Extend an ArNS name lease with Turbo Credits'), extendArNSLeaseOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, extendArNSLease);
+});
+applyOptions(program
+    .command('increase-arns-undernames')
+    .description('Increase the undername limit of an ArNS name with Turbo Credits'), increaseArNSUndernamesOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, increaseArNSUndernames);
+});
+applyOptions(program
+    .command('upgrade-arns-name')
+    .description('Upgrade an ArNS leased name to a permabuy with Turbo Credits'), upgradeArNSNameOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, upgradeArNSName);
+});
+applyOptions(program
+    .command('arns-purchase-status')
+    .description('Get the status of an ArNS purchase by its nonce'), arnsPurchaseStatusOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, arnsPurchaseStatus);
+});
+applyOptions(program
+    .command('transfer-arns-ant')
+    .description('Transfer a Turbo-custodied ANT to a Solana pubkey you control'), transferArNSAntOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, transferArNSAnt);
+});
+applyOptions(program
+    .command('set-arns-record')
+    .description('Set a resolution record on a Turbo-custodied ANT'), setArNSRecordOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, setArNSRecord);
+});
+applyOptions(program
+    .command('remove-arns-record')
+    .description('Remove a resolution record (undername) from a Turbo-custodied ANT'), removeArNSRecordOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, removeArNSRecord);
+});
 applyOptions(program
     .command('inspect-data-items')
     .description('Lists all given or received Turbo credit share approvals for specified address or connected wallet'), [optionMap.folderPath]).action(async (_commandOptions, command) => {

package/lib/esm/cli/commands/arns.js

@@ -0,0 +1,300 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { BigNumber } from 'bignumber.js';
+import { solanaOwnerSigner } from '../../common/arnsActions.js';
+import { TurboFactory } from '../../node/factory.js';
+import { FiatPaymentsDisabledError, InsufficientCreditsError, } from '../../utils/errors.js';
+import { wincPerCredit } from '../constants.js';
+import { configFromOptions, turboFromOptions } from '../utils.js';
+/**
+ * The ANT owner's Solana key.
+ *
+ * Deliberately separate from the wallet that pays: the payer holds Turbo
+ * credits (and may be Arweave or Ethereum), while the owner holds the ANT and
+ * must be Solana. The owner needs a key to SIGN with, not a funded account —
+ * Turbo is the fee payer on every sponsored action.
+ */
+function ownerFromOptions(options) {
+    if (options.ownerKey === undefined || options.ownerKey === '') {
+        throw new Error('Must provide --owner-key (a base58 Solana secret key) — it owns the ANT and signs for it. ' +
+            'This is separate from the wallet paying in Turbo Credits.');
+    }
+    return solanaOwnerSigner(options.ownerKey);
+}
+export function requiredNameFromOptions(options) {
+    if (options.name === undefined || options.name.length === 0) {
+        throw new Error('Must provide an ArNS --name');
+    }
+    return options.name;
+}
+export function positiveIntFromOption(value, flag) {
+    if (value === undefined) {
+        throw new Error(`Must provide ${flag}`);
+    }
+    const num = +value;
+    if (!Number.isFinite(num) || !Number.isInteger(num) || num <= 0) {
+        throw new Error(`${flag} must be a positive integer`);
+    }
+    return num;
+}
+export function typeFromOptions(value) {
+    if (value !== 'lease' && value !== 'permabuy') {
+        throw new Error("Must provide --type of 'lease' or 'permabuy'");
+    }
+    return value;
+}
+export function paidByFromArNSOptions(paidBy) {
+    return paidBy !== undefined && paidBy.length > 0 ? paidBy : undefined;
+}
+// A price quote depends only on the name (length), type, and years — NOT on the
+// ANT the name will resolve to. The service ignores `processId` for pricing, but
+// the SDK's Buy-Name validation still requires a non-empty one, so we substitute
+// this obvious placeholder when the user omits `--process-id` from `arns-price`.
+// (`buy-arns-name` still requires a real `--process-id`.)
+const PRICING_PLACEHOLDER_PROCESS_ID = 'pricing-only-no-process-id';
+/**
+ * Infer the ArNS pricing intent from the provided flags:
+ * - `--type` present            -> Buy-Name (lease needs --years; --process-id optional for pricing)
+ * - `--increase-qty` present    -> Increase-Undername-Limit
+ * - `--years` present (no type) -> Extend-Lease
+ * - otherwise                   -> Upgrade-Name
+ */
+export function arnsPriceParamsFromOptions(options) {
+    const name = requiredNameFromOptions(options);
+    if (options.type !== undefined) {
+        const type = typeFromOptions(options.type);
+        const processId = options.processId ?? PRICING_PLACEHOLDER_PROCESS_ID;
+        if (type === 'lease') {
+            return {
+                intent: 'Buy-Name',
+                name,
+                type: 'lease',
+                years: positiveIntFromOption(options.years, '--years'),
+                processId,
+            };
+        }
+        return {
+            intent: 'Buy-Name',
+            name,
+            type: 'permabuy',
+            processId,
+        };
+    }
+    if (options.increaseQty !== undefined) {
+        return {
+            intent: 'Increase-Undername-Limit',
+            name,
+            increaseQty: positiveIntFromOption(options.increaseQty, '--increase-qty'),
+        };
+    }
+    if (options.years !== undefined) {
+        return {
+            intent: 'Extend-Lease',
+            name,
+            years: positiveIntFromOption(options.years, '--years'),
+        };
+    }
+    return { intent: 'Upgrade-Name', name };
+}
+function creditsFromWinc(winc) {
+    return new BigNumber(winc).dividedBy(wincPerCredit).toFixed(12);
+}
+/** Rethrow a 402 as a clear, actionable "top up" message. */
+async function withCreditErrorMapping(fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (error instanceof InsufficientCreditsError) {
+            throw new Error('Insufficient Turbo credits to complete this ArNS purchase. ' +
+                'Top up your balance (e.g. `turbo top-up` or `turbo crypto-fund`) and retry.');
+        }
+        throw error;
+    }
+}
+function logPurchaseResult(action, result) {
+    console.log(JSON.stringify({
+        message: `${action} completed!`,
+        nonce: result.nonce,
+        antId: result.antId,
+        // Solana transaction id of the on-chain write.
+        messageId: result.messageId,
+        ...(result.alreadyCompleted === true ? { alreadyCompleted: true } : {}),
+    }, null, 2));
+    console.log(`\nTrack this purchase with:\n  turbo arns-purchase-status --nonce ${result.nonce}`);
+}
+export async function arnsPrice(options, turbo) {
+    const params = arnsPriceParamsFromOptions(options);
+    const client = turbo ?? TurboFactory.unauthenticated(configFromOptions(options));
+    const { winc, mARIO } = await client.getArNSPriceForName(params);
+    console.log(JSON.stringify({
+        name: params.name,
+        intent: params.intent,
+        winc,
+        credits: creditsFromWinc(winc),
+        mARIO,
+    }, null, 2));
+}
+export async function arnsFiatQuote(options, turbo) {
+    const params = arnsPriceParamsFromOptions(options);
+    // `arnsPriceParamsFromOptions` substitutes PRICING_PLACEHOLDER_PROCESS_ID for
+    // an omitted Buy-Name `processId`, which is fine for a price lookup but NOT
+    // here: a quote records a real purchase, and that placeholder is not a valid
+    // ANT. Send `processId` only when the caller actually supplied one — omitting
+    // it is what tells Turbo to custodially provision the ANT.
+    if (options.processId === undefined) {
+        delete params.processId;
+    }
+    const address = options.address;
+    if (address === undefined) {
+        throw new Error('A destination --address is required for a fiat ArNS quote.');
+    }
+    const client = turbo ?? TurboFactory.unauthenticated(configFromOptions(options));
+    try {
+        const { purchaseQuote, paymentSession, adjustments, fees } = await client.getArNSFiatPurchaseQuote({
+            ...params,
+            address,
+            currency: (options.currency ?? 'usd'),
+            method: options.method,
+            promoCodes: options.promoCode,
+        });
+        console.log(JSON.stringify({
+            name: purchaseQuote.name,
+            intent: purchaseQuote.intent,
+            nonce: purchaseQuote.nonce,
+            paymentAmount: purchaseQuote.paymentAmount,
+            currency: purchaseQuote.currencyType,
+            quoteExpirationDate: purchaseQuote.quoteExpirationDate,
+            paymentSessionId: paymentSession.id,
+            // Present for a payment intent / embedded checkout; a hosted
+            // checkout session returns `url` instead.
+            clientSecret: paymentSession.client_secret ?? undefined,
+            checkoutUrl: paymentSession.url ?? undefined,
+            adjustments,
+            fees,
+        }, null, 2));
+    }
+    catch (error) {
+        if (error instanceof FiatPaymentsDisabledError) {
+            console.error('Fiat (Stripe) payments are disabled on this payment service. Use the credit-paid commands (buy-arns-name, extend-arns-lease, ...) instead.');
+            throw error;
+        }
+        throw error;
+    }
+}
+export async function buyArNSName(options, turbo) {
+    const name = requiredNameFromOptions(options);
+    const type = typeFromOptions(options.type);
+    const paidBy = paidByFromArNSOptions(options.paidBy);
+    // Every buy mints a fresh ANT straight to `--owner-key`; Turbo never holds
+    // it, and there is no bring-your-own-ANT path any more.
+    const owner = ownerFromOptions(options);
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await withCreditErrorMapping(() => type === 'lease'
+        ? client.buyArNSName({
+            name,
+            owner,
+            type: 'lease',
+            years: positiveIntFromOption(options.years, '--years'),
+            paidBy,
+        })
+        : client.buyArNSName({ name, owner, type: 'permabuy', paidBy }));
+    logPurchaseResult('ArNS name purchase', result);
+}
+export async function extendArNSLease(options, turbo) {
+    const name = requiredNameFromOptions(options);
+    const years = positiveIntFromOption(options.years, '--years');
+    const paidBy = paidByFromArNSOptions(options.paidBy);
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await withCreditErrorMapping(() => client.extendArNSLease({ name, years, paidBy }));
+    logPurchaseResult('ArNS lease extension', result);
+}
+export async function increaseArNSUndernames(options, turbo) {
+    const name = requiredNameFromOptions(options);
+    const increaseQty = positiveIntFromOption(options.increaseQty, '--increase-qty');
+    const paidBy = paidByFromArNSOptions(options.paidBy);
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await withCreditErrorMapping(() => client.increaseArNSUndernameLimit({ name, increaseQty, paidBy }));
+    logPurchaseResult('ArNS undername limit increase', result);
+}
+export async function upgradeArNSName(options, turbo) {
+    const name = requiredNameFromOptions(options);
+    const paidBy = paidByFromArNSOptions(options.paidBy);
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await withCreditErrorMapping(() => client.upgradeArNSName({ name, paidBy }));
+    logPurchaseResult('ArNS name upgrade (to permabuy)', result);
+}
+export async function arnsPurchaseStatus(options, turbo) {
+    if (options.nonce === undefined || options.nonce.length === 0) {
+        throw new Error('Must provide a --nonce to look up purchase status');
+    }
+    const client = turbo ?? TurboFactory.unauthenticated(configFromOptions(options));
+    const status = await client.getArNSPurchaseStatus({ nonce: options.nonce });
+    const state = status.failedDate !== undefined
+        ? 'failed'
+        : status.messageId
+            ? 'success'
+            : 'pending';
+    console.log(JSON.stringify({ state, ...status }, null, 2));
+}
+export async function transferArNSAnt(options, turbo) {
+    if (options.antId === undefined) {
+        throw new Error('Must provide an --ant-id to transfer');
+    }
+    if (options.target === undefined) {
+        throw new Error('Must provide a --target address to transfer the ANT to');
+    }
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await client.transferArNSAnt({
+        antId: options.antId,
+        owner: ownerFromOptions(options),
+        target: options.target,
+    });
+    console.log(JSON.stringify({ message: 'ANT transfer submitted!', ...result }, null, 2));
+}
+export async function setArNSRecord(options, turbo) {
+    if (options.antId === undefined) {
+        throw new Error('Must provide an --ant-id to set a record on');
+    }
+    if (options.transactionId === undefined) {
+        throw new Error('Must provide a --transaction-id for the record');
+    }
+    const ttlSeconds = positiveIntFromOption(options.ttlSeconds, '--ttl-seconds');
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await client.setArNSRecord({
+        antId: options.antId,
+        owner: ownerFromOptions(options),
+        undername: options.undername ?? '@',
+        transactionId: options.transactionId,
+        ttlSeconds,
+    });
+    console.log(JSON.stringify({ message: 'ArNS record set!', ...result }, null, 2));
+}
+export async function removeArNSRecord(options, turbo) {
+    if (options.antId === undefined) {
+        throw new Error('Must provide an --ant-id to remove a record from');
+    }
+    if (options.undername === undefined || options.undername.length === 0) {
+        throw new Error('Must provide an --undername to remove');
+    }
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await client.removeArNSRecord({
+        antId: options.antId,
+        owner: ownerFromOptions(options),
+        undername: options.undername,
+    });
+    console.log(JSON.stringify({ message: 'ArNS record removed!', ...result }, null, 2));
+}

package/lib/esm/cli/commands/freeStatus.js

@@ -0,0 +1,44 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { TurboFactory } from '../../node/factory.js';
+import { addressOrPrivateKeyFromOptions, configFromOptions } from '../utils.js';
+export async function freeStatus(options) {
+    const config = configFromOptions(options);
+    const { address, privateKey } = await addressOrPrivateKeyFromOptions(options);
+    const { bytesRemaining, nativeAddress } = await (async () => {
+        if (address !== undefined) {
+            return {
+                ...(await TurboFactory.unauthenticated(config).getFreeStatus(address)),
+                nativeAddress: address,
+            };
+        }
+        if (privateKey === undefined) {
+            throw new Error('Must provide an (--address) or use a valid wallet');
+        }
+        const turbo = TurboFactory.authenticated({
+            ...config,
+            privateKey,
+        });
+        return {
+            ...(await turbo.getFreeStatus()),
+            nativeAddress: await turbo.signer.getNativeAddress(),
+        };
+    })();
+    console.log(`Turbo free-tier allowance for Native Address "${nativeAddress}"\n` +
+        (bytesRemaining === null
+            ? 'Free bytes remaining: unlimited (exempt/partner wallet)'
+            : `Free bytes remaining: ${bytesRemaining}`));
+}

package/lib/esm/cli/commands/index.js

@@ -13,8 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+export * from './arns.js';
 export * from './balance.js';
 export * from './cryptoFund.js';
+export * from './freeStatus.js';
+export * from './paymentHistory.js';
 export * from './price.js';
 export * from './topUp.js';
 export * from './uploadFile.js';

package/lib/esm/cli/commands/paymentHistory.js

@@ -0,0 +1,22 @@
+import { turboFromOptions } from '../utils.js';
+export async function paymentHistory(options) {
+    // Signature-required and self-scoped: a wallet is mandatory (there is no
+    // --address form), and the service returns only this signer's own top-ups.
+    const turbo = await turboFromOptions(options);
+    const limit = options.limit !== undefined ? +options.limit : undefined;
+    if (limit !== undefined &&
+        (!Number.isInteger(limit) || limit < 1 || limit > 100)) {
+        throw new Error('--limit must be an integer between 1 and 100');
+    }
+    const { payments, hasMore, cursor } = await turbo.getPaymentHistory({
+        limit,
+        cursor: options.cursor,
+    });
+    // stdout carries only the JSON page and the next-page hint goes to stderr, so
+    // `... | jq` works at the default log level. (--debug intentionally routes SDK
+    // logs to stdout and will interleave — expected when you ask for debug output.)
+    console.log(JSON.stringify({ payments, hasMore, cursor }, null, 2));
+    if (hasMore) {
+        console.error(`\nMore results available — fetch the next page with --cursor ${cursor}`);
+    }
+}