@onlyworlds/sdk 4.133.2 → 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/CHANGELOG.md CHANGED
@@ -5,6 +5,14 @@ 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
+
8
16
  ## [4.133.2] - 2026-11-08
9
17
 
10
18
  ### Changed
package/dist/index.d.ts CHANGED
@@ -3575,10 +3575,40 @@ interface OwMintedKey {
3575
3575
  last_used_at: string | null;
3576
3576
  revoked: boolean;
3577
3577
  key: string;
3578
- member?: Record<string, unknown>;
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`. */
@@ -5130,18 +5160,42 @@ declare class OwV2Client {
5130
5160
  * name). The full key comes back
5131
5161
  * once in `key`. The owner mints a world key; a member mints their own member key, 409
5132
5162
  * `pin_required` (`err.isPinRequired`) for a write key while the account has no PIN. Account
5133
- * token only; no Idempotency-Key. `keep: true` keeps the key across a sign-out: revoking the token
5163
+ * token only. `keep: true` keeps the key across a sign-out: revoking the token
5134
5164
  * that minted it leaves it live (a tool that stores a key on the device passes it), while
5135
5165
  * disconnecting the tool, or a replayed sign-in code, still takes it; the answer says `kept`.
5136
5166
  * Without it, revoking a token a tool got through Sign in with OnlyWorlds revokes the keys it minted,
5137
5167
  * unless the person holds another live token of the same tool; a token made by hand or by a password
5138
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.
5139
5180
  */
5140
5181
  mintWorldKey(worldId: string, opts?: {
5141
5182
  scope?: 'read' | 'write';
5142
5183
  name?: string | null;
5143
5184
  keep?: boolean;
5185
+ idempotencyKey?: string;
5186
+ signal?: AbortSignal;
5144
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>;
5145
5199
  /**
5146
5200
  * DELETE /account/worlds/{worldId}/keys/{keyId} -- revoke a world key, by the `id` mintWorldKey
5147
5201
  * returned: from then on it answers 401 `key_revoked`. The owner revokes any of the world's keys,
package/dist/index.js CHANGED
@@ -1939,18 +1939,32 @@ var OwV2Client = class {
1939
1939
  * name). The full key comes back
1940
1940
  * once in `key`. The owner mints a world key; a member mints their own member key, 409
1941
1941
  * `pin_required` (`err.isPinRequired`) for a write key while the account has no PIN. Account
1942
- * token only; no Idempotency-Key. `keep: true` keeps the key across a sign-out: revoking the token
1942
+ * token only. `keep: true` keeps the key across a sign-out: revoking the token
1943
1943
  * that minted it leaves it live (a tool that stores a key on the device passes it), while
1944
1944
  * disconnecting the tool, or a replayed sign-in code, still takes it; the answer says `kept`.
1945
1945
  * Without it, revoking a token a tool got through Sign in with OnlyWorlds revokes the keys it minted,
1946
1946
  * unless the person holds another live token of the same tool; a token made by hand or by a password
1947
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.
1948
1959
  */
1949
1960
  async mintWorldKey(worldId, opts = {}) {
1950
- only("mintWorldKey", opts, ["scope", "name", "keep"]);
1961
+ only("mintWorldKey", opts, ["scope", "name", "keep", "idempotencyKey", "signal"]);
1951
1962
  if (opts.keep !== void 0 && typeof opts.keep !== "boolean") {
1952
1963
  throw new TypeError(`mintWorldKey: keep is true or false, got ${JSON.stringify(opts.keep)}. Nothing was sent.`);
1953
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
+ }
1954
1968
  if (this.keyKind !== "account") {
1955
1969
  throw new TypeError("mintWorldKey needs an account token (ow_a_)");
1956
1970
  }
@@ -1958,7 +1972,37 @@ var OwV2Client = class {
1958
1972
  if (opts.scope !== void 0) body.scope = opts.scope;
1959
1973
  if (opts.name !== void 0) body.name = opts.name;
1960
1974
  if (opts.keep !== void 0) body.keep = opts.keep;
1961
- return this.request("POST", `/account/worlds/${seg("worldId", worldId)}/keys`, { body });
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
+ }
1962
2006
  }
1963
2007
  /**
1964
2008
  * DELETE /account/worlds/{worldId}/keys/{keyId} -- revoke a world key, by the `id` mintWorldKey
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.133.2",
3
+ "version": "4.134.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {