@pouchy_ai/world-sdk 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @pouchy_ai/world-sdk
 
+## 0.10.0
+
+Additive: an unattended backend can now read its own world. World API 1.7.
+
+- New `adminKey` client option — a project admin key (`pak_…`), minted once from
+  the dashboard, long-lived and machine-held. When present, the world READS
+  (`getWorldState`, `listTurns`, `listTurnsSince`, `getTurn`, `getWorldMetrics`,
+  `listDeliveries`) go to a new `/v1/admin/environments/**` mirror instead of the
+  owner plane.
+- Why this exists: `adminToken` is a Firebase ID token — roughly an hour of life,
+  minted by a browser sign-in, with no API-key path. A backend could DRIVE a turn
+  with its own credentials (Secret Key + provider signature) and then needed a
+  human at a browser to find out what the turn did. Resuming after a crash was
+  the same story. That was the single thing keeping a sixty-minute integration
+  out of reach, and it was a credential gap, not a missing capability.
+- The mirror is reads only, and every route is GET. Driving a turn still needs
+  `secretKey` + `signing`: an admin key proves the PROJECT, never the Provider,
+  and the world's turn door requires both proofs. The delivery queue ACTIONS
+  (requeue, rehydrate, resolve-gap, drain), ledger archival, and the content loop
+  stay on `adminToken` — each decides something about a real reader's experience
+  of a story, or shortens the committed record.
+- Both doors answer from one shared server-side read, so which credential you
+  hold does not change the answer.
+- No existing method changed shape, and `adminToken` keeps working exactly as
+  before.
+
 ## 0.9.0
 
 Additive: the read-back becomes a real recovery path, and the timeline gets a

package/README.md

