@needmoretruth/nmts-sdk 0.1.1

package/dist/env.d.ts

@@ -0,0 +1,15 @@
+import type { Credentials } from "./root.ts";
+/** Where each credential was found. Reported, never the value. */
+export type FoundIn = "file" | "variable";
+export interface FromEnvironment {
+    credentials: Credentials;
+    accountCodeFrom: FoundIn;
+    apiKeyFrom: FoundIn;
+}
+/**
+ * The two credentials from the environment, or a refusal naming the variable that was missing.
+ *
+ * ⛔ THE REFUSAL NEVER CONTAINS A VALUE. It names variables; the caller's log is not a place a
+ *    credential should be able to reach.
+ */
+export declare function credentialsFromEnvironment(): FromEnvironment;

package/dist/env.js

@@ -0,0 +1,42 @@
+// The one place this package reads the environment — and only when `Nmts.fromEnv()` asks.
+//
+// ⛔ THE SAME VARIABLE NAMES AS THE COMMAND-LINE TOOL, in the same order of preference, so a
+//    machine set up for `nmts` is set up for this package, and a container recipe written for one
+//    works for the other. A file named by `*_FILE` wins over a value in the variable itself,
+//    because a variable holding a path shows a reader a filename and a variable holding the value
+//    shows them the value (`docker inspect` prints the whole environment).
+//
+// ⚠ THE COMMAND-LINE TOOL STOPS ONCE FOR AN AGREEMENT before it will read the account code out of
+//   `NMTS_ACCOUNT_CODE`; this package does not, because it cannot: there is no terminal and no
+//   person on the other end of a library call. Choosing `fromEnv()` is that agreement. The README
+//   says so where the variables are explained, and says why the file form is the better one.
+import { API_KEY_ENV_VAR, API_KEY_FILE_ENV_VAR, CODE_ENV_VAR, CODE_FILE_ENV_VAR, NmtsError, readSecretFile, } from "@needmoretruth/nmts-cli";
+function fromFileOrVariable(fileVariable, valueVariable, what) {
+    const fromFile = readSecretFile(fileVariable);
+    if (fromFile !== null)
+        return { value: fromFile, from: "file" };
+    const fromVariable = process.env[valueVariable];
+    if (fromVariable !== undefined && fromVariable.length > 0) {
+        return { value: fromVariable, from: "variable" };
+    }
+    throw new NmtsError(`No ${what} in the environment.`, {
+        exitCode: 3,
+        nextStep: `Set ${fileVariable} to a file holding it (preferred), or ${valueVariable} to the value. ` +
+            `Or pass it to the constructor and do not use fromEnv().`,
+    });
+}
+/**
+ * The two credentials from the environment, or a refusal naming the variable that was missing.
+ *
+ * ⛔ THE REFUSAL NEVER CONTAINS A VALUE. It names variables; the caller's log is not a place a
+ *    credential should be able to reach.
+ */
+export function credentialsFromEnvironment() {
+    const code = fromFileOrVariable(CODE_FILE_ENV_VAR, CODE_ENV_VAR, "account code");
+    const key = fromFileOrVariable(API_KEY_FILE_ENV_VAR, API_KEY_ENV_VAR, "API key");
+    return {
+        credentials: { accountCode: code.value, apiKey: key.value },
+        accountCodeFrom: code.from,
+        apiKeyFrom: key.from,
+    };
+}

package/dist/get.d.ts

