@artblocks/abx-storage 0.1.0-alpha.8 → 0.1.0

package/dist/readiness.js

@@ -0,0 +1,183 @@
+import { gatewayConfigFromEnv, gatewayUrlFor, linearBackoffDelay, resolveGatewayBase as sdkResolveGatewayBase, sleep, } from '@artblocks/abx-sdk';
+// Re-export the SDK gateway types and helpers unchanged so this package's public API remains stable.
+export { gatewayUrlFor } from '@artblocks/abx-sdk';
+/**
+ * Gateways probed as alternates, per network. Kept short on purpose — this is a diagnosis, not a
+ * survey, and each entry is a request someone waits on. The Arweave pair is the one the second
+ * report actually measured serving ahead of `arweave.net`, so they are evidence rather than taste.
+ */
+const ALTERNATE_GATEWAYS = {
+    arweave: ['https://permagate.io', 'https://vilenarios.com'],
+    ipfs: ['https://dweb.link', 'https://w3s.link'],
+};
+const DEFAULT_TIMEOUT_MS = 6000;
+/** Parse any accepted locator form into its network + id. */
+export function parseLocator(locator) {
+    const raw = locator.trim();
+    if (/^ar:\/\//i.test(raw))
+        return { network: 'arweave', id: raw.slice(5).replace(/^\/+/, '') };
+    if (/^ipfs:\/\//i.test(raw))
+        return { network: 'ipfs', id: raw.slice(7).replace(/^\/+/, '') };
+    if (/^https?:\/\//i.test(raw)) {
+        // A gateway URL already names its own gateway; keep it whole and ask exactly it. Detecting the
+        // network from the shape lets the alternates still apply (that is the point of the whole probe).
+        if (/\/ipfs\//.test(raw) || /\.ipfs\./.test(raw))
+            return { network: 'ipfs', id: raw };
+        if (/arweave\.net|permagate\.io|vilenarios\.com|ar-io\.dev/.test(raw))
+            return { network: 'arweave', id: raw };
+        return { network: 'http', id: raw };
+    }
+    // Bare ids: an Arweave txid is 43 chars of base64url; a CIDv0 starts Qm…, a CIDv1 b…/f…
+    if (/^[A-Za-z0-9_-]{43}$/.test(raw))
+        return { network: 'arweave', id: raw };
+    if (/^(Qm[1-9A-HJ-NP-Za-km-z]{44}|b[a-z2-7]{20,}|f[0-9a-f]{20,})/.test(raw))
+        return { network: 'ipfs', id: raw };
+    throw new Error(`'${locator}' isn't a recognisable locator. Expected ar://<txid>, ipfs://<cid>, an https:// gateway URL, or a bare txid/CID.`);
+}
+/**
+ * The gateway BASE for a locator network — **override → env → generic public default**
+ * (`ABX_IPFS_GATEWAY`/`ABX_ARWEAVE_GATEWAY`, then `ipfs.io`/`arweave.net`). This is the READ-TIME
+ * default for resolving an arbitrary on-chain locator whose upload backend is unknown to the
+ * resolver — distinct from {@link ipfsConfigFromEnv}/{@link arweaveConfigFromEnv}'s MODE-aware
+ * defaults for a backend this toolkit itself configured to write through (e.g. a `kubo` IPFS
+ * gateway defaults to `127.0.0.1:8080`, a locator resolver has no such context and must default
+ * to something that resolves for anyone). `http` locators carry their own base (they are already
+ * an absolute URL) and never reach here — callers return them verbatim before consulting a gateway.
+ *
+ * A thin compose over the SDK's split: {@link resolveGatewayBase} used to own the
+ * `override ?? env ?? default` line itself (`process.env` read inline); now the pure decision
+ * lives in `@artblocks/abx-sdk`'s `resolveGatewayBase` (src/gateways.ts) and the env read in its
+ * `gatewayConfigFromEnv`, so this function's whole body is just wiring override → (env or
+ * nothing) → the SDK's pure default. Kept here, under this same name and signature, because
+ * every existing caller (this package's own `locatorStatus`, token-api's `resolveLocatorUrl`)
+ * still wants exactly this three-rung precedence with one call.
+ */
+export function resolveGatewayBase(network, override) {
+    if (network === 'http')
+        return '';
+    if (override)
+        return sdkResolveGatewayBase(network, network === 'ipfs' ? { ipfs: override } : { arweave: override });
+    return sdkResolveGatewayBase(network, gatewayConfigFromEnv());
+}
+/**
+ * Ask one gateway whether it serves these bytes, reading **headers only**.
+ *
+ * A ranged request (`Range: bytes=0-0`) is what keeps this cheap: the content in question can be tens of
+ * megabytes and the question is only whether it is there. Gateways that ignore `Range` answer 200
+ * with the whole body, so the body is cancelled rather than read — without that, checking a large
+ * locator would download it.
+ */
+export async function probeGateway(url, opts = {}) {
+    const doFetch = opts.fetchFn ?? fetch;
+    const gateway = safeHost(url);
+    const started = Date.now();
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        const res = await doFetch(url, { headers: { range: 'bytes=0-0' }, signal: ctrl.signal, redirect: 'follow' });
+        // Never read the body: a Range-ignoring gateway would otherwise stream the whole asset.
+        try {
+            await res.body?.cancel();
+        }
+        catch {
+            /* already consumed or unsupported — nothing to release */
+        }
+        return {
+            url,
+            gateway,
+            serving: res.status >= 200 && res.status < 300,
+            status: res.status,
+            contentType: res.headers.get('content-type'),
+            bytes: totalBytesFrom(res.headers.get('content-range'), res.headers.get('content-length'), res.status),
+            ms: Date.now() - started,
+        };
+    }
+    catch (err) {
+        const aborted = err.name === 'AbortError' || ctrl.signal.aborted;
+        return {
+            url,
+            gateway,
+            serving: false,
+            status: null,
+            contentType: null,
+            bytes: null,
+            ms: Date.now() - started,
+            error: aborted ? `no response in ${opts.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms` : err.message,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Accepted-vs-retrievable for one locator, across the gateway that matters and a couple of others. */
+export async function locatorStatus(locator, opts = {}) {
+    const { network, id } = parseLocator(locator);
+    const primaryGateway = resolveGatewayBase(network, opts.gateway);
+    const primaryUrl = gatewayUrlFor(network, id, primaryGateway);
+    // `http` locators have no notion of an alternate — the URL IS the address, so a second host would
+    // be answering about different bytes.
+    const alternateBases = opts.primaryOnly || network === 'http' ? [] : ALTERNATE_GATEWAYS[network];
+    const alternateUrls = alternateBases
+        .map((base) => gatewayUrlFor(network, id, base))
+        .filter((u) => u !== primaryUrl);
+    const probe = (u) => probeGateway(u, { timeoutMs: opts.timeoutMs, fetchFn: opts.fetchFn });
+    const [primary, ...alternates] = await Promise.all([probe(primaryUrl), ...alternateUrls.map(probe)]);
+    const readiness = primary.serving
+        ? 'ready'
+        : alternates.some((a) => a.serving)
+            ? 'propagating'
+            : 'unreachable';
+    return { locator, network, id, readiness, primary, alternates };
+}
+const DEFAULT_AWAIT_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_POLL_BASE_MS = 3000;
+/**
+ * Poll {@link locatorStatus} until it reports `'ready'` or the deadline passes.
+ *
+ * `locatorStatus` alone answers "right now" — the natural next question, for a caller that would
+ * otherwise upload during a mint and write the locator into a token that renders broken for its
+ * first minutes of life (see the module doc), is "wait until it's actually there." This is that,
+ * factored out once so a caller doesn't hand-roll its own poll/backoff loop around a one-shot check.
+ *
+ * `'propagating'` is treated the same as `'unreachable'` here — both mean "not yet what THIS caller
+ * can rely on" — but every intermediate status still reaches `onEvent`, so a caller that wants to
+ * distinguish "provably on the network, just behind" from "no evidence yet" can from the events.
+ */
+export async function awaitLocatorReady(locator, opts = {}) {
+    const deadlineMs = opts.timeoutMs ?? DEFAULT_AWAIT_TIMEOUT_MS;
+    const pollBaseMs = opts.pollBaseMs ?? DEFAULT_POLL_BASE_MS;
+    const started = Date.now();
+    const probeOpts = { gateway: opts.gateway, primaryOnly: opts.primaryOnly, timeoutMs: opts.probeTimeoutMs, fetchFn: opts.fetchFn };
+    let attempt = 0;
+    for (;;) {
+        attempt++;
+        const status = await locatorStatus(locator, probeOpts);
+        const elapsedMs = Date.now() - started;
+        opts.onEvent?.({ attempt, elapsedMs, status });
+        if (status.readiness === 'ready')
+            return { status, attempts: attempt, elapsedMs, ready: true };
+        const delay = linearBackoffDelay(attempt, pollBaseMs);
+        if (elapsedMs + delay >= deadlineMs)
+            return { status, attempts: attempt, elapsedMs, ready: false };
+        await sleep(delay);
+    }
+}
+/** Total size from a ranged response's `content-range` (`bytes 0-0/12345`), else `content-length`
+ *  when the gateway ignored the range and answered 200 with the whole thing. */
+function totalBytesFrom(contentRange, contentLength, status) {
+    const m = contentRange?.match(/\/\s*(\d+)\s*$/);
+    if (m)
+        return Number(m[1]);
+    if (status === 200 && contentLength && /^\d+$/.test(contentLength))
+        return Number(contentLength);
+    return null;
+}
+function safeHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+}
+//# sourceMappingURL=readiness.js.map

package/dist/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"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"}

package/dist/upload-readiness.d.ts

@@ -0,0 +1,89 @@
+import type { ResolveStorageOptions } from './resolve.js';
+import { type ArweaveConfig } from './arweave.js';
+/**
+ * Deploy-time storage readiness — what a REAL upload needs, decided from local facts (and, for the
+ * best-effort USD estimate, one price-API call) so "dry-run passes, then the real deploy fails at
+ * upload" can't happen. Three questions, each pure aside from the one noted network call:
+ *
+ *  - {@link planTurboUpload} — is THIS ONE file free (Turbo's 100 KiB tier) or chargeable?
+ *  - {@link assessStorageReadiness} — across every backend, what does a real upload of `sizes` need
+ *    (Arweave credits, a Pinata JWT, a cloud public base)?
+ *  - {@link assessTurboFunds} — does the resolved Turbo identity have ENOUGH prepaid credits for
+ *    `sizes`, and (when it's short) does the creator's own wallet already hold some?
+ *
+ * None of this mints or spends anything — it only INTERROGATES the resolved provider. Identity
+ * creation is the caller's job (the CLI's managed-key flow owns the key file location; see
+ * `arweave-identity.ts` / `ArweaveConfig.ensureJwk`), so `assessTurboFunds` expects a config that
+ * already has one.
+ */
+/** Whether `opts` resolves to Arweave via the Turbo (prepaid-credits) provider — the only provider
+ *  with a free tier and a funds balance to check; `http-bundler` skips every readiness/funds
+ *  question below (it has its own auth, not a balance this package knows how to read). */
+export declare function isTurboArweave(opts: ResolveStorageOptions): boolean;
+export interface TurboUploadPlan {
+    /** Whether this upload is over Turbo's 100 KiB free tier (so it draws on prepaid credits). */
+    chargeable: boolean;
+    /** `size` in KB, formatted to 1 decimal — for the free-vs-credit readout. */
+    sizeKb: string;
+}
+/** The free-vs-credit decision for ONE Turbo upload of `size` bytes — from the local byte size
+ *  alone, so it works under `--dry-run` too. Null when `opts` doesn't resolve to Turbo-Arweave
+ *  (nothing to decide). */
+export declare function planTurboUpload(opts: ResolveStorageOptions, size: number): TurboUploadPlan | null;
+/** Per-backend readiness facts for a real upload of `sizes` (per-file byte counts). Each variant
+ *  carries only what its backend needs checked; a backend with nothing to check (`fs`, or anything
+ *  this package doesn't know about) reports `'other'` — a literal, not the resolved id, so the
+ *  union stays a real discriminated union (a plain `string` member would swallow the other
+ *  branches on narrowing) — callers that branch on `backend` never needed the id anyway. */
+export type StorageReadinessReport = {
+    backend: 'arweave';
+    overCount: number;
+    totalCount: number;
+    totalKb: number;
+    usd: number | null;
+} | {
+    backend: 'ipfs';
+    pinataMissingJwt: boolean;
+} | {
+    backend: 'cloud';
+    missingPublicBase: boolean;
+} | {
+    backend: 'other';
+};
+/**
+ * What a REAL deploy against `opts` needs, from `sizes` (per-file byte sizes) alone — Arweave
+ * credit needs (plus a best-effort USD estimate for the chargeable bytes), a missing Pinata JWT, or
+ * a missing cloud public base. The one network call (Turbo's price API) is best-effort: a failure
+ * there degrades `usd` to `null` rather than failing the whole check.
+ */
+export declare function assessStorageReadiness(opts: ResolveStorageOptions, sizes: number[]): Promise<StorageReadinessReport>;
+export interface TurboFundsCheck {
+    /** True when the resolved identity does NOT have enough prepaid credits for `sizes`. */
+    short: boolean;
+    address: string;
+    /** Whether the identity is an EVM one (`.env` key or a remote wallet) rather than the CLI-managed
+     *  Arweave key — decides which recovery message applies. */
+    isEth: boolean;
+    haveWinc: number;
+    needWinc: number;
+    /** How many of `sizes` are over the free tier (what this shortfall is actually for). */
+    chargeableCount: number;
+    /** Set only when checked (short, a non-eth identity, and a wallet address was given): the
+     *  creator's OWN wallet's Turbo balance, queryable by address with no key — so "spend those
+     *  instead of topping up again" can be recommended before ever proposing a top-up. Null if that
+     *  wallet has never had a Turbo balance. */
+    walletCredits?: {
+        winc: number;
+        credits: string;
+    } | null;
+}
+/**
+ * The pre-upload funds decision for a Turbo (Arweave) upload of `sizes` (per-file byte sizes):
+ * chargeable bytes → the Winston cost → compare against the identity's prepaid balance. `cfg` must
+ * already have a resolved identity (`jwk`/`ethSignerKey`/`remoteEth`) — this module only
+ * INTERROGATES the resolved provider, never mints one (see the module doc). Returns `null` when
+ * nothing is chargeable (every file is free) or the provider can't be reached right now — a
+ * best-effort check never false-blocks; the upload itself will surface any real error.
+ */
+export declare function assessTurboFunds(cfg: ArweaveConfig, sizes: number[], walletAddr?: string): Promise<TurboFundsCheck | null>;
+//# sourceMappingURL=upload-readiness.d.ts.map

package/dist/upload-readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-readiness.d.ts","sourceRoot":"","sources":["../src/upload-readiness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,cAAc,CAAC;AACxD,OAAO,EAAyG,KAAK,aAAa,EAAC,MAAM,cAAc,CAAC;AAExJ;;;;;;;;;;;;;;;GAeG;AAEH;;0FAE0F;AAC1F,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAEnE;AAED,MAAM,WAAW,eAAe;IAC9B,8FAA8F;IAC9F,UAAU,EAAE,OAAO,CAAC;IACpB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;2BAE2B;AAC3B,wBAAgB,eAAe,CAAC,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAGjG;AAED;;;;4FAI4F;AAC5F,MAAM,MAAM,sBAAsB,GAC9B;IAAC,OAAO,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAC,GAChG;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,OAAO,CAAA;CAAC,GAC5C;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,iBAAiB,EAAE,OAAO,CAAA;CAAC,GAC9C;IAAC,OAAO,EAAE,OAAO,CAAA;CAAC,CAAC;AAEvB;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,qBAAqB,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAc1H;AAED,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;gEAC4D;IAC5D,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,eAAe,EAAE,MAAM,CAAC;IACxB;;;gDAG4C;IAC5C,aAAa,CAAC,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,GAAG,IAAI,CAAC;CACxD;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAuBhI"}

package/dist/upload-readiness.js

@@ -0,0 +1,85 @@
+import { ARWEAVE_FREE_UPLOAD_LIMIT, arweaveFunding, turboBalanceForAddress, turboUploadCostUsd, turboUploadWinc } from './arweave.js';
+/**
+ * Deploy-time storage readiness — what a REAL upload needs, decided from local facts (and, for the
+ * best-effort USD estimate, one price-API call) so "dry-run passes, then the real deploy fails at
+ * upload" can't happen. Three questions, each pure aside from the one noted network call:
+ *
+ *  - {@link planTurboUpload} — is THIS ONE file free (Turbo's 100 KiB tier) or chargeable?
+ *  - {@link assessStorageReadiness} — across every backend, what does a real upload of `sizes` need
+ *    (Arweave credits, a Pinata JWT, a cloud public base)?
+ *  - {@link assessTurboFunds} — does the resolved Turbo identity have ENOUGH prepaid credits for
+ *    `sizes`, and (when it's short) does the creator's own wallet already hold some?
+ *
+ * None of this mints or spends anything — it only INTERROGATES the resolved provider. Identity
+ * creation is the caller's job (the CLI's managed-key flow owns the key file location; see
+ * `arweave-identity.ts` / `ArweaveConfig.ensureJwk`), so `assessTurboFunds` expects a config that
+ * already has one.
+ */
+/** Whether `opts` resolves to Arweave via the Turbo (prepaid-credits) provider — the only provider
+ *  with a free tier and a funds balance to check; `http-bundler` skips every readiness/funds
+ *  question below (it has its own auth, not a balance this package knows how to read). */
+export function isTurboArweave(opts) {
+    return opts.backend === 'arweave' && (opts.arweave?.provider ?? 'turbo') === 'turbo';
+}
+/** The free-vs-credit decision for ONE Turbo upload of `size` bytes — from the local byte size
+ *  alone, so it works under `--dry-run` too. Null when `opts` doesn't resolve to Turbo-Arweave
+ *  (nothing to decide). */
+export function planTurboUpload(opts, size) {
+    if (!isTurboArweave(opts))
+        return null;
+    return { chargeable: size >= ARWEAVE_FREE_UPLOAD_LIMIT, sizeKb: (size / 1024).toFixed(1) };
+}
+/**
+ * What a REAL deploy against `opts` needs, from `sizes` (per-file byte sizes) alone — Arweave
+ * credit needs (plus a best-effort USD estimate for the chargeable bytes), a missing Pinata JWT, or
+ * a missing cloud public base. The one network call (Turbo's price API) is best-effort: a failure
+ * there degrades `usd` to `null` rather than failing the whole check.
+ */
+export async function assessStorageReadiness(opts, sizes) {
+    if (opts.backend === 'arweave') {
+        const chargeable = sizes.filter((s) => s >= ARWEAVE_FREE_UPLOAD_LIMIT);
+        const usd = chargeable.length ? await turboUploadCostUsd(chargeable.reduce((a, b) => a + b, 0)) : null;
+        const totalKb = Math.round(sizes.reduce((a, b) => a + b, 0) / 1024);
+        return { backend: 'arweave', overCount: chargeable.length, totalCount: sizes.length, totalKb, usd };
+    }
+    if (opts.backend === 'ipfs') {
+        return { backend: 'ipfs', pinataMissingJwt: (opts.ipfs?.mode ?? 'pinata') === 'pinata' && !opts.ipfs?.pinataJwt };
+    }
+    if (opts.backend === 'cloud') {
+        return { backend: 'cloud', missingPublicBase: !opts.cloud?.publicBase };
+    }
+    return { backend: 'other' };
+}
+/**
+ * The pre-upload funds decision for a Turbo (Arweave) upload of `sizes` (per-file byte sizes):
+ * chargeable bytes → the Winston cost → compare against the identity's prepaid balance. `cfg` must
+ * already have a resolved identity (`jwk`/`ethSignerKey`/`remoteEth`) — this module only
+ * INTERROGATES the resolved provider, never mints one (see the module doc). Returns `null` when
+ * nothing is chargeable (every file is free) or the provider can't be reached right now — a
+ * best-effort check never false-blocks; the upload itself will surface any real error.
+ */
+export async function assessTurboFunds(cfg, sizes, walletAddr) {
+    const chargeable = sizes.filter((s) => s >= ARWEAVE_FREE_UPLOAD_LIMIT);
+    if (chargeable.length === 0)
+        return null; // all free
+    const funding = await arweaveFunding(cfg);
+    let address;
+    let haveWinc;
+    try {
+        address = await funding.address();
+        haveWinc = Number((await funding.balance()).winc) || 0;
+    }
+    catch {
+        return null; // can't reach Turbo to check — don't false-block; the upload will surface any real error
+    }
+    const needWinc = (await turboUploadWinc(chargeable.reduce((a, b) => a + b, 0))) ?? 0;
+    const short = needWinc > 0 ? haveWinc < needWinc : haveWinc <= 0;
+    const isEth = !!(cfg.ethSignerKey || cfg.remoteEth);
+    let walletCredits;
+    if (short && !isEth && walletAddr) {
+        const wb = await turboBalanceForAddress(walletAddr, 'ethereum');
+        walletCredits = wb ? { winc: Number(wb.winc) || 0, credits: wb.credits } : null;
+    }
+    return { short, address, isEth, haveWinc, needWinc, chargeableCount: chargeable.length, walletCredits };
+}
+//# sourceMappingURL=upload-readiness.js.map

package/dist/upload-readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-readiness.js","sourceRoot":"","sources":["../src/upload-readiness.ts"],"names":[],"mappings":"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"}

package/dist/upload.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `abx storage upload` core — upload ONE file and return a public locator that PRESERVES the
+ * filename, so the declared mimeType survives when the locator is later attached (`abx attach`).
+ * The on-chain metadata field has no MIME slot: the URL extension IS the type declaration, so a
+ * bare content-addressed locator (`ar://<txid>`, `<gw>/ipfs/<cid>`) — which has no extension —
+ * would make the attached artifact `application/octet-stream`. Extracted from main.ts so the
+ * capability-based branch (the exact bug this guards) is unit-testable with fake backends.
+ */
+import type { StorageBackend, StoredContent } from './backend.js';
+export interface UploadResult {
+    /** A fetchable public URL for the file. */
+    locator: string;
+    /** True when `locator` carries the filename (extension → correct declared type on attach). */
+    filenamePreserved: boolean;
+    /** Set when we had to fall back to a bare (extension-less) locator — the caller warns. */
+    fallbackReason?: string;
+}
+/**
+ * Store `content` under `name` and return the best available public locator. Preference order:
+ *  1. path-addressed host (cloud/S3/R2): the object key IS the filename → `<publicBase>/<name>`.
+ *  2. content-addressed host with directory support (ipfs/arweave): wrap the single file in a
+ *     one-entry directory → `<base>/<name>` (filename preserved).
+ *  3. bare content-addressed locator (e.g. kubo IPFS with no dir-add): `<gw>/ipfs/<cid>` — no
+ *     extension; `filenamePreserved: false` so the caller can warn about the octet-stream type.
+ * Throws for a backend that can't produce any public URL (e.g. `fs`).
+ */
+export declare function uploadAndLocate(backend: StorageBackend, name: string, content: StoredContent): Promise<UploadResult>;
+//# sourceMappingURL=upload.d.ts.map

package/dist/upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../src/upload.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAC,cAAc,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAGhE,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,iBAAiB,EAAE,OAAO,CAAC;IAC3B,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAyB1H"}

package/dist/upload.js

@@ -0,0 +1,41 @@
+import { hashContent } from './backend.js';
+const trimSlash = (s) => s.replace(/\/+$/, '');
+/**
+ * Store `content` under `name` and return the best available public locator. Preference order:
+ *  1. path-addressed host (cloud/S3/R2): the object key IS the filename → `<publicBase>/<name>`.
+ *  2. content-addressed host with directory support (ipfs/arweave): wrap the single file in a
+ *     one-entry directory → `<base>/<name>` (filename preserved).
+ *  3. bare content-addressed locator (e.g. kubo IPFS with no dir-add): `<gw>/ipfs/<cid>` — no
+ *     extension; `filenamePreserved: false` so the caller can warn about the octet-stream type.
+ * Throws for a backend that can't produce any public URL (e.g. `fs`).
+ */
+export async function uploadAndLocate(backend, name, content) {
+    if (backend.publicBase && backend.putObject) {
+        await backend.putObject(name, content);
+        return { locator: `${trimSlash(backend.publicBase)}/${name}`, filenamePreserved: true };
+    }
+    if (backend.putDirectory && backend.locator) {
+        try {
+            const { base } = await backend.putDirectory([{ name, bytes: content.bytes, contentType: content.contentType }]);
+            return { locator: `${trimSlash(base)}/${name}`, filenamePreserved: true };
+        }
+        catch (e) {
+            const hash = hashContent(content.bytes);
+            await backend.put(hash, content);
+            const loc = await backend.locator(hash);
+            if (!loc)
+                throw e;
+            return { locator: loc, filenamePreserved: false, fallbackReason: e.message };
+        }
+    }
+    if (backend.locator) {
+        const hash = hashContent(content.bytes);
+        await backend.put(hash, content);
+        const loc = await backend.locator(hash);
+        if (!loc)
+            throw new Error(`backend '${backend.id}' stored the file but returned no durable locator`);
+        return { locator: loc, filenamePreserved: false };
+    }
+    throw new Error(`backend '${backend.id}' can't produce a public URL for an attached file — use ipfs, arweave, or cloud (with a public base).`);
+}
+//# sourceMappingURL=upload.js.map

package/dist/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../src/upload.ts"],"names":[],"mappings":"AASA,OAAO,EAAC,WAAW,EAAC,MAAM,cAAc,CAAC;AAWzC,MAAM,SAAS,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAuB,EAAE,IAAY,EAAE,OAAsB;IACjG,IAAI,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QAC5C,MAAM,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACvC,OAAO,EAAC,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,IAAI,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAC,CAAC;IACxF,CAAC;IACD,IAAI,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAC5C,IAAI,CAAC;YACH,MAAM,EAAC,IAAI,EAAC,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,EAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAC,CAAC,CAAC,CAAC;YAC5G,OAAO,EAAC,OAAO,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAC,CAAC;QAC1E,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACxC,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACjC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACxC,IAAI,CAAC,GAAG;gBAAE,MAAM,CAAC,CAAC;YAClB,OAAO,EAAC,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAE,cAAc,EAAG,CAAW,CAAC,OAAO,EAAC,CAAC;QACxF,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACxC,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACjC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,YAAY,OAAO,CAAC,EAAE,mDAAmD,CAAC,CAAC;QACrG,OAAO,EAAC,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAC,CAAC;IAClD,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,YAAY,OAAO,CAAC,EAAE,uGAAuG,CAAC,CAAC;AACjJ,CAAC"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@artblocks/abx-storage",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0",
   "license": "MIT",
-  "description": "ABX Self-Host Toolkit (Layer 3) — the reference byte-custody / storage service. Holds the source-of-truth bytes a token's content commitment points at, content-addressed by hash, behind a pluggable backend interface.",
+  "description": "Storage adapters for ABX content using filesystem, S3-compatible, IPFS, or Arweave backends.",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -13,18 +13,19 @@
   },
   "files": [
     "dist",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=22.13.0"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ArtBlocks/abx.git",
     "directory": "packages/storage"
   },
-  "homepage": "https://github.com/ArtBlocks/abx#readme",
+  "homepage": "https://docs.abx.io",
   "bugs": "https://github.com/ArtBlocks/abx/issues",
   "keywords": [
     "abx",
@@ -38,12 +39,19 @@
     "access": "public"
   },
   "dependencies": {
-    "viem": "^2.21.0",
-    "@artblocks/abx-sdk": "0.1.0-alpha.8"
+    "viem": "^2.56.5",
+    "@artblocks/abx-sdk": "0.1.0"
   },
-  "optionalDependencies": {
-    "@ardrive/turbo-sdk": "^1.23.0",
-    "@dha-team/arbundles": "^1.0.4"
+  "peerDependencies": {
+    "@artblocks/abx-storage-arweave": ">=0.1.0-alpha.0"
+  },
+  "peerDependenciesMeta": {
+    "@artblocks/abx-storage-arweave": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@artblocks/abx-storage-arweave": "0.1.0"
   },
   "scripts": {
     "build": "tsc -b tsconfig.build.json"