@onlyworlds/sdk 4.55.0 → 4.56.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # For AI agents using @onlyworlds/sdk
 
-**Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.45** (canonical 00.33.00).
+**Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.46** (canonical 00.33.00).
 This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
 re-read against it, the check fails rather than letting this document rot quietly.
 
@@ -109,6 +109,11 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   `mcp`, `declared`, `api`, `v1`, `sync`, `server`), and a `/changes` delete carries
   `deleted_by` and `deleted_via`; `isAgentDoor(door)` is true for the first three. An agent
   seat's key is recorded as an agent without the option. Never set it in a tool people use.
+- **Name your tool** (since 4.56.0): `new OwV2Client({ ..., client: 'atlas' })` sends
+  `X-OW-Client: atlas` on every element write (never on a read); left out, it sends `sdk`. The name
+  is lower case letters, digits and hyphens, 1 to 32 characters, else a TypeError at construction.
+  keel stores it as `changed_client` on the element and `deleted_client` on a `/changes` delete:
+  the client's claim, never proof, and null when none was sent.
 - A guest or player reads what its own Character's sheet links to as a **stub**, marked
   `known_of: true` (`isKnownOf(el)`): only `id`, `type`, `name`, `description`, `supertype`,
   `subtype`, `image_url`, the timestamps and the fields its type lists in `PUBLIC_FIELDS` are

package/CHANGELOG.md

@@ -5,6 +5,18 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.56.0] - 2026-10-22
+
+### Added
+
+- **The client's name** (keel #520, live 2026-10-22; Orrery's `client-name.md`, decision 2): a constructor option `client`, default `'sdk'`, sent as `X-OW-Client` on every element write (`create`, `upsert`, `patch`, `delete`, `editLinks`, `bulk`, `adopt`) and on no read. keel stores it on the element as `changed_client`, so a reader can tell which tool made the last change (`new OwV2Client({ ..., client: 'atlas' })`). The rule is keel's, exact here: lower case letters, digits and hyphens, 1 to 32 characters (`[a-z0-9-]{1,32}`). Anything else, a capital, a space, an empty string, 33 characters or a value that is not a string, is a TypeError at construction naming the option and the rule, and nothing is trimmed; keel's own fence for a stranger's header is to store null, never a 422. The name is the client's claim about itself, never proof; it changes no door and no permission, and `agent` still decides `X-OW-Agent`.
+- **`changed_client`** on `OwElementBase` (`string | null`, server-managed, read-only, beside `changed_by` and `changed_via`): the name the last write gave, null when it gave none or one outside the rule, for keel's own writes, and for changes from before names were recorded. Sent back in a write it is ignored. **`deleted_client`** on a `/changes` delete (`OwChangeDelete`, beside `deleted_by` and `deleted_via`), the same for the delete; null on a `hidden` row.
+
+### Changed
+
+- **The constructor refuses an unknown key by name**, as every options object has since 4.52.0: `new OwV2Client({ clinet: 'atlas' })` is a `TypeError` naming the key and the eight the constructor knows, where it fell back to the defaults silently before. Every known caller (Atlas, Lantern, the toolkit) passes known keys only.
+- **Schema repinned to schema-dist v0.33.0-dist.46** (same canonical 00.33.00). The dist's example export (`example/world-export.json`) gains `changed_client: null` on its bodies, `walk/lint_folder.py`'s server-key set names `changed_client`, and the README's sentence on server keys names it; `VERSION` and `MANIFEST.json` carry the new serial; no schema file moved. Generated output moves its provenance lines and gains `changed_client`.
+
 ## [4.55.0] - 2026-10-22
 
 ### Added

package/SCHEMA.md

@@ -1,6 +1,6 @@
 # OnlyWorlds Schema Reference
 
