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

package/lib/cjs/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validChunkingModes = exports.isJWK = exports.isWebUploadFolderParams = exports.isNodeUploadFolderParams = exports.multipartFinalizedStatus = exports.multipartFailedStatus = exports.multipartPendingStatus = exports.X402Funding = exports.OnDemandFunding = exports.ExistingBalanceFunding = exports.supportedEvmSignerTokens = exports.tokenTypes = exports.fiatCurrencyTypes = void 0;
+exports.arNSFiatPurchaseMethods = exports.arNSActions = exports.arNSPurchaseIntents = exports.validChunkingModes = exports.isJWK = exports.isWebUploadFolderParams = exports.isNodeUploadFolderParams = exports.multipartFinalizedStatus = exports.multipartFailedStatus = exports.multipartPendingStatus = exports.X402Funding = exports.OnDemandFunding = exports.ExistingBalanceFunding = exports.supportedEvmSignerTokens = exports.tokenTypes = exports.fiatCurrencyTypes = void 0;
 exports.isCurrency = isCurrency;
 exports.isKyvePrivateKey = isKyvePrivateKey;
 exports.isEthPrivateKey = isEthPrivateKey;
@@ -25,7 +25,6 @@ function isCurrency(currency) {
 exports.tokenTypes = [
     'arweave',
     'ario',
-    'base-ario',
     'solana',
     'ethereum',
     'kyve',
@@ -44,7 +43,6 @@ exports.supportedEvmSignerTokens = new Set([
     'polygon-usdc',
     'usdc',
     'base-usdc',
-    'base-ario',
 ]);
 class ExistingBalanceFunding {
 }
@@ -108,3 +106,55 @@ function isEthereumWalletAdapter(walletAdapter) {
     return 'getSigner' in walletAdapter;
 }
 exports.validChunkingModes = ['force', 'disabled', 'auto'];
+// ===== ArNS purchases paid with Turbo credits (via the bundler REST API) =====
+exports.arNSPurchaseIntents = [
+    'Buy-Name',
+    'Extend-Lease',
+    'Increase-Undername-Limit',
+    'Upgrade-Name',
+];
+// ===== ArNS actions (sponsored — the current bundler surface) =====
+/**
+ * The twelve sponsored ArNS actions.
+ *
+ * Sponsorship covers these twelve and NOTHING else. Everything else in the
+ * ArNS, ANT and core programs stays on the direct-signer path and costs the
+ * user SOL — notably `BuyReturnedName` (auctions, deliberately excluded: the
+ * premium is unbounded), `ClaimReservedName`, the primary-name flow (which
+ * lives in the ario core program), release/reassign, and ANT-LEVEL metadata.
+ * Note ANT-level metadata is distinct from RECORD-level metadata, which
+ * `set-record-metadata` does sponsor.
+ */
+exports.arNSActions = [
+    'buy-name',
+    'extend-lease',
+    'upgrade-name',
+    'increase-undername-limit',
+    'set-record',
+    'remove-record',
+    'add-controller',
+    'remove-controller',
+    'transfer',
+    // Record-scoped. Owner-or-controller on chain, so these follow set-record's
+    // degrade-on-revoke shape rather than needing a signature every time.
+    'set-record-metadata',
+    'remove-record-metadata',
+    'transfer-record',
+];
+// ===== ArNS purchases paid with fiat (Stripe) — no Turbo Credits in between ====
+/**
+ * Stripe integration mode for a fiat ArNS purchase quote.
+ *
+ * - `payment-intent` — returns a Stripe PaymentIntent. Confirm it client-side
+ *   with `stripe.confirmCardPayment(paymentSession.client_secret, ...)`.
+ * - `checkout-session` — returns a Stripe Checkout Session to redirect to
+ *   (`uiMode: 'hosted'`) or embed (`uiMode: 'embedded'`).
+ *
+ * Widened with `string & Record<never, never>` so a method added service-side is
+ * still callable without an SDK bump, while the known values keep autocomplete.
+ * (`string & {}` is the usual idiom but trips the `ban-types` lint rule.)
+ */
+exports.arNSFiatPurchaseMethods = [
+    'payment-intent',
+    'checkout-session',
+];

package/lib/cjs/utils/common.js

@@ -50,7 +50,6 @@ const baseMainnetRpc = 'https://mainnet.base.org';
 exports.tokenToDevGatewayMap = {
     arweave: 'https://turbo-gateway.com', // No arweave test net
     ario: 'https://api.devnet.solana.com',
-    'base-ario': baseMainnetRpc, // No base-ario test net contract deployed
     solana: 'https://api.devnet.solana.com',
     ethereum: ethTestnetRpc,
     'base-eth': baseTestnetRpc,
@@ -64,7 +63,6 @@ exports.tokenToDevGatewayMap = {
 exports.defaultProdGatewayUrls = {
     arweave: 'https://turbo-gateway.com',
     ario: 'https://api.mainnet-beta.solana.com',
-    'base-ario': baseMainnetRpc,
     solana: 'https://api.mainnet-beta.solana.com',
     ethereum: 'https://cloudflare-eth.com/',
     'base-eth': baseMainnetRpc,
@@ -102,7 +100,6 @@ function createTurboSigner({ signer: clientProvidedSigner, privateKey: clientPro
         case 'base-eth':
         case 'usdc':
         case 'base-usdc':
-        case 'base-ario':
         case 'polygon-usdc':
             if (!(0, types_js_1.isEthPrivateKey)(clientProvidedPrivateKey)) {
                 throw new Error('A valid Ethereum private key must be provided for EthereumSigner.');
@@ -167,7 +164,6 @@ function isValidUserAddress(address, type) {
         case 'matic':
         case 'pol':
         case 'base-usdc':
-        case 'base-ario':
         case 'usdc':
         case 'polygon-usdc':
             return isValidECDSAAddress(address);

package/lib/cjs/utils/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AbortError = exports.ProvidedInputError = exports.FailedRequestError = exports.UnauthenticatedRequestError = exports.BaseError = void 0;
+exports.AbortError = exports.FiatPaymentsDisabledError = exports.InsufficientCreditsError = exports.ProvidedInputError = exports.FailedRequestError = exports.UnauthenticatedRequestError = exports.BaseError = void 0;
 /**
  * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
  *
@@ -42,6 +42,43 @@ class ProvidedInputError extends BaseError {
     }
 }
 exports.ProvidedInputError = ProvidedInputError;
+/**
+ * Raised when a credit-paid operation (e.g. an ArNS purchase) is rejected by the
+ * service because the paying wallet does not hold enough Turbo credits. Maps the
+ * bundler's HTTP `402 Payment Required` response to a typed, catchable error so
+ * callers can prompt a top-up without string-matching on messages.
+ *
+ * Recovery: top up the balance, then retry the SAME operation reusing the
+ * captured `nonce` (the nonce is the idempotency key), or mint a fresh request.
+ */
+class InsufficientCreditsError extends BaseError {
+    constructor(message) {
+        super(message ??
+            'Insufficient Turbo credits to complete this purchase. Top up your balance and retry.');
+        /** Always the HTTP status that produced this error. */
+        this.status = 402;
+    }
+}
+exports.InsufficientCreditsError = InsufficientCreditsError;
+/**
+ * Raised when the payment service has fiat (Stripe) payments switched off, which
+ * it signals with `503` and the body "Fiat (Stripe) ArNS payments are disabled".
+ * This is a normal state in the testnet sandbox, not an outage.
+ *
+ * Distinguished from a generic `503` deliberately: the same status is also used
+ * for internal errors (body "Internal Server Error: ..."), so status alone is
+ * ambiguous. Recovery: fall back to the credit-paid path (`buyArNSName` and
+ * friends), or surface fiat checkout as unavailable.
+ */
+class FiatPaymentsDisabledError extends BaseError {
+    constructor(message) {
+        super(message ??
+            'Fiat (Stripe) payments are disabled on this payment service. Use the credit-paid purchase path instead.');
+        /** Always the HTTP status that produced this error. */
+        this.status = 503;
+    }
+}
+exports.FiatPaymentsDisabledError = FiatPaymentsDisabledError;
 class AbortError extends BaseError {
     constructor(message = 'Request was aborted') {
         super(message);

package/lib/cjs/utils/folderIndex.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contentHashTagName = void 0;
+exports.isValidContentHash = isValidContentHash;
+exports.isValidFolderIndexKey = isValidFolderIndexKey;
+exports.contentHashFromFolderIndexKey = contentHashFromFolderIndexKey;
+exports.folderIndexKey = folderIndexKey;
+/**
+ * Internals shared by the folder index layers and by `uploadFolder`. Not part
+ * of the package's public surface.
+ */
+/** Tag carrying the sha-256 of a file's own bytes, as lowercase hex. */
+exports.contentHashTagName = 'File-SHA256';
+const contentHashRegex = /^[0-9a-f]{64}$/;
+const folderIndexKeyRegex = /^[0-9a-f]{64}\.[0-9a-f]{64}$/;
+/** True for a lowercase hex sha-256 digest of a file's bytes. */
+function isValidContentHash(hash) {
+    return hash !== undefined && contentHashRegex.test(hash);
+}
+/**
+ * A folder index key is `<sha-256 of the bytes>.<sha-256 of the tags>`.
+ *
+ * Both halves matter. Keying on the bytes alone would reuse an item whose tags
+ * are not the ones the caller asked for: an empty `a.css` and an empty `b.js`
+ * hash identically, and reusing one for the other would serve JavaScript as
+ * `text/css`. Keying on the tags as well means a reused data item is always
+ * exactly the data item this call would otherwise have created.
+ *
+ * The bytes half is kept in the clear so a layer that queries a gateway can
+ * recover it and filter on the `File-SHA256` tag.
+ */
+function isValidFolderIndexKey(key) {
+    return key !== undefined && folderIndexKeyRegex.test(key);
+}
+/** The bytes half of a folder index key. */
+function contentHashFromFolderIndexKey(key) {
+    return key.slice(0, 64);
+}
+async function sha256Hex(data) {
+    const digest = await crypto.subtle.digest('SHA-256', data);
+    return Buffer.from(digest).toString('hex');
+}
+/**
+ * Canonical encoding of a tag set: the same tags in a different order encode
+ * identically, because two data items that differ only in tag order are the
+ * same item as far as reuse goes.
+ *
+ * The sort compares code units rather than using `localeCompare`, which is not
+ * a total order over distinct strings and depends on the host's ICU data --
+ * NFC and NFD spellings of the same word compare equal without being equal, and
+ * two locales disagree on where an accented letter sorts. Either would let one
+ * tag set hash differently on two machines, which costs a reuse.
+ *
+ * The encoding has to be injective, not merely stable. An ANS-104 tag name and
+ * value are arbitrary byte arrays, so a delimiter-joined string collides: with
+ * a 0x00/0x01 join, a single tag whose value embeds both delimiters encodes
+ * exactly like two separate tags. A collision here is a wrong reuse, which is
+ * the one failure the composite key exists to make impossible. JSON escapes
+ * the delimiters, so no value can forge a record boundary.
+ */
+function canonicalTags(tags) {
+    const pairs = tags
+        .map((tag) => [tag.name, tag.value])
+        .sort(([aName, aValue], [bName, bValue]) => {
+        const [a, b] = aName === bName ? [aValue, bValue] : [aName, bName];
+        return a < b ? -1 : a > b ? 1 : 0;
+    });
+    return new TextEncoder().encode(JSON.stringify(pairs));
+}
+/** The folder index key for a file with these bytes and these final tags. */
+async function folderIndexKey({ contentHash, tags, }) {
+    return `${contentHash}.${await sha256Hex(canonicalTags(tags))}`;
+}

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/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 { addArNSController, arnsActionPrice, arnsActionStatus, arnsFiatQuote, arnsPrice, arnsPurchaseStatus, buyArNSName, extendArNSLease, increaseArNSUndernames, removeArNSController, removeArNSRecord, removeArNSRecordMetadata, setArNSRecord, setArNSRecordMetadata, transferArNSAnt, transferArNSRecord, 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 { addArNSControllerOptions, arnsActionPriceOptions, arnsActionStatusOptions, arnsFiatQuoteOptions, arnsPriceOptions, arnsPurchaseStatusOptions, buyArNSNameOptions, extendArNSLeaseOptions, globalOptions, increaseArNSUndernamesOptions, listSharesOptions, optionMap, removeArNSControllerOptions, removeArNSRecordMetadataOptions, removeArNSRecordOptions, revokeCreditsOptions, setArNSRecordMetadataOptions, setArNSRecordOptions, shareCreditsOptions, transferArNSAntOptions, transferArNSRecordOptions, 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,92 @@ 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('arns-action-status')
+    .description('Get the status of a credit-paid ArNS action by its nonce (buy, extend, upgrade, and the non-purchase actions)'), arnsActionStatusOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, arnsActionStatus);
+});
+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('add-arns-controller')
+    .description('Grant controller rights on a Turbo-custodied ANT'), addArNSControllerOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, addArNSController);
+});
+applyOptions(program
+    .command('remove-arns-controller')
+    .description('Revoke controller rights on a Turbo-custodied ANT'), removeArNSControllerOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, removeArNSController);
+});
+applyOptions(program
+    .command('transfer-arns-record')
+    .description('Transfer one record (undername) on a Turbo-custodied ANT to another address'), transferArNSRecordOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, transferArNSRecord);
+});
+applyOptions(program
+    .command('set-arns-record-metadata')
+    .description("Set a record's display name, logo, description, or keywords on a Turbo-custodied ANT"), setArNSRecordMetadataOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, setArNSRecordMetadata);
+});
+applyOptions(program
+    .command('remove-arns-record-metadata')
+    .description("Clear a record's metadata on a Turbo-custodied ANT"), removeArNSRecordMetadataOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, removeArNSRecordMetadata);
+});
+applyOptions(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)'), arnsActionPriceOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, arnsActionPrice);
+});
 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) => {