@needmoretruth/nmts-sdk 0.1.1

package/dist/session.js

@@ -0,0 +1,74 @@
+// Turning a root and the two address options into an opened account: who it is, which server,
+// which network.
+//
+// ⛔ NOTHING HERE READS THE ENVIRONMENT OR ASKS A PERSON. The command-line tool's session module
+//    does both, because a terminal is where a person is; a library runs inside somebody else's
+//    server, where a prompt hangs and an environment read is a decision the caller did not make.
+//    `env.ts` is the one place this package reads the environment, and only when asked to.
+//
+// ⛔ THE CODE IS BORROWED, NOT HELD. `Opened` carries the ROOT, not the key, so nothing below this
+//    line changes when the key moves from a person's device to a business's sealed store.
+//    `withAccount` is the one door through which a verb borrows it, which is why "one call, one
+//    opening" is a number a test can read off a managed root — and why nothing this package keeps
+//    between calls can hold a code.
+//
+// ⛔ THE ACCOUNT CODE IS HELD, NOT COPIED, for the length of the work. It is the only key to the
+//    account. Every derivation below takes it, uses the bytes it needs, and wipes the rest before
+//    returning — the same discipline the command-line tool keeps, for the same reason: a live copy
+//    of the derived buffer is a live copy of the account.
+import { DERIVED, identityOf, loadCrypto, resolveNetwork, resolveServer, } from "@needmoretruth/nmts-cli";
+import { requireText } from "./root.js";
+/**
+ * Check what can be checked without the code, and work out where this account talks.
+ *
+ * The key is only checked for being present; the server is what judges a key, on the first request.
+ * Nothing here borrows the code, so a caller who got the key wrong is refused without a business's
+ * store having been opened for nothing.
+ */
+export function openAccount(root, options = {}) {
+    const apiKey = requireText(root.identity.apiKey, "API key", "Make one on the account screen at nmts.me and pass it as `apiKey`, or set NMTS_API_KEY_FILE.");
+    const server = resolveServer(options.server);
+    return { root, apiKey, server, network: resolveNetwork(server, options.network) };
+}
+/**
+ * Borrow the account's code for the length of `body`, and work out the account it names.
+ *
+ * ⛔ ONE CALL, ONE BORROW. Every verb in this package wraps the whole of itself in this, so a
+ *    managed root is asked to open its sealed code exactly once however many requests the verb makes.
+ *
+ * ⛔ THE ACCOUNT ID IS DERIVED HERE RATHER THAN KEPT, because deriving it is the only check there
+ *    is that a code is one: nothing about a string says which account it opens until the engine has
+ *    parsed it. It is a pure function of the code, and the code is only here.
+ */
+export async function withAccount(opened, body) {
+    return opened.root.withCode(async (code) => {
+        const identity = await identityOf(code);
+        return body({
+            code,
+            apiKey: opened.apiKey,
+            server: opened.server,
+            network: opened.network,
+            accountId: identity.accountId,
+        });
+    });
+}
+/**
+ * Run `body` with the account's data key, then wipe it.
+ *
+ * The data key wraps every file key in the account. It exists for exactly as long as the work
+ * that needs it, and the derivation output it came out of — which holds every other key too — is
+ * zeroed before `body` even starts.
+ */
+export async function withDataKey(code, body) {
+    const crypt = await loadCrypto();
+    const [from, to] = DERIVED.dataKey;
+    const derived = crypt.kdf_derive(crypt.account_code_parse(code));
+    const dataKey = derived.slice(from, to);
+    derived.fill(0);
+    try {
+        return await body(crypt, dataKey);
+    }
+    finally {
+        dataKey.fill(0);
+    }
+}

package/dist/wallets.d.ts

