@ardrive/turbo-sdk 1.42.0 → 1.43.0-alpha.1

package/lib/cjs/cli/cli.js

@@ -22,6 +22,7 @@ const arbundles_1 = require("@dha-team/arbundles");
 const commander_1 = require("commander");
 const fs_1 = require("fs");
 const version_js_1 = require("../version.js");
+const arns_js_1 = require("./commands/arns.js");
 const fiatEstimate_js_1 = require("./commands/fiatEstimate.js");
 const index_js_1 = require("./commands/index.js");
 const listShares_js_1 = require("./commands/listShares.js");
@@ -39,6 +40,16 @@ const utils_js_1 = require("./utils.js");
 (0, utils_js_1.applyOptions)(commander_1.program.command('balance').description('Get balance of a Turbo address'), [options_js_1.optionMap.address, ...options_js_1.walletOptions]).action(async (_commandOptions, command) => {
     await (0, utils_js_1.runCommand)(command, index_js_1.balance);
 });
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('free-status')
+    .description('Get the free-tier upload allowance remaining for a Turbo address'), [options_js_1.optionMap.address, ...options_js_1.walletOptions]).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, index_js_1.freeStatus);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('payment-history')
+    .description("Get the signing wallet's own top-up (payment) history"), [...options_js_1.walletOptions, options_js_1.optionMap.limit, options_js_1.optionMap.cursor]).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, index_js_1.paymentHistory);
+});
 (0, utils_js_1.applyOptions)(commander_1.program.command('top-up').description('Top up a Turbo address with Fiat'), [...options_js_1.walletOptions, options_js_1.optionMap.address, options_js_1.optionMap.value, options_js_1.optionMap.currency]).action(async (_commandOptions, command) => {
     await (0, utils_js_1.runCommand)(command, index_js_1.topUp);
 });
