@pouchy_ai/world-sdk 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @pouchy_ai/world-sdk
 
+## 0.13.0
+
+- `createWorldSession` now returns a typed `WorldSessionResponse` instead of
+  `Record<string, unknown>`. The wire fields are unchanged — this names what the
+  server has always sent.
+- **The field is `session_token`, not `token`.** The untyped return let that
+  mistake compile: `conformance.mjs` asserted `session.token`, which the server
+  has never sent, so the session check threw against any real server while every
+  local gate stayed green. Typing the response is what stops it recurring; the
+  runner and both quickstarts were corrected to match.
+- `release-check.mjs` now compares `WORLD_SDK_VERSION` against the version of
+  the package it actually INSTALLED. The constant sat at `0.1.0` for eight
+  releases while the package shipped 0.8.0, so every request reported the wrong
+  client in its `user-agent`; the drift was corrected in 0.12.0, and this is the
+  gate that stops it recurring.
+- No method changed shape, and no request or response bytes changed.
+
+## 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.
@@ -31,7 +71,7 @@ Additive: your backend can tell the world what it already knows. World API 1.8.
 
 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
+- New `adminKey` client option — a project admin key (`pchy_admin_…`), 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

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` (`pchy_admin_…`, 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({
@@ -156,16 +157,46 @@ an `approved` editorial can be exported.
 `newTurnId` / `isReservedTurnId` (idempotency), `describeTurn` (read a result
 without guessing), `WorldApiError` with typed codes and `.retryable`.
 
+## When a signed door refuses you
+
+All three signed doors answer one uniform 403 on a bad signature — they will
+never tell you which of the four things is wrong, because an endpoint that
+names the failing credential is an oracle. The reason lives in the project's own
+audit trail instead:
+
+```
+GET https://pouchy.ai/v1/projects/{projectId}/environments/{envId}/preflight
+Authorization: Bearer <OwnerToken>
+```
+
+**That is an OwnerToken — a signed-in project admin's Firebase ID token, not the
+Secret Key this client holds**, and not the Admin key either (preflight is
+deliberately absent from the `/admin` mirror). There is no SDK method for it for
+the same reason: it answers a question a developer asks once while looking at
+the dashboard, not one a backend asks in a loop.
+
+It returns the recent refusals with a closed reason vocabulary — `missing`,
+`malformed`, `unknown_key`, `stale`, `bad_signature`, `no_keys` — plus how many
+audit rows it scanned, because an empty feed is not a clean bill of health.
+
+`docs/world-sdk-errors.md` in the Pouchy repo maps every reason and every
+`WorldApiError` code to what to change.
+
 ## The three things integrators get wrong
 
 **1. Turn ids are the idempotency key.** Mint one per BEAT and re-send the same
 one to retry. A new id is a new beat: it will run the models again and commit
 again. `newTurnId()` exists so this is a deliberate choice rather than a habit.
 
-**2. Sign the bytes you send.** `signSourceRequest` hashes the exact body
-string. Serializing twice — once to sign, once to send — signs bytes you did
-not send, and the server will (correctly) refuse them. This client always signs
-the string it is about to write.
+**2. Sign the bytes you send, with the door's own id slot.** `signSourceRequest`
+hashes the exact body string. Serializing twice — once to sign, once to send —
+signs bytes you did not send, and the server will (correctly) refuse them. This
+client always signs the string it is about to write. The fourth canonical line
+is the ID SLOT, and it differs per door: `turnId` on the turns door, `eventId`
+on `/events`, and the body's own `world.request_id` on `/sessions` — a session
+mint has neither a turn nor an event. `createWorldSession` passes it for you; if you
+are signing by hand there, an invented or empty id verifies locally and comes
+back `bad_signature`, which reads exactly like a wrong secret.
 
 **3. Execution and delivery are different questions.** `executionStatus` says
 whether the world moved; `deliveryStatus` says whether the audience has heard

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'),
@@ -174,9 +184,12 @@ await check('session mint binds one user to one role (machine lane)', async () =
 		role: scenario.leadRole,
 		externalUserId: `conformance-${scenarioName}-${stamp}`
 	});
-	instanceId = session?.world?.instance ?? session?.world?.world_instance;
+	// The wire names, exactly as the server sends them (`WorldSessionResponse`).
+	// This check used to read `session.token`, which the server has never sent —
+	// so it threw against every real server while every local gate stayed green.
+	instanceId = session?.world?.instance;
 	if (!instanceId) throw new Error('no world instance in the session payload');
-	if (!session.token) throw new Error('no session token minted');
+	if (!session?.session_token) throw new Error('no session token minted (expected session_token)');
 	return instanceId;
 });
 

package/dist/index.d.ts

@@ -1,4 +1,10 @@
-export declare const WORLD_SDK_VERSION = "0.11.0";
+/** Kept in step with `package.json` by `release-check.mjs`, which compares this
+ *  constant against the version of the package it actually INSTALLED. It rides
+ *  the `user-agent` of every request, so a drift here misreports which client
+ *  a project is running — which is exactly the field you reach for when a
+ *  customer's integration behaves like an older SDK than they say they have.
+ *  It sat at '0.1.0' for eight releases before anything compared the two. */
+export declare const WORLD_SDK_VERSION = "0.13.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. */
@@ -26,7 +32,7 @@ export declare const SOURCE_SIGNATURE_HEADER = "X-Pouchy-Source-Signature";
 /** Build the `X-Pouchy-Source-Signature` header for one request body.
  *
  *  The canonical string is five newline-joined lines — scheme, unix seconds,
- *  the declared source, the event/turn id, and the sha256 of the EXACT body
+ *  the declared source, the door's id slot (see `id`), and the sha256 of the EXACT body
  *  bytes. Sign at SEND time, every attempt: a legitimate retry of the same id
  *  days later carries a fresh timestamp and passes the ±5 minute skew, because
  *  the signature proves origin and never doubles as a dedupe key.
@@ -36,7 +42,11 @@ export declare const SOURCE_SIGNATURE_HEADER = "X-Pouchy-Source-Signature";
  *  send. */
 export declare function signSourceRequest(input: {
     source: string;
-    /** eventId for `/events`, turnId for the turns door — the id slot. */
+    /** The id slot, which is per-door: `turnId` for the turns door, `eventId`
+     *  for `/events`, and the request's own `world.request_id` for `/sessions`
+     *  (`createWorldSession` passes it for you). A mint has neither a turn nor an
+     *  event, so signing an empty or invented id there is the classic first
+     *  failure — it verifies locally and is refused as `bad_signature`. */
     id: string;
     body: string;
     keyId: string;
@@ -470,6 +480,43 @@ export interface ApprovedScriptExportRow {
     deliveryAttempted?: number;
     deliveryOk?: number;
 }
+/** What `POST /v1/sessions` actually returns for a WORLD mint.
+ *
+ *  Typed because it was untyped: `createWorldSession` used to answer
+ *  `Record<string, unknown>`, so a caller reading `session.token` — a field the
+ *  server has never sent — compiled, shipped, and failed only against a live
+ *  server. The wire is snake_case and stays that way here; renaming it in the
+ *  client would put a second vocabulary between an integrator and the HTTP
+ *  responses they read in their own logs.
+ *
+ *  `world` is present because `createWorldSession` always sends a world block;
+ *  an ordinary (non-world) mint omits it, and that lane is not this method's. */
+export interface WorldSessionResponse {
+    /** The end-user session token. Hand it to YOUR frontend, which drives it with
+     *  `@pouchy_ai/companion-sdk`. Scoped to one instance and one role, and
+     *  carries no project credential. NOT named `token`. */
+    readonly session_token: string;
+    /** Seconds. The server clamps a requested ttl into [300, 86400]; this is the
+     *  clamped value, not what you asked for. */
+    readonly expires_in: number;
+    /** The agent the ROLE resolved to. The world decides it — passing an agent to
+     *  a world mint is refused. */
+    readonly agent: string;
+    readonly instance: {
+        readonly id: string;
+        readonly external_user_id: string;
+        /** True the first time this end user was provisioned. */
+        readonly created: boolean;
+    };
+    readonly world: {
+        readonly environment: string;
+        /** The revision this instance is PINNED to — for life. */
+        readonly environment_revision: number;
+        /** The world instance id to drive turns against. */
+        readonly instance: string;
+        readonly role: string;
+    };
+}
 export interface WorldClientOptions {
     /** The project this client acts for. */
     projectId: string;
@@ -480,7 +527,7 @@ export interface WorldClientOptions {
      *  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.
+    /** A project ADMIN key (`pchy_admin_…`), 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,
@@ -740,7 +787,7 @@ export declare class PouchyWorldClient {
         externalUserId: string;
         worldInstance?: string;
         requestId?: string;
-    }): Promise<Record<string, unknown>>;
+    }): Promise<WorldSessionResponse>;
     /** Drive ONE coordinated beat. `turnId` is the idempotency key: re-send the
      *  same one to retry, mint a new one for a new beat. */
     runTurn(input: {
@@ -784,12 +831,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 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.
      *
-     *  `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. */
+     *  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,13 @@
 // 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';
+/** Kept in step with `package.json` by `release-check.mjs`, which compares this
+ *  constant against the version of the package it actually INSTALLED. It rides
+ *  the `user-agent` of every request, so a drift here misreports which client
+ *  a project is running — which is exactly the field you reach for when a
+ *  customer's integration behaves like an older SDK than they say they have.
+ *  It sat at '0.1.0' for eight releases before anything compared the two. */
+export const WORLD_SDK_VERSION = '0.13.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 // ── errors ─────────────────────────────────────────────────────────────────
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
@@ -111,7 +117,7 @@ const SOURCE_SIGNATURE_SCHEME = 'POUCHY-SOURCE-V1';
 /** Build the `X-Pouchy-Source-Signature` header for one request body.
  *
  *  The canonical string is five newline-joined lines — scheme, unix seconds,
- *  the declared source, the event/turn id, and the sha256 of the EXACT body
+ *  the declared source, the door's id slot (see `id`), and the sha256 of the EXACT body
  *  bytes. Sign at SEND time, every attempt: a legitimate retry of the same id
  *  days later carries a fresh timestamp and passes the ±5 minute skew, because
  *  the signature proves origin and never doubles as a dedupe key.
@@ -244,34 +250,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 +541,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.13.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",