@@ -0,0 +1,35 @@
+import { type PlaintextSink, type ReadOptions } from "@needmoretruth/nmts-cli";
+import { type Held, type Opened } from "./session.ts";
+/** How big a file `get()` will hold in memory unless told otherwise: 256 MiB. */
+export declare const DEFAULT_IN_MEMORY_LIMIT: number;
+export interface GetResult {
+    /** The path as it was looked up. */
+    path: string;
+    /** How many plaintext bytes were delivered — the file's real length. */
+    bytes: number;
+    /** How many stored objects it came from. */
+    parts: number;
+    /**
+     * Whether the account had sealed a whole-file hash and it matched.
+     *
+     * ⚠ False is not a failure: it means there was nothing to check against. Every part still
+     *   opened under this account's key.
+     */
+    contentHashChecked: boolean;
+}
+/**
+ * A sink that keeps the file in memory and hands it over once, after it is proved.
+ *
+ * ⛔ IT COPIES. The caller of `write` zeroes each run of plaintext as soon as the call resolves,
+ *    so a sink that kept the reference would hold zeroes.
+ */
+export declare function bytesSink(limit: number): {
+    sink: PlaintextSink;
+    take(): Uint8Array;
+};
+/** Find the file the path names and fetch it into the sink. The sink decides what "delivered" means. */
+export declare function fetchInto(held: Held, path: string, sink: PlaintextSink, read: ReadOptions | undefined): Promise<GetResult>;
+/** The whole file, in memory, or a refusal. */
+export declare function getBytes(opened: Opened, path: string, limit: number, read: ReadOptions | undefined): Promise<Uint8Array>;
+/** The file written to `destination`, through a temporary name, visible only once it is proved. */
+export declare function getToFile(opened: Opened, path: string, destination: string, force: boolean, read: ReadOptions | undefined): Promise<GetResult>;

package/dist/get.js

