@pouchy_ai/world-sdk 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @pouchy_ai/world-sdk
 
+## 0.12.0
+
+Additive: authoring joins the machine lane, so nothing in an integration needs
+a browser.
+
+- `createStoryPackage`, `publishStoryPackage`, `getStoryPackage`,
+  `listStoryPackages`, `createWorld`, `publishWorld`, `getWorld` and
+  `listWorlds` now go to the `/v1/admin` plane when `adminKey` is set, exactly
+  as the reads have since 0.10.0.
+- These admin equivalents have existed since Batch 1. The SDK simply never used
+  them, so authoring kept demanding `adminToken` — a Firebase ID token, minted
+  by a browser sign-in and good for about an hour — for operations a project
+  admin key could always perform.
+- **`conformance.mjs` runs on machine credentials now.** That is what this
+  release is for. The one check that proves a project's world plane is wired
+  correctly could not run without a person opening a browser first, which is
+  precisely what the rest of this SDK stopped requiring in 0.10.0. Set
+  `POUCHY_ADMIN_KEY`; `POUCHY_ADMIN_TOKEN` still works if you prefer it.
+- `adminToken` remains supported and unchanged. It is still the only credential
+  for the content loop (script drafts, editorial review), where a person is the
+  point rather than an obstacle.
+- No method changed shape.
+
 ## 0.11.0
 
 Additive: your backend can tell the world what it already knows. World API 1.8.

package/README.md

@@ -56,12 +56,13 @@ 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 |
+| `adminKey` (`pak_…`, long-lived) | author story packages and worlds; read the world: overview, state, timeline, turn read-back, metrics, delivery queue, cost | drive a turn, act on the delivery queue, run the content loop |
+| `adminToken` (Firebase ID token, ~1h) | everything above plus 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.
+A server holds `secretKey` + `signing` + `adminKey` and needs **no browser login
+anywhere in its deployment** — including `conformance.mjs`, which used to demand
+one. `adminToken` is for a person: the content loop's review step is a human
+decision, which is the point of it rather than an obstacle.
 
 ```ts
 const world = new PouchyWorldClient({

package/conformance.mjs

@@ -20,7 +20,7 @@
 // has to answer AND touch world state, which is the failure mode that matters
 // there (an NPC that chats without the world moving looks fine and is not).
 //
-//   POUCHY_PROJECT_ID=… POUCHY_ADMIN_TOKEN=… POUCHY_SECRET_KEY=… \
+//   POUCHY_PROJECT_ID=… POUCHY_ADMIN_KEY=… POUCHY_SECRET_KEY=… \
 //   POUCHY_SOURCE=… POUCHY_SOURCE_KID=… POUCHY_SOURCE_SECRET=… \
 //   POUCHY_AGENT_A=… POUCHY_AGENT_B=… node conformance.mjs [--scenario=drama|npc]
 
@@ -114,7 +114,17 @@ async function check(name, fn) {
 
 const world = new PouchyWorldClient({
 	projectId: env('POUCHY_PROJECT_ID'),
-	adminToken: env('POUCHY_ADMIN_TOKEN'),
+	// Batch 10: an ADMIN KEY is enough, and is the point.
+	//
+	// This harness used to demand POUCHY_ADMIN_TOKEN — a Firebase ID token,
+	// browser-minted and good for about an hour. So the one check that proves a
+	// project's world plane is wired correctly could not run without a person
+	// opening a browser first, which is exactly the thing the rest of this SDK
+	// stopped requiring. Either credential works now; the key is preferred and
+	// needs no human.
+	...(process.env.POUCHY_ADMIN_KEY
+		? { adminKey: process.env.POUCHY_ADMIN_KEY }
+		: { adminToken: env('POUCHY_ADMIN_TOKEN') }),
 	secretKey: env('POUCHY_SECRET_KEY'),
 	signing: {
 		source: env('POUCHY_SOURCE'),

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const WORLD_SDK_VERSION = "0.11.0";
+export declare const WORLD_SDK_VERSION = "0.12.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. */
@@ -784,12 +784,23 @@ export declare class PouchyWorldClient {
          *  dropped — you will hear about it, which is the point. */
         proposedPatches?: readonly Record<string, unknown>[];
     }): Promise<Record<string, unknown>>;
-    /** A world READ. Prefers the machine lane when an admin key is present.
+    /** A call that BOTH planes serve. 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. */
+     *  `ownerPath` and `adminPath` address the same operation through two doors,
+     *  and the server answers both from one shared implementation — 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,
+     *  which is also what makes it unable to address another project's work.
+     *
+     *  Batch 10 PR-B2.1 widened this from reads to AUTHORING. The admin
+     *  equivalents for story packages and world definitions have existed since
+     *  Batch 1; the SDK simply never used them, which left `createStoryPackage`
+     *  and friends demanding an hour-lived browser token for an operation a
+     *  machine key could always perform. `conformance.mjs` is the proof: it
+     *  could not run without a person opening a browser first. */
+    private machine;
+    /** A world READ through whichever door the caller holds. */
     private read;
     private owner;
     /** The machine lane: Secret Key AND a source signature over the EXACT bytes

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.11.0';
+export const WORLD_SDK_VERSION = '0.12.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 // ── errors ─────────────────────────────────────────────────────────────────
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
@@ -244,34 +244,34 @@ export class PouchyWorldClient {
     }
     // ── control plane (owner token) ──────────────────────────────────────────
     listStoryPackages() {
-        return this.owner('GET', `/projects/${this.projectId}/story-packages`);
+        return this.machine('GET', `/projects/${this.projectId}/story-packages`, '/admin/story-packages');
     }
     createStoryPackage(content) {
-        return this.owner('POST', `/projects/${this.projectId}/story-packages`, content);
+        return this.machine('POST', `/projects/${this.projectId}/story-packages`, '/admin/story-packages', content);
     }
     getStoryPackage(packageId) {
-        return this.owner('GET', `/projects/${this.projectId}/story-packages/${packageId}`);
+        return this.machine('GET', `/projects/${this.projectId}/story-packages/${packageId}`, `/admin/story-packages/${packageId}`);
     }
     /** Publish the next IMMUTABLE story revision. Idempotent on content: the
      *  same bytes return the existing revision rather than minting a twin. */
     publishStoryPackage(packageId, content) {
-        return this.owner('PATCH', `/projects/${this.projectId}/story-packages/${packageId}`, content);
+        return this.machine('PATCH', `/projects/${this.projectId}/story-packages/${packageId}`, `/admin/story-packages/${packageId}`, content);
     }
     listWorlds() {
-        return this.owner('GET', `/projects/${this.projectId}/environments`);
+        return this.machine('GET', `/projects/${this.projectId}/environments`, '/admin/environments');
     }
     createWorld(definition) {
-        return this.owner('POST', `/projects/${this.projectId}/environments`, definition);
+        return this.machine('POST', `/projects/${this.projectId}/environments`, '/admin/environments', definition);
     }
     getWorld(environmentId) {
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}`);
+        return this.machine('GET', `/projects/${this.projectId}/environments/${environmentId}`, `/admin/environments/${environmentId}`);
     }
     /** Publish the next world revision. Existing world INSTANCES keep the
      *  revision they were created on — a published change reaches new instances
      *  only, which is what keeps a running story from changing runtime or rules
      *  underneath its players. */
     publishWorld(environmentId, definition) {
-        return this.owner('PATCH', `/projects/${this.projectId}/environments/${environmentId}`, definition);
+        return this.machine('PATCH', `/projects/${this.projectId}/environments/${environmentId}`, `/admin/environments/${environmentId}`, definition);
     }
     getWorldState(environmentId, worldInstanceId) {
         return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/state`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/state`);
@@ -535,19 +535,33 @@ 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.
+    /** A call that BOTH planes serve. 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 = '') {
+     *  `ownerPath` and `adminPath` address the same operation through two doors,
+     *  and the server answers both from one shared implementation — 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,
+     *  which is also what makes it unable to address another project's work.
+     *
+     *  Batch 10 PR-B2.1 widened this from reads to AUTHORING. The admin
+     *  equivalents for story packages and world definitions have existed since
+     *  Batch 1; the SDK simply never used them, which left `createStoryPackage`
+     *  and friends demanding an hour-lived browser token for an operation a
+     *  machine key could always perform. `conformance.mjs` is the proof: it
+     *  could not run without a person opening a browser first. */
+    async machine(method, ownerPath, adminPath, body, query = '') {
         if (this.adminKey) {
-            return this.request('GET', `${adminPath}${query}`, {
-                headers: { authorization: `Bearer ${this.adminKey}` }
+            return this.request(method, `${adminPath}${query}`, {
+                headers: { authorization: `Bearer ${this.adminKey}` },
+                ...(body !== undefined ? { raw: JSON.stringify(body) } : {})
             });
         }
-        return this.owner('GET', `${ownerPath}${query}`);
+        return this.owner(method, `${ownerPath}${query}`, body);
+    }
+    /** A world READ through whichever door the caller holds. */
+    async read(ownerPath, adminPath, query = '') {
+        return this.machine('GET', ownerPath, adminPath, undefined, query);
     }
     async owner(method, path, body) {
         if (!this.adminToken) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/world-sdk",
-	"version": "0.11.0",
+	"version": "0.12.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",