@onlyworlds/sdk 4.176.0 → 4.177.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,6 @@
1
1
  # For AI agents using @onlyworlds/sdk
2
2
 
3
- **Current as of**: SDK **4.x** · schema-dist **v0.34.1-dist.132** (canonical 00.34.01).
3
+ **Current as of**: SDK **4.x** · schema-dist **v0.34.1-dist.133** (canonical 00.34.01).
4
4
  This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
5
5
  re-read against it, the check fails rather than letting this document rot quietly.
6
6
 
package/CHANGELOG.md CHANGED
@@ -5,6 +5,22 @@ earlier history lives in git log only.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [4.177.0] - 2026-11-17
9
+
10
+ ### Added
11
+
12
+ - **The charter and strand packets say each element's type** (schema-dist serial 133). `charterOf` answers `type: 'law'` on the Charter and `type: 'construct'` on the Guide and on each Domain; `strandOf` answers `type` on every filled slot (`narrative`, `event`, `location`, `character`, and `location` for `now`): the kind the slot holds, singular and lowercase, never the spelling stored. A packet is handed to a reader that may hold nothing else of the world, and an id is fetched by its type. `OwReadingAidsCharter`, `OwReadingAidsGuide`, `OwReadingAidsDomain` and `OwStrandSlot` declare the key, so `OwServedReadingAids` reads it as onlyworlds.com's `reading_aids` serves it. The schema pin moves to `v0.34.1-dist.133`; the charter fixture holds 47 cases and the strand fixture 29.
13
+
14
+ ### Fixed
15
+
16
+ - **A Domain's hub is an element of the kind its field links to, in the reader's view.** An id of another kind in a hub field, or of an element the reader does not see, names no hub. Wherever the charter and strand readers compare an element's type to a kind, the type is trimmed and compared without regard to case, as the room profile defines it.
17
+ - **`getAccessKey`'s deprecation note names `ai('ask', ...)` and `ai('sort', ...)`**, where it sent a reader to `ask()` and `sort()`, themselves deprecated since 4.139.0. The example at the head of the ask module calls `ai('ask', ...)` too. The by-links-3d frame comment says every candidate is tested, and the README names the fixtures without a case count.
18
+
19
+ ### Deprecated
20
+
21
+ - **The `version` key on `layoutByKind`'s and `layoutAround`'s answers** leaves in 5.0. It was always 1, and the layout profile's mark carries no version key: read `method`.
22
+ - **Five token types that serve only methods already deprecated** (`TokenConsumeParams`, `TokenConsumeResponse`, `AccessKeyResponse`, `RevokeSessionResponse`, `RevokeAllSessionsResponse`) are marked and leave in 5.0 with those methods.
23
+
8
24
  ## [4.176.0] - 2026-11-16
9
25
 
10
26
  ### Added
package/README.md CHANGED
@@ -457,7 +457,7 @@ const heading = typeWord(world, 'character', { many: true }) ?? 'Characters';
457
457
  const label = typeWord(world, el.type, { supertype: el.supertype }) ?? el.type;
458
458
  ```
459
459
 
460
- The word is printed as written, never re-cased; folder names are never translated. The profile: [`profiles/names.md`](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/names.md) in the schema distribution, with its 23-case fixture, which is this function's test.
460
+ The word is printed as written, never re-cased; folder names are never translated. The profile: [`profiles/names.md`](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/names.md) in the schema distribution, with its fixture, which is this function's test.
461
461
 
462
462
  ### Addresses
463
463
 
@@ -471,7 +471,7 @@ const r = parseOwLink(text); // { form, world, worldIsSlug, type, id, lens, mome
471
471
  // a refusal throws OwAddressError: err.reason is the profile's name ('bad_id', 'uppercase', ...)
472
472
  ```
473
473
 
