@onlyworlds/sdk 4.183.0 → 4.184.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 +1 -1
- package/README.md +1 -1
- package/SCHEMA.md +1 -1
- package/dist/index.d.ts +15 -15
- package/dist/index.js +18 -14
- package/package.json +1 -1
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.
|
|
3
|
+
**Current as of**: SDK **4.x** · schema-dist **v0.34.1-dist.141** (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/README.md
CHANGED
|
@@ -436,7 +436,7 @@ The world holds the elements as the owner is served them; the reader's `rung` (`
|
|
|
436
436
|
|
|
437
437
|
`DATE_FIELD` is the profile's date table (each dated type's date field; the ten timeless types are not in it), and `dateOf(el)` is an element's date as that table reads it: the whole number in its type's date field, else null. A timeline or a horizon dates elements exactly as the lens reader's fence does.
|
|
438
438
|
|
|
439
|
-
`worldGraph(world, reader, options)` reads the same snapshot, for the same reader, as nodes and edges: `nodes` (`{ id, type, name, family, icon }`, by id; `family` is the type's colour word), `edges` (`{ source, field, target, index }`, one per link, by source, field and index), `edgesCut` (links to elements that are not nodes, by reason; with a lens, `outside_lens` counts links to elements the reader sees that the lens left out), `cut` and `unreadable` (the `x_lens` key a lens could not be read by, else null). Room elements, hidden and proposed ones and map space (Maps, Pins and Markers; a Zone is a node like any other) are out unless `rooms`, `hidden`, `proposed` or `mapSpace` brings them back (`hidden` and `proposed` are the owner's
|
|
439
|
+
`worldGraph(world, reader, options)` reads the same snapshot, for the same reader, as nodes and edges: `nodes` (`{ id, type, name, family, icon }`, by id; `family` is the type's colour word), `edges` (`{ source, field, target, index }`, one per link, by source, field and index), `edgesCut` (links to elements that are not nodes, by reason; with a lens, `outside_lens` counts links to elements the reader sees that the lens left out), `cut` and `unreadable` (the `x_lens` key a lens could not be read by, else null). Room elements, hidden and proposed ones and map space (Maps, Pins and Markers; a Zone is a node like any other) are out unless `rooms`, `hidden`, `proposed` or `mapSpace` brings them back (`hidden` and `proposed` are a keeper's alone, the owner's or a co-builder's, and a public reader takes no flag); the reading aids are out too, counted `reading_aid`, and no flag brings them back; with `{ lens }` the nodes are exactly what the lens kept, an aid among them when the lens names its pair in `types`.
|
|
440
440
|
|
|
441
441
|
```typescript
|
|
442
442
|
import { degreeOf, worldGraph } from '@onlyworlds/sdk';
|
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.
|
|
3
|
+
**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.34.1-dist.141** — canonical schema **00.34.01**, published 2026-11-20.
|
|
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
|
@@ -29,7 +29,7 @@ interface OwElementBase {
|
|
|
29
29
|
created_by?: string | null;
|
|
30
30
|
/** The membership whose write last changed this element (server-managed, read-only; served to the world's members only, absent for the public reader); null for the world's owner and for anything last changed before writes recorded it. */
|
|
31
31
|
changed_by?: string | null;
|
|
32
|
-
/** The door of the last write (server-managed, read-only; served to the world's members only, absent for the public reader): `seat` (an
|
|
32
|
+
/** The door of the last write (server-managed, read-only; served to the world's members only, absent for the public reader): `seat` (an AI 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). The first three are the doors the platform marks as an AI's. Null for anything last changed before writes recorded it. */
|
|
33
33
|
changed_via?: 'seat' | 'mcp' | 'declared' | 'api' | 'v1' | 'sync' | 'server' | 'site' | null;
|
|
34
34
|
/** The name the client gave in the X-OW-Client header on the last write (server-managed, read-only; served to the world's members only, absent for the public reader): 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. */
|
|
35
35
|
changed_client?: string | null;
|
|
@@ -2647,7 +2647,7 @@ interface OwHiddenRow {
|
|
|
2647
2647
|
* surface for everything else: `api`, `v1`, `sync`, and `server` for keel's own writes.
|
|
2648
2648
|
*/
|
|
2649
2649
|
type OwWriteDoor = NonNullable<OwElementBase['changed_via']>;
|
|
2650
|
-
/** The doors
|
|
2650
|
+
/** The doors the platform marks as an AI's: an AI seat, the MCP server, or a client that declared itself. */
|
|
2651
2651
|
declare const AGENT_DOORS: readonly OwWriteDoor[];
|
|
2652
2652
|
/** Whether a write came through an agent's door (`changed_via` or `deleted_via`); false for null. */
|
|
2653
2653
|
declare function isAgentDoor(door: OwWriteDoor | null | undefined): boolean;
|
|
@@ -3416,7 +3416,7 @@ interface OwJoinPreview {
|
|
|
3416
3416
|
/** The world owner's chosen Character's name, never a username; null when none is set, or when it is hidden. */
|
|
3417
3417
|
owner_character: string | null;
|
|
3418
3418
|
role: OwMemberRole;
|
|
3419
|
-
/** Whether joining gives the joiner a Character of their own (
|
|
3419
|
+
/** Whether joining gives the joiner a Character of their own (AI links). */
|
|
3420
3420
|
with_character: boolean | null;
|
|
3421
3421
|
/** ISO 8601, UTC. */
|
|
3422
3422
|
expires_at: string;
|
|
@@ -3442,7 +3442,7 @@ interface OwWorldLink {
|
|
|
3442
3442
|
/** `person`: accepted signed in, with acceptJoin. `agent`: redeemed by an AI agent at POST /join. `player`: redeemed with no account at POST /join, for a read key. */
|
|
3443
3443
|
reader: 'person' | 'agent' | 'player';
|
|
3444
3444
|
role: OwMemberRole;
|
|
3445
|
-
/** The name the owner gave an
|
|
3445
|
+
/** The name the owner gave an AI link on the website, or empty. */
|
|
3446
3446
|
label: string;
|
|
3447
3447
|
/** The name the link is signed with, or empty (the invite line then reads "Someone"). */
|
|
3448
3448
|
inviter_name: string;
|
|
@@ -3460,7 +3460,7 @@ interface OwWorldLink {
|
|
|
3460
3460
|
status: 'pending' | 'used' | 'revoked' | 'expired';
|
|
3461
3461
|
/** The membership (its id in GET /api/v2/members) of the co-builder who minted the link over POST /api/v2/links; null for a link the owner made. */
|
|
3462
3462
|
minted_by: string | null;
|
|
3463
|
-
/** Whether the link shows the world's name and picture when it is pasted into a chat: then the link is `/join/<world_id>#<code>`, else `/join#<code>`. Never on an
|
|
3463
|
+
/** Whether the link shows the world's name and picture when it is pasted into a chat: then the link is `/join/<world_id>#<code>`, else `/join#<code>`. Never on an AI link. */
|
|
3464
3464
|
preview?: boolean;
|
|
3465
3465
|
/** A player link only: the Character the player reads as; null while a link for a fresh Character is unused, and always null on a table. `name` is null if that Character was deleted (the redeem then makes a fresh one). */
|
|
3466
3466
|
character?: {
|
|
@@ -4239,7 +4239,7 @@ interface OwClientConfig {
|
|
|
4239
4239
|
/**
|
|
4240
4240
|
* Declare this client an AI agent: every element write (create, upsert, patch, delete,
|
|
4241
4241
|
* editLinks, bulk) carries `X-OW-Agent`, the operations the API document declares it on, and onlyworlds.com
|
|
4242
|
-
* records its writes as
|
|
4242
|
+
* records its writes as an AI's (`changed_via: 'declared'`; the server stores that the header
|
|
4243
4243
|
* was there, never its value). Off by default, and it must stay off in a tool people use:
|
|
4244
4244
|
* it describes the caller, so only the caller can set it. An AI seat's key is recorded
|
|
4245
4245
|
* as an agent without it.
|
|
@@ -5405,12 +5405,12 @@ declare class OwV2Client {
|
|
|
5405
5405
|
* `ow_a_` token owns: `reader` is required (`person`, accepted with acceptJoin;
|
|
5406
5406
|
* `agent`, redeemed at POST /join; `player`, a friend with no account, redeemed with
|
|
5407
5407
|
* redeemJoin for a read key); `role`, when left out, is the server's default: guest for a
|
|
5408
|
-
* person link, contributor for an
|
|
5408
|
+
* person link, contributor for an AI link (a player link is guest, and refuses any other), `days` (1, 7 or 30) to 7; `withCharacter` (AI links
|
|
5409
5409
|
* only) to true; `character` (player links only) a Character's id or `new` (the default):
|
|
5410
5410
|
* whoever opens the link first reads as it, until removed. `preview` (person and player links)
|
|
5411
5411
|
* to false: true puts the world's id in the link's path, so a chat that unfurls it
|
|
5412
|
-
* shows the world's name and picture (the code stays after `#`); true on an
|
|
5413
|
-
* 422, param `preview`. `maxUses` (person and player links; an
|
|
5412
|
+
* shows the world's name and picture (the code stays after `#`); true on an AI link is
|
|
5413
|
+
* 422, param `preview`. `maxUses` (person and player links; an AI link takes none) to 1, a
|
|
5414
5414
|
* link for one. On a person link 2 to 50 lets in that many accounts, each
|
|
5415
5415
|
* joining once with the link's role, until every use is taken, it expires or it is revoked;
|
|
5416
5416
|
* who already joined stays. On a player link 2 to 50 makes a table, one
|
|
@@ -5454,7 +5454,7 @@ declare class OwV2Client {
|
|
|
5454
5454
|
/**
|
|
5455
5455
|
* POST /account/worlds/{worldId}/seats -- a seat for your own AI in a world you own or are a
|
|
5456
5456
|
* member of: its own membership, write key and `ow_s_` secret, no join link. You answer for
|
|
5457
|
-
* it, and its writes are marked as an
|
|
5457
|
+
* it, and its writes are marked as an AI's. `name` is required (1 to 80 characters);
|
|
5458
5458
|
* `role` is at most your own (the owner may give any; default contributor, or your own role
|
|
5459
5459
|
* when that is lower); `character` is `new` (default: a Character of its own), `none`, or
|
|
5460
5460
|
* `mine` (members only: it plays the Character you play). 201 with `key`, `pin` and the
|
|
@@ -6587,9 +6587,9 @@ interface OwGraphOptions {
|
|
|
6587
6587
|
clock?: string | null;
|
|
6588
6588
|
/** Bring back room elements. Refused for a public reader. */
|
|
6589
6589
|
rooms?: boolean | null;
|
|
6590
|
-
/** Bring back hidden elements.
|
|
6590
|
+
/** Bring back hidden elements. A keeper's alone (the owner or a co-builder): refused from any other rung. */
|
|
6591
6591
|
hidden?: boolean | null;
|
|
6592
|
-
/** Bring back elements written as proposed.
|
|
6592
|
+
/** Bring back elements written as proposed. A keeper's alone (the owner or a co-builder): refused from any other rung. */
|
|
6593
6593
|
proposed?: boolean | null;
|
|
6594
6594
|
/** Bring back map space: Maps, Pins and Markers (a Zone is a node by default). Refused for a public reader. */
|
|
6595
6595
|
mapSpace?: boolean | null;
|
|
@@ -6635,9 +6635,9 @@ interface OwWorldGraph {
|
|
|
6635
6635
|
nodes: OwGraphNode[];
|
|
6636
6636
|
/** The edges, by source id, then field name (both in code point order), then index. */
|
|
6637
6637
|
edges: OwGraphEdge[];
|
|
6638
|
-
/** The links left out because their target is not a node, counted by the target's reason, in the reasons' one order. A reason with no count is absent; a reader that is not the owner never carries `anchor_not_visible
|
|
6638
|
+
/** The links left out because their target is not a node, counted by the target's reason, in the reasons' one order. A reason with no count is absent; a reader that is not the owner never carries `anchor_not_visible` or `not_visible`, one below a keeper (the owner or a co-builder) never carries `hidden` or `proposed`, and every reader carries `outside_lens`. */
|
|
6639
6639
|
edgesCut: Partial<Record<OwGraphCutReason, number>>;
|
|
6640
|
-
/** With a lens, the lens's own cut, unchanged. Without one, the elements out by default, counted by reason (`room`, `hidden` and `proposed` for
|
|
6640
|
+
/** With a lens, the lens's own cut, unchanged. Without one, the elements out by default, counted by reason (`room`, `hidden` and `proposed` for a keeper only, `map_space`, `reading_aid`). */
|
|
6641
6641
|
cut: Partial<Record<OwGraphCutReason, number>>;
|
|
6642
6642
|
/** With a lens whose `x_lens` the lens reader cannot read, the key it names (as `resolveLens`'s `unreadable`), and the graph is empty. Null otherwise, and always null without a lens. */
|
|
6643
6643
|
unreadable: string | null;
|
|
@@ -6675,7 +6675,7 @@ declare const DECLARED_LINKS: readonly string[];
|
|
|
6675
6675
|
* nor cut (counted for every rung); one of the kinds out by default without a lens; and `not_visible` for one the
|
|
6676
6676
|
* reader does not see. A link to an id that is not in the world is left out and not counted.
|
|
6677
6677
|
*
|
|
6678
|
-
* `hidden` or `proposed` from a reader
|
|
6678
|
+
* `hidden` or `proposed` from a reader below a keeper (the owner or a co-builder), or any flag from a public reader, is refused
|
|
6679
6679
|
* by name before anything is read; of several, the first in the order `hidden`, `proposed`, `rooms`, `mapSpace`,
|
|
6680
6680
|
* `readingAids`. An owner reading `as` another reader is judged by that reader's rung.
|
|
6681
6681
|
*/
|
package/dist/index.js
CHANGED
|
@@ -1767,12 +1767,12 @@ var OwV2Client = class {
|
|
|
1767
1767
|
* `ow_a_` token owns: `reader` is required (`person`, accepted with acceptJoin;
|
|
1768
1768
|
* `agent`, redeemed at POST /join; `player`, a friend with no account, redeemed with
|
|
1769
1769
|
* redeemJoin for a read key); `role`, when left out, is the server's default: guest for a
|
|
1770
|
-
* person link, contributor for an
|
|
1770
|
+
* person link, contributor for an AI link (a player link is guest, and refuses any other), `days` (1, 7 or 30) to 7; `withCharacter` (AI links
|
|
1771
1771
|
* only) to true; `character` (player links only) a Character's id or `new` (the default):
|
|
1772
1772
|
* whoever opens the link first reads as it, until removed. `preview` (person and player links)
|
|
1773
1773
|
* to false: true puts the world's id in the link's path, so a chat that unfurls it
|
|
1774
|
-
* shows the world's name and picture (the code stays after `#`); true on an
|
|
1775
|
-
* 422, param `preview`. `maxUses` (person and player links; an
|
|
1774
|
+
* shows the world's name and picture (the code stays after `#`); true on an AI link is
|
|
1775
|
+
* 422, param `preview`. `maxUses` (person and player links; an AI link takes none) to 1, a
|
|
1776
1776
|
* link for one. On a person link 2 to 50 lets in that many accounts, each
|
|
1777
1777
|
* joining once with the link's role, until every use is taken, it expires or it is revoked;
|
|
1778
1778
|
* who already joined stays. On a player link 2 to 50 makes a table, one
|
|
@@ -1833,7 +1833,7 @@ var OwV2Client = class {
|
|
|
1833
1833
|
/**
|
|
1834
1834
|
* POST /account/worlds/{worldId}/seats -- a seat for your own AI in a world you own or are a
|
|
1835
1835
|
* member of: its own membership, write key and `ow_s_` secret, no join link. You answer for
|
|
1836
|
-
* it, and its writes are marked as an
|
|
1836
|
+
* it, and its writes are marked as an AI's. `name` is required (1 to 80 characters);
|
|
1837
1837
|
* `role` is at most your own (the owner may give any; default contributor, or your own role
|
|
1838
1838
|
* when that is lower); `character` is `new` (default: a Character of its own), `none`, or
|
|
1839
1839
|
* `mine` (members only: it plays the Character you play). 201 with `key`, `pin` and the
|
|
@@ -4188,7 +4188,7 @@ function workOf(items, world, sourceWorld) {
|
|
|
4188
4188
|
var GRAPH_OPTION_KEYS = ["lens", "asOf", "clock", "rooms", "hidden", "proposed", "mapSpace", "readingAids"];
|
|
4189
4189
|
var DECLARED_LINKS = Object.freeze(["x_lens_leads_to", "x_spine_depends_on"]);
|
|
4190
4190
|
var GRAPH_REASONS = [...CUT_REASONS, "room", "hidden", "proposed", "map_space", "reading_aid", "outside_lens"];
|
|
4191
|
-
var
|
|
4191
|
+
var GRAPH_KEEPER_ONLY = /* @__PURE__ */ new Set(["hidden", "proposed"]);
|
|
4192
4192
|
function flag(opts, key3) {
|
|
4193
4193
|
const v = valueOf(opts, key3);
|
|
4194
4194
|
if (v !== null && typeof v !== "boolean") throw new TypeError(`worldGraph: ${key3} is a boolean; got ${JSON.stringify(v)}.`);
|
|
@@ -4213,7 +4213,9 @@ function worldGraph(world, reader, options) {
|
|
|
4213
4213
|
};
|
|
4214
4214
|
const seenRung = reader.rung === "owner" && reader.as != null ? reader.as.rung : reader.rung;
|
|
4215
4215
|
for (const [kind, key3] of [["hidden", "hidden"], ["proposed", "proposed"]]) {
|
|
4216
|
-
if (flags[kind] && seenRung !== "owner"
|
|
4216
|
+
if (flags[kind] && seenRung !== "owner" && seenRung !== "co-builder") {
|
|
4217
|
+
throw new TypeError(`worldGraph: ${key3} is a keeper's alone (the owner or a co-builder); a ${seenRung} reader may not ask it.`);
|
|
4218
|
+
}
|
|
4217
4219
|
}
|
|
4218
4220
|
if (seenRung === "public") {
|
|
4219
4221
|
for (const [kind, key3] of [["room", "rooms"], ["map_space", "mapSpace"], ["reading_aid", "readingAids"]]) {
|
|
@@ -4224,7 +4226,8 @@ function worldGraph(world, reader, options) {
|
|
|
4224
4226
|
const lens = valueOf(opts, "lens");
|
|
4225
4227
|
if (lens !== null && typeof lens !== "string" && !isBody2(lens)) throw new TypeError("worldGraph: lens is a lens body or its id.");
|
|
4226
4228
|
const r = new Reading(world, reader, asOf);
|
|
4227
|
-
const
|
|
4229
|
+
const seenKeeper = r.seenRung === "owner" || r.seenRung === "co-builder";
|
|
4230
|
+
const keeperCounts = seenKeeper || r.owner;
|
|
4228
4231
|
const kinds = (id) => {
|
|
4229
4232
|
const out = [];
|
|
4230
4233
|
if (r.room.has(id)) out.push("room");
|
|
@@ -4235,7 +4238,7 @@ function worldGraph(world, reader, options) {
|
|
|
4235
4238
|
return out;
|
|
4236
4239
|
};
|
|
4237
4240
|
const brought = (k) => flags[k];
|
|
4238
|
-
const candidate = (id) => r.view.has(id) ||
|
|
4241
|
+
const candidate = (id) => r.view.has(id) || seenKeeper && r.proposed.has(id);
|
|
4239
4242
|
const nodeIds = /* @__PURE__ */ new Set();
|
|
4240
4243
|
let cut2;
|
|
4241
4244
|
let reasonOf;
|
|
@@ -4255,7 +4258,7 @@ function worldGraph(world, reader, options) {
|
|
|
4255
4258
|
if (why === null) nodeIds.add(id);
|
|
4256
4259
|
else counts.set(why, (counts.get(why) ?? 0) + 1);
|
|
4257
4260
|
}
|
|
4258
|
-
cut2 = tally(counts, r.owner);
|
|
4261
|
+
cut2 = tally(counts, r.owner, keeperCounts);
|
|
4259
4262
|
reasonOf = (id) => candidate(id) ? outBy(id) : "not_visible";
|
|
4260
4263
|
}
|
|
4261
4264
|
const ids = [...nodeIds].sort(byCodePoint);
|
|
@@ -4300,9 +4303,9 @@ function worldGraph(world, reader, options) {
|
|
|
4300
4303
|
const typed = typeof t === "string" && r.typeOf.get(t) === to;
|
|
4301
4304
|
if (typed && !read.has(t)) {
|
|
4302
4305
|
read.add(t);
|
|
4303
|
-
visit(source, field, t,
|
|
4306
|
+
visit(source, field, t, seenKeeper ? i : served);
|
|
4304
4307
|
}
|
|
4305
|
-
if (
|
|
4308
|
+
if (seenKeeper || typed && r.linkable.has(t)) served++;
|
|
4306
4309
|
}
|
|
4307
4310
|
}
|
|
4308
4311
|
for (const field of DECLARED_LINKS) {
|
|
@@ -4317,12 +4320,13 @@ function worldGraph(world, reader, options) {
|
|
|
4317
4320
|
}
|
|
4318
4321
|
}
|
|
4319
4322
|
edges.sort((a, b) => byCodePoint(a.source, b.source) || byCodePoint(a.field, b.field) || a.index - b.index);
|
|
4320
|
-
return { nodes, edges, edgesCut: tally(cutEdges, r.owner), cut: cut2, unreadable };
|
|
4323
|
+
return { nodes, edges, edgesCut: tally(cutEdges, r.owner, keeperCounts), cut: cut2, unreadable };
|
|
4321
4324
|
}
|
|
4322
|
-
function tally(counts, owner) {
|
|
4325
|
+
function tally(counts, owner, keeper) {
|
|
4323
4326
|
const out = {};
|
|
4324
4327
|
for (const why of GRAPH_REASONS) {
|
|
4325
|
-
if (
|
|
4328
|
+
if (OWNER_ONLY.has(why) && !owner) continue;
|
|
4329
|
+
if (GRAPH_KEEPER_ONLY.has(why) && !keeper) continue;
|
|
4326
4330
|
const n = counts.get(why) ?? 0;
|
|
4327
4331
|
if (n > 0) out[why] = n;
|
|
4328
4332
|
}
|