@aithos/sdk 0.1.0-alpha.4 → 0.1.0-alpha.40

package/dist/src/endpoints.js

@@ -4,11 +4,16 @@
 export const DEFAULT_SDK_ENDPOINTS = {
     compute: "https://compute.aithos.be",
     wallet: "https://wallet.aithos.be",
+    web: "https://extract.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

@@ -1,2 +1,203 @@
-export { parsePublicZone, type ParsedZone, loadEditSnapshot, publishZoneEdit, publishPublicZoneAsDelegate, publishPrivateZoneAsDelegate, type EditSnapshot, type AddSectionInput, type ModifySectionInput, type PublishEditArgs, type PublishEditResult, addSectionToList, modifySectionInList, deleteSectionFromList, buildSignedFirstEdition, buildSignedNextEdition, type ZoneDoc, type ZoneManifest, type Section, SPHERES, type Sphere, } from "@aithos/protocol-client";
+import { type Section } from "@aithos/protocol-client";
+import type { AithosAuth } from "./auth.js";
+import type { AithosSdkEndpoints } from "./endpoints.js";
+import type { DelegateActor } from "./internal/delegate-state.js";
+import type { OwnerSigners } from "./internal/owner-signers.js";
+export type ZoneName = "public" | "circle" | "self";
+export declare const ZONE_NAMES: readonly ZoneName[];
+export interface AddSectionInput {
+    readonly title: string;
+    readonly body: string;
+    readonly tags?: readonly string[];
+}
+export interface UpdateSectionPatch {
+    readonly title?: string;
+    readonly body?: string;
+    readonly tags?: readonly string[];
+}
+export type StagedChange = {
+    readonly kind: "add";
+    readonly zone: ZoneName;
+    readonly section: Section;
+} | {
+    readonly kind: "update";
+    readonly zone: ZoneName;
+    readonly sectionId: string;
+    readonly patch: UpdateSectionPatch;
+} | {
+    readonly kind: "delete";
+    readonly zone: ZoneName;
+    readonly sectionId: string;
+};
+export interface PublishResult {
+    /** New manifest height after publish. */
+    readonly editionHeight: number;
+    /** SHA-256 hex of the canonical manifest. */
+    readonly manifestHash: string;
+    /** DID of the subject we published for. */
+    readonly subjectDid: string;
+    /** Zones whose contents changed in this edition. */
+    readonly zonesPublished: readonly ZoneName[];
+}
+type ActorOwner = {
+    readonly kind: "owner";
+    readonly subjectDid: string;
+    readonly signers: OwnerSigners;
+};
+type ActorDelegate = {
+    readonly kind: "delegate";
+    readonly subjectDid: string;
+    readonly actor: DelegateActor;
+};
+type ActorAnonymous = {
+    readonly kind: "anonymous";
+    readonly subjectDid: string;
+};
+type Actor = ActorOwner | ActorDelegate | ActorAnonymous;
+export declare class EthosClient {
+    #private;
+    readonly subjectDid: string;
+    readonly mode: Actor["kind"];
+    constructor(actor: Actor);
+    /** Return the per-zone proxy. */
+    zone(name: ZoneName): EthosZone;
+    hasPendingChanges(): boolean;
+    pendingChanges(): readonly StagedChange[];
+    discard(): void;
+    /**
+     * Build and publish a new edition with all staged mutations applied.
+     * Throws if there's nothing staged. After a successful publish, the
+     * mutation buffer is cleared and any cached snapshot is invalidated
+     * 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;
+    _stageDelete(zone: ZoneName, sectionId: string): void;
+}
+export declare class EthosZone {
+    #private;
+    constructor(parent: EthosClient, name: ZoneName);
+    get name(): ZoneName;
+    /** Effective sections (persisted + staged mutations applied). */
+    sections(): Promise<readonly Section[]>;
+    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;
+    readonly endpoints: AithosSdkEndpoints;
+    readonly fetch: typeof fetch;
+}
+export declare class EthosNamespace {
+    #private;
+    constructor(deps: EthosNamespaceDeps);
+    /**
+     * EthosClient for the currently signed-in owner. Throws if there is
+     * no owner — callers should check `auth.canSignAsOwner()` first or
+     * surface the error to the user as "please sign in".
+     */
+    me(): EthosClient;
+    /**
+     * EthosClient for an arbitrary subject DID. The mode is resolved at
+     * construction time:
+     *   - if `did` matches the currently signed-in owner → owner mode
+     *   - else if a mandate held by `auth` covers this subject → delegate mode
+     *   - else → anonymous read-only mode
+     *
+     * Async signature so future implementations may do an eager manifest
+     * fetch (e.g. to fail fast on unknown DIDs); today resolution is sync
+     * and the actual fetch happens on the first `sections()` / `publish()`
+     * call.
+     */
+    of(did: string): Promise<EthosClient>;
+}
+export {};
 //# sourceMappingURL=ethos.d.ts.map