@aithos/sdk 0.1.0-alpha.5 → 0.1.0-alpha.51

package/dist/src/endpoints.d.ts

@@ -10,11 +10,36 @@ export interface AithosSdkEndpoints {
      * suffixes a fixed path to it.
      */
     readonly wallet: string;
+    /**
+     * Web extractor proxy base URL — `aithos.web_extract`. Default
+     * `https://extract.aithos.be`. Same JSON-RPC + signed-envelope shape
+     * as the compute proxy, distinct audience so a mandate can hold one
+     * scope without the other.
+     */
+    readonly web: string;
+    /**
+     * Data PDS base URL — the `aithos.data.*` sub-protocol Personal Data Store.
+     * Default `https://pds.aithos.be`. Previously every app had to pass a raw
+     * `execute-api` URL to `createDataClient`; this centralizes it on the vanity
+     * domain (CloudFront-fronted, same as the other surfaces). Used by
+     * `createDataClient` / `createDelegateDataClient` / `createAppendDataClient`.
+     * Override for self-hosting or staging.
+     */
+    readonly pds: string;
+    /**
+     * Assets PDS base URL — the assets sub-protocol. This is a **separate** API
+     * Gateway from the data PDS (it exposes the same `/mcp/primitives/...` paths,
+     * so it needs its own host). Default `https://assets.aithos.be`. Used by
+     * `createAssetsClient`. Override for self-hosting or staging.
+     */
+    readonly assets: string;
 }
 /** Production defaults. */
 export declare const DEFAULT_SDK_ENDPOINTS: AithosSdkEndpoints;
 /** Compose the full compute-invoke URL: `${compute}/v1/invoke`. */
 export declare function computeInvokeUrl(endpoints: AithosSdkEndpoints): string;
+/** Compose the full web-extract URL: `${web}/v1/invoke`. */
+export declare function webInvokeUrl(endpoints: AithosSdkEndpoints): string;
 /** Compose the full top-up-checkout URL: `${wallet}/v1/wallet/topup/checkout`. */
 export declare function walletTopupCheckoutUrl(endpoints: AithosSdkEndpoints): string;
 /**

package/dist/src/endpoints.js

@@ -4,11 +4,18 @@
 export const DEFAULT_SDK_ENDPOINTS = {
     compute: "https://compute.aithos.be",
     wallet: "https://wallet.aithos.be",
+    web: "https://extract.aithos.be",
+    pds: "https://pds.aithos.be",
+    assets: "https://assets.aithos.be",
 };
 /** Compose the full compute-invoke URL: `${compute}/v1/invoke`. */
 export function computeInvokeUrl(endpoints) {
     return `${trimSlash(endpoints.compute)}/v1/invoke`;
 }
+/** Compose the full web-extract URL: `${web}/v1/invoke`. */
+export function webInvokeUrl(endpoints) {
+    return `${trimSlash(endpoints.web)}/v1/invoke`;
+}
 /** Compose the full top-up-checkout URL: `${wallet}/v1/wallet/topup/checkout`. */
 export function walletTopupCheckoutUrl(endpoints) {
     return `${trimSlash(endpoints.wallet)}/v1/wallet/topup/checkout`;

package/dist/src/ethos.d.ts

@@ -71,6 +71,44 @@ export declare class EthosClient {
      * so the next read picks up the fresh edition.
      */
     publish(): Promise<PublishResult>;
+    /**
+     * Idempotently ensure the subject's Ethos has at least one published
+     * edition. Required because a **delegate** cannot bootstrap a first
+     * edition (the first edition's manifest is signed with the owner's
+     * public-sphere key, which delegates do not have). Without an initial
+     * owner-published edition, subsequent delegate writes via
+     * {@link publish} fail with `not found: edition for did:…`.
+     *
+     * Semantics:
+     *   - If an edition already exists (owner OR delegate OR anonymous mode),
+     *     this is a NO-OP and returns `{ alreadyInitialized: true }`.
+     *   - If no edition exists AND the actor is the owner, this stages and
+     *     publishes a height=1 edition containing a single sentinel section
+     *     `aithos-init` in the `public` zone, then returns
+     *     `{ alreadyInitialized: false, editionHeight: 1 }`. Any previously
+     *     staged mutations on this client are preserved and NOT auto-flushed.
+     *   - If no edition exists AND the actor is NOT the owner (delegate or
+     *     anonymous), throws `ethos_bootstrap_not_owner` — only the owner
+     *     can sign a first edition.
+     *
+     * Call site: typically the owner's dashboard, right after sign-in and
+     * before any delegate-mode write (e.g. before triggering a backend
+     * worker that holds a mandate). Idempotent ⇒ safe to call on every
+     * mount.
+     *
+     * Implementation note: this routes through {@link #publishFirstEditionOwner}
+     * which the SDK already uses internally when {@link publish} detects a
+     * fresh Ethos with staged owner mutations. ensureInitialized() exposes
+     * the same code path as an explicit primitive, so the caller doesn't
+     * need to stage a mutation just to trigger first-edition logic.
+     */
+    ensureInitialized(): Promise<{
+        alreadyInitialized: true;
+    } | {
+        alreadyInitialized: false;
+        editionHeight: number;
+        manifestHash: string;
+    }>;
     _readZone(zone: ZoneName): Promise<readonly Section[]>;
     _stageAdd(zone: ZoneName, input: AddSectionInput): void;
     _stageUpdate(zone: ZoneName, sectionId: string, patch: UpdateSectionPatch): void;
@@ -85,6 +123,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;