@pouchy_ai/world-sdk 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @pouchy_ai/world-sdk
 
+## 0.19.0
+
+- `getApprovedExport(environmentId, worldInstanceId, draftId, editorialId, exportId)`
+  — **read an approved script, body included, from a backend.** With `adminKey`
+  set it goes to the `/admin` mirror and needs no browser anywhere in your
+  deployment; same mechanism as `getProgress` and `getTurn`.
+- **This closes the loop.** Until now nothing returned an export body: the
+  collection listing strips it, so the only response that ever carried a script
+  was the POST that minted one. Reading required the create verb and an
+  hour-lived browser token, which meant a person had to forward the file.
+- **Every field the call needs is in the `world.script_approved` webhook** —
+  `exportId` at the top level, and `environmentId`, `worldInstanceId`,
+  `evidenceDraftId`, `editorialDraftId` inside `lineage`. Webhook → read, with
+  nobody in the middle. The payload still carries no script.
+- **Creating an export is still a human act** and is deliberately NOT mirrored:
+  an export is a reviewer's signature on a specific text. `deriveStoryPackageCandidate`
+  is not mirrored either — it leads to published canon.
+- New `ApprovedScriptExportSummary`, and `listApprovedExports` is now typed with
+  it instead of `unknown[]`. **The summary carries no `content`** — that is the
+  point of the split, and treating one as a full row is now a compile error
+  rather than a crash reading `content.exportDigest` off `undefined`.
+- Any miss on the item read — wrong project, environment, instance, draft,
+  editorial, or no such id — answers the **same** 404, so refusals cannot be used
+  to map which objects exist.
+
 ## 0.18.0
 
 - `createApprovedExport({ version: 2 })` — the V2 production hand-off: a

package/README.md

@@ -160,7 +160,7 @@ copies, and `prune` — the one call here that deletes — refuses without
 `confirm`, and again unless the archive verifies and has outlived retention.
 
 **Production hand-off** — `createApprovedExport`, `listApprovedExports`,
-`deriveStoryPackageCandidate`. An approved editorial draft becomes a versioned
+`getApprovedExport`, `deriveStoryPackageCandidate`. An approved editorial draft becomes a versioned
 approved script export carrying the whole chain: original story package → world
 instance → ledger range → evidence draft → editorial draft → reviewer.
 Idempotent on content, so replaying an export is a no-op.
@@ -177,6 +177,14 @@ yields two different, individually stable ids. `content` is a union — narrow o
 `contractVersion` before reading version-specific fields, and expect an
 unrecognised `version` to be a 400 rather than a quiet fall back to 1.
 
+`listApprovedExports` returns **summaries** — identity, provenance, a scene
+count, and no script. `getApprovedExport` returns **one export with its body**,
+and it is the call an unattended backend makes: with `adminKey` set it routes to
+the `/admin` mirror, so no browser is involved anywhere in your deployment.
+Everything it needs arrives in the `world.script_approved` webhook, so the loop
+closes without a person in the middle. Creating an export is deliberately NOT on
+that lane — an export is a reviewer's signature on a specific text.
+
 The Story Package candidate is validated and *returned*; publishing it is a
 separate act by a person, and only evidence-origin material becomes canon. It
 takes **version 1 exports only** and refuses a V2 export with 422 — it is the

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  *  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.18.0";
+export declare const WORLD_SDK_VERSION = "0.19.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1";
 /** One direction a beat could take. The WHOLE of what a deliberation shows a
  *  player: no reasoning, no role secrets, no simulated effects, no scores. */
@@ -643,6 +643,29 @@ export interface ApprovedScriptExportContentV2 {
  *  reading anything version-specific; a stored row keeps the version it was
  *  written with, forever. */
 export type ApprovedScriptExportContent = ApprovedScriptExportContentV1 | ApprovedScriptExportContentV2;
+/** Identity and provenance for every export on an editorial draft, WITHOUT the
+ *  script. This is what `listApprovedExports` returns.
+ *
+ *  Split from `ApprovedScriptExportRow` deliberately, and the difference is the
+ *  whole script. Treating a summary as a full row reads `content.exportDigest`
+ *  off `undefined`; keeping them apart makes that a compile error rather than a
+ *  crash in front of a user. To get the body, call `getApprovedExport`. */
+export interface ApprovedScriptExportSummary {
+    exportId: string;
+    draftId: string;
+    editorialId: string;
+    worldInstanceId: string;
+    environmentId: string;
+    /** How many scenes the body carries — the shape of what is not here. */
+    scenes: number;
+    createdAt: string;
+    createdBy: string;
+    deliveredAt?: string;
+    deliveryAttempted?: number;
+    deliveryOk?: number;
+    approvalTimeSource?: 'stamped' | 'legacy_updated_at';
+    approvedContentDigest?: string;
+}
 export interface ApprovedScriptExportRow {
     exportId: string;
     draftId: string;
@@ -655,6 +678,8 @@ export interface ApprovedScriptExportRow {
     deliveredAt?: string;
     deliveryAttempted?: number;
     deliveryOk?: number;
+    approvalTimeSource?: 'stamped' | 'legacy_updated_at';
+    approvedContentDigest?: string;
 }
 /** What `POST /v1/sessions` actually returns for a WORLD mint.
  *
@@ -1012,8 +1037,30 @@ export declare class PouchyWorldClient {
         version?: 1 | 2;
     }): Promise<ApprovedScriptExportRow>;
     listApprovedExports(environmentId: string, worldInstanceId: string, draftId: string, editorialId: string): Promise<{
-        exports: unknown[];
+        exports: ApprovedScriptExportSummary[];
     }>;
+    /** Read ONE approved export, script included — the machine lane's read.
+     *
+     *  This is the call an unattended backend makes. With `adminKey` set it goes
+     *  to the `/admin` mirror and needs no browser anywhere in your deployment;
+     *  with an `adminToken` it goes to the owner plane. Same mechanism as
+     *  `getProgress` and `getTurn`.
+     *
+     *  Every field it needs is in the `world.script_approved` webhook you
+     *  received: `exportId` at the top level, and `environmentId`,
+     *  `worldInstanceId`, `evidenceDraftId` and `editorialDraftId` inside
+     *  `lineage`. So the webhook → read loop closes without a person in it.
+     *
+     *  It READS. It does not create, approve or re-approve: minting an export is
+     *  a reviewer signing off on a specific text, and that stays on the owner
+     *  plane with a human behind it. What comes back cannot change — `exportId`
+     *  is the content digest of the body it returns.
+     *
+     *  Narrow `content.contractVersion` before reading version-specific fields.
+     *  A miss of any kind — wrong instance, wrong draft, wrong id — is one 404;
+     *  they are not told apart, so a caller cannot map an id space by reading
+     *  refusals. */
+    getApprovedExport(environmentId: string, worldInstanceId: string, draftId: string, editorialId: string, exportId: string): Promise<ApprovedScriptExportRow>;
     /** The next Story Package as a CANDIDATE — validated, and returned rather
      *  than published. Publishing it is a separate act by a person, through
      *  `createStoryPackage`. Only evidence-origin material becomes canon.

package/dist/index.js

@@ -23,7 +23,7 @@ import { createHash, createHmac, randomUUID } from 'node:crypto';
  *  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.18.0';
+export const WORLD_SDK_VERSION = '0.19.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 /** Read the commit turn id out of an envelope, so the signature covers the id
  *  the server will commit under. The payload half is base64url JSON; the
@@ -475,6 +475,30 @@ export class PouchyWorldClient {
     listApprovedExports(environmentId, worldInstanceId, draftId, editorialId) {
         return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/approved-export`);
     }
+    /** Read ONE approved export, script included — the machine lane's read.
+     *
+     *  This is the call an unattended backend makes. With `adminKey` set it goes
+     *  to the `/admin` mirror and needs no browser anywhere in your deployment;
+     *  with an `adminToken` it goes to the owner plane. Same mechanism as
+     *  `getProgress` and `getTurn`.
+     *
+     *  Every field it needs is in the `world.script_approved` webhook you
+     *  received: `exportId` at the top level, and `environmentId`,
+     *  `worldInstanceId`, `evidenceDraftId` and `editorialDraftId` inside
+     *  `lineage`. So the webhook → read loop closes without a person in it.
+     *
+     *  It READS. It does not create, approve or re-approve: minting an export is
+     *  a reviewer signing off on a specific text, and that stays on the owner
+     *  plane with a human behind it. What comes back cannot change — `exportId`
+     *  is the content digest of the body it returns.
+     *
+     *  Narrow `content.contractVersion` before reading version-specific fields.
+     *  A miss of any kind — wrong instance, wrong draft, wrong id — is one 404;
+     *  they are not told apart, so a caller cannot map an id space by reading
+     *  refusals. */
+    getApprovedExport(environmentId, worldInstanceId, draftId, editorialId, exportId) {
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/approved-export/${encodeURIComponent(exportId)}`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/approved-export/${encodeURIComponent(exportId)}`);
+    }
     /** The next Story Package as a CANDIDATE — validated, and returned rather
      *  than published. Publishing it is a separate act by a person, through
      *  `createStoryPackage`. Only evidence-origin material becomes canon.

package/package.json

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