@@ -0,0 +1,116 @@
+// One file back out: fetched from the storage network, opened here, checked, then handed over.
+//
+// ⛔ IT REFUSES RATHER THAN RETURNS A HALF-RIGHT FILE. A wrong key, a part that will not open,
+//    parts that do not add up, a whole-file hash that does not match — none of them produce
+//    bytes. That promise is kept by the sink: the bytes are delivered only on `commit`, after the
+//    whole file has been checked, and `abandon` leaves nothing behind. The command-line tool keeps
+//    the same promise with a temporary file and a rename; `fileSink` here is that same code.
+//
+// ⛔ THE IN-MEMORY FORM HAS A CEILING AND SAYS SO. `get()` returns a `Uint8Array`, which means the
+//    whole file is in this process at once. A file that would not fit is refused before a byte is
+//    fetched, and the refusal names `getTo()`, which streams to disk and has no ceiling.
+import { entryAt, fetchFile, fileSink, KIND_FILE, NmtsError, } from "@needmoretruth/nmts-cli";
+import { readList } from "./list.js";
+import { withAccount } from "./session.js";
+/** How big a file `get()` will hold in memory unless told otherwise: 256 MiB. */
+export const DEFAULT_IN_MEMORY_LIMIT = 256 * 2 ** 20;
+/**
+ * A sink that keeps the file in memory and hands it over once, after it is proved.
+ *
+ * ⛔ IT COPIES. The caller of `write` zeroes each run of plaintext as soon as the call resolves,
+ *    so a sink that kept the reference would hold zeroes.
+ */
+export function bytesSink(limit) {
+    let buffer = null;
+    let at = 0;
+    let proved = false;
+    return {
+        sink: {
+            expect(size) {
+                if (size > limit) {
+                    throw new NmtsError(`This file is ${size} bytes, over the ${limit}-byte limit for holding it in memory.`, {
+                        exitCode: 4,
+                        nextStep: "Nothing was fetched. Use getTo(path, destination) to stream it to a file, or raise `maxBytes`.",
+                    });
+                }
+                buffer = new Uint8Array(size);
+                at = 0;
+            },
+            async write(bytes) {
+                if (buffer === null)
+                    throw new NmtsError("The sink was written before it was told the size.");
+                if (at + bytes.length > buffer.length) {
+                    throw new NmtsError(`The file produced more bytes (${at + bytes.length}) than its list entry says (${buffer.length}).`);
+                }
+                buffer.set(bytes, at);
+                at += bytes.length;
+            },
+            async commit() {
+                proved = true;
+                return true;
+            },
+            async abandon() {
+                buffer?.fill(0);
+                buffer = null;
+                at = 0;
+            },
+        },
+        take() {
+            if (!proved || buffer === null)
+                throw new NmtsError("The file was not proved, so there is nothing to hand over.");
+            const out = buffer;
+            buffer = null;
+            return out;
+        },
+    };
+}
+/** Find the file the path names and fetch it into the sink. The sink decides what "delivered" means. */
+export async function fetchInto(held, path, sink, read) {
+    const { entries } = await readList(held);
+    if (entries.length === 0) {
+        throw new NmtsError("This account has no file list, so there is nothing to get.", { exitCode: 4 });
+    }
+    const entry = entryAt(entries, path, { nothingHappened: "Nothing was fetched." });
+    if (entry.kind !== KIND_FILE) {
+        throw new NmtsError(`"${path}" is a folder.`, {
+            exitCode: 4,
+            nextStep: "Nothing was fetched. get() takes one file at a time; list() shows what is in the folder.",
+        });
+    }
+    if (entry.dekWrapped === undefined) {
+        throw new NmtsError(`The file list holds no key for "${path}".`, {
+            exitCode: 4,
+            nextStep: "Without it nothing can open the stored bytes. Open the account in a browser.",
+        });
+    }
+    const fetched = await fetchFile({
+        base: held.server,
+        apiKey: held.apiKey,
+        accountCode: held.code,
+        itemId: entry.id,
+        size: entry.size,
+        dekWrapped: entry.dekWrapped,
+        contentHashCt: entry.contentHashCt,
+        chain: held.network,
+        sink,
+        ...(read === undefined ? {} : { read }),
+    });
+    return {
+        path,
+        bytes: fetched.byteCount,
+        parts: fetched.partCount,
+        contentHashChecked: fetched.contentHashChecked,
+    };
+}
+/** The whole file, in memory, or a refusal. */
+export async function getBytes(opened, path, limit, read) {
+    return withAccount(opened, async (held) => {
+        const memory = bytesSink(limit);
+        await fetchInto(held, path, memory.sink, read);
+        return memory.take();
+    });
+}
+/** The file written to `destination`, through a temporary name, visible only once it is proved. */
+export async function getToFile(opened, path, destination, force, read) {
+    return withAccount(opened, async (held) => fetchInto(held, path, fileSink(destination, { force }), read));
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { Nmts } from "./nmts.ts";
+export type { AccountInfo, GetOptions, GetToOptions, NmtsOptions, WalletAddressOptions, } from "./nmts.ts";
+export { deviceRoot, managedRoot } from "./root.ts";
+export type { Credentials, Identity, ManagedCredentials, Root, RootMode } from "./root.ts";
+export type { Entry } from "./list.ts";
+export type { ActiveWallet, WalletInfo } from "./wallets.ts";
+export type { CreditsPut, CreditsReview, PutOptions, PutResult, PutReview, PutStorage, WalletPut, WalletReview, } from "./put.ts";
+export type { GetResult } from "./get.ts";
+export { NmtsError, ServerError, UploadError } from "@needmoretruth/nmts-cli";
+export type { FileUploadStep, ServerRefusal } from "@needmoretruth/nmts-cli";
+export { HOME_URL, SDK_NAME, SOURCE_URL, VERSION } from "./product.ts";

package/dist/index.js

@@ -0,0 +1,13 @@
+// `@needmoretruth/nmts-sdk` — what `import { Nmts } from "@needmoretruth/nmts-sdk"` hands you.
+//
+// One class, three verbs, and the two answers to "who holds the key". Everything else is a type, or
+// the error every failure arrives in.
+export { Nmts } from "./nmts.js";
+// Who holds the account's key. `Nmts.device()` and `Nmts.managed()` make these for you; the makers
+// are here for a program that builds its client from a root it was handed.
+export { deviceRoot, managedRoot } from "./root.js";
+// The failures. `NmtsError` carries `exitCode` and `nextStep` exactly as the command-line tool's
+// do, so a program can print the same sentence a person would have seen; `ServerError` is the
+// server's own refusal with its code; `UploadError` says whether money moved.
+export { NmtsError, ServerError, UploadError } from "@needmoretruth/nmts-cli";
+export { HOME_URL, SDK_NAME, SOURCE_URL, VERSION } from "./product.js";

package/dist/list.d.ts

@@ -0,0 +1,39 @@
+import { type ManifestEntry, type PaddingRule } from "@needmoretruth/nmts-cli";
+import { type Held, type Opened } from "./session.ts";
+/** One thing in the account. */
+export interface Entry {
+    /** The server's id for a file; a client-made id for a folder. Stable for the entry's life. */
+    id: string;
+    /** Full path from the top of the account, `photos/2026/cat.jpg`. Folders end without a slash. */
+    path: string;
+    kind: "file" | "folder";
+    /** Plaintext bytes. 0 for a folder. */
+    size: number;
+    /** ISO 8601, UTC. */
+    createdAt: string;
+    /** ISO 8601, UTC. */
+    updatedAt: string;
+}
+/** The opened list: its entries, and the settings an upload needs from it. */
+export interface OpenedList {
+    /** Empty for a new account that has no list yet — not an error. */
+    entries: readonly ManifestEntry[];
+    /**
+     * How coarsely a file's last part is rounded before sealing — the account's choice, made in the
+     * browser. An upload that rounded differently would say which program made it.
+     */
+    padding: PaddingRule;
+    /**
+     * Which of this key's wallets pays, by index — the account's own number.
+     *
+     * ⛔ IT COMES OUT OF THIS READ AND NOT A SECOND ONE, the way the command-line tool takes it. A
+     *    wallet-paid upload prices the wallet it is about to sign with, so the number that was priced
+     *    and the number that signs have to come from one answer.
+     */
+    activeWallet: number;
+}
+/** Read the sealed list and open it. */
+export declare function readList(held: Held): Promise<OpenedList>;
+/** Every live entry, as a path, sorted so a folder comes before what is in it. */
+export declare function toEntries(entries: readonly ManifestEntry[]): Entry[];
+export declare function listEntries(opened: Opened): Promise<Entry[]>;

package/dist/list.js

@@ -0,0 +1,35 @@
+// The account's files and folders, as paths.
+//
+// ⛔ THE LIST IS OPENED HERE, ON THIS MACHINE. The server holds it sealed and cannot read a name in
+//    it; the account code is what opens it, which is why `list()` needs the code and not just the
+//    key. What comes back is every live entry with its full path — the trash is left out, the same
+//    way `nmts ls` leaves it out unless asked.
+import { activeWalletOf, buildIndex, fullPathOf, isLive, KIND_FOLDER, readFileList, } from "@needmoretruth/nmts-cli";
+import { withAccount } from "./session.js";
+/** Read the sealed list and open it. */
+export async function readList(held) {
+    const list = await readFileList(held.server, held.apiKey, held.code, held.accountId);
+    return {
+        entries: list.manifest?.entries ?? [],
+        padding: list.manifest?.settings?.paddingMode === "pow2" ? "pow2" : "padme",
+        activeWallet: activeWalletOf(list.manifest?.settings),
+    };
+}
+/** Every live entry, as a path, sorted so a folder comes before what is in it. */
+export function toEntries(entries) {
+    const index = buildIndex(entries);
+    return entries
+        .filter((e) => isLive(index, e))
+        .map((e) => ({
+        id: e.id,
+        path: fullPathOf(index, e),
+        kind: e.kind === KIND_FOLDER ? "folder" : "file",
+        size: e.size,
+        createdAt: new Date(e.createdAt).toISOString(),
+        updatedAt: new Date(e.updatedAt).toISOString(),
+    }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+export async function listEntries(opened) {
+    return withAccount(opened, async (held) => toEntries((await readList(held)).entries));
+}

package/dist/nmts.d.ts

@@ -0,0 +1,103 @@
+import { type Network } from "@needmoretruth/nmts-cli";
+import { type GetResult } from "./get.ts";
+import { type Entry } from "./list.ts";
+import { type PutOptions, type PutResult, type PutReview } from "./put.ts";
+import { type Credentials, type ManagedCredentials, type Root } from "./root.ts";
+import { type ServerOptions } from "./session.ts";
+import { type ActiveWallet, type WalletInfo } from "./wallets.ts";
+export interface NmtsOptions extends ServerOptions {
+    /**
+     * Hosts to read stored bytes from, instead of the public aggregators for the network. For a
+     * development stack, or an aggregator you run yourself.
+     */
+    aggregators?: readonly string[] | undefined;
+}
+export interface GetOptions {
+    /** How many bytes `get()` may hold in memory. Default 256 MiB. Over it, use `getTo()`. */
+    maxBytes?: number | undefined;
+}
+export interface GetToOptions {
+    /** Replace a file already at the destination. Off by default, and saying so is the point. */
+    force?: boolean | undefined;
+}
+export interface WalletAddressOptions {
+    /** Which of this key's wallets. Absent = the one the account pays from. */
+    index?: number | undefined;
+}
+export interface AccountInfo {
+    /** The account's public id — what the server knows it by. Not a secret. */
+    accountId: string;
+    server: string;
+    network: Network;
+}
+export declare class Nmts {
+    #private;
+    constructor(root: Root, options?: NmtsOptions);
+    /** The key is in THIS process: a browser, an app, a game client, your own program. */
+    static device(credentials: Credentials & NmtsOptions): Nmts;
+    /**
+     * The key is in YOUR store, sealed, and `openCode` opens it for one call at a time.
+     *
+     * What this means for the people whose files they are is in the README's first table: a business
+     * that holds the key can read the files. It is a choice, not a defect, and it is the caller's.
+     */
+    static managed(source: ManagedCredentials & NmtsOptions): Nmts;
+    /**
+     * A device client whose credentials come from the environment, the way the command-line tool
+     * finds them.
+     *
+     * `NMTS_ACCOUNT_CODE_FILE` and `NMTS_API_KEY_FILE` name files (preferred); `NMTS_ACCOUNT_CODE`
+     * and `NMTS_API_KEY` hold the values. `NMTS_SERVER` and `NMTS_NETWORK` are read by every call
+     * either way. Nothing is read until this is called.
+     */
+    static fromEnv(options?: NmtsOptions): Nmts;
+    /** Which account this is, on which server and network. Offline: derived from the code alone. */
+    account(): Promise<AccountInfo>;
+    /**
+     * The Sui address of one of the wallets the account code derives — where a developer who pays
+     * for storage from their own coins sends them. Nothing is signed.
+     *
+     * With no argument it is the wallet the account PAYS FROM, read out of the sealed file list;
+     * when that cannot be read this throws rather than answering the first wallet, because coins
+     * sent to an address nobody chose are coins the account cannot spend. `{ index }` names one
+     * directly and is offline — numbers come from the key, so every one of them already exists.
+     */
+    walletAddress(options?: WalletAddressOptions): Promise<string>;
+    /**
+     * Every wallet this account has — the ones it has made, and any further out that a chain says
+     * have been used — with the one that pays marked. Nothing is spent and nothing is written.
+     */
+    wallets(): Promise<WalletInfo[]>;
+    /**
+     * Say which of this key's wallets pays for storage from now on.
+     *
+     * It is the ACCOUNT's choice and not this machine's: the number rides inside the sealed file
+     * list, so every device and every program on this account pays from the same address afterwards.
+     * Nothing is created or deleted — every number a key can derive already exists.
+     */
+    setActiveWallet(index: number): Promise<ActiveWallet>;
+    /** Every live file and folder, as paths. Nothing is spent. */
+    list(): Promise<Entry[]>;
+    /**
+     * Upload one file. **This spends.** By default it spends credits — one per started MiB of
+     * sealed bytes, for the storage period the account buys uploads for. With `pay: "wallet"` it
+     * spends WAL and SUI out of the wallet the account pays from instead — `wallet: n` names another
+     * of this key's wallets for this one upload — for as many of the storage network's epochs as
+     * `epochs` asks for. Neither comes back, and calling this is the agreement to that;
+     * `dryRun: true` says what it would cost and spends nothing.
+     *
+     * A path names a file on this machine; bytes need a `name`. A name already in use is numbered,
+     * `report (2).pdf`, unless the machine's `nmts on-collision` setting says overwrite.
+     */
+    put(file: string | Uint8Array, options: PutOptions & {
+        dryRun: true;
+    }): Promise<PutReview>;
+    put(file: string | Uint8Array, options?: PutOptions): Promise<PutResult>;
+    /** One file, whole and checked, in memory. Nothing is spent. */
+    get(path: string, options?: GetOptions): Promise<Uint8Array>;
+    /**
+     * One file, streamed to `destination` and made visible only once it is checked. No size
+     * ceiling. Refuses to overwrite unless `force` says so.
+     */
+    getTo(path: string, destination: string, options?: GetToOptions): Promise<GetResult>;
+}

package/dist/nmts.js

@@ -0,0 +1,157 @@
+// `Nmts` — one account, opened once, with the three things a program does with storage.
+//
+// ⛔ THE ROOT IS THE FIRST ARGUMENT BECAUSE IT IS THE ONE DECISION THAT MATTERS. Who holds the
+//    account's key — this process, or a business's sealed store — is answered once, where the
+//    client is made, and every method below reads the same whichever answer it was. That is the
+//    whole of how this package keeps the rule that a verb must work the same for both; the two
+//    convenience makers are named after the two answers so the choice cannot be made by accident.
+//
+// ⛔ THE CONSTRUCTOR DOES NO WORK. It keeps the root and the options and nothing else happens
+//    until the first call, so making one is free, making one with a bad code fails on the first
+//    call rather than in a constructor that cannot be awaited, and a server that is down is a
+//    failure of the call that needed it.
+//
+// ⛔ EVERY METHOD IS THE COMMAND-LINE TOOL'S CODE with the terminal taken off. `list` is `nmts ls`,
+//    `put` is `nmts put`, `get` is `nmts get`. Where this file decides something the tool decides
+//    by asking a person — spending, reading a code from the environment — the decision is the
+//    caller's, made by calling the method, and the README says so at the top.
+import { createBlobProtocol, createUploadApi, fileSource, measureLocal, readCurrentEpoch, walletAddress, } from "@needmoretruth/nmts-cli";
+import { credentialsFromEnvironment } from "./env.js";
+import { DEFAULT_IN_MEMORY_LIMIT, getBytes, getToFile } from "./get.js";
+import { listEntries } from "./list.js";
+import { bytesSource, nameOf, putSource, } from "./put.js";
+import { putSourceWithWallet } from "./put-wallet.js";
+import { deviceRoot, managedRoot } from "./root.js";
+import { openAccount, withAccount } from "./session.js";
+import { payingWallet, requireWalletIndex, setActiveWallet, wallets, } from "./wallets.js";
+/**
+ * The three fields that say where to talk, taken off a convenience maker's one object.
+ *
+ * ⛔ SO THAT NO CREDENTIAL IS COPIED ONTO THE CLIENT. `Nmts.device({ accountCode, … })` takes one
+ *    flat object because that is what is pleasant to write; what the client keeps out of it is
+ *    these three, and the code goes to the root and nowhere else.
+ */
+function optionsOf(from) {
+    return { server: from.server, network: from.network, aggregators: from.aggregators };
+}
+export class Nmts {
+    #root;
+    #options;
+    #opened = null;
+    constructor(root, options = {}) {
+        this.#root = root;
+        this.#options = { ...options };
+    }
+    /** The key is in THIS process: a browser, an app, a game client, your own program. */
+    static device(credentials) {
+        return new Nmts(deviceRoot(credentials), optionsOf(credentials));
+    }
+    /**
+     * The key is in YOUR store, sealed, and `openCode` opens it for one call at a time.
+     *
+     * What this means for the people whose files they are is in the README's first table: a business
+     * that holds the key can read the files. It is a choice, not a defect, and it is the caller's.
+     */
+    static managed(source) {
+        return new Nmts(managedRoot(source), optionsOf(source));
+    }
+    /**
+     * A device client whose credentials come from the environment, the way the command-line tool
+     * finds them.
+     *
+     * `NMTS_ACCOUNT_CODE_FILE` and `NMTS_API_KEY_FILE` name files (preferred); `NMTS_ACCOUNT_CODE`
+     * and `NMTS_API_KEY` hold the values. `NMTS_SERVER` and `NMTS_NETWORK` are read by every call
+     * either way. Nothing is read until this is called.
+     */
+    static fromEnv(options = {}) {
+        const found = credentialsFromEnvironment();
+        return Nmts.device({ ...options, ...found.credentials });
+    }
+    // A failed open is not kept: the assignment never happens, so the next call tries again.
+    #account() {
+        this.#opened ??= openAccount(this.#root, this.#options);
+        return this.#opened;
+    }
+    #read() {
+        const hosts = this.#options.aggregators;
+        return hosts === undefined || hosts.length === 0 ? undefined : { hosts };
+    }
+    /** Which account this is, on which server and network. Offline: derived from the code alone. */
+    async account() {
+        return withAccount(this.#account(), async (held) => ({
+            accountId: held.accountId,
+            server: held.server,
+            network: held.network,
+        }));
+    }
+    /**
+     * The Sui address of one of the wallets the account code derives — where a developer who pays
+     * for storage from their own coins sends them. Nothing is signed.
+     *
+     * With no argument it is the wallet the account PAYS FROM, read out of the sealed file list;
+     * when that cannot be read this throws rather than answering the first wallet, because coins
+     * sent to an address nobody chose are coins the account cannot spend. `{ index }` names one
+     * directly and is offline — numbers come from the key, so every one of them already exists.
+     */
+    async walletAddress(options = {}) {
+        const opened = this.#account();
+        const asked = options.index;
+        if (asked !== undefined) {
+            const index = requireWalletIndex(asked);
+            return opened.root.withCode(async (code) => walletAddress(code, index));
+        }
+        return withAccount(opened, async (held) => walletAddress(held.code, await payingWallet(held)));
+    }
+    /**
+     * Every wallet this account has — the ones it has made, and any further out that a chain says
+     * have been used — with the one that pays marked. Nothing is spent and nothing is written.
+     */
+    async wallets() {
+        return wallets(this.#account());
+    }
+    /**
+     * Say which of this key's wallets pays for storage from now on.
+     *
+     * It is the ACCOUNT's choice and not this machine's: the number rides inside the sealed file
+     * list, so every device and every program on this account pays from the same address afterwards.
+     * Nothing is created or deleted — every number a key can derive already exists.
+     */
+    async setActiveWallet(index) {
+        return setActiveWallet(this.#account(), index);
+    }
+    /** Every live file and folder, as paths. Nothing is spent. */
+    async list() {
+        return listEntries(this.#account());
+    }
+    async put(file, options = {}) {
+        const opened = this.#account();
+        const source = typeof file === "string" ? fileSource(file, measureLocal(file)) : bytesSource(file);
+        const name = options.name ?? (typeof file === "string" ? nameOf(file) : "");
+        // ⛔ WHICH MONEY IS DECIDED BEFORE ANYTHING IS READ, as the command-line tool decides it. The
+        //    credit rail below cannot price in WAL or sign a transaction, and it must not learn.
+        if (options.pay === "wallet")
+            return putSourceWithWallet(opened, source, name, options);
+        return putSource(opened, source, name, options, (sealedBytes) => this.#rail(opened, sealedBytes, options));
+    }
+    /** The credit-paid rail: the server sells the storage, the network's relay takes the bytes. */
+    async #rail(opened, sealedBytes, options) {
+        const protocol = createBlobProtocol(opened.network, sealedBytes, options.onProgress);
+        return {
+            api: createUploadApi(opened.server, opened.apiKey),
+            protocol,
+            relayUrl: protocol.relayUrl,
+            currentEpoch: await readCurrentEpoch(opened.network),
+        };
+    }
+    /** One file, whole and checked, in memory. Nothing is spent. */
+    async get(path, options = {}) {
+        return getBytes(this.#account(), path, options.maxBytes ?? DEFAULT_IN_MEMORY_LIMIT, this.#read());
+    }
+    /**
+     * One file, streamed to `destination` and made visible only once it is checked. No size
+     * ceiling. Refuses to overwrite unless `force` says so.
+     */
+    async getTo(path, destination, options = {}) {
+        return getToFile(this.#account(), path, destination, options.force === true, this.#read());
+    }
+}

package/dist/product.d.ts

@@ -0,0 +1,11 @@
+export declare const SDK_NAME = "@needmoretruth/nmts-sdk";
+/**
+ * The version this code says it is.
+ *
+ * ⛔ KEPT IN STEP WITH `package.json` BY HAND, for the same reason the command-line tool keeps two
+ *    copies: an installed package cannot read its own manifest from every place it may be loaded,
+ *    and a program that reports the wrong version makes every defect report about it untrustworthy.
+ */
+export declare const VERSION = "0.1.1";
+export declare const HOME_URL = "https://nmts.me";
+export declare const SOURCE_URL = "https://github.com/needmoretruth/nmts-sdk";

package/dist/product.js

@@ -0,0 +1,12 @@
+// What this package is. Pure constants, so anything may import them without loading the rest.
+export const SDK_NAME = "@needmoretruth/nmts-sdk";
+/**
+ * The version this code says it is.
+ *
+ * ⛔ KEPT IN STEP WITH `package.json` BY HAND, for the same reason the command-line tool keeps two
+ *    copies: an installed package cannot read its own manifest from every place it may be loaded,
+ *    and a program that reports the wrong version makes every defect report about it untrustworthy.
+ */
+export const VERSION = "0.1.1";
+export const HOME_URL = "https://nmts.me";
+export const SOURCE_URL = "https://github.com/needmoretruth/nmts-sdk";

package/dist/put-wallet.d.ts

@@ -0,0 +1,18 @@
+import { type PlaintextSource, type WalletPutSeams } from "@needmoretruth/nmts-cli";
+import { type PutOptions, type WalletPut, type WalletReview } from "./put.ts";
+import { type Opened } from "./session.ts";
+/**
+ * The chain, the signatures and the wire of this rail. ⚠ Seams, not options: no caller of `put()`
+ * reaches them, and a test hands in fakes exactly as it does for the credit rail.
+ */
+export type WalletSeams = Pick<WalletPutSeams, "readChain" | "sign" | "protocol" | "api">;
+/**
+ * Seal, buy with the account's OWN WALLET, push and record one file.
+ *
+ * ⛔ NOBODY IS ASKED, BECAUSE THERE IS NOBODY TO ASK. The command-line tool prints the review and
+ *    holds it against a standing wallet agreement; in a library the code that can spend is already
+ *    in this process and the caller wrote the call, so calling this IS the agreement — exactly as
+ *    the credit rail already says. What does not change is the order: the price, the balances and
+ *    a shortfall all come before the first signature.
+ */
+export declare function putSourceWithWallet(opened: Opened, source: PlaintextSource, name: string, options: PutOptions, seams?: WalletSeams): Promise<WalletPut | WalletReview>;