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

package/lib/cjs/common/chunked.js

@@ -41,13 +41,14 @@ const chunkingHeader = { 'x-chunking-version': '2' };
  * uploading them in parallel, and emitting progress/error events.
  */
 class ChunkedUploader {
-    constructor({ http, token, maxChunkConcurrency = exports.defaultMaxChunkConcurrency, maxFinalizeMs, chunkByteCount = exports.defaultChunkByteCount, logger = logger_js_1.Logger.default, chunkingMode = 'auto', dataItemByteCount, x402, x402RefundIdentity, }) {
+    constructor({ http, token, maxChunkConcurrency = exports.defaultMaxChunkConcurrency, maxFinalizeMs, chunkByteCount = exports.defaultChunkByteCount, logger = logger_js_1.Logger.default, chunkingMode = 'auto', dataItemByteCount, x402, x402RefundIdentity, paidUploadId, }) {
         this.assertChunkParams({
             chunkByteCount,
             chunkingMode,
             maxChunkConcurrency,
             maxFinalizeMs,
         });
+        this.paidUploadId = paidUploadId;
         this.chunkByteCount = chunkByteCount;
         this.maxChunkConcurrency = maxChunkConcurrency;
         this.maxFinalizeMs = maxFinalizeMs;
@@ -145,6 +146,14 @@ class ChunkedUploader {
         this.paidUploadId = res.id;
         return res.id;
     }
+    /**
+     * The paid upload id, once one has been bought. `uploadFile` reads this after
+     * a failed attempt so the next attempt resumes the upload already paid for
+     * rather than buying a second one.
+     */
+    get currentPaidUploadId() {
+        return this.paidUploadId;
+    }
     async initUpload() {
         if (this.x402 !== undefined) {
             return this.initPaidUpload(this.x402);

package/lib/cjs/common/http.js

@@ -52,8 +52,21 @@ class TurboHTTPService {
         this.baseURL = url;
         this.retryConfig = retryConfig;
     }
+    /**
+     * Refuse to pay over cleartext.
+     *
+     * An x402 payment authorization is a bearer credential: anyone who observes
+     * it can submit it. Sending one over `http:` hands it to the network, so a
+     * misconfigured service URL must fail loudly rather than quietly leak.
+     */
+    assertSecureForPayment() {
+        if (!this.baseURL.startsWith('https:') && !isLoopback(this.baseURL)) {
+            throw new Error(`Refusing to send an x402 payment over a non-HTTPS URL: ${this.baseURL}`);
+        }
+    }
     async get({ endpoint, signal, allowedStatuses = [200, 202], headers, x402Options, }) {
         if (x402Options !== undefined) {
+            this.assertSecureForPayment();
             const maxMUSDCAmount = x402Options.maxMUSDCAmount !== undefined
                 ? BigInt(x402Options.maxMUSDCAmount.toString())
                 : undefined;
@@ -162,6 +175,7 @@ class TurboHTTPService {
             endpoint,
             x402Options,
         });
+        this.assertSecureForPayment();
         const { body, duplex } = await toFetchBody(data);
         return this.tryRequest(async () => {
             const maxMUSDCAmount = x402Options.maxMUSDCAmount !== undefined
@@ -213,3 +227,13 @@ function isFirefoxOrSafari() {
             !ua.includes('Chrome') &&
             !ua.includes('Chromium')));
 }
+/** Loopback is exempt: local development never leaves the machine. */
+function isLoopback(url) {
+    try {
+        const { hostname } = new URL(url);
+        return (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1');
+    }
+    catch {
+        return false;
+    }
+}

package/lib/cjs/common/payment.js

@@ -657,13 +657,20 @@ class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymentServic
      * The owner needs a Solana key to sign with, NOT a funded one — Turbo pays
      * every lamport of fee and rent.
      */
-    async buyArNSName({ name, owner, type = 'lease', years, paidBy, onNonce, }) {
+    async buyArNSName({ name, owner, type = 'lease', years, paidBy, onNonce, antState, }) {
         return this.completeArNSAction('buy-name', {
             name,
             ownerAddress: await owner.getAddress(),
             type,
             ...(years !== undefined ? { years } : {}),
             ...(paidBy !== undefined ? { paidBy } : {}),
+            /*
+              Spread conditionally, like `paidBy` — an `antState: undefined` key
+              would serialize into the body and is not the same request as omitting
+              it. Sent whole in the BODY rather than the query string: it is an
+              object, and `createArNSAction` already posts every param as JSON.
+            */
+            ...(antState !== undefined ? { antState } : {}),
         }, owner, { onNonce });
     }
     /** Extend a lease. Permissionless on chain — no owner signature needed. */

package/lib/cjs/common/turbo.js

@@ -193,6 +193,20 @@ class TurboUnauthenticatedClient {
             maxMUSDCAmount,
         });
     }
+    /**
+     * Price a signed data item for an x402 upload without sending it. See
+     * `TurboUnauthenticatedUploadService.getX402PriceForDataItem`.
+     */
+    getX402PriceForDataItem(p) {
+        return this.uploadService.getX402PriceForDataItem(p);
+    }
+    /**
+     * Price raw data for an x402 upload, including the data-item wrapping
+     * overhead. See `TurboUnauthenticatedUploadService.getX402PriceForRawData`.
+     */
+    getX402PriceForRawData(p) {
+        return this.uploadService.getX402PriceForRawData(p);
+    }
 }
 exports.TurboUnauthenticatedClient = TurboUnauthenticatedClient;
 class TurboAuthenticatedClient extends TurboUnauthenticatedClient {
@@ -381,5 +395,19 @@ class TurboAuthenticatedClient extends TurboUnauthenticatedClient {
             maxMUSDCAmount,
         });
     }
+    /**
+     * Price a signed data item for an x402 upload without sending it. See
+     * `TurboUnauthenticatedUploadService.getX402PriceForDataItem`.
+     */
+    getX402PriceForDataItem(p) {
+        return this.uploadService.getX402PriceForDataItem(p);
+    }
+    /**
+     * Price raw data for an x402 upload, including the data-item wrapping
+     * overhead. See `TurboUnauthenticatedUploadService.getX402PriceForRawData`.
+     */
+    getX402PriceForRawData(p) {
+        return this.uploadService.getX402PriceForRawData(p);
+    }
 }
 exports.TurboAuthenticatedClient = TurboAuthenticatedClient;

package/lib/cjs/common/upload.js

@@ -17,6 +17,7 @@ exports.TurboAuthenticatedBaseUploadService = exports.TurboUnauthenticatedUpload
  * limitations under the License.
  */
 const bignumber_js_1 = require("bignumber.js");
+const node_stream_1 = require("node:stream");
 const plimit_lit_1 = require("plimit-lit");
 const types_js_1 = require("../types.js");
 const common_js_1 = require("../utils/common.js");
@@ -80,6 +81,29 @@ class TurboUnauthenticatedUploadService {
                 headers['x-paid-by'] = paidBy;
             }
         }
+        if (x402Options !== undefined) {
+            /*
+              x402 needs a body fetch can measure, and one it can send twice.
+      
+              `content-length` is a forbidden header, so setting it above does
+              nothing: a streamed body goes out chunked with no length. The service
+              prices from that header, so without it there is no 402 challenge — and
+              the protocol's paid retry has a spent stream to replay, which fails
+              outright. Buffering fixes both: the length is declared honestly and the
+              body can be re-sent.
+      
+              Bounded by the chunking decision above — anything over two chunks took
+              the chunked path, which pays at create and never reaches here.
+            */
+            const body = await streamToBuffer(streamWithUploadEvents, dataItemSize, resume, signal);
+            return this.httpService.post({
+                endpoint: `/tx/${this.token}`,
+                signal,
+                data: body,
+                headers,
+                x402Options,
+            });
+        }
         // setup the post request using the stream with upload events
         const postPromise = this.httpService.post({
             endpoint: `/tx/${this.token}`,
@@ -92,6 +116,46 @@ class TurboUnauthenticatedUploadService {
         resume();
         return postPromise;
     }
+    /**
+     * Price a SIGNED data item for an x402 upload, without sending it.
+     *
+     * The only other way to learn an x402 price is to POST the payload and read
+     * the 402 challenge, which means transmitting it to find out what it costs.
+     *
+     * `byteCount` is the size of the signed data item — what
+     * `dataItemSizeFactory()` returns — not the payload inside it. Use
+     * `getX402PriceForRawData` when the service does the wrapping.
+     *
+     * `network` names the x402 network, not the SDK token: the route builds its
+     * token as `usdc-{network}`. `base-usdc` is accepted on mainnet only because
+     * the network there is literally `base`, so a testnet caller must pass
+     * `base-sepolia` explicitly.
+     */
+    async getX402PriceForDataItem({ byteCount, network = 'base', }) {
+        return this.httpService.get({
+            endpoint: `/price/x402/data-item/usdc-${network}/${byteCount}`,
+        });
+    }
+    /**
+     * Price RAW data for an x402 upload, where the service wraps it into a data
+     * item itself.
+     *
+     * Also reports the wrapping overhead — a data item is larger than its
+     * payload by its header, signature and tags — which the caller has no way to
+     * compute. `tagCount` and `contentType` feed that estimate, so pass what the
+     * upload will actually carry or the quote will read low.
+     */
+    async getX402PriceForRawData({ byteCount, network = 'base', tagCount, contentType, }) {
+        const query = new URLSearchParams();
+        if (tagCount !== undefined)
+            query.set('tags', `${tagCount}`);
+        if (contentType !== undefined)
+            query.set('contentType', contentType);
+        const qs = query.toString();
+        return this.httpService.get({
+            endpoint: `/price/x402/data/usdc-${network}/${byteCount}${qs ? `?${qs}` : ''}`,
+        });
+    }
     async uploadRawX402Data({ data, tags, signal, maxMUSDCAmount, signer, }) {
         if (!this.x402EnabledTokens.includes(this.token)) {
             throw new Error('x402 uploads are not supported for token: ' + this.token);
@@ -226,8 +290,28 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
             !this.x402EnabledTokens.includes(this.token)) {
             throw new Error('x402 uploads are not supported for token: ' + this.token);
         }
+        /*
+          Buffering the single request is only safe because anything larger chunks.
+          `chunkingMode: 'disabled'` removes that guarantee, so an arbitrarily large
+          item would be pulled into memory — and the service caps single-request
+          items anyway, so it would be refused after the fact. Check before signing:
+          signing a large item only to reject it wastes the expensive part.
+        */
+        if (fundingMode instanceof types_js_1.X402Funding &&
+            params.chunkingMode === 'disabled' &&
+            fileSizeFactory() > maxX402SingleRequestByteCount) {
+            throw new Error(`An x402 upload of ${fileSizeFactory()} bytes must be chunked: the ` +
+                `single-request path buffers the item in memory and is limited to ` +
+                `${maxX402SingleRequestByteCount} bytes. Remove ` +
+                `chunkingMode: 'disabled' to upload this item.`);
+        }
         this.logger.debug('Starting file upload', { params });
         let retries = 0;
+        // Carried ACROSS retry attempts. A paid chunked upload is bought before any
+        // chunk is accepted, so an attempt that fails after paying must hand its
+        // upload id to the next attempt. Rebuilding the uploader with no id is how
+        // a single upload gets billed once per retry.
+        let paidUploadId;
         const maxRetries = this.retryConfig.retries ?? 3;
         const retryDelay = this.retryConfig.retryDelay ??
             ((retryNumber) => retryNumber * 1000);
@@ -283,6 +367,7 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
                     dataItemByteCount: dataItemSizeFactory(),
                     chunkingMode: params.chunkingMode,
                     maxFinalizeMs: params.maxFinalizeMs,
+                    paidUploadId,
                     ...(x402Options ? { x402: x402Options } : {}),
                     ...(x402Options
                         ? {
@@ -294,14 +379,21 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
                         : {}),
                 });
                 if (chunkedUploader.shouldUseChunkUploader) {
-                    const response = await chunkedUploader.upload({
-                        dataItemStreamFactory,
-                        dataItemSizeFactory,
-                        dataItemOpts,
-                        signal,
-                        events,
-                    });
-                    return { ...response, cryptoFundResult };
+                    try {
+                        const response = await chunkedUploader.upload({
+                            dataItemStreamFactory,
+                            dataItemSizeFactory,
+                            dataItemOpts,
+                            signal,
+                            events,
+                        });
+                        return { ...response, cryptoFundResult };
+                    }
+                    finally {
+                        // Read on the way out, success or failure. On failure this is the
+                        // whole point: the next attempt resumes what this one paid for.
+                        paidUploadId = chunkedUploader.currentPaidUploadId ?? paidUploadId;
+                    }
                 }
                 const response = await this.uploadSignedDataItem({
                     dataItemStreamFactory,
@@ -983,3 +1075,88 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
     }
 }
 exports.TurboAuthenticatedBaseUploadService = TurboAuthenticatedBaseUploadService;
+/**
+ * The largest data item the x402 single-request path will buffer.
+ *
+ * Normally unreachable: anything over two chunks takes the chunked path, which
+ * pays at create and streams. It bites only when chunking is explicitly
+ * disabled, and it exists so that case fails with an explanation rather than
+ * by exhausting memory.
+ */
+const maxX402SingleRequestByteCount = 100 * 1024 * 1024;
+/**
+ * Drain a data-item stream into a Buffer, resuming it once the reader is
+ * attached so upload-progress events still fire.
+ *
+ * Checks the running total as it fills rather than at the end: a stream that
+ * overruns its declared size would otherwise be held in memory in full before
+ * anything objected.
+ */
+async function streamToBuffer(stream, byteCount, resume, signal) {
+    // A closure, so TypeScript does not narrow `aborted` away for the whole
+    // function — it genuinely can flip while the stream is draining.
+    const isAborted = () => signal?.aborted === true;
+    if (isAborted()) {
+        throw new errors_js_1.AbortError();
+    }
+    const chunks = [];
+    let received = 0;
+    const take = (chunk) => {
+        received += chunk.byteLength;
+        if (received > byteCount) {
+            throw new Error(`Data item stream exceeded its declared size of ${byteCount} bytes`);
+        }
+        chunks.push(chunk);
+    };
+    if (stream instanceof node_stream_1.Readable) {
+        const done = new Promise((resolve, reject) => {
+            const onAbort = () => {
+                stream.destroy();
+                reject(new errors_js_1.AbortError());
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            stream.on('data', (c) => {
+                try {
+                    take(Buffer.from(c));
+                }
+                catch (error) {
+                    stream.destroy();
+                    reject(error);
+                }
+            });
+            stream.on('end', () => {
+                signal?.removeEventListener('abort', onAbort);
+                resolve();
+            });
+            stream.on('error', reject);
+        });
+        resume();
+        await done;
+    }
+    else {
+        const reader = stream.getReader();
+        resume();
+        try {
+            for (;;) {
+                if (isAborted()) {
+                    await reader.cancel();
+                    throw new errors_js_1.AbortError();
+                }
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (value !== undefined)
+                    take(Buffer.from(value));
+            }
+        }
+        catch (error) {
+            await reader.cancel().catch(() => undefined);
+            throw error;
+        }
+    }
+    const buf = Buffer.concat(chunks);
+    if (buf.byteLength !== byteCount) {
+        throw new Error(`Data item stream produced ${buf.byteLength} bytes, expected ${byteCount}`);
+    }
+    return buf;
+}

package/lib/esm/common/chunked.js

@@ -35,13 +35,14 @@ const chunkingHeader = { 'x-chunking-version': '2' };
  * uploading them in parallel, and emitting progress/error events.
  */
 export class ChunkedUploader {
-    constructor({ http, token, maxChunkConcurrency = defaultMaxChunkConcurrency, maxFinalizeMs, chunkByteCount = defaultChunkByteCount, logger = Logger.default, chunkingMode = 'auto', dataItemByteCount, x402, x402RefundIdentity, }) {
+    constructor({ http, token, maxChunkConcurrency = defaultMaxChunkConcurrency, maxFinalizeMs, chunkByteCount = defaultChunkByteCount, logger = Logger.default, chunkingMode = 'auto', dataItemByteCount, x402, x402RefundIdentity, paidUploadId, }) {
         this.assertChunkParams({
             chunkByteCount,
             chunkingMode,
             maxChunkConcurrency,
             maxFinalizeMs,
         });
+        this.paidUploadId = paidUploadId;
         this.chunkByteCount = chunkByteCount;
         this.maxChunkConcurrency = maxChunkConcurrency;
         this.maxFinalizeMs = maxFinalizeMs;
@@ -139,6 +140,14 @@ export class ChunkedUploader {
         this.paidUploadId = res.id;
         return res.id;
     }
+    /**
+     * The paid upload id, once one has been bought. `uploadFile` reads this after
+     * a failed attempt so the next attempt resumes the upload already paid for
+     * rather than buying a second one.
+     */
+    get currentPaidUploadId() {
+        return this.paidUploadId;
+    }
     async initUpload() {
         if (this.x402 !== undefined) {
             return this.initPaidUpload(this.x402);

package/lib/esm/common/http.js

@@ -48,8 +48,21 @@ export class TurboHTTPService {
         this.baseURL = url;
         this.retryConfig = retryConfig;
     }
+    /**
+     * Refuse to pay over cleartext.
+     *
+     * An x402 payment authorization is a bearer credential: anyone who observes
+     * it can submit it. Sending one over `http:` hands it to the network, so a
+     * misconfigured service URL must fail loudly rather than quietly leak.
+     */
+    assertSecureForPayment() {
+        if (!this.baseURL.startsWith('https:') && !isLoopback(this.baseURL)) {
+            throw new Error(`Refusing to send an x402 payment over a non-HTTPS URL: ${this.baseURL}`);
+        }
+    }
     async get({ endpoint, signal, allowedStatuses = [200, 202], headers, x402Options, }) {
         if (x402Options !== undefined) {
+            this.assertSecureForPayment();
             const maxMUSDCAmount = x402Options.maxMUSDCAmount !== undefined
                 ? BigInt(x402Options.maxMUSDCAmount.toString())
                 : undefined;
@@ -158,6 +171,7 @@ export class TurboHTTPService {
             endpoint,
             x402Options,
         });
+        this.assertSecureForPayment();
         const { body, duplex } = await toFetchBody(data);
         return this.tryRequest(async () => {
             const maxMUSDCAmount = x402Options.maxMUSDCAmount !== undefined
@@ -208,3 +222,13 @@ function isFirefoxOrSafari() {
             !ua.includes('Chrome') &&
             !ua.includes('Chromium')));
 }
+/** Loopback is exempt: local development never leaves the machine. */
+function isLoopback(url) {
+    try {
+        const { hostname } = new URL(url);
+        return (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1');
+    }
+    catch {
+        return false;
+    }
+}

package/lib/esm/common/payment.js

@@ -653,13 +653,20 @@ export class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymen
      * The owner needs a Solana key to sign with, NOT a funded one — Turbo pays
      * every lamport of fee and rent.
      */
-    async buyArNSName({ name, owner, type = 'lease', years, paidBy, onNonce, }) {
+    async buyArNSName({ name, owner, type = 'lease', years, paidBy, onNonce, antState, }) {
         return this.completeArNSAction('buy-name', {
             name,
             ownerAddress: await owner.getAddress(),
             type,
             ...(years !== undefined ? { years } : {}),
             ...(paidBy !== undefined ? { paidBy } : {}),
+            /*
+              Spread conditionally, like `paidBy` — an `antState: undefined` key
+              would serialize into the body and is not the same request as omitting
+              it. Sent whole in the BODY rather than the query string: it is an
+              object, and `createArNSAction` already posts every param as JSON.
+            */
+            ...(antState !== undefined ? { antState } : {}),
         }, owner, { onNonce });
     }
     /** Extend a lease. Permissionless on chain — no owner signature needed. */

package/lib/esm/common/turbo.js

@@ -190,6 +190,20 @@ export class TurboUnauthenticatedClient {
             maxMUSDCAmount,
         });
     }
+    /**
+     * Price a signed data item for an x402 upload without sending it. See
+     * `TurboUnauthenticatedUploadService.getX402PriceForDataItem`.
+     */
+    getX402PriceForDataItem(p) {
+        return this.uploadService.getX402PriceForDataItem(p);
+    }
+    /**
+     * Price raw data for an x402 upload, including the data-item wrapping
+     * overhead. See `TurboUnauthenticatedUploadService.getX402PriceForRawData`.
+     */
+    getX402PriceForRawData(p) {
+        return this.uploadService.getX402PriceForRawData(p);
+    }
 }
 export class TurboAuthenticatedClient extends TurboUnauthenticatedClient {
     constructor({ paymentService, uploadService, signer, }) {
@@ -377,4 +391,18 @@ export class TurboAuthenticatedClient extends TurboUnauthenticatedClient {
             maxMUSDCAmount,
         });
     }
+    /**
+     * Price a signed data item for an x402 upload without sending it. See
+     * `TurboUnauthenticatedUploadService.getX402PriceForDataItem`.
+     */
+    getX402PriceForDataItem(p) {
+        return this.uploadService.getX402PriceForDataItem(p);
+    }
+    /**
+     * Price raw data for an x402 upload, including the data-item wrapping
+     * overhead. See `TurboUnauthenticatedUploadService.getX402PriceForRawData`.
+     */
+    getX402PriceForRawData(p) {
+        return this.uploadService.getX402PriceForRawData(p);
+    }
 }