474
- A field that holds an address is text: never fetch or resolve it on the server, and show one wording ("private or missing") for a world you cannot read and an element that is not there. `parseOwLink` reads one string whole; finding a link inside other text is yours. The profile: [`profiles/address.md`](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/address.md), with its 133-case fixture, which is these functions' test.
474
+ A field that holds an address is text: never fetch or resolve it on the server, and show one wording ("private or missing") for a world you cannot read and an element that is not there. `parseOwLink` reads one string whole; finding a link inside other text is yours. The profile: [`profiles/address.md`](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/address.md), with its fixture, which is these functions' test.
475
475
 
476
476
  ### Open with
477
477
 
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.132** — canonical schema **00.34.01**, published 2026-11-16.
3
+ **Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.34.1-dist.133** — canonical schema **00.34.01**, published 2026-11-16.
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.
package/dist/index.d.ts CHANGED
@@ -2352,6 +2352,8 @@ interface OwStrandWorld extends OwLensWorld {
2352
2352
  /** A filled slot. */
2353
2353
  interface OwStrandSlot {
2354
2354
  id: string;
2355
+ /** The element's type: the slot's own (narrative, event, location, character; `now` a location). */
2356
+ type: 'narrative' | 'event' | 'location' | 'character';
2355
2357
  name: string;
2356
2358
  }
2357
2359
  /** A world's strand as one reader sees it: five slots and whether then and now are one place. An empty slot is null. */
@@ -3198,6 +3200,8 @@ interface OwServedReadingAids extends OwReadingAids {
3198
3200
  /** The Charter in `reading_aids`. */
3199
3201
  interface OwReadingAidsCharter {
3200
3202
  id: string;
3203
+ /** The Charter is a Law. */
3204
+ type: 'law';
3201
3205
  name: string;
3202
3206
  /** Its `x_checks_rules` (the checks profile) as stored; empty when it has none. */
3203
3207
  rules: unknown[];
@@ -3207,11 +3211,15 @@ interface OwReadingAidsCharter {
3207
3211
  /** The Guide in `reading_aids`. */
3208
3212
  interface OwReadingAidsGuide {
3209
3213
  id: string;
3214
+ /** The Guide is a Construct. */
3215
+ type: 'construct';
3210
3216
  name: string;
3211
3217
  }
3212
3218
  /** One Domain in `reading_aids`. */
3213
3219
  interface OwReadingAidsDomain {
3214
3220
  id: string;
3221
+ /** A Domain is a Construct. */
3222
+ type: 'construct';
3215
3223
  name: string;
3216
3224
  /** Its description up to the first line break, trimmed; empty when it has none. */
3217
3225
  sentence: string;
@@ -6760,7 +6768,10 @@ interface OwLayoutPoint {
6760
6768
  /** What `layoutByKind` answers: one point per node, in the graph's node order, and the method that made them. */
6761
6769
  interface OwLayoutByKind {
6762
6770
  method: 'by-kind';
6763
- /** Always 1. A method's word is its version: a method that changes takes a new word, so read `method`, never this number. */
6771
+ /**
6772
+ * Always 1. A method's word is its version: a method that changes takes a new word, so read `method`, never this number.
6773
+ * @deprecated The layout profile's mark carries no version key. Leaves in 5.0.
6774
+ */
6764
6775
  version: 1;
6765
6776
  points: OwLayoutPoint[];
6766
6777
  }
@@ -6775,7 +6786,10 @@ interface OwLayoutAroundPoint {
6775
6786
  /** What `layoutAround` answers: the focus and every element within the steps, in the graph's node order. */
6776
6787
  interface OwLayoutAround {
6777
6788
  method: 'around';
6778
- /** Always 1. A method's word is its version: a method that changes takes a new word, so read `method`, never this number. */
6789
+ /**
6790
+ * Always 1. A method's word is its version: a method that changes takes a new word, so read `method`, never this number.
6791
+ * @deprecated The layout profile's mark carries no version key. Leaves in 5.0.
6792
+ */
6779
6793
  version: 1;
6780
6794
  points: OwLayoutAroundPoint[];
6781
6795
  }
@@ -7544,7 +7558,7 @@ declare function renderElement<T extends OwLookupElement>(element: T, index: OwW
7544
7558
  *
7545
7559
  * const hits = lookupWorld(index, question).slice(0, 8); // what the screen lists
7546
7560
  * const { context, kept, leftOut } = buildAskContext(hits, index);
7547
- * const reply = await account.ask({ worldId, question, context });
7561
+ * const reply = await account.ai('ask', { world_id: worldId, question, context });
7548
7562
  *
7549
7563
  * It is a reader that hands a world on, so three published rules hold here, not only in
7550
7564
  * the caller: an element marked proposed (the review profile, rules 1 and 4: an
@@ -8005,6 +8019,9 @@ interface TokenStatus {
8005
8019
  }
8006
8020
  /**
8007
8021
  * Response from token consumption endpoint
8022
+ *
8023
+ * @deprecated Serves only a `TokenResource` method keel answers with 404 (production,
8024
+ * since 2026-10). Leaves in 5.0 with that method.
8008
8025
  */
8009
8026
  interface TokenConsumeResponse {
8010
8027
  /** Whether the consumption was successful */
@@ -8020,6 +8037,9 @@ interface TokenConsumeResponse {
8020
8037
  }
8021
8038
  /**
8022
8039
  * Parameters for consuming tokens
8040
+ *
8041
+ * @deprecated Serves only a `TokenResource` method keel answers with 404 (production,
8042
+ * since 2026-10). Leaves in 5.0 with that method.
8023
8043
  */
8024
8044
  interface TokenConsumeParams {
8025
8045
  /** Number of tokens to consume (required) */
@@ -8033,6 +8053,9 @@ interface TokenConsumeParams {
8033
8053
  }
8034
8054
  /**
8035
8055
  * Response from getting encrypted access key (advanced use case)
8056
+ *
8057
+ * @deprecated Serves only a `TokenResource` method keel answers with 404 (production,
8058
+ * since 2026-10). Leaves in 5.0 with that method.
8036
8059
  */
8037
8060
  interface AccessKeyResponse {
8038
8061
  /** Base64 encoded encrypted OpenAI key */
@@ -8067,6 +8090,9 @@ interface EncryptionInfo {
8067
8090
  }
8068
8091
  /**
8069
8092
  * Response from session revocation
8093
+ *
8094
+ * @deprecated Serves only a `TokenResource` method keel answers with 404 (production,
8095
+ * since 2026-10). Leaves in 5.0 with that method.
8070
8096
  */
8071
8097
  interface RevokeSessionResponse {
8072
8098
  /** Whether revocation was successful */
@@ -8076,6 +8102,9 @@ interface RevokeSessionResponse {
8076
8102
  }
8077
8103
  /**
8078
8104
  * Response from revoking all sessions
8105
+ *
8106
+ * @deprecated Serves only a `TokenResource` method keel answers with 404 (production,
8107
+ * since 2026-10). Leaves in 5.0 with that method.
8079
8108
  */
8080
8109
  interface RevokeAllSessionsResponse {
8081
8110
  /** Whether revocation was successful */
@@ -8207,8 +8236,8 @@ declare class TokenResource {
8207
8236
  * Get encrypted OpenAI API key (advanced use case)
8208
8237
  *
8209
8238
  * @deprecated keel serves no access-key route (404 on production since
8210
- * 2026-10). AI answers come from keel's own proxy: `OwV2Client.ask()` and
8211
- * `sort()`. Removed in 5.0.
8239
+ * 2026-10). AI answers come from keel's own proxy: `OwV2Client.ai('ask', ...)`
8240
+ * and `ai('sort', ...)`. Removed in 5.0.
8212
8241
  *
8213
8242
  * Requires minimum 100 tokens available. Creates a 1-hour session for tracking.
8214
8243
  * Returns encrypted key that must be decrypted client-side using Fernet.
package/dist/index.js CHANGED
@@ -3734,7 +3734,7 @@ function hubsOf(id, r) {
3734
3734
  const v = body[field];
3735
3735
  const target = schema[field]?.target ?? "";
3736
3736
  for (const t of many ? Array.isArray(v) ? v : [] : [v]) {
3737
- if (typeof t !== "string" || t === "" || r.proposed.has(t) || seen.has(`${target}/${t}`)) continue;
3737
+ if (typeof t !== "string" || t === "" || r.proposed.has(t) || !r.view.has(t) || r.typeOf.get(t) !== target || seen.has(`${target}/${t}`)) continue;
3738
3738
  seen.add(`${target}/${t}`);
3739
3739
  out.push({ type: target, id: t });
3740
3740
  }
@@ -3758,6 +3758,7 @@ function charterOf(world, reader) {
3758
3758
  const skill = idsIn(el.description).filter((id) => r.view.has(id) && r.typeOf.get(id) === "object").slice(0, SKILL_MAX);
3759
3759
  out.charter = {
3760
3760
  id: law,
3761
+ type: "law",
3761
3762
  name: typeof el.name === "string" ? el.name : "",
3762
3763
  rules: Array.isArray(rules) ? JSON.parse(JSON.stringify(rules)) : [],
3763
3764
  skill
@@ -3766,7 +3767,7 @@ function charterOf(world, reader) {
3766
3767
  const guide = newest(seen("construct/guide"), r);
3767
3768
  if (guide !== null) {
3768
3769
  const el = r.byId.get(guide);
3769
- out.guide = { id: guide, name: typeof el.name === "string" ? el.name : "" };
3770
+ out.guide = { id: guide, type: "construct", name: typeof el.name === "string" ? el.name : "" };
3770
3771
  }
3771
3772
  const domains = new Set(seen("construct/domain"));
3772
3773
  const order = [];
@@ -3781,6 +3782,7 @@ function charterOf(world, reader) {
3781
3782
  const rest = [...domains].filter((id) => !order.includes(id)).sort((a, b) => byCodePoint(fold(nameOf(a)), fold(nameOf(b))) || byCodePoint(a, b));
3782
3783
  out.domains = [...order, ...rest].map((id) => ({
3783
3784
  id,
3785
+ type: "construct",
3784
3786
  name: nameOf(id),
3785
3787
  sentence: firstLine(r.body(id).description),
3786
3788
  hubs: hubsOf(id, r)
@@ -3820,7 +3822,7 @@ function strandOf(world, reader) {
3820
3822
  const seen = (id, type) => typeof id === "string" && r.view.has(id) && r.typeOf.get(id) === type;
3821
3823
  const slot = (id) => {
3822
3824
  const name = r.body(id).name;
3823
- return { id, name: typeof name === "string" ? name : "" };
3825
+ return { id, type: r.typeOf.get(id), name: typeof name === "string" ? name : "" };
3824
3826
  };
3825
3827
  const listed = (holder, field, id) => {
3826
3828
  const v = r.body(holder)[field];
@@ -9325,8 +9327,8 @@ var TokenResource = class {
9325
9327
  * Get encrypted OpenAI API key (advanced use case)
9326
9328
  *
9327
9329
  * @deprecated keel serves no access-key route (404 on production since
9328
- * 2026-10). AI answers come from keel's own proxy: `OwV2Client.ask()` and
9329
- * `sort()`. Removed in 5.0.
9330
+ * 2026-10). AI answers come from keel's own proxy: `OwV2Client.ai('ask', ...)`
9331
+ * and `ai('sort', ...)`. Removed in 5.0.
9330
9332
  *
9331
9333
  * Requires minimum 100 tokens available. Creates a 1-hour session for tracking.
9332
9334
  * Returns encrypted key that must be decrypted client-side using Fernet.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.176.0",
3
+ "version": "4.177.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {