@ardrive/turbo-sdk 1.42.0-alpha.2 → 1.42.0-alpha.3

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");
@@ -86,6 +87,51 @@ 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('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('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,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requiredNameFromOptions = requiredNameFromOptions;
+exports.positiveIntFromOption = positiveIntFromOption;
+exports.typeFromOptions = typeFromOptions;
+exports.paidByFromArNSOptions = paidByFromArNSOptions;
+exports.arnsPriceParamsFromOptions = arnsPriceParamsFromOptions;
+exports.arnsPrice = arnsPrice;
+exports.buyArNSName = buyArNSName;
+exports.extendArNSLease = extendArNSLease;
+exports.increaseArNSUndernames = increaseArNSUndernames;
+exports.upgradeArNSName = upgradeArNSName;
+exports.arnsPurchaseStatus = arnsPurchaseStatus;
+exports.transferArNSAnt = transferArNSAnt;
+exports.setArNSRecord = setArNSRecord;
+exports.removeArNSRecord = removeArNSRecord;
+/**
+ * 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 factory_js_1 = require("../../node/factory.js");
+const errors_js_1 = require("../../utils/errors.js");
+const constants_js_1 = require("../constants.js");
+const utils_js_1 = require("../utils.js");
+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;
+}
+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} submitted!`,
+        nonce: result.nonce,
+        arioWriteId: result.arioWriteResult?.id,
+        purchaseReceipt: result.purchaseReceipt,
+    }, 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, mARIO } = await client.getArNSPriceForName(params);
+    console.log(JSON.stringify({
+        name: params.name,
+        intent: params.intent,
+        winc,
+        credits: creditsFromWinc(winc),
+        mARIO,
+    }, null, 2));
+}
+async function buyArNSName(options, turbo) {
+    const name = requiredNameFromOptions(options);
+    const type = typeFromOptions(options.type);
+    const paidBy = paidByFromArNSOptions(options.paidBy);
+    // `--process-id` is OPTIONAL: omit it to have Turbo custodially provision the
+    // ANT (Turbo spawns + owns it — Model A); supply it to point the name at a
+    // user-owned ANT (Model B). When omitted, no `processId` is sent.
+    const processId = options.processId;
+    const client = turbo ?? (await (0, utils_js_1.turboFromOptions)(options));
+    const result = await withCreditErrorMapping(() => type === 'lease'
+        ? client.buyArNSName({
+            name,
+            type: 'lease',
+            years: positiveIntFromOption(options.years, '--years'),
+            processId,
+            paidBy,
+        })
+        : client.buyArNSName({ name, type: 'permabuy', processId, 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,
+        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,
+        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,
+        undername: options.undername,
+    });
+    console.log(JSON.stringify({ message: 'ArNS record removed!', ...result }, null, 2));
+}

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

@@ -29,6 +29,7 @@ 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("./price.js"), exports);

package/lib/cjs/cli/options.js

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listSharesOptions = exports.revokeCreditsOptions = exports.shareCreditsOptions = exports.uploadFileOptions = exports.uploadFolderOptions = exports.uploadOptions = exports.globalOptions = exports.walletOptions = exports.optionMap = void 0;
+exports.removeArNSRecordOptions = exports.setArNSRecordOptions = exports.transferArNSAntOptions = exports.arnsPurchaseStatusOptions = exports.upgradeArNSNameOptions = exports.increaseArNSUndernamesOptions = exports.extendArNSLeaseOptions = exports.buyArNSNameOptions = exports.arnsPriceOptions = exports.listSharesOptions = exports.revokeCreditsOptions = exports.shareCreditsOptions = exports.uploadFileOptions = exports.uploadFolderOptions = exports.uploadOptions = exports.globalOptions = exports.walletOptions = exports.optionMap = void 0;
 exports.optionMap = {
     token: {
         alias: '-t, --token <type>',
@@ -189,6 +189,51 @@ exports.optionMap = {
         alias: '--max-crypto-top-up-value <maxCryptoTopUpValue>',
         description: 'Maximum crypto top-up value to use for the upload. Defaults to no limit.',
     },
+    // ---- ArNS (paid with Turbo Credits) ----
+    arnsName: {
+        alias: '--name <name>',
+        description: 'ArNS name to price, buy, or manage',
+    },
+    arnsType: {
+        alias: '--type <type>',
+        description: "ArNS purchase type for Buy-Name: 'lease' or 'permabuy'",
+    },
+    arnsYears: {
+        alias: '--years <years>',
+        description: 'Lease duration in years (Buy-Name lease / Extend-Lease)',
+    },
+    arnsIncreaseQty: {
+        alias: '--increase-qty <qty>',
+        description: 'Number of additional undernames (Increase-Undername-Limit)',
+    },
+    arnsProcessId: {
+        alias: '--process-id <processId>',
+        description: 'ANT process ID the ArNS name resolves to (Buy-Name). Optional: omit for Turbo custodial provisioning (Turbo owns the ANT); supply for a user-owned ANT',
+    },
+    arnsNonce: {
+        alias: '--nonce <nonce>',
+        description: 'ArNS purchase nonce to look up the status for',
+    },
+    arnsAntId: {
+        alias: '--ant-id <antId>',
+        description: 'ANT (Metaplex Core asset) ID to transfer or manage',
+    },
+    arnsTarget: {
+        alias: '--target <address>',
+        description: 'Target Solana pubkey to transfer the ANT to',
+    },
+    arnsUndername: {
+        alias: '--undername <undername>',
+        description: "ArNS undername record to set or remove (defaults to '@')",
+    },
+    arnsTransactionId: {
+        alias: '--transaction-id <transactionId>',
+        description: 'Arweave transaction ID the ArNS record resolves to',
+    },
+    arnsTtlSeconds: {
+        alias: '--ttl-seconds <ttlSeconds>',
+        description: 'TTL in seconds for the ArNS record',
+    },
 };
 exports.walletOptions = [
     exports.optionMap.walletFile,
@@ -242,3 +287,54 @@ exports.shareCreditsOptions = [
 ];
 exports.revokeCreditsOptions = [...exports.walletOptions, exports.optionMap.address];
 exports.listSharesOptions = exports.revokeCreditsOptions;
+// ---- ArNS command option sets (token + --payment-url come from globalOptions) ----
+exports.arnsPriceOptions = [
+    exports.optionMap.arnsName,
+    exports.optionMap.arnsType,
+    exports.optionMap.arnsYears,
+    exports.optionMap.arnsIncreaseQty,
+    exports.optionMap.arnsProcessId,
+];
+exports.buyArNSNameOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsName,
+    exports.optionMap.arnsType,
+    exports.optionMap.arnsYears,
+    exports.optionMap.arnsProcessId,
+    exports.optionMap.paidBy,
+];
+exports.extendArNSLeaseOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsName,
+    exports.optionMap.arnsYears,
+    exports.optionMap.paidBy,
+];
+exports.increaseArNSUndernamesOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsName,
+    exports.optionMap.arnsIncreaseQty,
+    exports.optionMap.paidBy,
+];
+exports.upgradeArNSNameOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsName,
+    exports.optionMap.paidBy,
+];
+exports.arnsPurchaseStatusOptions = [exports.optionMap.arnsNonce];
+exports.transferArNSAntOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsAntId,
+    exports.optionMap.arnsTarget,
+];
+exports.setArNSRecordOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsAntId,
+    exports.optionMap.arnsUndername,
+    exports.optionMap.arnsTransactionId,
+    exports.optionMap.arnsTtlSeconds,
+];
+exports.removeArNSRecordOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsAntId,
+    exports.optionMap.arnsUndername,
+];

package/lib/cjs/common/http.js

@@ -47,7 +47,7 @@ class TurboHTTPService {
             signal,
         }), allowedStatuses);
     }
-    async post({ endpoint, signal, allowedStatuses = [200, 202], headers, data, x402Options, }) {
+    async post({ endpoint, signal, allowedStatuses = [200, 202], headers, data, x402Options, retry = true, }) {
         if (x402Options !== undefined) {
             return this.x402Post({
                 signal,
@@ -59,9 +59,10 @@ class TurboHTTPService {
         }
         // Convert all data types to fetch-compatible body
         const { body, duplex } = await toFetchBody(data);
-        // Use retry for Buffer/Uint8Array, tryRequest for streams
+        // Use retry for Buffer/Uint8Array, tryRequest for streams. Callers can opt
+        // out of retry for non-idempotent signed writes via `retry: false`.
         const isReusableData = data instanceof Buffer || data instanceof Uint8Array;
-        const requestFn = isReusableData
+        const requestFn = isReusableData && retry
             ? this.withRetry.bind(this)
             : this.tryRequest.bind(this);
         return requestFn(() => fetch(this.baseURL + endpoint, {

package/lib/cjs/common/index.js

@@ -34,3 +34,6 @@ __exportStar(require("./payment.js"), exports);
 __exportStar(require("./turbo.js"), exports);
 __exportStar(require("./currency.js"), exports);
 __exportStar(require("./token/index.js"), exports);
+// Typed errors so consumers can `catch (e) { if (e instanceof InsufficientCreditsError) ... }`
+// e.g. to prompt a top-up on a 402 ArNS purchase.
+__exportStar(require("../utils/errors.js"), exports);