@onlyworlds/sdk 4.186.1 → 4.187.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -1,6 +1,7 @@
1
1
  # For AI agents using @onlyworlds/sdk
2
+ If you are changing this package's source rather than using it, read [CONTRIBUTING.md](https://github.com/OnlyWorlds/sdk/blob/main/CONTRIBUTING.md) in the repository.
2
3
 
3
- **Current as of**: SDK **4.x** · schema-dist **v0.34.1-dist.143** (canonical 00.34.01).
4
+ **Current as of**: SDK **4.x** · schema-dist **v0.34.1-dist.145** (canonical 00.34.01).
4
5
  This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
5
6
  re-read against it, the check fails rather than letting this document rot quietly.
6
7
 
@@ -21,7 +22,8 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
21
22
  - Known, deterministic operations (CRUD, sync, bulk) → **this SDK**. Typed calls, typed
22
23
  responses, far cheaper than tool-schema reasoning.
23
24
  - Live exploration of a user's world from a chat/agent context → the **MCP server** at
24
- `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers, 12 tools).
25
+ `https://www.onlyworlds.com/mcp` (same `API-Key`/`API-Pin` headers; its tools are listed at
26
+ https://onlyworlds.github.io/docs/development/mcp).
25
27
 
26
28
  **Wire facts that bite** (full details in README):
27
29
  - Never send a `"world"` field in payloads — world identity comes from the API key (422 otherwise).
package/README.md CHANGED
@@ -339,6 +339,25 @@ An element's author fields, `created_by`, `changed_by`, `changed_via`, `changed_
339
339
  const backup = writeWorldFile(files, topDir, { includeAuthorFields: true }); // every file byte for byte
340
340
  ```
341
341
 
342
+ ## Bringing in a Kanka export
343
+
344
+ `@onlyworlds/sdk/convert` turns another tool's export into a world folder, in memory: bytes in, the folder's files and a report out, with no file system and no network, in the browser and in Node. Kanka is the first tool. `convertKanka` reads the zip Kanka's "Export the campaign" gives for the JSON type and writes the same folder as the Python package's door (`python -m onlyworlds.kanka`), byte for byte, and the same report. Both read their tables and wording from one data file, the same bytes in both packages.
345
+
346
+ ```typescript
347
+ import { convertKanka, kankaReportText } from '@onlyworlds/sdk/convert';
348
+
349
+ const { files, report } = convertKanka(bytes, { source: 'my-campaign.zip' }); // the zip, as a Uint8Array
350
+ files; // [{ path, data }]: world.json and elements/<type>/<slug>--<tail8>.json
351
+ report.counts; report.total; // elements written, by type
352
+ report.unplaced; report.unresolved; // keys kept as x_kanka_ extensions, links whose target is not in the folder
353
+ report.madeNames; // names the door made (`<entity>: hidden details`), by kind
354
+ const text = kankaReportText(report, 'my-world'); // the report as the Python door prints it
355
+ ```
356
+
357
+ Write `files` under a new folder yourself, each `path` relative to it. Each entity becomes an element of its module's type (a module with no OnlyWorlds type becomes a Narrative with supertype `Article`), its entry and posts the description, its parent, places and memberships links, and every key with no field is kept as `x_kanka_<key>` and named in the report. What Kanka hides comes in carrying `hidden: true`: a private entity whole, a post or a relationship not visible to all, and an entity's private details in one hidden Narrative. Ids are made from the campaign and Kanka's own ids, so the same export gives the same folder every time.
358
+
359
+ `world.json`'s `producer` line names this package and its version (`{ tool: '@onlyworlds/sdk', version, input: 'kanka-export' }`); pass `producer: { tool, version }` to name your own tool. A file that is not a zip, or a zip with no `campaign.json`, throws an `OwConvertError` with `reason` `not_a_zip` or `not_an_export`. From the repository, `node scripts/convert-kanka.mjs EXPORT.zip OUT-DIR` writes the folder and prints the report.
360
+
342
361
  ## World calendars
343
362
 
344
363
  A world's time is an integer line (`time_range_current` is a point on it, and so is an Event's `start_date`). A calendar names its points: months, days, eras. Atlas keeps a calendar on an element (a Construct by convention) in its `atlas_calendar` field, and the SDK reads it with Atlas's own calendar code (since 4.20.0). Atlas owns that field and is its only writer; read it, never write it.
package/SCHEMA.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # OnlyWorlds Schema Reference
2
2
 
3
- **Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.34.1-dist.143** — canonical schema **00.34.01**, published 2026-11-21.
3
+ **Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.34.1-dist.145** — canonical schema **00.34.01**, published 2026-11-22.
4
4
 
5
5
  GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
6
6
  Written for both humans and AI agents reading this package locally.