@@ -86,6 +97,87 @@ const utils_js_1 = require("./utils.js");
     .description('Lists all given or received Turbo credit share approvals for specified address or connected wallet'), options_js_1.listSharesOptions).action(async (_commandOptions, command) => {
     await (0, utils_js_1.runCommand)(command, listShares_js_1.listShares);
 });
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('arns-price')
+    .description('Get the Turbo Credit (winc + mARIO) price to buy, extend, increase undernames, or upgrade an ArNS name'), options_js_1.arnsPriceOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.arnsPrice);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('arns-fiat-quote')
+    .description('Quote an ArNS purchase paid by credit card (Stripe) - no credits needed'), options_js_1.arnsFiatQuoteOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.arnsFiatQuote);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('buy-arns-name')
+    .description('Buy an ArNS name (lease or permabuy) with Turbo Credits'), options_js_1.buyArNSNameOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.buyArNSName);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('extend-arns-lease')
+    .description('Extend an ArNS name lease with Turbo Credits'), options_js_1.extendArNSLeaseOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.extendArNSLease);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('increase-arns-undernames')
+    .description('Increase the undername limit of an ArNS name with Turbo Credits'), options_js_1.increaseArNSUndernamesOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.increaseArNSUndernames);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('upgrade-arns-name')
+    .description('Upgrade an ArNS leased name to a permabuy with Turbo Credits'), options_js_1.upgradeArNSNameOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.upgradeArNSName);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('arns-purchase-status')
+    .description('Get the status of an ArNS purchase by its nonce'), options_js_1.arnsPurchaseStatusOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.arnsPurchaseStatus);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('transfer-arns-ant')
+    .description('Transfer a Turbo-custodied ANT to a Solana pubkey you control'), options_js_1.transferArNSAntOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.transferArNSAnt);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('set-arns-record')
+    .description('Set a resolution record on a Turbo-custodied ANT'), options_js_1.setArNSRecordOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.setArNSRecord);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('remove-arns-record')
+    .description('Remove a resolution record (undername) from a Turbo-custodied ANT'), options_js_1.removeArNSRecordOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.removeArNSRecord);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('add-arns-controller')
+    .description('Grant controller rights on a Turbo-custodied ANT'), options_js_1.addArNSControllerOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.addArNSController);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('remove-arns-controller')
+    .description('Revoke controller rights on a Turbo-custodied ANT'), options_js_1.removeArNSControllerOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.removeArNSController);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('transfer-arns-record')
+    .description('Transfer one record (undername) on a Turbo-custodied ANT to another address'), options_js_1.transferArNSRecordOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.transferArNSRecord);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('set-arns-record-metadata')
+    .description("Set a record's display name, logo, description, or keywords on a Turbo-custodied ANT"), options_js_1.setArNSRecordMetadataOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.setArNSRecordMetadata);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('remove-arns-record-metadata')
+    .description("Clear a record's metadata on a Turbo-custodied ANT"), options_js_1.removeArNSRecordMetadataOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.removeArNSRecordMetadata);
+});
+(0, utils_js_1.applyOptions)(commander_1.program
+    .command('arns-action-price')
+    .description('Preview the Turbo Credit price of a non-purchase ArNS action (set-record, remove-record, ' +
+    'set-record-metadata, remove-record-metadata, transfer-record, add-controller, remove-controller, transfer)'), options_js_1.arnsActionPriceOptions).action(async (_commandOptions, command) => {
+    await (0, utils_js_1.runCommand)(command, arns_js_1.arnsActionPrice);
+});
 (0, utils_js_1.applyOptions)(commander_1.program
     .command('inspect-data-items')
     .description('Lists all given or received Turbo credit share approvals for specified address or connected wallet'), [options_js_1.optionMap.folderPath]).action(async (_commandOptions, command) => {

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

@@ -0,0 +1,440 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requiredNameFromOptions = requiredNameFromOptions;
+exports.positiveIntFromOption = positiveIntFromOption;
+exports.typeFromOptions = typeFromOptions;
+exports.actionFromOptions = actionFromOptions;
+exports.paidByFromArNSOptions = paidByFromArNSOptions;
+exports.arnsPriceParamsFromOptions = arnsPriceParamsFromOptions;
+exports.arnsPrice = arnsPrice;
+exports.arnsFiatQuote = arnsFiatQuote;
+exports.buyArNSName = buyArNSName;
+exports.extendArNSLease = extendArNSLease;
+exports.increaseArNSUndernames = increaseArNSUndernames;
+exports.upgradeArNSName = upgradeArNSName;
+exports.arnsPurchaseStatus = arnsPurchaseStatus;
+exports.transferArNSAnt = transferArNSAnt;
+exports.setArNSRecord = setArNSRecord;
+exports.removeArNSRecord = removeArNSRecord;
+exports.addArNSController = addArNSController;
+exports.removeArNSController = removeArNSController;
+exports.transferArNSRecord = transferArNSRecord;
+exports.setArNSRecordMetadata = setArNSRecordMetadata;
+exports.removeArNSRecordMetadata = removeArNSRecordMetadata;
+exports.arnsActionPrice = arnsActionPrice;
+/**
+ * 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 bignumber_js_1 = require("bignumber.js");
+const arnsActions_js_1 = require("../../common/arnsActions.js");
+const factory_js_1 = require("../../node/factory.js");
+const types_js_1 = require("../../types.js");
+const errors_js_1 = require("../../utils/errors.js");
+const constants_js_1 = require("../constants.js");
+const utils_js_1 = require("../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 (0, arnsActions_js_1.solanaOwnerSigner)(options.ownerKey);
+}
+/** The four ARIO-purchase actions are priced via `arnsPrice`, not this route. */
+const ARNS_PURCHASE_ACTIONS = new Set([
+    'buy-name',
+    'extend-lease',
+    'upgrade-name',
+    'increase-undername-limit',
+]);
+function requiredNameFromOptions(options) {
+    if (options.name === undefined || options.name.length === 0) {
+        throw new Error('Must provide an ArNS --name');
+    }
+    return options.name;
+}
+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;
+}
+function typeFromOptions(value) {
+    if (value !== 'lease' && value !== 'permabuy') {
+        throw new Error("Must provide --type of 'lease' or 'permabuy'");
+    }
+    return value;
+}
+/** Parses `--action` for `arns-action-price`, rejecting the four purchase actions. */
+function actionFromOptions(options) {
+    const { action } = options;
+    if (action === undefined || action.length === 0) {
+        throw new Error(`Must provide --action. One of: ${types_js_1.arNSActions.join(', ')}`);
+    }
+    if (!types_js_1.arNSActions.includes(action)) {
+        throw new Error(`Invalid --action '${action}'. One of: ${types_js_1.arNSActions.join(', ')}`);
+    }
+    if (ARNS_PURCHASE_ACTIONS.has(action)) {
+        throw new Error(`'${action}' is priced via \`turbo arns-price\`, not \`arns-action-price\` — ` +
+            'it spends ARIO, not just the flat credits margin this route quotes.');
+    }
+    return action;
+}
+/** `null` clears the field (Set-Record-Metadata's tri-state), `undefined` leaves it unchanged. */
+function metadataFieldFromOptions(value, clear) {
+    return clear ? null : value;
+}
+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
+ */
+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_js_1.BigNumber(winc).dividedBy(constants_js_1.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 errors_js_1.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}`);
+}
+async function arnsPrice(options, turbo) {
+    const params = arnsPriceParamsFromOptions(options);
+    const client = turbo ?? factory_js_1.TurboFactory.unauthenticated((0, utils_js_1.configFromOptions)(options));
+    const { winc, wincTotal, antSpawnSurchargeWinc, mARIO } = await client.getArNSPriceForName(params);
+    // `wincTotal` is the figure to pay. `winc` is the name only and excludes the
+    // ANT spawn surcharge, which for a Buy-Name can exceed the name's own price,
+    // so printing it as the price under-quotes what `buy-arns-name` then debits.
+    console.log(JSON.stringify({
+        name: params.name,
+        intent: params.intent,
+        wincTotal,
+        credits: creditsFromWinc(wincTotal),
+        nameOnlyWinc: winc,
+        antSpawnSurchargeWinc,
+        mARIO,
+    }, null, 2));
+}
+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 ?? factory_js_1.TurboFactory.unauthenticated((0, utils_js_1.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 errors_js_1.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;
+    }
+}
+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 (0, utils_js_1.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);
+}
+async function extendArNSLease(options, turbo) {
+    const name = requiredNameFromOptions(options);
+    const years = positiveIntFromOption(options.years, '--years');
+    const paidBy = paidByFromArNSOptions(options.paidBy);
+    const client = turbo ?? (await (0, utils_js_1.turboFromOptions)(options));
+    const result = await withCreditErrorMapping(() => client.extendArNSLease({ name, years, paidBy }));
+    logPurchaseResult('ArNS lease extension', result);
+}
+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 (0, utils_js_1.turboFromOptions)(options));
+    const result = await withCreditErrorMapping(() => client.increaseArNSUndernameLimit({ name, increaseQty, paidBy }));
+    logPurchaseResult('ArNS undername limit increase', result);
+}
+async function upgradeArNSName(options, turbo) {
+    const name = requiredNameFromOptions(options);
+    const paidBy = paidByFromArNSOptions(options.paidBy);
+    const client = turbo ?? (await (0, utils_js_1.turboFromOptions)(options));
+    const result = await withCreditErrorMapping(() => client.upgradeArNSName({ name, paidBy }));
+    logPurchaseResult('ArNS name upgrade (to permabuy)', result);
+}
+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 ?? factory_js_1.TurboFactory.unauthenticated((0, utils_js_1.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));
+}
+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 (0, utils_js_1.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));
+}
+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 (0, utils_js_1.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));
+}
+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 (0, utils_js_1.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));
+}
+async function addArNSController(options, turbo) {
+    if (options.antId === undefined) {
+        throw new Error('Must provide an --ant-id to add a controller to');
+    }
+    const client = turbo ?? (await (0, utils_js_1.turboFromOptions)(options));
+    const result = await client.addArNSController({
+        antId: options.antId,
+        owner: ownerFromOptions(options),
+        target: options.target,
+    });
+    console.log(JSON.stringify({ message: 'ArNS controller added!', ...result }, null, 2));
+}
+async function removeArNSController(options, turbo) {
+    if (options.antId === undefined) {
+        throw new Error('Must provide an --ant-id to remove a controller from');
+    }
+    const client = turbo ?? (await (0, utils_js_1.turboFromOptions)(options));
+    const result = await client.removeArNSController({
+        antId: options.antId,
+        owner: ownerFromOptions(options),
+        target: options.target,
+    });
+    console.log(JSON.stringify({ message: 'ArNS controller removed!', ...result }, null, 2));
+}
+async function transferArNSRecord(options, turbo) {
+    if (options.antId === undefined) {
+        throw new Error('Must provide an --ant-id whose record to transfer');
+    }
+    if (options.undername === undefined || options.undername.length === 0) {
+        throw new Error('Must provide an --undername to transfer');
+    }
+    if (options.target === undefined) {
+        throw new Error('Must provide a --target address to transfer the record to');
+    }
+    const client = turbo ?? (await (0, utils_js_1.turboFromOptions)(options));
+    const result = await client.transferArNSRecord({
+        antId: options.antId,
+        owner: ownerFromOptions(options),
+        undername: options.undername,
+        target: options.target,
+    });
+    console.log(JSON.stringify({ message: 'ArNS record transferred!', ...result }, null, 2));
+}
+async function setArNSRecordMetadata(options, turbo) {
+    if (options.antId === undefined) {
+        throw new Error('Must provide an --ant-id to set record metadata on');
+    }
+    const client = turbo ?? (await (0, utils_js_1.turboFromOptions)(options));
+    const result = await client.setArNSRecordMetadata({
+        antId: options.antId,
+        owner: ownerFromOptions(options),
+        undername: options.undername ?? '@',
+        displayName: metadataFieldFromOptions(options.displayName, options.clearDisplayName),
+        recordLogo: metadataFieldFromOptions(options.recordLogo, options.clearRecordLogo),
+        recordDescription: metadataFieldFromOptions(options.recordDescription, options.clearRecordDescription),
+        recordKeywords: metadataFieldFromOptions(options.recordKeywords, options.clearRecordKeywords),
+    });
+    console.log(JSON.stringify({ message: 'ArNS record metadata set!', ...result }, null, 2));
+}
+async function removeArNSRecordMetadata(options, turbo) {
+    if (options.antId === undefined) {
+        throw new Error('Must provide an --ant-id to remove record metadata from');
+    }
+    if (options.undername === undefined || options.undername.length === 0) {
+        throw new Error('Must provide an --undername');
+    }
+    const client = turbo ?? (await (0, utils_js_1.turboFromOptions)(options));
+    const result = await client.removeArNSRecordMetadata({
+        antId: options.antId,
+        owner: ownerFromOptions(options),
+        undername: options.undername,
+    });
+    console.log(JSON.stringify({ message: 'ArNS record metadata removed!', ...result }, null, 2));
+}
+/**
+ * Preview what one of the eight non-purchase actions will debit, without
+ * creating it.
+ */
+async function arnsActionPrice(options, turbo) {
+    const action = actionFromOptions(options);
+    const client = turbo ?? factory_js_1.TurboFactory.unauthenticated((0, utils_js_1.configFromOptions)(options));
+    const { wincQty } = await client.getArNSActionPrice(action);
+    console.log(JSON.stringify({ action, wincQty, credits: creditsFromWinc(wincQty) }, null, 2));
+}

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

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.freeStatus = freeStatus;
+/**
+ * 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 factory_js_1 = require("../../node/factory.js");
+const utils_js_1 = require("../utils.js");
+async function freeStatus(options) {
+    const config = (0, utils_js_1.configFromOptions)(options);
+    const { address, privateKey } = await (0, utils_js_1.addressOrPrivateKeyFromOptions)(options);
+    const { bytesRemaining, nativeAddress } = await (async () => {
+        if (address !== undefined) {
+            return {
+                ...(await factory_js_1.TurboFactory.unauthenticated(config).getFreeStatus(address)),
+                nativeAddress: address,
+            };
+        }
+        if (privateKey === undefined) {
+            throw new Error('Must provide an (--address) or use a valid wallet');
+        }
+        const turbo = factory_js_1.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/cjs/cli/commands/index.js

@@ -29,8 +29,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./arns.js"), exports);
 __exportStar(require("./balance.js"), exports);
 __exportStar(require("./cryptoFund.js"), exports);
+__exportStar(require("./freeStatus.js"), exports);
+__exportStar(require("./paymentHistory.js"), exports);
 __exportStar(require("./price.js"), exports);
 __exportStar(require("./topUp.js"), exports);
 __exportStar(require("./uploadFile.js"), exports);

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paymentHistory = paymentHistory;
+const utils_js_1 = require("../utils.js");
+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 (0, utils_js_1.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}`);
+    }
+}