@pouchy_ai/world-sdk 0.8.0

package/dist/index.js

@@ -0,0 +1,560 @@
+// @pouchy_ai/world-sdk — the SERVER-side client for Pouchy World.
+//
+// Node only, and deliberately so: this client holds a project Secret Key
+// (`pchy_sk_…`) and a source signing secret (`pesk_…`). They never belong in a
+// browser or a mobile app — a world turn is a backend-to-backend act, and the
+// two credentials together are what prove it. Ship the results to your users
+// through your own surface; ship the keys nowhere.
+//
+// What this covers, and nothing more: the world plane. Story packages, world
+// definitions, world sessions, coordinated turns, trusted events, the turn
+// read-back, world state, replay verification and script drafts. Agents,
+// capabilities and keys stay with `@pouchy_ai/admin-sdk`; the end-user runtime
+// stays with `@pouchy_ai/companion-sdk`.
+//
+// Zero dependencies (Node's own `fetch` and `node:crypto`), typed errors, and
+// helpers for the two things every integrator gets wrong on the first try:
+// 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.1.0';
+export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
+// ── errors ─────────────────────────────────────────────────────────────────
+/** The refusal classes a world call can produce. `unknown` is deliberate: an
+ *  unrecognized status is never quietly folded into a neighbour. */
+export const WORLD_ERROR_CODES = [
+    'unauthorized',
+    'forbidden',
+    'not_found',
+    'conflict',
+    'unprocessable',
+    'rate_limited',
+    'payload_too_large',
+    'server_error',
+    'network',
+    'unknown'
+];
+export class WorldApiError extends Error {
+    code;
+    status;
+    /** The server's own message, when it sent one. */
+    detail;
+    retryAfterSec;
+    constructor(input) {
+        super(input.message);
+        this.name = 'WorldApiError';
+        this.code = input.code;
+        this.status = input.status;
+        if (input.detail !== undefined)
+            this.detail = input.detail;
+        if (input.retryAfterSec !== undefined)
+            this.retryAfterSec = input.retryAfterSec;
+    }
+    /** Worth trying again with the SAME idempotency key. A 409 is not: it means
+     *  the world disagreed with the request, and repeating it will disagree
+     *  again. */
+    get retryable() {
+        return this.code === 'rate_limited' || this.code === 'server_error' || this.code === 'network';
+    }
+}
+/** Retry-After, both carriers and both forms (RFC 9110). A client that hands a
+ *  caller a negative or non-finite backoff turns a polite 429 into a hot loop
+ *  or a crash, so: the body's own seconds first, then the header as a
+ *  delta-seconds number, then the HTTP-date form proxies and CDNs emit.
+ *  Anything that is not a non-negative finite number is `undefined` — no
+ *  guessing. */
+function retryAfterFrom(res, body) {
+    for (const k of ['retryAfterSec', 'retryAfter']) {
+        const v = body?.[k];
+        if (typeof v === 'number' && Number.isFinite(v) && v >= 0)
+            return v;
+    }
+    // Optional-chained: `options.fetch` is a documented injection point, and a
+    // hand-rolled double that returns a bare { ok, status, text } must not turn
+    // a 4xx fixture into a TypeError.
+    const raw = res.headers?.get?.('Retry-After');
+    if (raw === null || raw === undefined || raw.trim() === '')
+        return undefined;
+    const header = Number(raw);
+    if (Number.isFinite(header) && header >= 0)
+        return header;
+    const at = Date.parse(raw);
+    if (!Number.isNaN(at))
+        return Math.max(0, Math.ceil((at - Date.now()) / 1000));
+    return undefined;
+}
+function codeForStatus(status) {
+    switch (status) {
+        case 401:
+            return 'unauthorized';
+        case 403:
+            return 'forbidden';
+        case 404:
+            return 'not_found';
+        case 409:
+            return 'conflict';
+        case 413:
+            return 'payload_too_large';
+        case 422:
+            return 'unprocessable';
+        case 429:
+            return 'rate_limited';
+        default:
+            if (status >= 500)
+                return 'server_error';
+            return 'unknown';
+    }
+}
+// ── signing + idempotency helpers ──────────────────────────────────────────
+export const SOURCE_SIGNATURE_HEADER = 'X-Pouchy-Source-Signature';
+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
+ *  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.
+ *
+ *  Pass the same string you will actually send as the body. Serializing twice
+ *  (once to sign, once to send) is the classic way to sign bytes you did not
+ *  send. */
+export function signSourceRequest(input) {
+    const tSec = Math.floor((input.nowMs ?? Date.now()) / 1000);
+    const bodySha = input.body ? createHash('sha256').update(input.body, 'utf8').digest('hex') : '-';
+    const canonical = [SOURCE_SIGNATURE_SCHEME, String(tSec), input.source, input.id, bodySha].join('\n');
+    const v1 = createHmac('sha256', input.secret).update(canonical, 'utf8').digest('hex');
+    return `t=${tSec},kid=${input.keyId},v1=${v1}`;
+}
+/** A fresh turn id for a NEW beat. Retrying a beat means re-sending the SAME
+ *  id — that is what makes the retry free of a second commit, a second model
+ *  call and a second message. Generate once, store it with whatever you are
+ *  about to do, and reuse it until you get an answer. */
+export function newTurnId(prefix = 'turn') {
+    return `${prefix}_${randomUUID().replace(/-/g, '')}`;
+}
+/** `evt:` is the platform's own namespace for turns derived from trusted
+ *  events; the turns door refuses caller ids in it. */
+export function isReservedTurnId(turnId) {
+    return turnId.startsWith('evt:');
+}
+/** What to DO about a stuck delivery, in one call. The three answers are the
+ *  three verbs, in the order they should be tried: re-send what is still there,
+ *  rebuild it from the record, or tell the reader the beat is gone. */
+export function describeDeliveryResolution(row) {
+    const blocking = row.blocking;
+    switch (row.status) {
+        case 'delivered':
+            return { action: 'none', blocking: false, summary: 'delivered' };
+        case 'resolved_gap':
+            return {
+                action: 'none',
+                blocking: false,
+                summary: 'the reader was told this beat could not be delivered'
+            };
+        case 'unrecoverable':
+            return {
+                action: 'resolve_gap',
+                blocking,
+                summary: `cannot be rebuilt (${row.unrecoverableReason ?? 'unknown'}) — resolve the gap so the session continues`
+            };
+        case 'rehydrating':
+            return { action: 'wait', blocking, summary: 'a rebuild is in flight' };
+        case 'dead':
+            return row.payloadRedactedAt
+                ? {
+                    action: 'rehydrate',
+                    blocking,
+                    summary: 'the line aged out; rebuild it from the committed record'
+                }
+                : {
+                    action: 'requeue',
+                    blocking,
+                    summary: `dead after ${row.attempts} attempts — requeue once the cause is fixed`
+                };
+        default:
+            return { action: 'wait', blocking, summary: 'still in the queue' };
+    }
+}
+export function describeDelivery(row) {
+    if (row.status === 'delivered') {
+        return { state: 'landed', blocking: false, summary: 'delivered' };
+    }
+    if (row.status === 'dead') {
+        return {
+            state: 'stuck',
+            blocking: row.blocking,
+            summary: row.payloadRedactedAt
+                ? `dead after ${row.attempts} attempts; the line has aged out and cannot be requeued`
+                : `dead after ${row.attempts} attempts (${row.lastErrorClass ?? 'unknown'}) — requeue once the cause is fixed`
+        };
+    }
+    if (row.status === 'delivering') {
+        return { state: 'in_flight', blocking: row.blocking, summary: 'a worker holds it' };
+    }
+    return {
+        state: 'waiting',
+        blocking: row.blocking,
+        summary: `attempt ${row.attempts + 1}, next at ${new Date(row.nextAttemptAt).toISOString()}`
+    };
+}
+export function describeTurn(result) {
+    const worldMoved = result.executionStatus === 'committed';
+    const audienceHeard = result.deliveryStatus === 'delivered';
+    const shouldRetrySameTurn = result.completionStatus === 'conflict';
+    const needsDifferentRequest = result.completionStatus === 'rejected' || result.completionStatus === 'refused';
+    return {
+        worldMoved,
+        audienceHeard,
+        shouldRetrySameTurn,
+        needsDifferentRequest,
+        summary: `${result.completionStatus}: world ${worldMoved ? 'moved' : 'did not move'}` +
+            ` (rev ${result.beforeStateRevision}→${result.afterStateRevision}),` +
+            ` delivery ${result.deliveryStatus}`
+    };
+}
+/** True for every code except `narrative_conflict`. */
+export function isDefectRejection(code) {
+    return code !== undefined && code !== 'narrative_conflict';
+}
+export class PouchyWorldClient {
+    projectId;
+    baseUrl;
+    doFetch;
+    adminToken;
+    secretKey;
+    signing;
+    timeoutMs;
+    constructor(options) {
+        if (!options.projectId)
+            throw new Error('projectId is required');
+        this.projectId = options.projectId;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.doFetch = options.fetch ?? globalThis.fetch;
+        if (options.adminToken !== undefined)
+            this.adminToken = options.adminToken;
+        if (options.secretKey !== undefined)
+            this.secretKey = options.secretKey;
+        if (options.signing !== undefined)
+            this.signing = options.signing;
+        this.timeoutMs = options.timeoutMs ?? 300_000;
+    }
+    // ── control plane (owner token) ──────────────────────────────────────────
+    listStoryPackages() {
+        return this.owner('GET', `/projects/${this.projectId}/story-packages`);
+    }
+    createStoryPackage(content) {
+        return this.owner('POST', `/projects/${this.projectId}/story-packages`, content);
+    }
+    getStoryPackage(packageId) {
+        return this.owner('GET', `/projects/${this.projectId}/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);
+    }
+    listWorlds() {
+        return this.owner('GET', `/projects/${this.projectId}/environments`);
+    }
+    createWorld(definition) {
+        return this.owner('POST', `/projects/${this.projectId}/environments`, definition);
+    }
+    getWorld(environmentId) {
+        return this.owner('GET', `/projects/${this.projectId}/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);
+    }
+    getWorldState(environmentId, worldInstanceId) {
+        return this.owner('GET', `/projects/${this.projectId}/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. */
+    getTurn(environmentId, worldInstanceId, turnId) {
+        return this.owner('GET', `/projects/${this.projectId}/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
+     *  report's `cursor` to continue a run that came back `incomplete`. */
+    replayLedger(environmentId, worldInstanceId, options = {}) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/ledger/replay`, options);
+    }
+    /** Walk a replay to completion, page by page. Bounded by `maxPages` so a
+     *  caller can never spin: an unfinished walk returns its last report, and
+     *  the cursor is in it. */
+    async replayLedgerToEnd(environmentId, worldInstanceId, options = {}) {
+        const maxPages = Math.max(1, Math.min(options.maxPages ?? 20, 100));
+        let report = await this.replayLedger(environmentId, worldInstanceId);
+        for (let page = 1; page < maxPages && report.verdict === 'incomplete' && report.cursor; page++) {
+            report = await this.replayLedger(environmentId, worldInstanceId, { cursor: report.cursor });
+        }
+        return report;
+    }
+    /** The delivery queue for one instance (Batch 7). Statuses, timings, attempt
+     *  counts, error classes, and which row is blocking its session — never the
+     *  message bodies. */
+    listDeliveries(environmentId, worldInstanceId, filters = {}) {
+        const q = new URLSearchParams();
+        for (const [k, v] of Object.entries(filters))
+            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}`);
+    }
+    /** One delivery. `includePayload` returns the line itself and writes an audit
+     *  row naming you — pass it deliberately, not by default. */
+    getDelivery(environmentId, worldInstanceId, deliveryId, options = {}) {
+        const suffix = options.includePayload ? '?includePayload=true' : '';
+        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/deliveries/${deliveryId}${suffix}`);
+    }
+    /** Run one bounded drain now — for the moment after a requeue. */
+    drainDeliveries(environmentId, worldInstanceId) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/deliveries/drain`, {});
+    }
+    /** Put a dead letter back in the queue. There is deliberately no payload
+     *  parameter: the beat was committed by the coordinator, and supplying a
+     *  different line here would be authoring world history through the delivery
+     *  plane. Idempotent — an already-queued row is a no-op. */
+    requeueDelivery(environmentId, worldInstanceId, deliveryId) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/deliveries/${deliveryId}/requeue`, {});
+    }
+    /** Turn an APPROVED editorial draft into a versioned production hand-off
+     *  (Batch 7). Idempotent on content — the same approved review exports to
+     *  the same id forever, so replaying one is a no-op rather than a second
+     *  script. `notify` also sends `world.script_approved` to the project's
+     *  webhooks, carrying lineage and identifiers but never the script body. */
+    createApprovedExport(environmentId, worldInstanceId, draftId, editorialId, options = {}) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/approved-export`, options.notify ? { notify: true } : {});
+    }
+    listApprovedExports(environmentId, worldInstanceId, draftId, editorialId) {
+        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/approved-export`);
+    }
+    /** 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. */
+    deriveStoryPackageCandidate(environmentId, worldInstanceId, draftId, editorialId, exportId, options = {}) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/approved-export/candidate?exportId=${encodeURIComponent(exportId)}`, options);
+    }
+    /** Rebuild a dead letter whose text was redacted, FROM THE RECORD (Batch
+     *  7.1). Takes no body — nobody types a replacement line and no model
+     *  regenerates one. Accepted only if the rebuild re-derives the same delivery
+     *  id and the same content digest captured before the text was destroyed;
+     *  otherwise it refuses with a code and the row becomes `unrecoverable`,
+     *  which still blocks the session. */
+    rehydrateDelivery(environmentId, worldInstanceId, deliveryId) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/deliveries/${deliveryId}/rehydrate`, {});
+    }
+    /** Account for a beat that cannot be recovered. The only exit from
+     *  `unrecoverable`, and it takes NO text: the notice is generated
+     *  server-side from a fixed catalogue and rendered in the reader's language.
+     *  The original resolves when the notice LANDS, not when you call this. */
+    resolveDeliveryGap(environmentId, worldInstanceId, deliveryId) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/deliveries/${deliveryId}/resolve-gap`, {});
+    }
+    /** Operator metrics for one instance (Batch 6): delivery and turn families,
+     *  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`);
+    }
+    /** Score the committed history against a quality suite. Deterministic — no
+     *  model judges the output, so a score is something you can regress. */
+    evaluateWorld(environmentId, worldInstanceId, options = {}) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/eval`, { suite: options.suite ?? 'drama', ...(options.replayVerdict ? { replayVerdict: options.replayVerdict } : {}) });
+    }
+    /** Ledger archival. The default action is `plan`, which writes nothing;
+     *  `execute` copies and never deletes; `prune` is the only call in this
+     *  client that destroys a row, and it refuses without `confirm` — and again
+     *  unless the archive verifies and has outlived its retention. */
+    archiveLedger(environmentId, worldInstanceId, options = {}) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/ledger/archive`, { action: options.action ?? 'plan', ...(options.confirm ? { confirm: true } : {}) });
+    }
+    listScriptDrafts(environmentId, worldInstanceId) {
+        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts`);
+    }
+    /** Generate (or return) the draft for this instance's committed history.
+     *  Idempotent on the ledger range: the same range is the same draft. */
+    createScriptDraft(environmentId, worldInstanceId) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts`, {});
+    }
+    getScriptDraft(environmentId, worldInstanceId, draftId) {
+        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}`);
+    }
+    /** Mark a draft reviewed. The reviewer is the SIGNED-IN human whose token
+     *  this client carries — never a field in the body. */
+    reviewScriptDraft(environmentId, worldInstanceId, draftId, note) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/review`, note ? { note } : {});
+    }
+    /** The reviewed draft as standard JSON. Refuses with 409 until a human has
+     *  reviewed it — that gate is the product, not an obstacle. */
+    exportScriptDraft(environmentId, worldInstanceId, draftId) {
+        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/export`);
+    }
+    /** The EDITORIAL layer over an evidence draft (Batch 6). The evidence draft
+     *  is deterministic and never changes; this is a model's reading of it, and
+     *  every line it claims came from the story was re-checked server-side. */
+    listEditorialDrafts(environmentId, worldInstanceId, draftId) {
+        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial`);
+    }
+    /** Generate (or return) an editorial reading. Idempotent per model + prompt
+     *  version + input digest, so asking twice is not a second opinion. */
+    createEditorialDraft(environmentId, worldInstanceId, draftId, model) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial`, model ? { model } : {});
+    }
+    getEditorialDraft(environmentId, worldInstanceId, draftId, editorialId) {
+        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}`);
+    }
+    /** Move an editorial draft through its review lifecycle. `exported` is not
+     *  settable here — `exportEditorialDraft` writes it. */
+    setEditorialStatus(environmentId, worldInstanceId, draftId, editorialId, status, note) {
+        return this.owner('PATCH', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}`, { status, ...(note ? { note } : {}) });
+    }
+    /** One human verdict on one scene. `edited` carries the editor's own text —
+     *  the only way text in this layer changes after generation. */
+    decideEditorialScene(environmentId, worldInstanceId, draftId, editorialId, input) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/scenes`, input);
+    }
+    /** Export an APPROVED editorial draft. `preview: true` reads the same payload
+     *  without stamping it exported, so a reviewer can see what would leave. */
+    exportEditorialDraft(environmentId, worldInstanceId, draftId, editorialId, options = {}) {
+        const path = `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/export`;
+        return options.preview ? this.owner('GET', path) : this.owner('POST', path, {});
+    }
+    // ── machine lane (secret key + source signature) ─────────────────────────
+    /** Mint a world SESSION for one end user in one role. The returned token is
+     *  what your own frontend uses with the companion SDK; it is scoped to that
+     *  instance and role and carries no project credential. */
+    createWorldSession(input) {
+        const requestId = input.requestId ?? randomUUID();
+        const body = {
+            external_user_id: input.externalUserId,
+            world: {
+                environment: input.environment,
+                role: input.role,
+                request_id: requestId,
+                ...(input.worldInstance ? { world_instance: input.worldInstance } : {})
+            }
+        };
+        return this.signed(`/sessions`, body, requestId);
+    }
+    /** 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) {
+        const turnId = input.turnId ?? newTurnId();
+        if (isReservedTurnId(turnId)) {
+            throw new Error('turnId prefix "evt:" is reserved for trusted world events');
+        }
+        const body = {
+            turnId,
+            trigger: {
+                kind: 'user',
+                text: input.text,
+                ...(input.sourceRoleId ? { sourceRoleId: input.sourceRoleId } : {})
+            },
+            ...(input.traceId ? { traceId: input.traceId } : {})
+        };
+        return this.signed(`/projects/${this.projectId}/environments/${input.environmentId}/instances/${input.worldInstanceId}/turns`, body, turnId);
+    }
+    /** Send a trusted EVENT into a world. On a `coordinated` world this becomes
+     *  one coordinator turn; on an `actor` world it wakes each subscribed role.
+     *  Either way `eventId` is the dedupe key — re-send it freely. */
+    sendEvent(input) {
+        const eventId = input.eventId ?? newTurnId('evt');
+        const body = {
+            name: input.name,
+            eventId,
+            schemaVersion: input.schemaVersion ?? 1,
+            data: input.data,
+            world: { environment: input.environment, instance: input.worldInstance },
+            ...(input.occurredAt !== undefined ? { occurredAt: input.occurredAt } : {})
+        };
+        return this.signed(`/projects/${this.projectId}/events`, body, eventId);
+    }
+    // ── transport ────────────────────────────────────────────────────────────
+    async owner(method, path, body) {
+        if (!this.adminToken) {
+            throw new Error(`${method} ${path} needs an owner token (adminToken)`);
+        }
+        return this.request(method, path, {
+            headers: { authorization: `Bearer ${this.adminToken}` },
+            ...(body !== undefined ? { raw: JSON.stringify(body) } : {})
+        });
+    }
+    /** The machine lane: Secret Key AND a source signature over the EXACT bytes
+     *  being sent — the two proofs the world requires of a backend. */
+    async signed(path, body, idSlot) {
+        if (!this.secretKey)
+            throw new Error(`${path} needs a project Secret Key (secretKey)`);
+        if (!this.signing)
+            throw new Error(`${path} needs a source signing key (signing)`);
+        const raw = JSON.stringify(body);
+        return this.request('POST', path, {
+            raw,
+            headers: {
+                authorization: `Bearer ${this.secretKey}`,
+                [SOURCE_SIGNATURE_HEADER]: signSourceRequest({
+                    source: this.signing.source,
+                    id: idSlot,
+                    body: raw,
+                    keyId: this.signing.keyId,
+                    secret: this.signing.secret
+                })
+            }
+        });
+    }
+    async request(method, path, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await this.doFetch(`${this.baseUrl}${path}`, {
+                method,
+                headers: {
+                    'content-type': 'application/json',
+                    'user-agent': `pouchy-world-sdk/${WORLD_SDK_VERSION}`,
+                    ...init.headers
+                },
+                ...(init.raw !== undefined ? { body: init.raw } : {}),
+                signal: controller.signal
+            });
+        }
+        catch (err) {
+            throw new WorldApiError({
+                code: 'network',
+                status: 0,
+                message: `${method} ${path} failed to reach Pouchy`,
+                detail: err instanceof Error ? err.message : undefined
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = await response.text();
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : {};
+        }
+        catch {
+            parsed = { error: text.slice(0, 300) };
+        }
+        if (!response.ok) {
+            const detail = parsed && typeof parsed === 'object' && 'error' in parsed
+                ? String(parsed.error)
+                : undefined;
+            const retryAfterSec = retryAfterFrom(response, parsed && typeof parsed === 'object' ? parsed : null);
+            throw new WorldApiError({
+                code: codeForStatus(response.status),
+                status: response.status,
+                message: `${method} ${path} → ${response.status}`,
+                ...(detail !== undefined ? { detail } : {}),
+                ...(retryAfterSec !== undefined ? { retryAfterSec } : {})
+            });
+        }
+        return parsed;
+    }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@pouchy_ai/world-sdk",
+	"version": "0.8.0",
+	"description": "Server-side TypeScript client for Pouchy World — 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",
+	"homepage": "https://pouchy.ai/sdk",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/oviswang/Pouchy.git",
+		"directory": "packages/world-sdk"
+	},
+	"bugs": {
+		"email": "support@pouchy.ai"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"conformance.mjs",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
+	"sideEffects": false,
+	"engines": {
+		"node": ">=18"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"prepublishOnly": "npm run build"
+	},
+	"devDependencies": {
+		"typescript": "^5.5.0"
+	},
+	"keywords": [
+		"pouchy",
+		"world",
+		"interactive-fiction",
+		"npc",
+		"sdk",
+		"agent-platform"
+	],
+	"publishConfig": {
+		"access": "public"
+	}
+}