@@ -50,6 +50,34 @@ const world = new PouchyWorldClient({
 **Reading** — `getWorldState`, `getTurn`, `listTurns`, `listTurnsSince`,
 `replayLedger`, `replayLedgerToEnd`.
 
+**Which credential does what.** This matters more than it looks: one of them
+expires within the hour.
+
+| you hold | you can | you cannot |
+|---|---|---|
+| `secretKey` + `signing` | mint sessions, drive turns, send events | read anything back |
+| `adminKey` (`pak_…`, long-lived) | read the world: overview, state, timeline, turn read-back, metrics, delivery queue | drive a turn, act on the queue, author |
+| `adminToken` (Firebase ID token, ~1h) | everything above plus authoring and the content loop | outlive the hour |
+
+A server holds `secretKey` + `signing` + `adminKey` and needs no browser login
+anywhere in its deployment. `adminToken` is for a person, or for a script a
+person is watching.
+
+```ts
+const world = new PouchyWorldClient({
+  projectId: process.env.POUCHY_PROJECT_ID!,
+  secretKey: process.env.POUCHY_SECRET_KEY!,      // drive
+  adminKey:  process.env.POUCHY_ADMIN_KEY!,       // read back — does not expire
+  signing: { source: 'drama-backend', keyId: …, secret: … }
+});
+```
+
+An admin key proves the PROJECT, never the Provider, so it cannot drive a turn —
+the turn door requires a Secret Key *and* a signature over the exact bytes. And
+the delivery queue ACTIONS stay on `adminToken` on purpose: requeue, rehydrate
+and resolve-gap each decide what happens to a reader who is missing a beat, and
+resolve-gap tells them it is never coming.
+
 **Resuming after a crash.** `getTurn` returns the same fields the live result
 did — `nextOptions` included — so a recovered session can offer the audience
 the choices it was about to. To catch up on beats you missed entirely, store

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const WORLD_SDK_VERSION = "0.9.0";
+export declare const WORLD_SDK_VERSION = "0.10.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1";
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
  *  unrecognized status is never quietly folded into a neighbour. */
@@ -474,8 +474,23 @@ export interface WorldClientOptions {
     /** The project this client acts for. */
     projectId: string;
     /** An OWNER-plane credential (a signed-in admin's ID token) for the control
-     *  plane: story packages, world definitions, drafts, replay, reads. */
+     *  plane: story packages, world definitions, drafts, replay, reads.
+     *
+     *  Short-lived — a Firebase ID token, roughly an hour — and minted by a
+     *  browser sign-in. Fine for a script a person is watching; wrong for a
+     *  server. For a server, use `adminKey`. */
     adminToken?: string;
+    /** A project ADMIN key (`pak_…`), minted once from the dashboard.
+     *
+     *  Long-lived and machine-held: this is what an unattended backend uses.
+     *  When present, the world READS (overview, state, timeline, turn read-back,
+     *  metrics, deliveries) go to the `/admin` mirror instead of the owner
+     *  plane, and no browser login is involved anywhere in your deployment.
+     *
+     *  It proves the PROJECT, never the Provider, so it cannot drive a turn —
+     *  that still needs `secretKey` + `signing`. Authoring calls and the content
+     *  loop still need `adminToken`; see the README for which is which. */
+    adminKey?: string;
     /** A project Secret Key (`pchy_sk_…`) for the MACHINE lane: world sessions,
      *  turns and trusted events. It also carries the test/live axis. */
     secretKey?: string;
@@ -497,6 +512,7 @@ export declare class PouchyWorldClient {
     private readonly baseUrl;
     private readonly doFetch;
     private readonly adminToken?;
+    private readonly adminKey?;
     private readonly secretKey?;
     private readonly signing?;
     private readonly timeoutMs;
@@ -747,6 +763,13 @@ export declare class PouchyWorldClient {
         schemaVersion?: number;
         occurredAt?: number;
     }): Promise<Record<string, unknown>>;
+    /** A world READ. Prefers the machine lane when an admin key is present.
+     *
+     *  `ownerPath` and `adminPath` address the same read through two doors; the
+     *  server answers both from one shared function, so which door you came in
+     *  by does not change the answer. The admin door drops `projectId` from the
+     *  path because the key already names the project. */
+    private read;
     private owner;
     /** The machine lane: Secret Key AND a source signature over the EXACT bytes
      *  being sent — the two proofs the world requires of a backend. */

package/dist/index.js

@@ -17,7 +17,7 @@
 // SIGNING a request the way the server verifies it, and choosing turn ids that
 // make a retry idempotent instead of a second beat.
 import { createHash, createHmac, randomUUID } from 'node:crypto';
-export const WORLD_SDK_VERSION = '0.9.0';
+export const WORLD_SDK_VERSION = '0.10.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 // ── errors ─────────────────────────────────────────────────────────────────
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
@@ -222,6 +222,7 @@ export class PouchyWorldClient {
     baseUrl;
     doFetch;
     adminToken;
+    adminKey;
     secretKey;
     signing;
     timeoutMs;
@@ -233,6 +234,8 @@ export class PouchyWorldClient {
         this.doFetch = options.fetch ?? globalThis.fetch;
         if (options.adminToken !== undefined)
             this.adminToken = options.adminToken;
+        if (options.adminKey !== undefined)
+            this.adminKey = options.adminKey;
         if (options.secretKey !== undefined)
             this.secretKey = options.secretKey;
         if (options.signing !== undefined)
@@ -271,7 +274,7 @@ export class PouchyWorldClient {
         return this.owner('PATCH', `/projects/${this.projectId}/environments/${environmentId}`, definition);
     }
     getWorldState(environmentId, worldInstanceId) {
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/state`);
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/state`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/state`);
     }
     /** Read back a COMMITTED turn. The recovery path when a response was lost:
      *  it re-runs nothing, and a 404 means the turn never committed. */
@@ -282,7 +285,7 @@ export class PouchyWorldClient {
      *  same choices it would have. Rows committed before that carry none of the
      *  four turn-time facts: absent means UNKNOWN, never "none". */
     getTurn(environmentId, worldInstanceId, turnId) {
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/turns/${encodeURIComponent(turnId)}`);
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/turns/${encodeURIComponent(turnId)}`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/turns/${encodeURIComponent(turnId)}`);
     }
     /** Verify that the materialized state is what the committed ledger says.
      *  Always a dry run — it reports, it never repairs. Pass the previous
@@ -300,7 +303,7 @@ export class PouchyWorldClient {
         if (opts?.sinceSeq !== undefined)
             q.set('sinceSeq', String(opts.sinceSeq));
         const suffix = q.toString() ? `?${q}` : '';
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/turns${suffix}`);
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/turns`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/turns`, suffix);
     }
     /** Walk the timeline FORWARD from a revision already processed, following
      *  the cursor to the end. The resume primitive: a backend that stored the
@@ -355,7 +358,7 @@ export class PouchyWorldClient {
             if (v !== undefined)
                 q.set(k, String(v));
         const suffix = q.toString() ? `?${q}` : '';
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/deliveries${suffix}`);
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/deliveries`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/deliveries`, suffix);
     }
     /** One delivery. `includePayload` returns the line itself and writes an audit
      *  row naming you — pass it deliberately, not by default. */
@@ -411,7 +414,7 @@ export class PouchyWorldClient {
      *  kept apart because "the lines arrived" and "the world played well" are
      *  different questions. */
     getWorldMetrics(environmentId, worldInstanceId) {
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/metrics`);
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/metrics`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/metrics`);
     }
     /** Score the committed history against a quality suite. Deterministic — no
      *  model judges the output, so a score is something you can regress. */
@@ -527,9 +530,25 @@ export class PouchyWorldClient {
         return this.signed(`/projects/${this.projectId}/events`, body, eventId);
     }
     // ── transport ────────────────────────────────────────────────────────────
+    /** A world READ. Prefers the machine lane when an admin key is present.
+     *
+     *  `ownerPath` and `adminPath` address the same read through two doors; the
+     *  server answers both from one shared function, so which door you came in
+     *  by does not change the answer. The admin door drops `projectId` from the
+     *  path because the key already names the project. */
+    async read(ownerPath, adminPath, query = '') {
+        if (this.adminKey) {
+            return this.request('GET', `${adminPath}${query}`, {
+                headers: { authorization: `Bearer ${this.adminKey}` }
+            });
+        }
+        return this.owner('GET', `${ownerPath}${query}`);
+    }
     async owner(method, path, body) {
         if (!this.adminToken) {
-            throw new Error(`${method} ${path} needs an owner token (adminToken)`);
+            throw new Error(`${method} ${path} needs an owner token (adminToken) — or, for a world READ ` +
+                `from an unattended backend, a project admin key (adminKey), which routes ` +
+                `the read through the /admin mirror and does not expire`);
         }
         return this.request(method, path, {
             headers: { authorization: `Bearer ${this.adminToken}` },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/world-sdk",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"description": "Server-side TypeScript client for Pouchy World \u2014 story packages, world definitions, world sessions, coordinated turns, trusted events, replay verification and script drafts. Node only: it holds a project Secret Key and a source signing key, which never belong in a browser or a mobile app.",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",