-**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.33.0-dist.45** — canonical schema **00.33.00**, published 2026-10-22.
+**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.33.0-dist.46** — canonical schema **00.33.00**, published 2026-10-22.
 
 GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
 Written for both humans and AI agents reading this package locally.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /** Every element carries these. The extension index signature admits namespaced
  *  pass-through fields (atlas_* / shadow_* / x_*) returned verbatim by the server.
  *  Derived from base_properties.yaml: `World` is dropped (the API rejects it in
- *  bodies -- the key determines the world) and the seven server-managed fields are
+ *  bodies -- the key determines the world) and the eight server-managed fields are
  *  added, since they ride every wire body and appear in no element YAML; `known_of`
  *  rides only a stub. */
 interface OwElementBase {
@@ -31,6 +31,8 @@ interface OwElementBase {
     changed_by?: string | null;
     /** The door of the last write (server-managed, read-only): `seat` (an agent seat), `mcp`, `declared` (a client that sent X-OW-Agent), then `api`, `v1`, `sync`, `server` (keel's own writes) or `site` (the owner signed in on onlyworlds.com; keel PR 160). The first three are agent-made. Null for anything last changed before writes recorded it. */
     changed_via?: 'seat' | 'mcp' | 'declared' | 'api' | 'v1' | 'sync' | 'server' | 'site' | null;
+    /** The name the client gave in the X-OW-Client header on the last write (server-managed, read-only): lower case letters, digits and hyphens, 1 to 32 characters, such as `sdk` or `atlas`. It is the client's claim about itself, never proof, and says nothing about whether an agent drove the write (that is `changed_via`). Null when the last write sent no name or one outside the rule, for keel's own writes, and for anything last changed before names were recorded. Sent in a write it is ignored. This SDK sends its `client` option, `sdk` by default. */
+    changed_client?: string | null;
     /** Present, and true, only when the world's owner or a co-builder hid this element and this reader still sees it (server-managed, read-only): the owner, a co-builder, a key the owner minted, or the member who made it; to every other reader the element does not exist. Absent otherwise, whatever `fields` asked; on the read, the list, the change feed's upserts and MCP, never in the download, world sync or v1. Sent in a write it is ignored. */
     hidden?: true;
     /** Present, and true, only on a stub (server-managed, read-only): an element a guest or player reaches only through its own Character's sheet. A stub keeps id, type, name, description, supertype, subtype, image_url, created_at, updated_at and change_seq, and the fields its type lists in PUBLIC_FIELDS with their values; every other field reads unset ("", null, []), created_by/changed_by/changed_via null, no extension fields, and its files are 404. Its empties are not values and not a deletion: never write a stub back. Absent: the element is whole. See isKnownOf(). */
@@ -1981,6 +1983,12 @@ interface OwChangeDelete {
     deleted_by?: string | null;
     /** The door the delete came through (see {@link OwWriteDoor}); null for deletes before writes recorded it. */
     deleted_via?: OwWriteDoor | null;
+    /**
+     * The name the deleting client gave in its `X-OW-Client` header (keel #520), as an element's
+     * `changed_client`: the client's claim, never proof. Null when none was recorded, and on a
+     * `hidden` row (a hide carries no client).
+     */
+    deleted_client?: string | null;
     /**
      * Why the element left this reader's view (keel #421): `deleted` (it is gone; a GET answers 410),
      * `hidden` (the world's owner or a co-builder hid it from this reader; it still exists, a GET answers
@@ -2812,6 +2820,18 @@ interface OwClientConfig {
      * as an agent without it.
      */
     agent?: boolean;
+    /**
+     * This client's own name, sent as `X-OW-Client` on every element write (create, upsert, patch,
+     * delete, editLinks, bulk, adopt) and on no read (keel #520). keel stores it on the element as
+     * `changed_client`, and on a /changes delete as `deleted_client`, so a reader can tell which tool
+     * made a change: `'atlas'`, `'lantern'`, your app's name. Default `'sdk'`.
+     *
+     * The rule: lower case letters, digits and hyphens, 1 to 32 characters (`[a-z0-9-]{1,32}`), no
+     * version (`'atlas'`, not `'atlas-1.76'`). Anything else is a TypeError when the client is
+     * constructed, and nothing is trimmed. It is the client's claim about itself, not proof, and it
+     * changes no permission and no door: whether an agent made a write is `agent`'s business.
+     */
+    client?: string;
 }
 
 /**
@@ -3158,6 +3178,8 @@ declare class OwV2Client {
     private readonly apiPin;
     private readonly fetchImpl;
     private readonly agent;
+    /** The name sent as X-OW-Client on element writes (keel #520), checked at construction. */
+    private readonly clientName;
     constructor(config?: OwClientConfig);
     /** GET /health -- unauthenticated liveness pulse. */
     health(): Promise<unknown>;
@@ -3763,8 +3785,10 @@ declare class OwV2Client {
         allowEmpty?: boolean;
         replayAware?: boolean;
         /** A `change_seq` to send as `If-Match` (keel #210); a whole number, else TypeError before sending. */
-        /** An element write (create, put, patch, delete, links, bulk): where an agent client sends X-OW-Agent. */
+        /** A write keel's document lists X-OW-Agent on (the element writes, hide and unhide, the file ticket, setMyCharacter, mintWorldKey): where an agent client sends it. */
         write?: boolean;
+        /** One of the seven element writes keel reads X-OW-Client on (keel #520: create, put, patch, delete, links, bulk, adopt): where the client's name goes. */
+        elementWrite?: boolean;
         ifMatch?: number;
     }): Promise<T>;
 }

package/dist/index.js

