@needmoretruth/nmts-cli 0.17.2 → 0.34.2

package/dist/support-wire.js

@@ -0,0 +1,194 @@
+// Talking to the support routes, and reading what they answer.
+//
+// ⛔ SPLIT OUT OF THE COMMAND, AND THE LENGTH GATE IS THE HONEST REASON — but the line it was cut
+//    on means something: everything here is about the SERVER (its addresses, its limits, its
+//    refusals and the shapes it sends back), and everything left in `commands/support.ts` is
+//    about the person (what they are shown, what they are asked, what is printed).
+//
+// ⛔ THE SERVER'S LIMITS ARE MIRRORED, NOT GUESSED. A message too long is refused here rather than
+//    after a round trip, so the words somebody typed are still in their terminal when they are
+//    told. ⚠ A mirror goes stale: the server is the authority, and its 400 is passed through with
+//    the categories named beside it.
+//
+// ⛔ NOTHING HERE OPENS THE NMTS KEY. The API key is the whole credential these four routes
+//    need, so this resolves that and the server address and nothing else.
+import { request, ServerError } from "./api.js";
+import { readCredentialsFile } from "./credentials.js";
+import { NmtsError } from "./errors.js";
+import { isRecord } from "./guards.js";
+import { SHORTEST_OMIT } from "./redact.js";
+import { resolveServer } from "./server.js";
+import { requireApiKey } from "./session.js";
+import { categoryCodes, SUPPORT_CATEGORIES } from "./support-copy.js";
+/** The server's own ceilings on what one message may carry. */
+export const MAX_MESSAGE_CHARS = 4000;
+export const MAX_REPLY_CHARS = 8000;
+export function open(options) {
+    const apiKey = requireApiKey();
+    const stored = readCredentialsFile();
+    return { server: resolveServer(options.server ?? stored?.server), apiKey };
+}
+export async function call(wire, path, init) {
+    try {
+        return await request(wire.server, path, { token: wire.apiKey, ...init });
+    }
+    catch (error) {
+        throw translate(error);
+    }
+}
+/**
+ * The refusals this command has something to add to.
+ *
+ * ⛔ 409 KEEPS THE SERVER'S OWN SENTENCE. It means this exact message was already sent, and the
+ *    server is the half that knows why; a second wording here would be a guess at its reason.
+ *
+ * ⛔ A VALIDATION REFUSAL IS 400 AND NAMES ITS FIELD ("category: unknown", "message: too long").
+ *    It is a command-line mistake, so it gets the command-line exit code rather than the generic
+ *    one — and the category list is added only to the refusal that is about a category, because a
+ *    list of categories under "message: too long" would be an answer to a question nobody asked.
+ */
+function translate(error) {
+    if (!(error instanceof ServerError))
+        return error;
+    if (error.status === 429) {
+        const wait = error.retryAfter;
+        return new NmtsError(wait === null
+            ? error.message
+            : `NMTS is asking you to wait ${wait} seconds before another message.`, {
+            exitCode: 1,
+            nextStep: `Nothing was sent. This is a limit on how often, not a refusal of what was written.`,
+        });
+    }
+    if (error.status === 400 && error.code === "VALIDATION") {
+        return new NmtsError(error.message, {
+            exitCode: 2,
+            ...(error.message.startsWith("category")
+                ? { nextStep: `The categories are ${categoryCodes().join(" · ")}.` }
+                : {}),
+        });
+    }
+    // ⚠ The reports this rail lists are the ones FILED FROM IT. A ticket written in the browser, and
+    //   any other account's, are both 404 here — so the refusal points at the list rather than
+    //   suggesting the code was mistyped.
+    if (error.status === 404) {
+        return new NmtsError(error.message, {
+            exitCode: 4,
+            nextStep: `\`nmts support list\` prints the reports filed from the command line.`,
+        });
+    }
+    return error;
+}
+function unreadable() {
+    return new NmtsError("The server answered with a report this version cannot read.", {
+        nextStep: "A newer version of this tool may understand it.",
+    });
+}
+function text(value, fallback = "") {
+    return typeof value === "string" ? value : fallback;
+}
+function optional(value) {
+    return typeof value === "string" ? value : null;
+}
+export function asTicket(value) {
+    if (!isRecord(value))
+        throw unreadable();
+    const id = value["id"];
+    const code = value["code"];
+    if (typeof id !== "string" || typeof code !== "string")
+        throw unreadable();
+    const rows = value["messages"];
+    return {
+        id,
+        code,
+        category: text(value["category"], "other"),
+        subcategory: optional(value["subcategory"]),
+        message: text(value["message"]),
+        status: text(value["status"], "open"),
+        createdAt: text(value["created_at"]),
+        lastReadAt: optional(value["last_read_at"]),
+        messages: Array.isArray(rows) ? rows.filter(isRecord).map(asMessage) : null,
+    };
+}
+function asMessage(row) {
+    return {
+        fromOperator: row["from_operator"] === true,
+        body: text(row["body"]),
+        createdAt: text(row["created_at"]),
+        deletedAt: optional(row["deleted_at"]),
+    };
+}
+export function asList(value) {
+    if (!isRecord(value))
+        throw unreadable();
+    const rows = value["tickets"];
+    if (!Array.isArray(rows))
+        throw unreadable();
+    const unread = value["unread"];
+    return {
+        tickets: rows.map(asTicket),
+        unread: typeof unread === "number" ? unread : 0,
+    };
+}
+/** The date part of an instant. The time of day is noise in a list of reports. */
+export function day(at) {
+    return at.slice(0, 10).padEnd(10);
+}
+export function requireCategory(given) {
+    const codes = categoryCodes();
+    if (given === undefined) {
+        throw new NmtsError("`support send` needs --category.", {
+            exitCode: 2,
+            nextStep: `The categories are ${codes.join(" · ")}.`,
+        });
+    }
+    if (!codes.includes(given)) {
+        throw new NmtsError(`There is no support category called ${given}.`, {
+            exitCode: 2,
+            nextStep: `The categories are ${codes.join(" · ")}.`,
+        });
+    }
+    return given;
+}
+/**
+ * The narrowing, checked against the category it was given with.
+ *
+ * ⚠ It is optional everywhere, and stays optional here: somebody who does not know which one
+ *   applies must be able to send anyway.
+ */
+export function checkSub(category, given) {
+    if (given === undefined)
+        return null;
+    const subs = SUPPORT_CATEGORIES.find((c) => c.code === category)?.subs ?? [];
+    if (!subs.includes(given)) {
+        throw new NmtsError(`${category} has no part called ${given}.`, {
+            exitCode: 2,
+            nextStep: `Its parts are ${subs.join(" · ")}.`,
+        });
+    }
+    return given;
+}
+/** Values too short to name one thing would blank half the report, so they are refused. */
+export function checkOmit(values) {
+    for (const value of values) {
+        if (value.length < SHORTEST_OMIT) {
+            throw new NmtsError(`--omit needs at least ${SHORTEST_OMIT} characters: "${value}" is shorter.`, {
+                exitCode: 2,
+            });
+        }
+    }
+    return [...values];
+}
+export function requireLength(message, most, what) {
+    if (message === "") {
+        throw new NmtsError(`There is no ${what} to send.`, {
+            exitCode: 2,
+            nextStep: `Pass --message <text>, --message-file <path>, or pipe it in.`,
+        });
+    }
+    const characters = Array.from(message).length;
+    if (characters > most) {
+        throw new NmtsError(`A ${what} is at most ${most} characters, and this one is ${characters}.`, {
+            exitCode: 2,
+        });
+    }
+}

package/dist/trash-sweep.d.ts

@@ -0,0 +1,55 @@
+import { type ManifestIndex } from "./drive-paths.ts";
+import type { ManifestEntry } from "./shared/lib/drive/manifest-codec.ts";
+/**
+ * How long a trashed item stays restorable.
+ *
+ * ⛔ It must match the browser's `web/src/lib/drive/manifest-views.ts::TRASH_RETENTION_DAYS`, and
+ *    both of those describe the same promise the server enforces on its own rows. A tool that
+ *    counted to a different number would either drop an entry whose file the person could still
+ *    have restored, or leave one behind for a file whose key the server had already destroyed.
+ */
+export declare const TRASH_RETENTION_DAYS = 30;
+/**
+ * Whole days left of the thirty, counting up rather than down.
+ *
+ * Rounded UP so a row with four hours left says "1 day left" rather than "0 days left" — the
+ * number is what somebody decides whether to restore on, and rounding it to nothing reads as
+ * "already gone".
+ */
+export declare function daysLeftInTrash(trashedAtMs: number, nowMs: number): number;
+/**
+ * Entries whose thirty days have run out.
+ *
+ * Measured from the INHERITED instant, so a file inside a trashed folder is measured from the
+ * moment the folder was thrown away — which is also the moment the server stamped on its row.
+ * Reading each entry's own `deletedAt` would leave every file under a swept folder in the list.
+ */
+export declare function expiredTrashEntries(index: ManifestIndex, nowMs: number): ManifestEntry[];
+/** What one sweep may do, and what it must not do yet. */
+export interface PurgePlan {
+    /** Entries that may leave the file list now. */
+    drop: readonly ManifestEntry[];
+    /** Expired entries the server has not let go of yet. Nothing is wrong; it sweeps on a timer. */
+    waiting: readonly ManifestEntry[];
+    /** Expired entries held only because something underneath them is being kept. */
+    tangled: readonly ManifestEntry[];
+}
+/**
+ * Split the expired entries into what may go and what may not.
+ *
+ * `stillOnServer` is every item id the server still has a row for, live or trashed. An id in that
+ * set has a key the server has not destroyed, so dropping this side's copy would hide a file that
+ * is still stored and still being paid for.
+ *
+ * ⚠ Folder entries never appear in that set — the server holds no row for a folder — so a folder
+ *   is held back only by the branch rule below, which is exactly when it should be.
+ */
+export declare function planPurge(index: ManifestIndex, expired: readonly ManifestEntry[], stillOnServer: ReadonlySet<string>): PurgePlan;
+/**
+ * How many of the entries about to be dropped hold bytes.
+ *
+ * Said out loud before the write, because a count of ENTRIES reads as harmless — most of a trashed
+ * branch is folders, which hold nothing at all — and the number that matters is how many keys are
+ * being destroyed.
+ */
+export declare function filesAmong(entries: readonly ManifestEntry[]): number;