@@ -0,0 +1,63 @@
+import { type ChainReader, type Network } from "@needmoretruth/nmts-cli";
+import { type Held, type Opened } from "./session.ts";
+/** One of the wallets this account's NMTS key opens. */
+export interface WalletInfo {
+    /** The index the key derives it at. 0 is the wallet every account starts with. */
+    index: number;
+    /** Its Sui address — the same address on every network. */
+    address: string;
+    /** Is this the wallet storage is paid from? Exactly one wallet of an account is. */
+    active: boolean;
+}
+/** What `setActiveWallet()` answers: the wallet that pays now, and whether this call moved it. */
+export interface ActiveWallet {
+    index: number;
+    address: string;
+    /** False when the account already paid from this wallet, so nothing was written. */
+    changed: boolean;
+}
+/**
+ * What the walk asks a chain. ⚠ Seams, not options: no caller of `wallets()` reaches them, and a
+ * test hands in a chain that answers from a table exactly as the command-line tool's own do.
+ */
+export interface WalletReads {
+    openChain?: ((network: Network, address: string) => ChainReader | Promise<ChainReader>) | undefined;
+    hasHistory?: ((network: Network, address: string) => Promise<boolean>) | undefined;
+}
+/**
+ * A wallet number as a caller wrote it.
+ *
+ * ⛔ REFUSED, NEVER ROUNDED. `1.5` and `-1` are calls to correct; taking either of them to a
+ *    neighbouring wallet would pay from an address nobody named. The write path below clamps, which
+ *    is right for a slider and wrong for an argument, so the refusal happens before it.
+ */
+export declare function requireWalletIndex(value: number): number;
+/**
+ * Which wallet this account pays from, out of its sealed list.
+ *
+ * An account that has never written the setting pays from the first wallet — that is a READ
+ * answer and not a fallback: the list opened, and it said nothing about a wallet.
+ */
+export declare function payingWallet(held: Held): Promise<number>;
+/**
+ * Every wallet this account has, in index order: the ones it has made, and any further out that a
+ * chain says have been used.
+ *
+ * Nothing is spent and nothing is written. The walk costs one balance read per number it asks
+ * about, plus a transaction question for a wallet that holds neither coin — a wallet somebody
+ * emptied is in use too, and a walk that asked about balances alone would report it as one that
+ * does not exist.
+ *
+ * ⚠ A WALLET FUNDED FURTHER OUT THAN THE GAP IS NOT FOUND HERE. It is not lost: numbers come from
+ *   the key, so `walletAddress({ index })` and `setActiveWallet(index)` still reach it.
+ */
+export declare function wallets(opened: Opened, reads?: WalletReads): Promise<WalletInfo[]>;
+/**
+ * Say which of this key's wallets pays for storage from now on, on this account rather than on
+ * this machine.
+ *
+ * Nothing is deleted and nothing is created: every number a key can derive already exists, and
+ * this says which of them the next payment comes out of. The account's count of wallets comes up
+ * with it, never down, so every screen lists the wallet it just named.
+ */
+export declare function setActiveWallet(opened: Opened, index: number): Promise<ActiveWallet>;

package/dist/wallets.js

@@ -0,0 +1,129 @@
+// Every wallet one NMTS key opens, and which of them pays for storage.
+//
+// ⛔ THE NUMBERS COME FROM THE KEY, SO THERE IS NOTHING TO CREATE AND NOTHING TO DELETE. One NMTS
+//    key derives a wallet at every index (NCF-3 §1.3); "which of them exist" is not a list anybody
+//    keeps, so it is answered by WALKING — ask the chain about a number, then the next, and stop
+//    after twenty unused ones in a row. The walk itself is the command-line package's own
+//    (`discoverWallets`), so this library and `nmts wallet list` show one key the same wallets.
+//
+// ⛔ WHICH ONE PAYS IS THE ACCOUNT'S, NOT THIS PROCESS'S. It rides inside the sealed file list,
+//    where no server can read it, so a phone, a browser and a program built on this package all
+//    spend from the same address. Money leaving from one address on one device and another address
+//    on another is how a balance goes missing without anything failing.
+//
+// ⛔ AND IT IS REFUSED RATHER THAN GUESSED. When the list cannot be read this does not fall back to
+//    wallet 0: that would name one address in a price and sign with another, on an account whose
+//    owner may never have funded the first. "I do not know which wallet should pay" is an answer;
+//    wallet 0 is not. It is the command-line tool's rule (`wallet-pay-index.ts`), for money that
+//    does not come back either way.
+import { activeWalletOf, applyManyToList, chainReader, discoverWallets, hasHistory, NmtsError, readBalances, readFileList, walCoinType, walletAddress, walletCountOf, WALLET_INDEX_LIMIT, } from "@needmoretruth/nmts-cli";
+import { withAccount } from "./session.js";
+/**
+ * A wallet number as a caller wrote it.
+ *
+ * ⛔ REFUSED, NEVER ROUNDED. `1.5` and `-1` are calls to correct; taking either of them to a
+ *    neighbouring wallet would pay from an address nobody named. The write path below clamps, which
+ *    is right for a slider and wrong for an argument, so the refusal happens before it.
+ */
+export function requireWalletIndex(value) {
+    if (!Number.isSafeInteger(value) || value < 0 || value >= WALLET_INDEX_LIMIT) {
+        throw new NmtsError(`A wallet number is a whole number from 0 to ${WALLET_INDEX_LIMIT - 1}.`, {
+            exitCode: 2,
+            nextStep: "`wallets()` lists this key's wallets and their numbers.",
+        });
+    }
+    return value;
+}
+/**
+ * Which wallet this account pays from, out of its sealed list.
+ *
+ * An account that has never written the setting pays from the first wallet — that is a READ
+ * answer and not a fallback: the list opened, and it said nothing about a wallet.
+ */
+export async function payingWallet(held) {
+    try {
+        const list = await readFileList(held.server, held.apiKey, held.code, held.accountId);
+        return activeWalletOf(list.manifest?.settings);
+    }
+    catch (error) {
+        // A refusal this package already worded — no API key, a server that said no — is passed on as
+        // it stands; it names the thing to fix, and a second sentence over it would bury that.
+        if (error instanceof NmtsError)
+            throw error;
+        throw new NmtsError(`Which wallet this account pays from is written in its file list, and it could not be read: ` +
+            `${error instanceof Error ? error.message : String(error)}`, {
+            exitCode: 1,
+            nextStep: "Nothing was signed. Try again when the list can be read, or name the wallet for this one " +
+                "call — `walletAddress({ index })` and `put(…, { wallet })` each take a number.",
+        });
+    }
+}
+/**
+ * Every wallet this account has, in index order: the ones it has made, and any further out that a
+ * chain says have been used.
+ *
+ * Nothing is spent and nothing is written. The walk costs one balance read per number it asks
+ * about, plus a transaction question for a wallet that holds neither coin — a wallet somebody
+ * emptied is in use too, and a walk that asked about balances alone would report it as one that
+ * does not exist.
+ *
+ * ⚠ A WALLET FUNDED FURTHER OUT THAN THE GAP IS NOT FOUND HERE. It is not lost: numbers come from
+ *   the key, so `walletAddress({ index })` and `setActiveWallet(index)` still reach it.
+ */
+export async function wallets(opened, reads = {}) {
+    const open = reads.openChain ?? chainReader;
+    const history = reads.hasHistory ?? hasHistory;
+    return withAccount(opened, async (held) => {
+        const list = await readFileList(held.server, held.apiKey, held.code, held.accountId);
+        const settings = list.manifest?.settings;
+        const active = activeWalletOf(settings);
+        const count = walletCountOf(settings);
+        const walType = walCoinType(held.network);
+        // Every number the walk asked about, so no address is derived or read twice.
+        const seen = new Map();
+        const scan = await discoverWallets(async (index) => {
+            const address = await walletAddress(held.code, index);
+            seen.set(index, address);
+            const balances = await readBalances(await open(held.network, address), walType);
+            // ⛔ A BALANCE THAT COULD NOT BE READ IS NOT A ZERO, so it is not a wallet this walk gets to
+            //    call unused: the transaction question below still has its say, and a wallet that has
+            //    one is reported whatever the node did with the balance.
+            const holds = (coin) => coin.read && coin.baseUnits > 0n;
+            if (holds(balances.sui) || holds(balances.wal))
+                return true;
+            return history(held.network, address);
+        }, { count });
+        // ⛔ THE COUNT IS READ AND NOT RAISED HERE. "Making a wallet" is a person's act on the wallets
+        //    screen, and a library that wrote the account's list while answering a question about it
+        //    would be spending a file-list version on a read its caller did not ask to change anything
+        //    with. What the walk found is reported; what the account holds stays what it held.
+        return [...seen]
+            .filter(([index]) => index < count || scan.used.includes(index))
+            .map(([index, address]) => ({ index, address, active: index === active }))
+            .sort((a, b) => a.index - b.index);
+    });
+}
+/**
+ * Say which of this key's wallets pays for storage from now on, on this account rather than on
+ * this machine.
+ *
+ * Nothing is deleted and nothing is created: every number a key can derive already exists, and
+ * this says which of them the next payment comes out of. The account's count of wallets comes up
+ * with it, never down, so every screen lists the wallet it just named.
+ */
+export async function setActiveWallet(opened, index) {
+    // ⛔ BEFORE THE NETWORK. A number that is not one is a call to fix, and a run that opened the
+    //    account first — a business's sealed store, for a managed root — would refuse for the wrong
+    //    reason after having opened it for nothing.
+    const wanted = requireWalletIndex(index);
+    return withAccount(opened, async (held) => {
+        const before = await readFileList(held.server, held.apiKey, held.code, held.accountId);
+        // The setting lives IN the list, so an account with no list has nowhere to put it — the same
+        // refusal `nmts wallet use` gives, with the same way out.
+        if (before.manifest === null) {
+            throw new NmtsError("This account has no file list yet; which wallet pays lives in the list, and there is nothing to write it into.", { exitCode: 4, nextStep: "Upload once with `put()` and set the wallet after." });
+        }
+        const result = await applyManyToList(held, () => [], { activeWallet: wanted });
+        return { index: wanted, address: await walletAddress(held.code, wanted), changed: result.changed };
+    });
+}

package/examples/quickstart.mjs

@@ -0,0 +1,16 @@
+// The README's quickstart, runnable: `node examples/quickstart.mjs ./some-file`.
+//
+// Needs NMTS_ACCOUNT_CODE_FILE (or NMTS_ACCOUNT_CODE) and NMTS_API_KEY_FILE (or NMTS_API_KEY) in
+// the environment. The upload spends credits: one per started MiB of sealed bytes.
+import { Nmts } from "@needmoretruth/nmts-sdk";
+
+const file = process.argv[2] ?? "./README.md";
+const nmts = Nmts.fromEnv();
+
+const put = await nmts.put(file);
+console.log(`stored ${put.path} — ${put.bytes} bytes, ${put.credits} credit(s)`);
+
+const bytes = await nmts.get(put.path);
+console.log(`fetched ${bytes.length} bytes back`);
+
+for (const entry of await nmts.list()) console.log(`${entry.kind === "folder" ? "d" : "f"}  ${entry.size}\t${entry.path}`);

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@needmoretruth/nmts-sdk",
+  "version": "0.1.1",
+  "description": "Put, get and list files in an NMTS account from your own program: open-source, end-to-end encrypted storage on the Walrus network, with the keys on your machine. One constructor, three methods, typed.",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/needmoretruth/nmts-sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/needmoretruth/nmts-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/needmoretruth/nmts-sdk/issues"
+  },
+  "keywords": [
+    "nmts",
+    "walrus",
+    "sui",
+    "encryption",
+    "e2ee",
+    "storage",
+    "sdk",
+    "backend",
+    "agent"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE",
+    "LICENSING.md"
+  ],
+  "scripts": {
+    "compile": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run compile",
+    "pretest": "node scripts/ensure-cli.mjs",
+    "test": "node --test \"test/**/*.test.ts\""
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@needmoretruth/nmts-cli": "^0.35.0"
+  }
+}