@gemmein/sdk 0.7.0 → 0.9.0

package/dist/index.js

@@ -4,7 +4,7 @@
  *  second module). `scripts/sync-version.mjs` rewrites the literal from
  *  package.json before every build (`prebuild`), and a test pins the two
  *  equal, so a bump can never ship with a stale header. */
-export const SDK_VERSION = "0.7.0"; // synced from package.json — do not edit by hand
+export const SDK_VERSION = "0.9.0"; // synced from package.json — do not edit by hand
 /** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
  *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
  *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
@@ -375,14 +375,24 @@ export class CreditsClient {
     }
 }
 /**
- * The AI route. `chat` takes the provider's own request body — exactly what
- * you would POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages
- * or Google's generateContent — and answers with the fetch `Response`
- * untouched, streaming intact (SSE stays SSE). Gemmein spends one credit,
- * adds the owner's key, forwards, and passes status and bytes back.
- * Response headers: `x-gemmein-credits-remaining` on every answer that
- * passed the spend; `x-gemmein-credit: refunded` when the provider failed
- * before its first byte.
+ * The AI route. The primary path is a NAMED TOOL defined on the server:
+ * `run(name, inputs)` sends a name and inputs, the server composes the
+ * provider request from the tool's own instructions and template (never
+ * the browser), gates it, spends the tool's credits and streams the
+ * answer back; `runText` is the same call collected to one string;
+ * `calls()` is the signed-in person's own history. `chat` is the RAW
+ * call: it takes the provider's own request body — exactly what you would
+ * POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages or
+ * Google's generateContent — and answers with the fetch `Response`
+ * untouched, streaming intact (SSE stays SSE). Raw calls are off by
+ * default for every provider key (`raw_calls_off`, 403) until the founder
+ * switches them on for that key on the AI tools page. Gemmein spends a
+ * credit, adds the owner's key, forwards, and passes status and bytes
+ * back. Pass `tool` (W9.3b) to a raw call to price and gate it as a named
+ * tool instead of the implicit default (one credit, any allowed model, no
+ * gate). Response headers: `x-gemmein-credits-remaining` on every answer
+ * that passed the spend; `x-gemmein-credit: refunded` when the provider
+ * failed before its first byte.
  */
 export class AiClient {
     constructor(config) {
@@ -393,23 +403,34 @@ export class AiClient {
      *   for await (const chunk of res.body) { … }
      *
      * Browser sessions only — a server key is refused (`scope_denied`, 403).
-     * Refusals, all `GemmeinError`: `session_required` (401) ·
+     * Refusals, all `GemmeinError`: `raw_calls_off` (403 — raw calls are off
+     * for this provider until the founder switches them on for its key on
+     * the AI tools page; call a named tool with `run` instead) ·
+     * `session_required` (401) ·
      * `credits_exhausted` (402 — the message carries the balance; show your
      * own "buy more" door, which is a product checkout) · `ai_not_configured`
      * (409 — the owner has set no key) · `provider_required` (400) ·
      * `model_not_allowed` (403 — the owner's models list) · `ai_capped`
      * (429 — 20 calls a minute per person; `err.resetAt`) ·
      * `payload_too_large` (413 — 256 KB) · `provider_unreachable` (502,
-     * before the first byte, refunded). Those are GEMMEIN's refusals. The
-     * PROVIDER's own answer — 2xx or not — is returned as it came: an answer
-     * that carries `x-gemmein-credits-remaining` (or `x-gemmein-credit`)
-     * passed the spend, so its status and body are the provider's; read
-     * `res.ok` / `res.status` yourself (a provider 4xx before the first byte
-     * is refunded, header `x-gemmein-credit: refunded`).
+     * before the first byte, refunded). W9.3b, `tool` only: `unknown_tool`
+     * (404 — no tool by that name in this environment) · `tool_disabled`
+     * (403) · `entitlement_required` (403 — the message names the plan or
+     * product that unlocks it) · `model_pinned` (403 — the tool's model is
+     * fixed; leave `model` out of the body). Those are GEMMEIN's refusals.
+     * The PROVIDER's own answer — 2xx or not — is returned as it came: an
+     * answer that carries `x-gemmein-credits-remaining` passed the spend, so
+     * its status and body are the provider's; read `res.ok` / `res.status`
+     * yourself (a provider 4xx before the first byte is refunded, header
+     * `x-gemmein-credit: refunded`). `x-gemmein-tool` names the tool; absent
+     * on the implicit default.
      */
     async chat(body, options = {}) {
         const payload = options.provider ? { provider: options.provider, ...body } : body;
-        const response = await fetch(new URL("/ai/chat", this.config.apiUrl), {
+        const url = new URL("/ai/chat", this.config.apiUrl);
+        if (options.tool)
+            url.searchParams.set("tool", options.tool);
+        const response = await fetch(url, {
             method: "POST",
             body: JSON.stringify(payload),
             headers: await runtimeHeaders(this.config, { "content-type": "application/json" }),
@@ -431,6 +452,91 @@ export class AiClient {
         }
         return response;
     }
+    /**
+     * W9.6: run a named tool with INPUTS — the server composes the provider
+     * request from the tool's own instructions and template (never the
+     * browser), gates it, spends its credits and streams the answer back.
+     * The answer is the provider's own shape for the tool's provider (SSE
+     * when `stream`), so read it as you would `chat()`'s.
+     *
+     *   const res = await g.ai.run("summarise", { text }, { stream: true });
+     *
+     * Browser sessions only — a server key is refused (`scope_denied`, 403).
+     * Refusals, all `GemmeinError`: `session_required` (401 — sign in
+     * first) · `ai_capped` (429 — 20 calls a minute per person;
+     * `err.resetAt`) · `unknown_tool` (404 — no tool by that name in this
+     * environment) · `tool_disabled` (403 — the owner switched it off) ·
+     * `entitlement_required` (403 — the message names the plan or product
+     * it needs) · `payload_too_large` (413 — inputs over 64 KB) ·
+     * `invalid_body` (400 — the body must be a JSON object
+     * `{ inputs, stream? }`) · `invalid_inputs` (400 — the message names the
+     * input and the rule) · `tool_incomplete` (409 — the tool composes
+     * nothing; a founder's fix) · `ai_not_configured` (409 — the tool's
+     * provider has no key set; the owner pastes one) · `credits_exhausted`
+     * (402 — the message names the tool, its price and the balance) ·
+     * `provider_unreachable` (502 — no answer before the first byte; the
+     * tool's credits are refunded, header `x-gemmein-credit: refunded`).
+     * The provider's own answer — 2xx or not — is returned as it came; read
+     * `res.ok` yourself. `x-gemmein-tool` names the tool.
+     */
+    async run(tool, inputs = {}, options = {}) {
+        const url = new URL(`/ai/run/${encodeURIComponent(tool)}`, this.config.apiUrl);
+        const response = await fetch(url, {
+            method: "POST",
+            body: JSON.stringify({ inputs, ...(options.stream ? { stream: true } : {}) }),
+            headers: await runtimeHeaders(this.config, { "content-type": "application/json" }),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        if (!response.ok) {
+            if (isForwardedAnswer(response)) {
+                const peek = (await response.clone().json().catch(() => null));
+                if (peek?.code !== "provider_unreachable")
+                    return response;
+            }
+            const errorBody = await readErrorBody(response);
+            if (errorBody.code === "auth_expired")
+                await this.config.tokenStore.clear();
+            throw new GemmeinError({ status: response.status, ...errorBody });
+        }
+        return response;
+    }
+    /**
+     * W9.6: `run()` without a stream, as one string — the text lifted out
+     * of the tool's provider's answer (the same readers `text()` uses).
+     * `run()`'s refusals, plus: a provider's own non-2xx throws
+     * `provider_error` with the provider's status and message; an answer
+     * with no text to lift out throws `invalid_response` (status 0).
+     *
+     *   const summary = await g.ai.runText("summarise", { text });
+     */
+    async runText(tool, inputs = {}, options = {}) {
+        const response = await this.run(tool, inputs, options);
+        if (!response.ok) {
+            throw new GemmeinError({ status: response.status, code: "provider_error", message: await providerErrorMessage(response) });
+        }
+        const data = (await response.json());
+        const text = extractAiText(data);
+        if (text === null) {
+            throw new GemmeinError({ status: 0, code: "invalid_response", message: "the provider answered without any text — use g.ai.run() with { stream: true } and read the stream" });
+        }
+        return text;
+    }
+    /**
+     * W9.6 §16: the signed-in person's OWN AI calls, newest first — what they
+     * ran, when, what it cost, how it ended; the prompt and answer only where
+     * the tool keeps them. Session required.
+     *
+     *   const { calls, nextCursor } = await g.ai.calls();
+     */
+    async calls(options = {}) {
+        const params = new URLSearchParams();
+        if (options.limit)
+            params.set("limit", String(options.limit));
+        if (options.before)
+            params.set("before", options.before);
+        const query = params.toString();
+        return runtimeRequest(this.config, `/auth/ai-calls${query ? `?${query}` : ""}`);
+    }
     /**
      * The non-streaming convenience: one call, one string. Pass a body that
      * does NOT stream (`stream` unset or false); the provider's JSON answer is