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

package/dist/src/agent-tools.js

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/* ----------------------------------- read ---------------------------------- */
+export const TOOL_ETHOS_LIST_SECTIONS = "ethos_list_sections";
+export const TOOL_ETHOS_READ_SECTION = "ethos_read_section";
+export const TOOL_DATA_QUERY = "data_query";
+/* ---------------------------------- write ---------------------------------- */
+export const TOOL_ETHOS_ADD_SECTION = "ethos_add_section";
+export const TOOL_ETHOS_UPDATE_SECTION = "ethos_update_section";
+export const TOOL_ETHOS_DELETE_SECTION = "ethos_delete_section";
+/** The ethos zones a section can live in. */
+const ZONE_ENUM = ["public", "circle", "self"];
+export const AITHOS_AGENT_READ_TOOLS = [
+    {
+        name: TOOL_ETHOS_LIST_SECTIONS,
+        description: "Liste les sections disponibles de l'ethos de l'utilisateur (zone, id, " +
+            "titre), SANS leur contenu. À appeler en premier pour découvrir ce qui " +
+            "est lisible, puis utiliser ethos_read_section pour obtenir le détail.",
+        input_schema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: TOOL_ETHOS_READ_SECTION,
+        description: "Renvoie le contenu (titre + corps) d'une section de l'ethos, " +
+            "identifiée par son id obtenu via ethos_list_sections.",
+        input_schema: {
+            type: "object",
+            properties: {
+                section_id: { type: "string", description: "id de la section à lire" },
+            },
+            required: ["section_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: TOOL_DATA_QUERY,
+        description: "Renvoie les enregistrements d'une collection de données structurées " +
+            "de l'utilisateur (zone gamma).",
+        input_schema: {
+            type: "object",
+            properties: {
+                collection: { type: "string", description: "nom de la collection" },
+                limit: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 100,
+                    description: "nombre maximum d'enregistrements (défaut 20)",
+                },
+            },
+            required: ["collection"],
+            additionalProperties: false,
+        },
+    },
+];
+export const AITHOS_AGENT_WRITE_TOOLS = [
+    {
+        name: TOOL_ETHOS_ADD_SECTION,
+        description: "Ajoute une NOUVELLE section à l'ethos de l'utilisateur dans la zone " +
+            "indiquée. À n'utiliser que si l'information n'existe pas déjà (vérifier " +
+            "avec ethos_list_sections d'abord pour éviter les doublons). La " +
+            "modification est signée et publiée localement avec les clés de " +
+            "l'utilisateur.",
+        input_schema: {
+            type: "object",
+            properties: {
+                zone: {
+                    type: "string",
+                    enum: [...ZONE_ENUM],
+                    description: "zone de l'ethos : 'public' (visible de tous), 'circle' (cercle " +
+                        "de confiance), 'self' (privé). Choisir selon la sensibilité.",
+                },
+                title: { type: "string", description: "titre de la section" },
+                body: { type: "string", description: "contenu (texte) de la section" },
+            },
+            required: ["zone", "title", "body"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: TOOL_ETHOS_UPDATE_SECTION,
+        description: "Met à jour une section existante de l'ethos (titre et/ou corps), " +
+            "identifiée par son id (obtenu via ethos_list_sections). Ne modifier " +
+            "que ce qui doit changer.",
+        input_schema: {
+            type: "object",
+            properties: {
+                section_id: {
+                    type: "string",
+                    description: "id de la section à modifier",
+                },
+                title: { type: "string", description: "nouveau titre (optionnel)" },
+                body: { type: "string", description: "nouveau corps (optionnel)" },
+            },
+            required: ["section_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: TOOL_ETHOS_DELETE_SECTION,
+        description: "Supprime une section de l'ethos, identifiée par son id. Action " +
+            "irréversible une fois publiée — n'utiliser que si la suppression est " +
+            "explicitement justifiée.",
+        input_schema: {
+            type: "object",
+            properties: {
+                section_id: {
+                    type: "string",
+                    description: "id de la section à supprimer",
+                },
+            },
+            required: ["section_id"],
+            additionalProperties: false,
+        },
+    },
+];
+export const AITHOS_AGENT_TOOLS = [
+    ...AITHOS_AGENT_READ_TOOLS,
+    ...AITHOS_AGENT_WRITE_TOOLS,
+];
+const TOOL_BY_NAME = new Map(AITHOS_AGENT_TOOLS.map((t) => [t.name, t]));
+export function isWriteTool(name) {
+    return (name === TOOL_ETHOS_ADD_SECTION ||
+        name === TOOL_ETHOS_UPDATE_SECTION ||
+        name === TOOL_ETHOS_DELETE_SECTION);
+}
+/**
+ * Resolve the tool specs to forward to the proxy.
+ *
+ * - `undefined` / empty → the full catalogue (read + write).
+ * - a list of names → exactly those (unknown names ignored).
+ * - `{ readOnly: true }` → only the read family (a caller that wants a
+ *   strictly non-mutating agent).
+ */
+export function selectAgentTools(opts) {
+    if (opts?.readOnly)
+        return AITHOS_AGENT_READ_TOOLS;
+    const requested = opts?.tools;
+    if (!requested || requested.length === 0)
+        return AITHOS_AGENT_TOOLS;
+    const out = [];
+    for (const name of requested) {
+        const spec = TOOL_BY_NAME.get(name);
+        if (spec)
+            out.push(spec);
+    }
+    return out;
+}
+//# sourceMappingURL=agent-tools.js.map

package/dist/src/apps.d.ts

@@ -0,0 +1,224 @@
+import type { AithosAuth } from "./auth.js";
+import type { AithosSdkEndpoints } from "./endpoints.js";
+/**
+ * The audience set scopes which consumers are eligible. `"open"` lets
+ * any DID invoke the app; `"list"` restricts to an explicit allowlist.
+ */
+export type AudienceSet = "open" | "list";
+export interface SponsorshipBudgetInput {
+    /**
+     * Authority-interpreted unit of account. Default `"aithos.mc"` (the
+     * platform microcredit, ≈ €0.001 of AWS pass-through cost). Authorities
+     * MAY accept other units — see draft §13.3.4.
+     */
+    readonly unit?: string;
+    /** Lifetime cap per consumer, in `unit`. */
+    readonly perUserCap: number;
+    /** If set, the per-user cap applies over a sliding window. */
+    readonly perUserWindowSeconds?: number | null;
+    /** UTC-day cap on total sponsored consumption across all consumers. */
+    readonly perDayTotalCap: number;
+    /** Lifetime pool cap across all consumers. `null` ≡ no cap. */
+    readonly poolCapTotal?: number | null;
+}
+export interface SponsorshipAudienceInput {
+    /** App DID the sponsorship covers (typically `sdk.appDid`). */
+    readonly appDid: string;
+    readonly audienceSet: AudienceSet;
+    /** Required iff `audienceSet === "list"`. */
+    readonly consumers?: readonly string[];
+}
+export interface SponsorshipAccountingAuthorityInput {
+    readonly did: string;
+    readonly endpoint: string;
+}
+export interface CreateSponsorshipMandateArgs {
+    readonly audience: SponsorshipAudienceInput;
+    readonly scopes: readonly string[];
+    readonly allowedMethods: readonly string[];
+    readonly allowedModels?: readonly string[];
+    readonly budget: SponsorshipBudgetInput;
+    readonly accountingAuthority: SponsorshipAccountingAuthorityInput;
+    /** Defaults to now. */
+    readonly notBefore?: Date;
+    /** Defaults to 365 days. */
+    readonly ttlSeconds?: number;
+}
+/**
+ * Signed sponsorship mandate, ready to seed into the authority's
+ * `aithos-app-sponsorships` table. Same shape as
+ * `@aithos/protocol-core`'s `SponsorshipMandate`.
+ */
+export interface SignedSponsorshipMandate {
+    readonly "aithos-sponsorship-mandate": "0.1.0";
+    readonly id: string;
+    readonly issuer: string;
+    readonly issued_by_key: string;
+    readonly audience: {
+        readonly app_did: string;
+        readonly audience_set: AudienceSet;
+        readonly consumers?: readonly string[];
+    };
+    readonly scopes: readonly string[];
+    readonly allowed_methods: readonly string[];
+    readonly allowed_models?: readonly string[];
+    readonly budget: {
+        readonly unit: string;
+        readonly per_user_cap: number;
+        readonly per_user_window_seconds: number | null;
+        readonly per_day_total_cap: number;
+        readonly pool_cap_total: number | null;
+    };
+    readonly accounting_authority: {
+        readonly did: string;
+        readonly endpoint: string;
+    };
+    readonly not_before: string;
+    readonly not_after: string;
+    readonly issued_at: string;
+    readonly nonce: string;
+    readonly signature: {
+        readonly alg: "ed25519";
+        readonly key: string;
+        readonly value: string;
+    };
+}
+export interface SignedSponsorshipRevocation {
+    readonly "aithos-revocation": "0.1.0";
+    readonly mandate_id: string;
+    readonly mandate_kind: "sponsorship-mandate";
+    readonly issuer: string;
+    readonly issued_by_key: string;
+    readonly revoked_at: string;
+    readonly reason: string;
+    readonly signature: {
+        readonly alg: "ed25519";
+        readonly key: string;
+        readonly value: string;
+    };
+}
+export type AppCreditPackId = "app-credits-10k" | "app-credits-50k" | "app-credits-200k";
+export interface CreateAppTopupSessionArgs {
+    /** Which app-credits pack to purchase. */
+    readonly packId: AppCreditPackId;
+    /** Where Stripe redirects after a successful payment. */
+    readonly successUrl: string;
+    /** Where Stripe redirects if the user cancels. */
+    readonly cancelUrl: string;
+    /** Abort signal to cancel the request. */
+    readonly signal?: AbortSignal;
+}
+export interface CreateAppTopupSessionResult {
+    readonly checkoutUrl: string;
+    readonly sessionId: string;
+}
+export interface AppsNamespaceDeps {
+    readonly auth: AithosAuth;
+    readonly appDid: string;
+    readonly endpoints: AithosSdkEndpoints;
+    readonly fetch: typeof fetch;
+}
+export declare class AppsNamespace {
+    #private;
+    constructor(deps: AppsNamespaceDeps);
+    /**
+     * Build and sign a `SponsorshipMandate` as the calling owner. The
+     * returned JSON is signed by the owner's `#public` sphere key, ready
+     * to be seeded into the authority's `aithos-app-sponsorships` table.
+     *
+     * V0.1 has no server endpoint — get the row into DDB via:
+     *   1. `aws dynamodb put-item --table-name aithos-app-sponsorships
+     *      --item file://mandate.json` (raw), or
+     *   2. The ops bootstrap script in
+     *      `innoesate/aithos/platform/scripts/seed-sponsorship.mjs`
+     *      (planned for V0.2).
+     *
+     * Hash with `sponsorshipMandateHash()` from `@aithos/protocol-core`
+     * if you need to embed it in an envelope's `sponsorship.hash` field.
+     */
+    createSponsorshipMandate(args: CreateSponsorshipMandateArgs): Promise<SignedSponsorshipMandate>;
+    /**
+     * Build and sign a §4.6 revocation document targeting a sponsorship
+     * mandate. Same upload caveat as `createSponsorshipMandate`.
+     */
+    revokeSponsorshipMandate(mandate: SignedSponsorshipMandate, reason: string): Promise<SignedSponsorshipRevocation>;
+    /**
+     * Stripe Checkout session for an `app-credits-*` pack. The session is
+     * bound to the calling owner's DID (which is treated as the app's
+     * funding DID — Option A unified wallet, see plan §3.4).
+     *
+     * Same endpoint and auth pattern as `sdk.wallet.createTopupSession`,
+     * 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