package/dist/units.d.ts

@@ -0,0 +1,2 @@
+/** Bytes as a person reads them: 1 kB is 1,000 bytes, the way the storage is priced. */
+export declare function humanSize(bytes: number): string;

package/dist/update-check.d.ts

@@ -0,0 +1,50 @@
+export { checkingIsOff, NO_CHECK_ENV_VAR } from "./update-source.ts";
+/** How long an answer is kept before another is asked for. */
+export declare const CHECK_EVERY_MS: number;
+/** What the last attempt found, or why it found nothing. */
+export interface UpdateCheck {
+    /** When the last attempt happened — whether or not it answered. */
+    checkedAt: string;
+    /** The newest version the last attempt that DID answer found. */
+    latest?: string;
+    /** Why the last attempt did not answer. Absent when it did. */
+    failed?: string;
+}
+export declare function checkPath(): string;
+/** What is on disk, or null when there is nothing readable there. */
+export declare function readCheck(): UpdateCheck | null;
+/** Write the attempt down. Failing to write is itself ignored: there is nothing to fall back to. */
+export declare function writeCheck(record: UpdateCheck): void;
+/** Is it time to ask again? Never having asked counts as due. */
+export declare function dueForCheck(record: UpdateCheck | null, nowMs: number): boolean;
+/** What one lookup produced. */
+export type Lookup = {
+    version: string;
+} | {
+    failed: string;
+};
+/**
+ * Ask which release is newest.
+ *
+ * ⛔ THE REDIRECT IS THE ANSWER, so it is not followed. `releases/latest` replies with the address
+ *    of the tagged page and an empty body; following it would download a page this has no use for.
+ */
+export declare function lookupLatest(url?: string): Promise<Lookup>;
+export interface NoteOptions {
+    /** The version running now. */
+    running: string;
+    /** The clock. Injected so a test does not depend on today. */
+    now?: Date;
+    /** Where the notice goes. Defaults to stderr. */
+    say?: (line: string) => void;
+    /** The lookup. Injected so a test does not depend on a host. */
+    lookup?: () => Promise<Lookup>;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Print the notice this run has earned, then refresh the file for the next one.
+ *
+ * The order is deliberate: whatever is already known is said first, so a slow or unreachable host
+ * cannot delay it, and the run that pays for the lookup is not the run that reads its result.
+ */
+export declare function noteUpdate(options: NoteOptions): Promise<void>;

package/dist/update-source.d.ts

@@ -0,0 +1,63 @@
+/** Setting this to anything stops the lookup and the notice, both. */
+export declare const NO_CHECK_ENV_VAR = "NMTS_NO_UPDATE_CHECK";
+/** Is the version check switched off here? */
+export declare function checkingIsOff(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The address that names the newest release whatever it is called.
+ *
+ * It answers with a redirect to the tagged page, and the tag carries the version. That is one
+ * request with an empty body — cheaper than the release listing, and it needs no credential.
+ */
+export declare const LATEST_RELEASE_URL = "https://github.com/needmoretruth/nmts-cli/releases/latest";
+/** Is this string a version this file is willing to reason about? */
+export declare function isVersion(value: string): boolean;
+/**
+ * The version a `releases/latest` redirect landed on, or null.
+ *
+ * ⛔ THE ADDRESS IS CHECKED, NOT JUST READ. It arrives from the network, and a redirect that
+ *    pointed somewhere else entirely would otherwise decide what this tool calls the newest
+ *    release. It has to be the tag page of this repository, over an encrypted connection, and the
+ *    tag itself has to be a version.
+ */
+export declare function versionFromLocation(location: string): string | null;
+/**
+ * -1, 0 or 1 — or null when either side is not a version this can compare.
+ *
+ * ⚠ Null is not "equal". A caller that treats it as equal says nothing; one that treats it as
+ *   "newer" nags forever about a release that does not exist. Both callers here read it as
+ *   "no answer".
+ */
+export declare function compareVersions(left: string, right: string): number | null;
+/** Is `candidate` a release later than the one running? Unanswerable counts as no. */
+export declare function isNewer(candidate: string, running: string): boolean;
+/** The page a person can read about one release on. */
+export declare function releasePageUrl(version: string): string | null;
+/**
+ * Where one release's package is.
+ *
+ * ⛔ THE TAGGED ADDRESS, NEVER "LATEST". This is handed to another program to install, and
+ *    "latest" would install whatever is newest at the moment that program runs — which is not
+ *    necessarily the version this tool just named on the screen. Naming the release means what
+ *    was reported and what gets installed are the same thing.
+ */
+export declare function packageUrl(version: string): string | null;
+/**
+ * The exact command that installs one release, as an argument list.
+ *
+ * ⛔ A LIST AND NOT A STRING, because it is both printed and run. A string would have to be split
+ *    again to be run, and splitting a string is where a shell gets involved — the one thing a
+ *    command built partly from a value off the network must not touch. `packageUrl` has already
+ *    refused anything that is not three numbers, so nothing here can carry a space, a quote or a
+ *    semicolon, and it never needs to.
+ */
+export declare function installCommand(version: string): readonly string[] | null;
+/** The same command as one line, for printing. */
+export declare function installCommandLine(version: string): string | null;
+/**
+ * The one line printed when a newer release exists.
+ *
+ * ⛔ IT SAYS WHAT IS PUBLISHED AND WHAT IS RUNNING, AND NOTHING ABOUT WHETHER TO UPGRADE. What is
+ *    in a release is not known here, and a line that called it important, recommended or a fix
+ *    would be inventing a reason to act.
+ */
+export declare function newerVersionLine(latest: string, running: string, binary: string): string;

package/dist/upload-api.d.ts

@@ -0,0 +1,3 @@
+import type { UploadApi } from "./upload-wire.ts";
+/** Bind the four calls to one server and one credential. */
+export declare function createUploadApi(base: string, apiKey: string): UploadApi;

package/dist/upload-file.d.ts

@@ -0,0 +1,97 @@
+import { type CryptoGlue } from "./crypto.ts";
+import { type PaddingRule } from "./shared/lib/crypto/size-padding.ts";
+import { entryOf } from "./upload.ts";
+import type { BlobProtocol, PaidPart, UploadApi, UploadInput, UploadResult, UploadStep } from "./upload-wire.ts";
+/**
+ * Where the plaintext comes from.
+ *
+ * ⛔ A SEAM, NOT A CONVENIENCE. The tests drive every branch of a multi-part upload — including
+ *    the ones that resume after a part was paid for — without a file and without a network. A
+ *    module that opened the path itself could only be tested by writing gigabytes to a disk.
+ */
+export interface PlaintextSource {
+    /** Total plaintext bytes. */
+    size: number;
+    /** Read `[offset, offset + length)`, in pieces small enough to hold. */
+    read(offset: number, length: number): AsyncIterable<Uint8Array>;
+}
+/** Read a file off the disk, a chunk at a time. */
+export declare function fileSource(path: string, size: number): PlaintextSource;
+export interface FileUploadInput {
+    api: UploadApi;
+    protocol: BlobProtocol;
+    crypt: CryptoGlue;
+    /** The account's data key. Borrowed — the caller wipes it. */
+    dataKey: Uint8Array;
+    source: PlaintextSource;
+    /** What the file is called in the account. */
+    name: string;
+    /** The folder id it goes in, or null for the root. */
+    parentId: string | null;
+    /** The destination AS TYPED. Part of the reservation key — see `upload-store.ts`. */
+    destination: string;
+    relayUrl: string;
+    epochs: number;
+    currentEpoch: number | null;
+    /** How much of the file goes into one part. */
+    partSize: number;
+    /**
+     * How coarsely the file's LAST part is rounded up before sealing, and the billing unit that
+     * decides how much of that rounding is free.
+     *
+     * ⛔ THE ACCOUNT'S CHOICE, NOT THIS TOOL'S. A stored stream states in the clear the length it was
+     *    sealed from, so without this the exact byte length of everything this tool uploads is
+     *    legible to anybody who fetches it from the storage network. Rounding differently from the
+     *    browser would be worse than not rounding: it would say which program uploaded the file.
+     */
+    padding: {
+        rule: PaddingRule;
+        unitBytes: number;
+    };
+    /**
+     * How many credits this file sets aside as a deposit, 0 to 64. Absent on the wallet rail, which
+     * buys its own storage and has no treasury deposit to set aside against it.
+     *
+     * ⛔ ONE NUMBER FOR THE WHOLE FILE, sent with every part's reservation, because the deposit is a
+     *    property of the FILE the person chose it for — not of how many parts it happened to need.
+     */
+    depositCredits?: number;
+    onStep?: (step: FileUploadStep) => void;
+    /**
+     * Who buys ONE part and gets its bytes onto the network. Absent = the credit rail
+     * (`buyAndPushPart`); the wallet rail (`upload-wallet.ts`) supplies its own.
+     *
+     * ⛔ A SEAM SO THERE IS ONE FILE DRIVER. Sealing, the reservation key, the resume of a file
+     *    already committed and the one-commit-per-file rule are the same whoever pays; a second
+     *    driver for the wallet would be a second place for those to drift.
+     */
+    buy?: (input: UploadInput) => Promise<PaidPart>;
+}
+/** Told about each part as it starts, so a long upload visibly moves. */
+export type FileUploadStep = {
+    step: "planning";
+    parts: number;
+    partSize: number;
+} | {
+    step: "hashing";
+    parts: number;
+} | {
+    step: "sealing";
+    partIndex: number;
+    parts: number;
+    bytes: number;
+} | ({
+    partIndex: number;
+    parts: number;
+} & UploadStep);
+/**
+ * Upload one file and return what the caller must write into the account's file list.
+ *
+ * ⛔ IT DOES NOT WRITE THE FILE LIST, and the caller must — before clearing the records. A
+ *    committed file the list does not name is invisible and, to the person, indistinguishable from
+ *    one that never uploaded.
+ */
+export declare function uploadFile(input: FileUploadInput): Promise<UploadResult>;
+/** The file key's records, so a caller can clear them once the list is written. */
+export declare function partKeysOf(fileKey: string, parts: number): string[];
+export { entryOf };

package/dist/upload-file.js

@@ -120,7 +120,7 @@ export async function uploadFile(input) {
             const sealed = stored === null
                 ? await sealPartOf(input, secrets.dek, range, plan.length, sealFrom)
                 : readReservationBytes(key);
-            paid.push(await buyAndPushPart({
+            paid.push(await (input.buy ?? buyAndPushPart)({
                 api: input.api,
                 protocol: input.protocol,
                 key,
@@ -130,6 +130,7 @@ export async function uploadFile(input) {
                 currentEpoch: input.currentEpoch,
                 // ⚠ The length the STREAM declares, which for a padded last part is more than the file
                 //   contributes. The list entry keeps the file's real size; this is what was sealed.
+                depositCredits: input.depositCredits ?? 0,
                 part: { index: range.partIndex, total: plan.length, plaintextLen: sealFrom },
                 entry,
                 onStep: (step) => onStep?.({ ...step, partIndex: range.partIndex, parts: plan.length }),
@@ -145,7 +146,7 @@ export async function uploadFile(input) {
         return {
             itemId,
             resumed: paid.every((part) => part.resumed),
-            ledgerIds: paid.map((part) => part.ledgerId),
+            ledgerIds: paid.flatMap((part) => (part.ledgerId === null ? [] : [part.ledgerId])),
             fileKey,
             parts: plan.length,
             entry,

package/dist/upload-price.d.ts

@@ -0,0 +1,50 @@
+import { type PaddingRule } from "./shared/lib/crypto/size-padding.ts";
+import { type PartRange } from "./shared/lib/upload/part-plan.ts";
+/**
+ * Storage term, in storage-network epochs.
+ *
+ * ⛔ NOT CHOOSABLE HERE, and that is a property of credits rather than of this tool: one credit is
+ *    defined as one mebibyte for exactly this term. Offering a duration picker would be offering
+ *    to spend a multiple of a unit the credit surface does not speak in. A browser's own-wallet
+ *    upload has a picker because it is paying in WAL, which does divide.
+ */
+export declare const UPLOAD_EPOCHS = 2;
+/** Bytes one credit stores for `UPLOAD_EPOCHS`. */
+export declare const CREDIT_BYTES: number;
+/**
+ * What this upload will cost, in credits — the same arithmetic the server does.
+ *
+ * Printed BEFORE anything is spent so the number can be compared with what the account screen
+ * shows afterwards. The server is still the authority; this is a quote, not a promise.
+ */
+export declare function creditsFor(sealedBytes: number, epochs?: number): number;
+/**
+ * How big the local file is, with the two refusals that are worth their own words.
+ *
+ * ⛔ IT IS NOT READ HERE. A file large enough to need several parts is a file too large to hold,
+ *    and the size is all that is needed to plan the upload and quote its price. The bytes are read
+ *    later, a slice at a time, by the part that is being sealed.
+ */
+export declare function measureLocal(path: string): number;
+/**
+ * How much of the file goes into one part.
+ *
+ * ⛔ THE SAME NUMBER ON A RESUME OR NOTHING MATCHES. The parts already written down were sealed
+ *    and paid for at one size; a second run that split the file differently would be asking to
+ *    push different bytes under reservations that bought the first ones. `buyAndPushPart` refuses
+ *    that rather than doing it, and this is where the number comes from.
+ */
+export declare function partSizeFor(chosen: string | number | undefined): number;
+/**
+ * The plan, and what it will cost — one function so the price and the sealing cannot disagree.
+ *
+ * ⛔ ONLY THE LAST PART IS ROUNDED UP. The earlier ones are exactly the part size, which is what
+ *    lets a reader work out where the padding is. Quoting any other way would price a file
+ *    differently from how it is actually stored.
+ */
+export declare function planAndPrice(size: number, partSize: number, rule: PaddingRule): {
+    plan: PartRange[];
+    sealedBytes: number;
+    credits: number;
+    sealFor(range: PartRange): number;
+};

package/dist/upload-steps.d.ts

@@ -0,0 +1,26 @@
+import { type CommitInput, type PaidPart, type UploadInput } from "./upload-wire.ts";
+/** Push ONE part's bytes at the relay and report the certificate. Commits nothing. */
+export declare function pushPart(input: UploadInput, step: {
+    ledgerId: number;
+    blobId: string;
+    nonce: Uint8Array;
+    registerTxDigest: string;
+    blobObjectId: string;
+    /** ⛔ The bytes the reservation bought — from the record on a resume. Never re-sealed ones. */
+    sealed: Uint8Array;
+    /** ⛔ The relay the tip was paid to. From the record on a resume. */
+    relayUrl: string;
+}): Promise<void>;
+/**
+ * Make the file real: one `POST /v1/items` naming EVERY part and the reservation that paid for it.
+ *
+ * ⛔ ONE CALL FOR THE WHOLE FILE. The server derives the item's size as the sum of the parts'
+ *    sealed lengths and refuses a set whose indices are not a contiguous 0..n — so a file cannot
+ *    be committed a piece at a time, and a part left out is not a smaller file, it is a rejection.
+ *
+ * ⛔ EVERY FACT HERE COMES OFF A RECORD. The parts were read back from what was written down
+ *    before each reservation; the key and the content hash come from whichever record the caller
+ *    read them from. A resumed run that used its own freshly generated key would produce a file
+ *    that is paid for, present, correctly named — and impossible to open.
+ */
+export declare function commitItem(input: CommitInput, fileKey: string, parts: readonly PaidPart[]): Promise<string>;

package/dist/upload-steps.js

@@ -12,6 +12,8 @@ const STORAGE_KIND_DEDICATED_BLOB = 0;
 const NETWORK_WALRUS = 0;
 /** Only this account can read it. Sharing is a separate act, made in a browser. */
 const VISIBILITY_PERSONAL = 0;
+/** ITEM PARTS `owner_kind`: the person's own wallet paid. ⚠ The server decides this itself, from the absence of a reservation; the field is sent for wire compatibility, as the browser sends it. */
+const OWNER_USER_WALLET = 0;
 function why(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -83,15 +85,7 @@ export async function commitItem(input, fileKey, parts) {
             dek_wrapped: input.entry.dekWrapped,
             content_hash_ct: input.entry.contentHashCt,
             visibility: VISIBILITY_PERSONAL,
-            parts: parts.map((part) => ({
-                part_index: part.partIndex,
-                storage_kind: STORAGE_KIND_DEDICATED_BLOB,
-                network: NETWORK_WALRUS,
-                blob_id: part.blobId,
-                sealed_len: part.sealedLen,
-                expiry_epoch: expiryEpoch,
-                sponsored_ledger_id: part.ledgerId,
-            })),
+            parts: parts.map((part) => describePart(part, expiryEpoch)),
         }, `nmts-cli-commit-${fileKey}-${attempt}`);
     }
     catch (error) {
@@ -109,3 +103,29 @@ export async function commitItem(input, fileKey, parts) {
     writeItemRecord(fileKey, { attempt, itemId: view.id });
     return view.id;
 }
+/**
+ * One part as `POST /v1/items` takes it.
+ *
+ * ⛔ WHO PAID IS SAID BY ONE FIELD AND NOTHING ELSE. A part the treasury paid for names its
+ *    reservation and the server checks it; a part the person's wallet paid for names none, and
+ *    carries instead what the recovery list needs — the blob object and the epoch the chain says
+ *    the storage ends at — exactly as the browser's wallet-paid commit does.
+ */
+function describePart(part, expiryEpoch) {
+    const common = {
+        part_index: part.partIndex,
+        storage_kind: STORAGE_KIND_DEDICATED_BLOB,
+        network: NETWORK_WALRUS,
+        blob_id: part.blobId,
+        sealed_len: part.sealedLen,
+    };
+    if (part.ledgerId !== null) {
+        return { ...common, expiry_epoch: expiryEpoch, sponsored_ledger_id: part.ledgerId };
+    }
+    return {
+        ...common,
+        owner_kind: OWNER_USER_WALLET,
+        expiry_epoch: part.endEpoch ?? expiryEpoch,
+        ...(part.suiObjectId !== undefined ? { sui_object_id: part.suiObjectId } : {}),
+    };
+}