@aithos/sdk 0.1.0-alpha.6 → 0.1.0-alpha.7

package/dist/src/ethos.js

@@ -25,7 +25,7 @@
 // actor and forwards all real work into protocol-client's
 // `loadEditSnapshot` / `publishZoneEdit` / `publishPublicZoneAsDelegate`
 // / `publishPrivateZoneAsDelegate`.
-import { addSectionToList, deleteSectionFromList, loadEditSnapshot, modifySectionInList, publishPrivateZoneAsDelegate, publishPublicZoneAsDelegate, publishZoneEdit, } from "@aithos/protocol-client";
+import { addSectionToList, AithosRpcError, browserIdentityFromStored, buildSignedEnvelope, buildSignedFirstEditionFromSections, deleteSectionFromList, loadEditSnapshot, modifySectionInList, publishPrivateZoneAsDelegate, publishPublicZoneAsDelegate, publishZoneEdit, signedDidDocument, writeEndpoint, } from "@aithos/protocol-client";
 import { delegateKeyPair } from "./internal/protocol-client-bridge.js";
 import { AithosSDKError } from "./types.js";
 export const ZONE_NAMES = ["public", "circle", "self"];
@@ -38,6 +38,15 @@ export class EthosClient {
     #actor;
     #snapshots = new Map();
     #mutations = [];
+    /**
+     * Set to `true` when the server reports that no edition has been
+     * published yet for this subject (JSON-RPC code -32020 with the message
+     * `not found: edition for <did>`). Toggled lazily on the first read /
+     * publish attempt and cleared again after a successful first-edition
+     * publish so subsequent operations take the regular `publishZoneEdit`
+     * path.
+     */
+    #ethosHasNoEditionYet = false;
     constructor(actor) {
         this.#actor = actor;
         this.subjectDid = actor.subjectDid;
@@ -80,8 +89,15 @@ export class EthosClient {
         // have staged mutations for. Build everything we need then call
         // publishZoneEdit once.
         if (this.#actor.kind === "owner") {
-            // Need the snapshot regardless — we read base sections + zoneBytes.
-            const snap = await this.#ensureSnapshotOwner();
+            // First-edition path: no prior edition exists. Detected when the
+            // tolerant snapshot wrapper returned null on a previous read OR
+            // when this is the first network touch and the server responds
+            // with "not found: edition". Skip the snapshot fetch entirely and
+            // build a height=1 manifest from the staged mutations.
+            const snap = await this.#tryEnsureSnapshotOwner();
+            if (snap === null) {
+                return this.#publishFirstEditionOwner();
+            }
             const newPublic = touched.has("public")
                 ? this.#applyMutations("public", snap.publicSections)
                 : undefined;
@@ -175,12 +191,18 @@ export class EthosClient {
             if (zone !== "public") {
                 throw new AithosSDKError("ethos_anonymous_private_zone", `anonymous reader cannot access the "${zone}" zone`);
             }
-            const snap = await this.#ensureSnapshotAnonymous();
-            const base = snap.publicSections;
+            const snap = await this.#tryEnsureSnapshotAnonymous();
+            // No edition yet → no base sections; only staged mutations contribute.
+            const base = snap === null ? [] : snap.publicSections;
             return this.#applyMutations(zone, base);
         }
         if (this.#actor.kind === "owner") {
-            const snap = await this.#ensureSnapshotOwner();
+            const snap = await this.#tryEnsureSnapshotOwner();
+            if (snap === null) {
+                // No edition yet for this owner — base sections are empty in every
+                // zone. Staged mutations apply on top of an empty list.
+                return this.#applyMutations(zone, []);
+            }
             const base = baseSectionsFromSnapshot(snap, zone);
             // Surface decryption errors clearly (if reading a private zone we
             // can't unwrap, the snapshot has it in zoneDecryptErrors).
@@ -190,7 +212,10 @@ export class EthosClient {
             return this.#applyMutations(zone, base);
         }
         // Delegate
-        const snap = await this.#ensureSnapshotDelegate();
+        const snap = await this.#tryEnsureSnapshotDelegate();
+        if (snap === null) {
+            return this.#applyMutations(zone, []);
+        }
         const base = baseSectionsFromSnapshot(snap, zone);
         if (zone !== "public" && snap.zoneDecryptErrors?.[zone]) {
             throw new AithosSDKError("ethos_zone_unreadable", `cannot read ${zone}: ${snap.zoneDecryptErrors[zone]}`);
@@ -283,6 +308,57 @@ export class EthosClient {
         this.#cacheSnapshotAllZones(snap);
         return snap;
     }
+    /**
+     * Wrap {@link #ensureSnapshotOwner} so the "no edition published yet"
+     * server response (-32020 with message `not found: edition for <did>`)
+     * is converted into `null`. Once converted, {@link #ethosHasNoEditionYet}
+     * is set to short-circuit subsequent reads without re-hitting the network.
+     *
+     * Returns `null` to mean "subject has an identity but no editions yet —
+     * treat all zones as empty". Any other error is re-thrown.
+     */
+    async #tryEnsureSnapshotOwner() {
+        if (this.#ethosHasNoEditionYet)
+            return null;
+        try {
+            return await this.#ensureSnapshotOwner();
+        }
+        catch (e) {
+            if (isNoEditionYetError(e)) {
+                this.#ethosHasNoEditionYet = true;
+                return null;
+            }
+            throw e;
+        }
+    }
+    async #tryEnsureSnapshotDelegate() {
+        if (this.#ethosHasNoEditionYet)
+            return null;
+        try {
+            return await this.#ensureSnapshotDelegate();
+        }
+        catch (e) {
+            if (isNoEditionYetError(e)) {
+                this.#ethosHasNoEditionYet = true;
+                return null;
+            }
+            throw e;
+        }
+    }
+    async #tryEnsureSnapshotAnonymous() {
+        if (this.#ethosHasNoEditionYet)
+            return null;
+        try {
+            return await this.#ensureSnapshotAnonymous();
+        }
+        catch (e) {
+            if (isNoEditionYetError(e)) {
+                this.#ethosHasNoEditionYet = true;
+                return null;
+            }
+            throw e;
+        }
+    }
     #cacheSnapshotAllZones(snap) {
         for (const z of ZONE_NAMES)
             this.#snapshots.set(z, snap);
@@ -291,6 +367,110 @@ export class EthosClient {
         this.#mutations = [];
         this.#snapshots.clear();
     }
+    /* ------------------------------------------------------------------------ */
+    /*  First-edition publish (owner)                                           */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Publish height=1 for an owner whose Ethos identity exists on
+     * `api.aithos.be` (provisioned by `auth.signUp()` in alpha.6+) but who
+     * has no editions yet. Builds the manifest from the staged ADD
+     * mutations on the public zone and POSTs `aithos.publish_ethos_edition`.
+     *
+     * Limitations of the alpha.7 cut:
+     *   - Public zone only. Staged mutations on circle/self are rejected
+     *     with `ethos_first_edition_public_only` — those zones can be
+     *     populated in subsequent editions via the regular
+     *     `publishZoneEdit` path once the public zone has been seeded.
+     *   - First-edition publishes don't accept update/delete mutations
+     *     (there's nothing to update or delete yet) — those are rejected
+     *     with `ethos_first_edition_invalid_op`.
+     */
+    async #publishFirstEditionOwner() {
+        if (this.#actor.kind !== "owner") {
+            // Defensive — caller already checked this branch.
+            throw new AithosSDKError("ethos_invalid_actor", "expected owner actor");
+        }
+        // Validate the staged operation set. First edition = ADDs on public
+        // zone only.
+        const publicAdds = [];
+        for (const m of this.#mutations) {
+            if (m.kind !== "add") {
+                throw new AithosSDKError("ethos_first_edition_invalid_op", `first edition: cannot ${m.kind} a section before any edition exists; only addSection is supported on a fresh Ethos`, { data: { mutation: m } });
+            }
+            if (m.zone !== "public") {
+                throw new AithosSDKError("ethos_first_edition_public_only", `first edition: only the "public" zone is supported on a fresh Ethos; "${m.zone}" sections can be added after the first publish`, { data: { zone: m.zone } });
+            }
+            publicAdds.push({ section: m.section });
+        }
+        if (publicAdds.length === 0) {
+            // Should never reach here — publish() short-circuits on empty
+            // mutations. Belt-and-braces in case the contract drifts.
+            throw new AithosSDKError("ethos_first_edition_empty", "first edition: stage at least one public-zone section before publishing");
+        }
+        const identity = this.#actor.signers._unsafeStoredIdentity();
+        const browserId = browserIdentityFromStored(identity);
+        const signedDoc = signedDidDocument(browserId);
+        const built = buildSignedFirstEditionFromSections({
+            identity: browserId,
+            signedDidDoc: signedDoc,
+            publicSections: publicAdds.map((a) => a.section),
+        });
+        const url = writeEndpoint();
+        const params = {
+            manifest: built.manifest,
+            zones: {
+                public: { bytes_base64: bytesToBase64Padded(built.publicMarkdownBytes) },
+            },
+        };
+        const envelope = buildSignedEnvelope({
+            iss: browserId.did,
+            aud: url,
+            method: "aithos.publish_ethos_edition",
+            verificationMethod: `${browserId.did}#public`,
+            params,
+            signer: browserId.public,
+        });
+        const body = JSON.stringify({
+            jsonrpc: "2.0",
+            id: "publish_ethos_edition",
+            method: "aithos.publish_ethos_edition",
+            params: { ...params, _envelope: envelope },
+        });
+        let res;
+        try {
+            res = await fetch(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body,
+            });
+        }
+        catch (e) {
+            throw new AithosSDKError("ethos_publish_network", `publish_ethos_edition (first edition): network error: ${e.message ?? "unknown"}`);
+        }
+        let json;
+        try {
+            json = (await res.json());
+        }
+        catch {
+            throw new AithosSDKError("ethos_publish_invalid_response", `publish_ethos_edition (first edition): server returned non-JSON (HTTP ${res.status})`);
+        }
+        if (json.error) {
+            throw new AithosSDKError("ethos_first_edition_rejected", `publish_ethos_edition (first edition) rejected: ${json.error.message}`, {
+                status: res.status,
+                data: { rpc_code: json.error.code, ...(json.error.data ?? {}) },
+            });
+        }
+        // Success: clear the no-edition flag so subsequent reads/publishes
+        // take the regular next-edition path.
+        this.#ethosHasNoEditionYet = false;
+        this.#afterPublish();
+        return {
+            editionHeight: 1,
+            manifestHash: "", // protocol-client surfaces this on later editions; not on first
+            subjectDid: browserId.did,
+            zonesPublished: ["public"],
+        };
+    }
 }
 /* -------------------------------------------------------------------------- */
 /*  EthosZone — per-zone proxy                                                */
@@ -410,6 +590,36 @@ function projectPublishResult(manifest, subjectDid, zones) {
         zonesPublished: zones,
     };
 }
+/**
+ * Detect the server-side "no edition published yet" response. Matches the
+ * exact error shape emitted by primitives-read's `notFound("edition for
+ * <did>")` helper: JSON-RPC code -32020 + message starting with `not
+ * found: edition for `. Other -32020 cases (e.g. "not found: manifest
+ * <did>@<height>" raised when the index advertises an edition the S3
+ * bucket can't serve) deliberately fall through — they're symptoms, not
+ * the "fresh subject" case we're trying to swallow.
+ */
+function isNoEditionYetError(e) {
+    if (!(e instanceof AithosRpcError))
+        return false;
+    if (e.code !== -32020)
+        return false;
+    return typeof e.message === "string"
+        && e.message.startsWith("not found: edition for ");
+}
+/**
+ * Standard base64 with `=` padding — matches what protocol-client's
+ * publishZoneEdit uses for `zones.<zone>.bytes_base64`. The server is
+ * tolerant of either padded or unpadded variants per the API contract,
+ * but we mirror the existing wire to keep payloads byte-identical for
+ * easy diffing in dev tools.
+ */
+function bytesToBase64Padded(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
 function randomHex(n) {
     const bytes = new Uint8Array(Math.ceil(n / 2));
     crypto.getRandomValues(bytes);

package/dist/src/index.d.ts

@@ -2,6 +2,7 @@ export declare const VERSION = "0.1.0-alpha.5";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 export { AithosSDKError } from "./types.js";
+export { AithosRpcError } from "@aithos/protocol-client";
 export type { AithosSdkEndpoints } from "./endpoints.js";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
 export type { ComputeMessage, InvokeBedrockArgs, InvokeBedrockResult, StopReason, } from "./compute.js";

package/dist/src/index.js

@@ -20,6 +20,10 @@
 export const VERSION = "0.1.0-alpha.5";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
+// Re-export protocol-client's JSON-RPC error type so consumers can
+// `instanceof`-check server-side errors and inspect the JSON-RPC code
+// without taking a direct dependency on @aithos/protocol-client.
+export { AithosRpcError } from "@aithos/protocol-client";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
 export { ComputeNamespace } from "./compute.js";
 export { WalletNamespace } from "./wallet.js";

package/dist/test/ethos-first-edition.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ethos-first-edition.test.d.ts.map

package/dist/test/ethos-first-edition.test.js

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+// Tests for the alpha.7 first-edition path in EthosClient — the case
+// where an Ethos identity exists on api.aithos.be (provisioned by
+// auth.signUp() since alpha.6) but no edition has been published yet.
+//
+// Two flows must work:
+//   1. Reading any zone returns an empty list (instead of throwing
+//      "not found: edition").
+//   2. Publishing for the first time builds height=1 from staged
+//      mutations and POSTs publish_ethos_edition directly, instead
+//      of going through publishZoneEdit (which requires a previous
+//      manifest).
+//
+// We mock global fetch end-to-end so the tests run offline.
+import { strict as assert } from "node:assert";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { createBrowserIdentity } from "@aithos/protocol-client";
+import { AithosAuth, AithosSDKError, EthosNamespace, memoryKeyStore, noopStore, } from "../src/index.js";
+import { serializeRecoveryFile } from "../src/internal/recovery-file.js";
+import { DEFAULT_SDK_ENDPOINTS } from "../src/endpoints.js";
+let fetchCalls = [];
+let savedFetch;
+function installFetchMock(handlers) {
+    savedFetch = globalThis.fetch;
+    fetchCalls = [];
+    globalThis.fetch = (async (input, init) => {
+        const url = String(input);
+        const method = init?.method ?? "GET";
+        const bodyText = typeof init?.body === "string"
+            ? init.body
+            : init?.body == null
+                ? null
+                : String(init.body);
+        const body = bodyText ? JSON.parse(bodyText) : null;
+        const call = { url, method, body };
+        fetchCalls.push(call);
+        for (const h of handlers) {
+            if (!url.includes(h.url))
+                continue;
+            if (h.rpcMethod && body?.method !== h.rpcMethod)
+                continue;
+            const out = h.respond(call);
+            const status = out.status ?? 200;
+            return new Response(JSON.stringify(out.json), {
+                status,
+                headers: { "content-type": "application/json" },
+            });
+        }
+        throw new Error(`unhandled fetch: ${method} ${url} (rpc: ${body?.method ?? "n/a"})`);
+    });
+}
+function uninstallFetchMock() {
+    if (savedFetch) {
+        globalThis.fetch = savedFetch;
+        savedFetch = undefined;
+    }
+    fetchCalls = [];
+}
+function makeAuth() {
+    return new AithosAuth({
+        authBaseUrl: "https://auth.test",
+        apiBaseUrl: "https://api.test",
+        fetch: (() => {
+            throw new Error("AithosAuth.fetch must not be called in these tests");
+        }),
+        sessionStore: noopStore(),
+        keyStore: memoryKeyStore(),
+    });
+}
+function makeNamespace(auth) {
+    return new EthosNamespace({
+        auth,
+        endpoints: DEFAULT_SDK_ENDPOINTS,
+        // EthosNamespace itself doesn't read fetch from this slot today;
+        // protocol-client uses the global fetch we mock above.
+        fetch: globalThis.fetch.bind(globalThis),
+    });
+}
+async function signInAsAlice(auth) {
+    const id = createBrowserIdentity("alice", "Alice");
+    const { text } = serializeRecoveryFile(id);
+    const info = await auth.signInWithRecovery({ file: text });
+    return { did: info.did };
+}
+function noEditionYetResponse() {
+    // Mirrors the server's primitives-read `notFound("edition for <did>")`:
+    // JSON-RPC error code -32020, message starts with "not found: edition for ".
+    return {
+        json: {
+            jsonrpc: "2.0",
+            id: "aithos.get_ethos_manifest",
+            error: {
+                code: -32020,
+                message: "not found: edition for did:aithos:zSomething",
+            },
+        },
+    };
+}
+function publishOkResponse() {
+    return {
+        json: {
+            jsonrpc: "2.0",
+            id: "publish_ethos_edition",
+            result: { ok: true, height: 1, manifest_uri: "s3://aithos/.../manifest.json" },
+        },
+    };
+}
+/* -------------------------------------------------------------------------- */
+/*  Tests                                                                     */
+/* -------------------------------------------------------------------------- */
+describe("EthosClient — fresh Ethos (no edition published yet)", () => {
+    beforeEach(() => {
+        fetchCalls = [];
+    });
+    afterEach(() => {
+        uninstallFetchMock();
+    });
+    it("zone(public).sections() returns [] when server says 'not found: edition'", async () => {
+        installFetchMock([
+            {
+                url: "/mcp/primitives/read",
+                rpcMethod: "aithos.get_ethos_manifest",
+                respond: noEditionYetResponse,
+            },
+        ]);
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        const sections = await me.zone("public").sections();
+        assert.deepEqual(sections, []);
+    });
+    it("zone(public).sections() reflects locally staged adds even when no edition exists", async () => {
+        installFetchMock([
+            {
+                url: "/mcp/primitives/read",
+                rpcMethod: "aithos.get_ethos_manifest",
+                respond: noEditionYetResponse,
+            },
+        ]);
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        me.zone("public").addSection({ title: "Hello", body: "World" });
+        const sections = await me.zone("public").sections();
+        assert.equal(sections.length, 1);
+        assert.equal(sections[0].title, "Hello");
+    });
+    it("publish() routes to publish_ethos_edition with height=1 on first publish", async () => {
+        let publishBody = null;
+        installFetchMock([
+            {
+                url: "/mcp/primitives/read",
+                rpcMethod: "aithos.get_ethos_manifest",
+                respond: noEditionYetResponse,
+            },
+            {
+                url: "/mcp/primitives/write",
+                rpcMethod: "aithos.publish_ethos_edition",
+                respond: (call) => {
+                    publishBody = call.body;
+                    return publishOkResponse();
+                },
+            },
+        ]);
+        const auth = makeAuth();
+        const alice = await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        me.zone("public").addSection({ title: "First", body: "Hello." });
+        me.zone("public").addSection({ title: "Second", body: "World." });
+        const r = await me.publish();
+        assert.equal(r.editionHeight, 1);
+        assert.equal(r.subjectDid, alice.did);
+        assert.deepEqual(r.zonesPublished, ["public"]);
+        // Verify the wire shape: JSON-RPC publish_ethos_edition with a height=1
+        // manifest containing both staged sections.
+        assert.equal(publishBody.method, "aithos.publish_ethos_edition");
+        const manifest = publishBody.params.manifest;
+        assert.equal(manifest.edition.height, 1);
+        assert.equal(manifest.edition.prev_hash, null);
+        assert.equal(manifest.edition.supersedes, null);
+        assert.deepEqual(manifest.zones.public.section_titles, ["First", "Second"]);
+        // Envelope is signed under #public.
+        const env = publishBody.params._envelope;
+        assert.equal(env.method, "aithos.publish_ethos_edition");
+        assert.match(env.proof.verificationMethod, /#public$/);
+    });
+    it("publish() rejects circle/self mutations on first edition", async () => {
+        installFetchMock([
+            {
+                url: "/mcp/primitives/read",
+                rpcMethod: "aithos.get_ethos_manifest",
+                respond: noEditionYetResponse,
+            },
+        ]);
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        me.zone("circle").addSection({ title: "Private", body: "..." });
+        await assert.rejects(() => me.publish(), (e) => e instanceof AithosSDKError && e.code === "ethos_first_edition_public_only");
+    });
+    it("publish() rejects update/delete operations on a fresh Ethos", async () => {
+        installFetchMock([
+            {
+                url: "/mcp/primitives/read",
+                rpcMethod: "aithos.get_ethos_manifest",
+                respond: noEditionYetResponse,
+            },
+        ]);
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        // Stage a delete for a section that doesn't exist (no edition exists at all).
+        me.zone("public")["_parent"]; // type-safety placeholder; we use the public API
+        // EthosZone exposes deleteSection — go via that.
+        me.zone("public").deleteSection("sec_doesnotexist000");
+        await assert.rejects(() => me.publish(), (e) => e instanceof AithosSDKError && e.code === "ethos_first_edition_invalid_op");
+    });
+    it("publish() surfaces server JSON-RPC errors as ethos_first_edition_rejected", async () => {
+        installFetchMock([
+            {
+                url: "/mcp/primitives/read",
+                rpcMethod: "aithos.get_ethos_manifest",
+                respond: noEditionYetResponse,
+            },
+            {
+                url: "/mcp/primitives/write",
+                rpcMethod: "aithos.publish_ethos_edition",
+                respond: () => ({
+                    json: {
+                        jsonrpc: "2.0",
+                        id: "publish_ethos_edition",
+                        error: {
+                            code: -32020,
+                            message: "subject identity not published (call publish_identity first)",
+                        },
+                    },
+                }),
+            },
+        ]);
+        const auth = makeAuth();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        me.zone("public").addSection({ title: "Hi", body: "There." });
+        await assert.rejects(() => me.publish(), (e) => e instanceof AithosSDKError && e.code === "ethos_first_edition_rejected");
+    });
+});
+//# sourceMappingURL=ethos-first-edition.test.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "description": "Aithos SDK — high-level TypeScript developer kit for building agentic apps on the Aithos protocol. Wraps @aithos/protocol-client and exposes the Aithos compute proxy and wallet (Stripe top-up) endpoints.",
   "keywords": [
     "aithos",
@@ -52,10 +52,10 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@aithos/protocol-client": ">=0.1.0-alpha.11 <0.2.0"
+    "@aithos/protocol-client": ">=0.1.0-alpha.12 <0.2.0"
   },
   "devDependencies": {
-    "@aithos/protocol-client": "^0.1.0-alpha.11",
+    "@aithos/protocol-client": "^0.1.0-alpha.12",
     "@types/node": "^24.12.2",
     "fake-indexeddb": "^6.2.5",
     "typescript": "^5.9.2"