@aithos/sdk 0.1.0-alpha.41 → 0.1.0-alpha.43

package/dist/src/apps.d.ts

@@ -151,5 +151,74 @@ export declare class AppsNamespace {
      * just with the app-credits pack id family.
      */
     createAppTopupSession(args: CreateAppTopupSessionArgs): Promise<CreateAppTopupSessionResult>;
+    /**
+     * Build, sign, and PUBLISH a SponsorshipMandate to the authority's
+     * `aithos-app-sponsorships` table via `aithos.sponsorship_create`.
+     *
+     * Combines local signing (see {@link createSponsorshipMandate}) with the
+     * server upload step. After this resolves, the sponsorship is active —
+     * the next `sdk.compute.invokeBedrock` call targeting `args.audience.appDid`
+     * may be sponsored (subject to caps).
+     *
+     * Requires that the calling owner is the registered `owner_did` of
+     * `args.audience.appDid` in `aithos-auth-apps`; otherwise the server
+     * rejects with `-32042` "not the owner".
+     */
+    publishSponsorship(args: CreateSponsorshipMandateArgs): Promise<{
+        mandate: SignedSponsorshipMandate;
+        sponsorshipId: string;
+        mandateHash: string;
+        status: "active";
+        createdAt: number;
+    }>;
+    /**
+     * Read the active sponsorship for an app. Open endpoint (no envelope
+     * required): the mandate is publicly signed and resolvable anyway.
+     *
+     * Returns `{ exists: false }` when no row exists for the app.
+     */
+    getSponsorship(args: {
+        appDid: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        exists: false;
+    } | {
+        exists: true;
+        sponsorshipId: string;
+        mandate: SignedSponsorshipMandate;
+        mandateHash: string;
+        status: "active" | "paused" | "depleted" | "expired" | "revoked";
+        poolConsumedLifetime: number;
+        createdAt: number;
+        lastUpdatedAt: number;
+    }>;
+    /**
+     * Revoke a published sponsorship by `app_did` + `sponsorship_id`. The
+     * row is marked `status: "revoked"` server-side; the routing cache is
+     * invalidated so the next compute call falls back to the user wallet.
+     */
+    revokeSponsorship(args: {
+        appDid: string;
+        sponsorshipId: string;
+        reason: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        status: "revoked";
+    }>;
+    /**
+     * Read the app's wallet balance (= the sponsor pool). Requires owner
+     * signature.
+     */
+    getAppWalletBalance(args: {
+        appDid: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        appDid: string;
+        exists: boolean;
+        balance: number;
+        balancePurchase: number;
+        balanceGrant: number;
+        dailySpent: number;
+    }>;
 }
 //# sourceMappingURL=apps.d.ts.map

package/dist/src/apps.js

@@ -25,8 +25,8 @@
 // a CloudFront-fronted read endpoint or direct DDB access. We'll add it
 // in V0.2 once the sponsorship-api Lambda exists; for now, devs check
 // their sponsorship via the AWS Console.
-import { base64url, sign } from "@aithos/protocol-client";
-import { walletTopupCheckoutUrl } from "./endpoints.js";
+import { base64url, buildSignedEnvelope, sign } from "@aithos/protocol-client";
+import { computeInvokeUrl, walletTopupCheckoutUrl } from "./endpoints.js";
 import { ownerKeyPair } from "./internal/protocol-client-bridge.js";
 import { AithosSDKError } from "./types.js";
 /* -------------------------------------------------------------------------- */
@@ -191,6 +191,161 @@ export class AppsNamespace {
         }
         return { checkoutUrl: ok.checkout_url, sessionId: ok.session_id };
     }
+    /**
+     * Build, sign, and PUBLISH a SponsorshipMandate to the authority's
+     * `aithos-app-sponsorships` table via `aithos.sponsorship_create`.
+     *
+     * Combines local signing (see {@link createSponsorshipMandate}) with the
+     * server upload step. After this resolves, the sponsorship is active —
+     * the next `sdk.compute.invokeBedrock` call targeting `args.audience.appDid`
+     * may be sponsored (subject to caps).
+     *
+     * Requires that the calling owner is the registered `owner_did` of
+     * `args.audience.appDid` in `aithos-auth-apps`; otherwise the server
+     * rejects with `-32042` "not the owner".
+     */
+    async publishSponsorship(args) {
+        const mandate = await this.createSponsorshipMandate(args);
+        const result = await this.#signedRpc({
+            method: "aithos.sponsorship_create",
+            params: { mandate },
+        });
+        return {
+            mandate,
+            sponsorshipId: result.sponsorship_id,
+            mandateHash: result.mandate_hash,
+            status: result.status,
+            createdAt: result.created_at,
+        };
+    }
+    /**
+     * Read the active sponsorship for an app. Open endpoint (no envelope
+     * required): the mandate is publicly signed and resolvable anyway.
+     *
+     * Returns `{ exists: false }` when no row exists for the app.
+     */
+    async getSponsorship(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const url = computeInvokeUrl(endpoints);
+        let res;
+        try {
+            res = await fetchImpl(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: "aithos.sponsorship_get",
+                    method: "aithos.sponsorship_get",
+                    params: { app_did: args.appDid },
+                }),
+                ...(args.signal ? { signal: args.signal } : {}),
+            });
+        }
+        catch (e) {
+            throw new AithosSDKError("network", e.message);
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new AithosSDKError(String(body.error.code), body.error.message);
+        }
+        const r = body.result ?? {};
+        if (r.exists === false || !r.exists) {
+            return { exists: false };
+        }
+        return {
+            exists: true,
+            sponsorshipId: r.sponsorship_id,
+            mandate: r.mandate,
+            mandateHash: r.mandate_hash,
+            status: r.status,
+            poolConsumedLifetime: r.pool_consumed_lifetime ?? 0,
+            createdAt: r.created_at ?? 0,
+            lastUpdatedAt: r.last_updated_at ?? 0,
+        };
+    }
+    /**
+     * Revoke a published sponsorship by `app_did` + `sponsorship_id`. The
+     * row is marked `status: "revoked"` server-side; the routing cache is
+     * invalidated so the next compute call falls back to the user wallet.
+     */
+    async revokeSponsorship(args) {
+        const result = await this.#signedRpc({
+            method: "aithos.sponsorship_revoke",
+            params: {
+                app_did: args.appDid,
+                sponsorship_id: args.sponsorshipId,
+                reason: args.reason,
+            },
+            ...(args.signal ? { signal: args.signal } : {}),
+        });
+        return result;
+    }
+    /**
+     * Read the app's wallet balance (= the sponsor pool). Requires owner
+     * signature.
+     */
+    async getAppWalletBalance(args) {
+        const result = await this.#signedRpc({
+            method: "aithos.app_wallet_get_balance",
+            params: { app_did: args.appDid },
+            ...(args.signal ? { signal: args.signal } : {}),
+        });
+        return {
+            appDid: result.app_did,
+            exists: result.exists,
+            balance: result.balance,
+            balancePurchase: result.balance_purchase,
+            balanceGrant: result.balance_grant,
+            dailySpent: result.daily_spent,
+        };
+    }
+    /**
+     * Internal: sign an envelope with the calling owner's `#public` sphere
+     * and POST a JSON-RPC request to the compute proxy. Used by the
+     * sponsorship CRUD methods above. Mirrors `ComputeNamespace.#signAndPost`.
+     */
+    async #signedRpc(opts) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const owner = this.#requireOwner();
+        const publicKp = ownerKeyPair(owner, "public");
+        const url = computeInvokeUrl(endpoints);
+        const envelope = buildSignedEnvelope({
+            iss: owner.did,
+            aud: url,
+            method: opts.method,
+            verificationMethod: `${owner.did}#public`,
+            params: opts.params,
+            signer: publicKp,
+        });
+        let res;
+        try {
+            res = await fetchImpl(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: opts.method,
+                    method: opts.method,
+                    params: { ...opts.params, _envelope: envelope },
+                }),
+                ...(opts.signal ? { signal: opts.signal } : {}),
+            });
+        }
+        catch (e) {
+            throw new AithosSDKError("network", e.message);
+        }
+        if (!res.ok) {
+            throw new AithosSDKError("http", `HTTP ${res.status} ${res.statusText}`, { status: res.status });
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new AithosSDKError(String(body.error.code), body.error.message, body.error.data ? { data: body.error.data } : undefined);
+        }
+        if (body.result === undefined) {
+            throw new AithosSDKError("empty", `empty result for ${opts.method}`);
+        }
+        return body.result;
+    }
     #requireOwner() {
         const owner = this.#deps.auth._getOwnerSigners();
         if (!owner || owner.destroyed) {

package/dist/src/ethos.js

@@ -485,38 +485,72 @@ export class EthosClient {
      * 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`.
+     * mutations 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.
+     * Behaviour:
+     *   - All three zones (public / circle / self) are supported at
+     *     height=1 since `@aithos/protocol-client@>=0.1.0-alpha.14`. Circle
+     *     and self sections are sealed via the same DEK + HKDF wrap
+     *     machinery that the height>=2 path uses, so they're verifiable by
+     *     the existing reader path with no special-casing.
+     *   - If the caller staged only circle / self mutations (typical for
+     *     an app like Linkedone that writes a personality section straight
+     *     to `circle`), an `aithos-init` sentinel is auto-injected into
+     *     the public zone. This preserves the invariant that every Ethos
+     *     has a non-empty public zone at height=1 — which all resolution
+     *     flows (handle lookup, public crawl) depend on.
      *   - 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`.
+     *   - The `ethos_first_edition_public_only` error code is no longer
+     *     emitted; the bucket-and-auto-inject path replaces it.
      */
     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.
+        // Validate the staged operation set and bucket by zone. First
+        // edition = ADD mutations only; update / delete are rejected because
+        // there's no prior state to mutate.
         const publicAdds = [];
+        const circleAdds = [];
+        const selfAdds = [];
         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) {
+            if (m.zone === "public")
+                publicAdds.push(m.section);
+            else if (m.zone === "circle")
+                circleAdds.push(m.section);
+            else if (m.zone === "self")
+                selfAdds.push(m.section);
+        }
+        if (publicAdds.length === 0 &&
+            circleAdds.length === 0 &&
+            selfAdds.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");
+            throw new AithosSDKError("ethos_first_edition_empty", "first edition: stage at least one section before publishing");
+        }
+        // Public zone invariant: every Ethos has a non-empty public zone at
+        // height=1. If the caller only staged encrypted-zone mutations
+        // (typical for apps like Linkedone that write straight to circle),
+        // auto-inject an `aithos-init` sentinel — identical in shape to
+        // what `ensureInitialized()` would produce if called explicitly.
+        if (publicAdds.length === 0) {
+            publicAdds.push({
+                id: "sec_" + randomHex(12),
+                title: "aithos-init",
+                body: "Ethos initialized.\n\n" +
+                    "This section is a sentinel created by `EthosClient.publish()` " +
+                    "to materialise the subject's first edition alongside the " +
+                    "encrypted-zone content the caller staged. It is safe to delete " +
+                    "or edit later — its only purpose is to satisfy the invariant " +
+                    "that every Ethos has a non-empty public zone at height=1.",
+                gamma_ref: "gamma_none_" + randomHex(24),
+            });
         }
         const identity = this.#actor.signers._unsafeStoredIdentity();
         const browserId = browserIdentityFromStored(identity);
@@ -524,14 +558,27 @@ export class EthosClient {
         const built = buildSignedFirstEditionFromSections({
             identity: browserId,
             signedDidDoc: signedDoc,
-            publicSections: publicAdds.map((a) => a.section),
+            publicSections: publicAdds,
+            ...(circleAdds.length > 0 ? { circleSections: circleAdds } : {}),
+            ...(selfAdds.length > 0 ? { selfSections: selfAdds } : {}),
         });
         const url = writeEndpoint();
+        const zonesPayload = {
+            public: { bytes_base64: bytesToBase64Padded(built.publicMarkdownBytes) },
+        };
+        if (built.circleBytes) {
+            zonesPayload.circle = {
+                bytes_base64: bytesToBase64Padded(built.circleBytes),
+            };
+        }
+        if (built.selfBytes) {
+            zonesPayload.self = {
+                bytes_base64: bytesToBase64Padded(built.selfBytes),
+            };
+        }
         const params = {
             manifest: built.manifest,
-            zones: {
-                public: { bytes_base64: bytesToBase64Padded(built.publicMarkdownBytes) },
-            },
+            zones: zonesPayload,
         };
         const envelope = buildSignedEnvelope({
             iss: browserId.did,
@@ -575,11 +622,16 @@ export class EthosClient {
         // take the regular next-edition path.
         this.#ethosHasNoEditionYet = false;
         this.#afterPublish();
+        const zonesPublished = ["public"];
+        if (built.circleBytes)
+            zonesPublished.push("circle");
+        if (built.selfBytes)
+            zonesPublished.push("self");
         return {
             editionHeight: 1,
             manifestHash: "", // protocol-client surfaces this on later editions; not on first
             subjectDid: browserId.did,
-            zonesPublished: ["public"],
+            zonesPublished,
         };
     }
 }

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0-alpha.41";
+export declare const VERSION = "0.1.0-alpha.43";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 export { AithosSDKError } from "./types.js";

package/dist/src/index.js

@@ -17,7 +17,7 @@
 // Public types specific to the SDK (`AithosSDKConfig`, `AithosSDKError`)
 // are exported from here. Endpoint config (`AithosSdkEndpoints`,
 // `DEFAULT_SDK_ENDPOINTS`) likewise.
-export const VERSION = "0.1.0-alpha.41";
+export const VERSION = "0.1.0-alpha.43";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
 // Re-export protocol-client's JSON-RPC error type so consumers can

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

@@ -185,19 +185,142 @@ describe("EthosClient — fresh Ethos (no edition published yet)", () => {
         assert.equal(env.method, "aithos.publish_ethos_edition");
         assert.match(env.proof.verificationMethod, /#public$/);
     });
-    it("publish() rejects circle/self mutations on first edition", async () => {
+    it("publish() accepts circle mutations on first edition with auto-injected public sentinel", async () => {
+        // Regression target: this used to throw `ethos_first_edition_public_only`.
+        // Since aithos-sdk@0.1.0-alpha.43 + protocol-client@0.1.0-alpha.14, the
+        // SDK auto-injects an `aithos-init` public section and seals the circle
+        // sections in the same height=1 manifest.
+        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();
         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");
+        const r = await me.publish();
+        assert.equal(r.editionHeight, 1);
+        assert.deepEqual(r.zonesPublished, ["public", "circle"]);
+        const manifest = publishBody.params.manifest;
+        assert.equal(manifest.edition.height, 1);
+        assert.equal(manifest.edition.prev_hash, null);
+        // Auto-injected sentinel.
+        assert.deepEqual(manifest.zones.public.section_titles, ["aithos-init"]);
+        assert.equal(manifest.zones.public.encrypted, false);
+        // Sealed circle zone.
+        assert.deepEqual(manifest.zones.circle.section_titles, ["Private"]);
+        assert.equal(manifest.zones.circle.encrypted, true);
+        assert.ok(manifest.zones.circle.cipher, "circle cipher must be present");
+        // Both zones uploaded.
+        assert.ok(publishBody.params.zones.public?.bytes_base64);
+        assert.ok(publishBody.params.zones.circle?.bytes_base64);
+        assert.equal(publishBody.params.zones.self, undefined);
+    });
+    it("publish() preserves the caller's explicit public section when mixed with circle", async () => {
+        // When the caller stages BOTH a public and a circle add, the SDK
+        // must NOT inject a sentinel — the user's public section is enough.
+        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();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        me.zone("public").addSection({ title: "About", body: "Public bio." });
+        me.zone("circle").addSection({ title: "Notes", body: "Private notes." });
+        const r = await me.publish();
+        assert.deepEqual(r.zonesPublished, ["public", "circle"]);
+        const manifest = publishBody.params.manifest;
+        // No sentinel — the user's section is the public titles entry.
+        assert.deepEqual(manifest.zones.public.section_titles, ["About"]);
+        assert.deepEqual(manifest.zones.circle.section_titles, ["Notes"]);
+    });
+    it("publish() auto-injects public sentinel when only self mutations are staged", 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();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        me.zone("self").addSection({ title: "Journal", body: "Private." });
+        const r = await me.publish();
+        assert.deepEqual(r.zonesPublished, ["public", "self"]);
+        const manifest = publishBody.params.manifest;
+        assert.deepEqual(manifest.zones.public.section_titles, ["aithos-init"]);
+        assert.deepEqual(manifest.zones.self.section_titles, ["Journal"]);
+        assert.equal(manifest.zones.self.encrypted, true);
+        assert.equal(manifest.zones.circle, undefined);
+    });
+    it("publish() lands public + circle + self in a single height=1 edition", 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();
+        await signInAsAlice(auth);
+        const me = makeNamespace(auth).me();
+        me.zone("public").addSection({ title: "Bio", body: "Bio body." });
+        me.zone("circle").addSection({ title: "Circle", body: "Circle body." });
+        me.zone("self").addSection({ title: "Self", body: "Self body." });
+        const r = await me.publish();
+        assert.equal(r.editionHeight, 1);
+        assert.deepEqual(r.zonesPublished, ["public", "circle", "self"]);
+        const manifest = publishBody.params.manifest;
+        assert.deepEqual(manifest.zones.public.section_titles, ["Bio"]);
+        assert.deepEqual(manifest.zones.circle.section_titles, ["Circle"]);
+        assert.deepEqual(manifest.zones.self.section_titles, ["Self"]);
+        assert.ok(publishBody.params.zones.public?.bytes_base64);
+        assert.ok(publishBody.params.zones.circle?.bytes_base64);
+        assert.ok(publishBody.params.zones.self?.bytes_base64);
     });
     it("publish() rejects update/delete operations on a fresh Ethos", async () => {
         installFetchMock([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.41",
+  "version": "0.1.0-alpha.43",
   "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",
@@ -56,8 +56,8 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@aithos/protocol-client": ">=0.1.0-alpha.13 <0.2.0",
     "@aithos/assets-crypto": ">=0.1.0-alpha.1 <0.2.0",
+    "@aithos/protocol-client": "^0.1.0-alpha.14",
     "react": "^18.0.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
@@ -69,7 +69,8 @@
     }
   },
   "devDependencies": {
-    "@aithos/protocol-client": "^0.1.0-alpha.13",
+    "@aithos/assets-crypto": "^0.1.0-alpha.1",
+    "@aithos/protocol-client": "^0.1.0-alpha.14",
     "@types/node": "^24.12.2",
     "fake-indexeddb": "^6.2.5",
     "typescript": "^5.9.2"