@aithos/sdk 0.1.0-alpha.20 → 0.1.0-alpha.21

package/dist/src/ethos.d.ts

@@ -85,6 +85,53 @@ export declare class EthosZone {
     addSection(input: AddSectionInput): void;
     updateSection(sectionId: string, patch: UpdateSectionPatch): void;
     deleteSection(sectionId: string): void;
+    /**
+     * Return every section in this zone whose `title` is exactly `title`.
+     *
+     * Match is exact and case-sensitive. The result is always an array — it
+     * may be empty (no match), have one element (the typical case), or have
+     * more than one element when the author has happened to publish two
+     * sections with the same title. Section titles are not required by the
+     * protocol to be unique within a zone.
+     *
+     * The order of returned sections is the zone's authored order
+     * (`sections()` ordering, spec §2.5.2).
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     */
+    findSectionsByTitle(title: string): Promise<readonly Section[]>;
+    /**
+     * Stage an update for **every** section in this zone whose `title`
+     * matches `title` exactly. Returns the list of section IDs that were
+     * staged — empty when nothing matched.
+     *
+     * Apply with `client.publish()` like any other staged mutation. The
+     * staged entries are identical to what `updateSection(id, patch)` would
+     * produce, one per matched section, so `pendingChanges()` /
+     * `discard()` behave normally.
+     *
+     * Note: this method does NOT throw when there is no match — it returns
+     * `[]`. That's intentional: callers driven by an LLM frequently want to
+     * upsert (try update, then fall back to add) and shouldn't have to
+     * catch.
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     * @param patch Same patch shape accepted by `updateSection`.
+     * @returns Array of `section.id` strings whose updates were staged.
+     */
+    updateSectionsByTitle(title: string, patch: UpdateSectionPatch): Promise<readonly string[]>;
+    /**
+     * Stage a delete for **every** section in this zone whose `title`
+     * matches `title` exactly. Returns the list of section IDs that were
+     * staged — empty when nothing matched.
+     *
+     * Same semantics as {@link updateSectionsByTitle}: silent on no-match,
+     * apply with `client.publish()`.
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     * @returns Array of `section.id` strings whose deletes were staged.
+     */
+    deleteSectionsByTitle(title: string): Promise<readonly string[]>;
 }
 export interface EthosNamespaceDeps {
     readonly auth: AithosAuth;

package/dist/src/ethos.js

@@ -517,6 +517,89 @@ export class EthosZone {
     deleteSection(sectionId) {
         this.#parent._stageDelete(this.#name, sectionId);
     }
+    /* ------------------------------------------------------------------------ */
+    /*  By-title helpers                                                        */
+    /*                                                                          */
+    /*  The Aithos protocol does not (yet) treat section titles as a queryable  */
+    /*  index — only `section.id` is a normative anchor. These three methods    */
+    /*  are an ergonomic SDK-side affordance for the common LLM-driven case    */
+    /*  "act on the section called X". They resolve titles client-side by      */
+    /*  loading the full zone (`sections()`) and exact-match filtering on      */
+    /*  `Section.title`.                                                       */
+    /*                                                                          */
+    /*  When a future revision of `aithos.get_ethos_zone` (or a new            */
+    /*  `aithos.find_sections` primitive) supports server-side title           */
+    /*  filtering, the implementation behind these three methods can swap to   */
+    /*  the server call without changing the public signatures here. The      */
+    /*  contract — async, exact case-sensitive match, plural semantics — is    */
+    /*  intentionally aligned with what such an API would return.             */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Return every section in this zone whose `title` is exactly `title`.
+     *
+     * Match is exact and case-sensitive. The result is always an array — it
+     * may be empty (no match), have one element (the typical case), or have
+     * more than one element when the author has happened to publish two
+     * sections with the same title. Section titles are not required by the
+     * protocol to be unique within a zone.
+     *
+     * The order of returned sections is the zone's authored order
+     * (`sections()` ordering, spec §2.5.2).
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     */
+    async findSectionsByTitle(title) {
+        const all = await this.#parent._readZone(this.#name);
+        return all.filter((s) => s.title === title);
+    }
+    /**
+     * Stage an update for **every** section in this zone whose `title`
+     * matches `title` exactly. Returns the list of section IDs that were
+     * staged — empty when nothing matched.
+     *
+     * Apply with `client.publish()` like any other staged mutation. The
+     * staged entries are identical to what `updateSection(id, patch)` would
+     * produce, one per matched section, so `pendingChanges()` /
+     * `discard()` behave normally.
+     *
+     * Note: this method does NOT throw when there is no match — it returns
+     * `[]`. That's intentional: callers driven by an LLM frequently want to
+     * upsert (try update, then fall back to add) and shouldn't have to
+     * catch.
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     * @param patch Same patch shape accepted by `updateSection`.
+     * @returns Array of `section.id` strings whose updates were staged.
+     */
+    async updateSectionsByTitle(title, patch) {
+        const matches = await this.findSectionsByTitle(title);
+        const ids = [];
+        for (const s of matches) {
+            this.#parent._stageUpdate(this.#name, s.id, patch);
+            ids.push(s.id);
+        }
+        return ids;
+    }
+    /**
+     * Stage a delete for **every** section in this zone whose `title`
+     * matches `title` exactly. Returns the list of section IDs that were
+     * staged — empty when nothing matched.
+     *
+     * Same semantics as {@link updateSectionsByTitle}: silent on no-match,
+     * apply with `client.publish()`.
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     * @returns Array of `section.id` strings whose deletes were staged.
+     */
+    async deleteSectionsByTitle(title) {
+        const matches = await this.findSectionsByTitle(title);
+        const ids = [];
+        for (const s of matches) {
+            this.#parent._stageDelete(this.#name, s.id);
+            ids.push(s.id);
+        }
+        return ids;
+    }
 }
 export class EthosNamespace {
     #deps;

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0-alpha.19";
+export declare const VERSION = "0.1.0-alpha.21";
 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.19";
+export const VERSION = "0.1.0-alpha.21";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
 // Re-export protocol-client's JSON-RPC error type so consumers can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.21",
   "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",