@onlyworlds/sdk 4.133.1 → 4.134.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/CHANGELOG.md +19 -0
- package/SCHEMA.md +1 -1
- package/dist/index.d.ts +70 -12
- package/dist/index.js +60 -12
- 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.0-dist.
|
|
3
|
+
**Current as of**: SDK **4.x** · schema-dist **v0.34.0-dist.109** (canonical 00.34.00).
|
|
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,25 @@ earlier history lives in git log only.
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [4.134.0] - 2026-11-08
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- `madeWorldKey(worldId, idempotencyKey, { signal })`: the key a `mintWorldKey` call sent with that idempotency key made, as its row without the key itself (`OwWorldKeyRow`: id, name, last four, scope, last used, revoked, kept, and `member` on a member-bound key), or null when it made none. A revoked key still answers, with `revoked: true`. Null too from a server before the lookup, which answers that address 405.
|
|
13
|
+
- `mintWorldKey` takes `idempotencyKey`, sent as the Idempotency-Key header, and `signal`. The mint is never replayed (a stored answer would keep the key), so a second mint with the same key makes a second key. The server remembers the idempotency key on the row instead. When an answer is lost: keep the idempotency key on the device before the send, ask `madeWorldKey` after a network error or a timeout, revoke the id it names, and mint again. A 4xx made no key, and "none made" is worth believing only a couple of minutes after the send. An `idempotencyKey` that is not a non-empty string is a TypeError before anything is sent.
|
|
14
|
+
- `OwWorldKeyMember`, the membership a member-bound key is bound to; `OwMintedKey.member` is typed with it (it was a plain record).
|
|
15
|
+
|
|
16
|
+
## [4.133.2] - 2026-11-08
|
|
17
|
+
|
|
18
|
+
### Changed
|
|
19
|
+
|
|
20
|
+
- Schema repinned to schema-dist `v0.34.0-dist.109` (canonical 00.34.00 unchanged, no field moved). The calendar profile now refuses an era whose `year_base` is present and not 0 or 1, as its field table always said, and its fixture gains `refuse-year-base-five` (77 cases, 43 refusals). The calendar reader already refused such an era; the replayed fixture now holds it.
|
|
21
|
+
|
|
22
|
+
### Fixed
|
|
23
|
+
|
|
24
|
+
- `mintWorldKey`'s comment said that without `keep`, revoking the token takes the keys it minted. That holds for a token a tool got through Sign in with OnlyWorlds; a token from `signInWithPassword` or one made by hand never takes its keys, as `revokeAccountToken`'s comment already said. Words only.
|
|
25
|
+
- `createAccountWorld`'s comments said an account with a PIN must leave `pin` out (a 422) and that the route takes no Idempotency-Key. Since 2026-11-07 the server checks a `pin` sent by an account that has one before it makes the world (a wrong one is a 401 with `param: 'pin'`, nothing made) and takes an Idempotency-Key, whose replay answers the world without its key. The call is unchanged: it sends `pin` as given and no Idempotency-Key. Words only.
|
|
26
|
+
|
|
8
27
|
## [4.133.1] - 2026-11-06
|
|
9
28
|
|
|
10
29
|
### Changed
|
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.0-dist.
|
|
3
|
+
**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.34.0-dist.109** — canonical schema **00.34.00**, published 2026-11-07.
|
|
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
|
@@ -3533,7 +3533,7 @@ interface OwAccountWorld {
|
|
|
3533
3533
|
interface OwCreateAccountWorldInput {
|
|
3534
3534
|
/** The world's name: 1 to 255 characters, not blank (keel trims it). */
|
|
3535
3535
|
name: string;
|
|
3536
|
-
/**
|
|
3536
|
+
/** The account PIN, 4 digits. An account with no PIN yet must send one (1000-9999), which becomes the account PIN; an account with a PIN may send it to have it checked before the world is made (wrong: 401 with `param: 'pin'`, nothing made), or leave it out. */
|
|
3537
3537
|
pin?: string | number;
|
|
3538
3538
|
/** A name for the world's write key, as the website's key list shows it: 1 to 80 characters, trimmed. Left out or null: no name. */
|
|
3539
3539
|
keyName?: string | null;
|
|
@@ -3575,10 +3575,40 @@ interface OwMintedKey {
|
|
|
3575
3575
|
last_used_at: string | null;
|
|
3576
3576
|
revoked: boolean;
|
|
3577
3577
|
key: string;
|
|
3578
|
-
member?:
|
|
3578
|
+
member?: OwWorldKeyMember;
|
|
3579
3579
|
/** True when minted with `keep: true`: no revoke of the token that minted it takes it (a sign-out keeps it). */
|
|
3580
3580
|
kept?: boolean;
|
|
3581
3581
|
}
|
|
3582
|
+
/**
|
|
3583
|
+
* The membership a member-bound world key is bound to. A person's carries `username`; an agent
|
|
3584
|
+
* seat's `agent_name` (its username null); a player seat's `kind` and `name` (its username null).
|
|
3585
|
+
*/
|
|
3586
|
+
interface OwWorldKeyMember {
|
|
3587
|
+
id: string;
|
|
3588
|
+
username?: string | null;
|
|
3589
|
+
agent_name?: string;
|
|
3590
|
+
kind?: string;
|
|
3591
|
+
name?: string;
|
|
3592
|
+
}
|
|
3593
|
+
/**
|
|
3594
|
+
* A world key's row as GET /account/worlds/{id}/keys/made answers it (madeWorldKey): the key a
|
|
3595
|
+
* mint sent with that Idempotency-Key made, without the key itself. A revoked key still answers,
|
|
3596
|
+
* with `revoked: true`.
|
|
3597
|
+
*/
|
|
3598
|
+
interface OwWorldKeyRow {
|
|
3599
|
+
id: string;
|
|
3600
|
+
/** The key's label, an empty string when it has none. */
|
|
3601
|
+
name: string;
|
|
3602
|
+
/** The key's last four characters; the key itself is shown once, at the mint. */
|
|
3603
|
+
last4: string;
|
|
3604
|
+
scope: 'READ' | 'WRITE';
|
|
3605
|
+
last_used_at: string | null;
|
|
3606
|
+
revoked: boolean;
|
|
3607
|
+
/** True when the key is kept across a sign-out (`keep` at the mint). */
|
|
3608
|
+
kept: boolean;
|
|
3609
|
+
/** On a member-bound key only: the membership it is bound to. An owner key has none. */
|
|
3610
|
+
member?: OwWorldKeyMember;
|
|
3611
|
+
}
|
|
3582
3612
|
/** An account token as GET /account/tokens lists it: by name and last four, never the token itself. */
|
|
3583
3613
|
interface OwAccountToken {
|
|
3584
3614
|
/** The token's id: revokeAccountToken takes it, and a sign-in answers it as `tokenId`. */
|
|
@@ -5108,18 +5138,20 @@ declare class OwV2Client {
|
|
|
5108
5138
|
listAccountWorlds(): Promise<OwAccountWorld[]>;
|
|
5109
5139
|
/**
|
|
5110
5140
|
* POST /account/worlds -- make a world on the account, with its one write key. `name` is required
|
|
5111
|
-
* (1 to 255 characters, not blank; keel trims it). `pin`
|
|
5112
|
-
*
|
|
5113
|
-
*
|
|
5114
|
-
*
|
|
5115
|
-
* `pin`
|
|
5141
|
+
* (1 to 255 characters, not blank; keel trims it). `pin` is the account PIN, 4 digits. An account
|
|
5142
|
+
* with no PIN must send one (1000-9999): it becomes the account PIN and the write wall on every
|
|
5143
|
+
* world of the account; left out, a 422 with `param: 'pin'` (`err.param`) and nothing made. An
|
|
5144
|
+
* account with a PIN may send it to have it checked before the world is made: a wrong one is a 401
|
|
5145
|
+
* `invalid_credentials` with `param: 'pin'` and nothing made, counted toward the same lockout as a
|
|
5146
|
+
* write's PIN (then 429 `rate_limited`); left out, the world takes the account's PIN. So a tool
|
|
5147
|
+
* that holds the person's PIN can always send it. `keyName` names the write key as the website's key
|
|
5116
5148
|
* list shows it (1 to 80 characters, trimmed; null or left out: no name). `source` and `producer`
|
|
5117
5149
|
* are the folder format's provenance lines (spec 4.2), each an object or null, from a tool that
|
|
5118
5150
|
* makes the world from a folder: kept on the World as given, served by getWorld() as `origin`.
|
|
5119
5151
|
* Only the keys given are sent, `keyName` as `key_name`. 201: the world's row, as
|
|
5120
|
-
* listAccountWorlds lists it, with the full write key once in `key`. Account token only
|
|
5121
|
-
* Idempotency-Key (keel
|
|
5122
|
-
* listAccountWorlds, and mintWorldKey gives it a key.
|
|
5152
|
+
* listAccountWorlds lists it, with the full write key once in `key`. Account token only. Sends no
|
|
5153
|
+
* Idempotency-Key (keel takes one since 2026-11-07, and a replay answers the world without `key`):
|
|
5154
|
+
* if the answer is lost, the world is in listAccountWorlds, and mintWorldKey gives it a key.
|
|
5123
5155
|
*/
|
|
5124
5156
|
createAccountWorld(opts: OwCreateAccountWorldInput): Promise<OwCreatedAccountWorld>;
|
|
5125
5157
|
/**
|
|
@@ -5128,16 +5160,42 @@ declare class OwV2Client {
|
|
|
5128
5160
|
* name). The full key comes back
|
|
5129
5161
|
* once in `key`. The owner mints a world key; a member mints their own member key, 409
|
|
5130
5162
|
* `pin_required` (`err.isPinRequired`) for a write key while the account has no PIN. Account
|
|
5131
|
-
* token only
|
|
5163
|
+
* token only. `keep: true` keeps the key across a sign-out: revoking the token
|
|
5132
5164
|
* that minted it leaves it live (a tool that stores a key on the device passes it), while
|
|
5133
5165
|
* disconnecting the tool, or a replayed sign-in code, still takes it; the answer says `kept`.
|
|
5134
|
-
* Without it, revoking
|
|
5166
|
+
* Without it, revoking a token a tool got through Sign in with OnlyWorlds revokes the keys it minted,
|
|
5167
|
+
* unless the person holds another live token of the same tool; a token made by hand or by a password
|
|
5168
|
+
* sign-in (signInWithPassword), or one of a tool that asks each time, never takes its keys.
|
|
5169
|
+
*
|
|
5170
|
+
* `idempotencyKey` is sent as the Idempotency-Key header. The mint is never replayed (a stored
|
|
5171
|
+
* answer would keep the key): a second mint with the same key makes a second key. The server
|
|
5172
|
+
* remembers the key on the row instead, so when an answer is lost, madeWorldKey finds the key this
|
|
5173
|
+
* call made, and the tool revokes it by its id and mints again. `signal` (an AbortSignal) goes to
|
|
5174
|
+
* fetch as given; an abort rejects with an OwNetworkError.
|
|
5175
|
+
*
|
|
5176
|
+
* When the answer may be lost: keep the idempotency key on the device before the send. A 4xx made
|
|
5177
|
+
* no key. After a network error or a timeout, ask madeWorldKey, and revoke the id it names. Believe
|
|
5178
|
+
* its "none made" only a couple of minutes after the send, since an abort stops the wait, not the
|
|
5179
|
+
* server's work.
|
|
5135
5180
|
*/
|
|
5136
5181
|
mintWorldKey(worldId: string, opts?: {
|
|
5137
5182
|
scope?: 'read' | 'write';
|
|
5138
5183
|
name?: string | null;
|
|
5139
5184
|
keep?: boolean;
|
|
5185
|
+
idempotencyKey?: string;
|
|
5186
|
+
signal?: AbortSignal;
|
|
5140
5187
|
}): Promise<OwMintedKey>;
|
|
5188
|
+
/**
|
|
5189
|
+
* GET /account/worlds/{worldId}/keys/made?key= -- the key a mintWorldKey call sent with this
|
|
5190
|
+
* `idempotencyKey` made, as a row without the key itself (`OwWorldKeyRow`), or null when it made
|
|
5191
|
+
* none. A revoked key still answers, with `revoked: true`. The owner finds the keys they minted; a
|
|
5192
|
+
* member only the keys bound to their seat; anything else is null (the server's one 404). Null also
|
|
5193
|
+
* for a server from before the lookup, which answers this address 405. `signal` goes to fetch as
|
|
5194
|
+
* given. Account token only.
|
|
5195
|
+
*/
|
|
5196
|
+
madeWorldKey(worldId: string, idempotencyKey: string, opts?: {
|
|
5197
|
+
signal?: AbortSignal;
|
|
5198
|
+
}): Promise<OwWorldKeyRow | null>;
|
|
5141
5199
|
/**
|
|
5142
5200
|
* DELETE /account/worlds/{worldId}/keys/{keyId} -- revoke a world key, by the `id` mintWorldKey
|
|
5143
5201
|
* returned: from then on it answers 401 `key_revoked`. The owner revokes any of the world's keys,
|
package/dist/index.js
CHANGED
|
@@ -1903,18 +1903,20 @@ var OwV2Client = class {
|
|
|
1903
1903
|
}
|
|
1904
1904
|
/**
|
|
1905
1905
|
* POST /account/worlds -- make a world on the account, with its one write key. `name` is required
|
|
1906
|
-
* (1 to 255 characters, not blank; keel trims it). `pin`
|
|
1907
|
-
*
|
|
1908
|
-
*
|
|
1909
|
-
*
|
|
1910
|
-
* `pin`
|
|
1906
|
+
* (1 to 255 characters, not blank; keel trims it). `pin` is the account PIN, 4 digits. An account
|
|
1907
|
+
* with no PIN must send one (1000-9999): it becomes the account PIN and the write wall on every
|
|
1908
|
+
* world of the account; left out, a 422 with `param: 'pin'` (`err.param`) and nothing made. An
|
|
1909
|
+
* account with a PIN may send it to have it checked before the world is made: a wrong one is a 401
|
|
1910
|
+
* `invalid_credentials` with `param: 'pin'` and nothing made, counted toward the same lockout as a
|
|
1911
|
+
* write's PIN (then 429 `rate_limited`); left out, the world takes the account's PIN. So a tool
|
|
1912
|
+
* that holds the person's PIN can always send it. `keyName` names the write key as the website's key
|
|
1911
1913
|
* list shows it (1 to 80 characters, trimmed; null or left out: no name). `source` and `producer`
|
|
1912
1914
|
* are the folder format's provenance lines (spec 4.2), each an object or null, from a tool that
|
|
1913
1915
|
* makes the world from a folder: kept on the World as given, served by getWorld() as `origin`.
|
|
1914
1916
|
* Only the keys given are sent, `keyName` as `key_name`. 201: the world's row, as
|
|
1915
|
-
* listAccountWorlds lists it, with the full write key once in `key`. Account token only
|
|
1916
|
-
* Idempotency-Key (keel
|
|
1917
|
-
* listAccountWorlds, and mintWorldKey gives it a key.
|
|
1917
|
+
* listAccountWorlds lists it, with the full write key once in `key`. Account token only. Sends no
|
|
1918
|
+
* Idempotency-Key (keel takes one since 2026-11-07, and a replay answers the world without `key`):
|
|
1919
|
+
* if the answer is lost, the world is in listAccountWorlds, and mintWorldKey gives it a key.
|
|
1918
1920
|
*/
|
|
1919
1921
|
async createAccountWorld(opts) {
|
|
1920
1922
|
only("createAccountWorld", opts, ["name", "pin", "keyName", "source", "producer"]);
|
|
@@ -1937,16 +1939,32 @@ var OwV2Client = class {
|
|
|
1937
1939
|
* name). The full key comes back
|
|
1938
1940
|
* once in `key`. The owner mints a world key; a member mints their own member key, 409
|
|
1939
1941
|
* `pin_required` (`err.isPinRequired`) for a write key while the account has no PIN. Account
|
|
1940
|
-
* token only
|
|
1942
|
+
* token only. `keep: true` keeps the key across a sign-out: revoking the token
|
|
1941
1943
|
* that minted it leaves it live (a tool that stores a key on the device passes it), while
|
|
1942
1944
|
* disconnecting the tool, or a replayed sign-in code, still takes it; the answer says `kept`.
|
|
1943
|
-
* Without it, revoking
|
|
1945
|
+
* Without it, revoking a token a tool got through Sign in with OnlyWorlds revokes the keys it minted,
|
|
1946
|
+
* unless the person holds another live token of the same tool; a token made by hand or by a password
|
|
1947
|
+
* sign-in (signInWithPassword), or one of a tool that asks each time, never takes its keys.
|
|
1948
|
+
*
|
|
1949
|
+
* `idempotencyKey` is sent as the Idempotency-Key header. The mint is never replayed (a stored
|
|
1950
|
+
* answer would keep the key): a second mint with the same key makes a second key. The server
|
|
1951
|
+
* remembers the key on the row instead, so when an answer is lost, madeWorldKey finds the key this
|
|
1952
|
+
* call made, and the tool revokes it by its id and mints again. `signal` (an AbortSignal) goes to
|
|
1953
|
+
* fetch as given; an abort rejects with an OwNetworkError.
|
|
1954
|
+
*
|
|
1955
|
+
* When the answer may be lost: keep the idempotency key on the device before the send. A 4xx made
|
|
1956
|
+
* no key. After a network error or a timeout, ask madeWorldKey, and revoke the id it names. Believe
|
|
1957
|
+
* its "none made" only a couple of minutes after the send, since an abort stops the wait, not the
|
|
1958
|
+
* server's work.
|
|
1944
1959
|
*/
|
|
1945
1960
|
async mintWorldKey(worldId, opts = {}) {
|
|
1946
|
-
only("mintWorldKey", opts, ["scope", "name", "keep"]);
|
|
1961
|
+
only("mintWorldKey", opts, ["scope", "name", "keep", "idempotencyKey", "signal"]);
|
|
1947
1962
|
if (opts.keep !== void 0 && typeof opts.keep !== "boolean") {
|
|
1948
1963
|
throw new TypeError(`mintWorldKey: keep is true or false, got ${JSON.stringify(opts.keep)}. Nothing was sent.`);
|
|
1949
1964
|
}
|
|
1965
|
+
if (opts.idempotencyKey !== void 0 && (typeof opts.idempotencyKey !== "string" || opts.idempotencyKey === "")) {
|
|
1966
|
+
throw new TypeError(`mintWorldKey: idempotencyKey is a non-empty string, got ${JSON.stringify(opts.idempotencyKey)}. Nothing was sent.`);
|
|
1967
|
+
}
|
|
1950
1968
|
if (this.keyKind !== "account") {
|
|
1951
1969
|
throw new TypeError("mintWorldKey needs an account token (ow_a_)");
|
|
1952
1970
|
}
|
|
@@ -1954,7 +1972,37 @@ var OwV2Client = class {
|
|
|
1954
1972
|
if (opts.scope !== void 0) body.scope = opts.scope;
|
|
1955
1973
|
if (opts.name !== void 0) body.name = opts.name;
|
|
1956
1974
|
if (opts.keep !== void 0) body.keep = opts.keep;
|
|
1957
|
-
return this.request("POST", `/account/worlds/${seg("worldId", worldId)}/keys`, {
|
|
1975
|
+
return this.request("POST", `/account/worlds/${seg("worldId", worldId)}/keys`, {
|
|
1976
|
+
body,
|
|
1977
|
+
...opts.idempotencyKey !== void 0 ? { idempotencyKey: opts.idempotencyKey } : {},
|
|
1978
|
+
...withSignal(opts.signal)
|
|
1979
|
+
});
|
|
1980
|
+
}
|
|
1981
|
+
/**
|
|
1982
|
+
* GET /account/worlds/{worldId}/keys/made?key= -- the key a mintWorldKey call sent with this
|
|
1983
|
+
* `idempotencyKey` made, as a row without the key itself (`OwWorldKeyRow`), or null when it made
|
|
1984
|
+
* none. A revoked key still answers, with `revoked: true`. The owner finds the keys they minted; a
|
|
1985
|
+
* member only the keys bound to their seat; anything else is null (the server's one 404). Null also
|
|
1986
|
+
* for a server from before the lookup, which answers this address 405. `signal` goes to fetch as
|
|
1987
|
+
* given. Account token only.
|
|
1988
|
+
*/
|
|
1989
|
+
async madeWorldKey(worldId, idempotencyKey, opts = {}) {
|
|
1990
|
+
only("madeWorldKey", opts, ["signal"]);
|
|
1991
|
+
if (typeof idempotencyKey !== "string" || idempotencyKey === "") {
|
|
1992
|
+
throw new TypeError(`madeWorldKey: the idempotency key is a non-empty string, got ${JSON.stringify(idempotencyKey)}. Nothing was sent.`);
|
|
1993
|
+
}
|
|
1994
|
+
if (this.keyKind !== "account") {
|
|
1995
|
+
throw new TypeError("madeWorldKey needs an account token (ow_a_)");
|
|
1996
|
+
}
|
|
1997
|
+
try {
|
|
1998
|
+
return await this.request("GET", `/account/worlds/${seg("worldId", worldId)}/keys/made`, {
|
|
1999
|
+
query: `key=${encodeURIComponent(idempotencyKey)}`,
|
|
2000
|
+
...withSignal(opts.signal)
|
|
2001
|
+
});
|
|
2002
|
+
} catch (err) {
|
|
2003
|
+
if (err instanceof OwApiError && (err.status === 404 || err.status === 405)) return null;
|
|
2004
|
+
throw err;
|
|
2005
|
+
}
|
|
1958
2006
|
}
|
|
1959
2007
|
/**
|
|
1960
2008
|
* DELETE /account/worlds/{worldId}/keys/{keyId} -- revoke a world key, by the `id` mintWorldKey
|