@@ -504,6 +504,8 @@ var DEFAULT_PAGE_SIZE = 100;
 var DEFAULT_CHANGES_PAGE_SIZE = 100;
 var OwV2Client = class {
   constructor(config = {}) {
+    only("new OwV2Client", config, CLIENT_CONFIG_KEYS);
+    this.clientName = clientNameOf(config.client);
     this.apiKey = config.apiKey ?? "";
     this.apiPin = config.apiPin || void 0;
     this.keyKind = config.apiKey ? detectKeyKind(config.apiKey) : "none";
@@ -649,6 +651,7 @@ var OwV2Client = class {
     }
     return this.request("POST", `/${type}/`, {
       write: true,
+      elementWrite: true,
       body,
       idempotencyKey: opts.idempotencyKey
     });
@@ -660,7 +663,7 @@ var OwV2Client = class {
    */
   async upsert(type, id, element) {
     refuseKnownOf(element, "upsert");
-    return this.request("PUT", `/${type}/${id}/`, { write: true, body: sanitizePayload(element) });
+    return this.request("PUT", `/${type}/${id}/`, { write: true, elementWrite: true, body: sanitizePayload(element) });
   }
   /**
    * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
@@ -675,7 +678,7 @@ var OwV2Client = class {
   async patch(type, id, partial, opts = {}) {
     only("patch", opts, ["ifMatch"]);
     refuseKnownOf(partial, "patch");
-    return this.request("PATCH", `/${type}/${id}/`, { write: true, body: sanitizePayload(partial), ifMatch: opts.ifMatch });
+    return this.request("PATCH", `/${type}/${id}/`, { write: true, elementWrite: true, body: sanitizePayload(partial), ifMatch: opts.ifMatch });
   }
   /**
    * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
@@ -683,7 +686,7 @@ var OwV2Client = class {
    * transaction -- no client-side unlink pass needed, ever.
    */
   async delete(type, id) {
-    await this.request("DELETE", `/${type}/${id}/`, { write: true, allowEmpty: true });
+    await this.request("DELETE", `/${type}/${id}/`, { write: true, elementWrite: true, allowEmpty: true });
   }
   /**
    * POST /{type}/{id}/links/{field} with {add, remove} -- atomic link merge.
@@ -695,7 +698,7 @@ var OwV2Client = class {
   async editLinks(type, id, field, edit, opts = {}) {
     only("editLinks", opts, ["ifMatch"]);
     only("editLinks", edit, ["add", "remove"], "The edit is { add?: string[], remove?: string[] }.");
-    return this.request("POST", `/${type}/${id}/links/${field}`, { write: true, body: edit, ifMatch: opts.ifMatch });
+    return this.request("POST", `/${type}/${id}/links/${field}`, { write: true, elementWrite: true, body: edit, ifMatch: opts.ifMatch });
   }
   /**
    * POST /{type}/{id}/adopt with {member} -- change who made an element (keel #427, D141).
@@ -711,7 +714,7 @@ var OwV2Client = class {
    */
   async adopt(type, id, member) {
     if (typeof member !== "string" || member === "") throw new TypeError('adopt: member must be a membership id or "owner"');
-    return this.request("POST", `/${type}/${id}/adopt`, { write: true, body: { member } });
+    return this.request("POST", `/${type}/${id}/adopt`, { write: true, elementWrite: true, body: { member } });
   }
   // -- Bulk ----------------------------------------------------------------
   /**
@@ -745,6 +748,7 @@ var OwV2Client = class {
     };
     return this.request("POST", "/bulk/", {
       write: true,
+      elementWrite: true,
       body,
       idempotencyKey: opts.idempotencyKey,
       replayAware: true
@@ -1511,6 +1515,7 @@ var OwV2Client = class {
     if (opts.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
     if (opts.ifMatch !== void 0) headers["If-Match"] = `"${opts.ifMatch}"`;
     if (this.agent && opts.write) headers["X-OW-Agent"] = "1";
+    if (opts.elementWrite) headers["X-OW-Client"] = this.clientName;
     let res;
     try {
       res = await this.fetchImpl(url, {
@@ -1670,6 +1675,16 @@ function only(method, obj, keys, hint = "") {
     }
   }
 }
+var CLIENT_CONFIG_KEYS = ["apiKey", "apiPin", "baseUrl", "pageSize", "changesPageSize", "fetch", "agent", "client"];
+var CLIENT_NAME_RULE = /^[a-z0-9-]{1,32}$/;
+var DEFAULT_CLIENT_NAME = "sdk";
+function clientNameOf(value) {
+  if (value === void 0) return DEFAULT_CLIENT_NAME;
+  if (typeof value !== "string" || !CLIENT_NAME_RULE.test(value)) {
+    throw new TypeError(`OwV2Client: client must be lower case letters, digits and hyphens, 1 to 32 characters ([a-z0-9-]{1,32}), such as 'atlas'; got ${JSON.stringify(value) ?? String(value)}. It is sent as X-OW-Client on writes; leave it out for '${DEFAULT_CLIENT_NAME}'.`);
+  }
+  return value;
+}
 function buildQuery(params) {
   const q = new URLSearchParams();
   for (const [k, v] of Object.entries(params)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.55.0",
+  "version": "4.56.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {