@onlyworlds/sdk 4.163.0 → 4.164.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,20 @@ earlier history lives in git log only.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [4.164.0] - 2026-11-14
9
+
10
+ ### Added
11
+
12
+ - `signInWithOnlyWorlds({ scope: 'world:read' })`: a read-only sign-in, for a tool that only reads. The token it gives reads everything the account reads, and every write (a world key minted, a world made, another token minted, an AI call) is refused with 403 `permission_error`, except revoking the token itself. Any other `scope` is refused before anything is kept or sent; left out, the token writes as the account does, as before.
13
+ - `completeSignIn` answers `scope`: `'world:read'` when the server granted a read-only token, null when its answer carries none, so a tool that asked for read-only reads what it holds. A read-only sign-in gets no AI door token: `aiUses` beside one is refused before the code is spent, and the same return then completes without it.
14
+ - `OwAccountToken` (and `OwMintedAiToken`) declare `scope`, present only on a token a read-only sign-in minted, as `GET /account/tokens` lists it.
15
+
16
+ ## [4.163.1] - 2026-11-14
17
+
18
+ ### Fixed
19
+
20
+ - The descriptions of `isRoomElement` and `isCharterElement` say what 4.163.0 reads: an empty list or an empty object is no mark. They still said any value but null counted, and an editor shows them beside the code. No code changes.
21
+
8
22
  ## [4.163.0] - 2026-11-14
9
23
 
10
24
  ### Changed
package/dist/index.d.ts CHANGED
@@ -3851,6 +3851,8 @@ interface OwAccountToken {
3851
3851
  client?: string;
3852
3852
  /** On an `mcp` token only: the host the client returns the person to. */
3853
3853
  return_host?: string;
3854
+ /** Only on a token a sign-in with `scope: 'world:read'` minted: it reads, and every write but its own revoke is refused with 403 `permission_error`. Absent on every other token. */
3855
+ scope?: 'world:read';
3854
3856
  }
3855
3857
  /**
3856
3858
  * An AI door token as minted by mintAiToken (POST /account/tokens with `ai_uses`): its row, as the
@@ -4631,6 +4633,14 @@ interface OwSignInBegin {
4631
4633
  storage?: OwSignInStorage;
4632
4634
  /** How the browser is sent: a function taking the URL, or `false` to only return it. Default: `location.assign` where there is one. */
4633
4635
  navigate?: ((url: string) => void) | false;
4636
+ /**
4637
+ * `'world:read'` for a tool that only reads: the token the sign-in gives is read-only. It reads
4638
+ * everything the account reads, and every write (a world key minted, a world made, another token
4639
+ * minted, an AI call) is refused with 403 `permission_error`, except revoking the token itself.
4640
+ * Left out, the token writes as the account does. The one value there is; any other is refused
4641
+ * before anything is sent. `completeSignIn` answers the scope the server granted.
4642
+ */
4643
+ scope?: 'world:read';
4634
4644
  }
4635
4645
  interface OwSignInBegun {
4636
4646
  /** The authorize URL: `https://www.onlyworlds.com/signin/authorize?...`. */
@@ -4694,6 +4704,13 @@ interface OwSignInResult {
4694
4704
  id: string;
4695
4705
  username: string;
4696
4706
  };
4707
+ /**
4708
+ * `'world:read'` when the server granted a read-only token (the sign-in asked `scope: 'world:read'`):
4709
+ * every write but revoking the token itself is refused with 403 `permission_error`. Null when the
4710
+ * answer carries no scope: the token writes as the account does, which is also what a server that
4711
+ * does not know scopes answers, so a tool that asked for read-only reads it here.
4712
+ */
4713
+ scope: 'world:read' | null;
4697
4714
  /** The `resume` given to `beginSignIn`, or null. */
4698
4715
  resume: unknown;
4699
4716
  /**
@@ -5607,7 +5624,9 @@ declare class OwV2Client {
5607
5624
  * bound for this sign-in (`http://127.0.0.1:<port>/<path>` or `http://[::1]:<port>/<path>`,
5608
5625
  * registered without the port) or its own scheme as registered (`obsidian://onlyworlds-signin`),
5609
5626
  * and opens the URL in the system browser with `navigate`. `resume` is small JSON handed back by
5610
- * `completeSignIn`. No request is sent; any client, keyless included.
5627
+ * `completeSignIn`. `scope: 'world:read'` asks for a read-only token, for a tool that only reads:
5628
+ * every write but revoking it is refused with 403 `permission_error`, and `completeSignIn` answers
5629
+ * the scope granted. No request is sent; any client, keyless included.
5611
5630
  */
5612
5631
  signInWithOnlyWorlds(opts: OwSignInBegin): Promise<OwSignInBegun>;
5613
5632
  /**
@@ -5898,7 +5917,7 @@ declare function getElementLabel(elementType: ElementType): string;
5898
5917
  * True when the element is a room element: its type and supertype, each trimmed and compared
5899
5918
  * without regard to case, match one of ROOM_PAIRS, AND it carries the mark `x_room_of` (the id of
5900
5919
  * the world or the sitting the room belongs to), read by presence: any value but null, a string only
5901
- * when something is left after trimming, the value never compared. Both, always:
5920
+ * when something is left after trimming, an empty list or object never, the value never compared. Both, always:
5902
5921
  * a pair without the mark is lore (a novel's letters are Narratives with supertype Message),
5903
5922
  * and a mark without a pair is not a room element (a malformed mark: report it, never hide it).
5904
5923
  * The pair match is the whole word: a Narrative with supertype `Messages` is lore. The charter
@@ -5926,7 +5945,7 @@ declare function isRoomElement(el: {
5926
5945
  * domains (`construct`, supertype `Domain`), the type and supertype each trimmed and compared without
5927
5946
  * regard to case, the whole word, AND the mark `x_charter_of`, the id of the world the aid belongs to. The
5928
5947
  * mark counts when it is present and not null; a string mark counts only when something is left after
5929
- * trimming. Both, always: the pair without the mark is lore, and stays in every view (a kingdom's Charter
5948
+ * trimming, and an empty list or object never. Both, always: the pair without the mark is lore, and stays in every view (a kingdom's Charter
5930
5949
  * in a novel's world is a Law like any other).
5931
5950
  *
5932
5951
  * What it is for: a tool's front door shows the aids first; a lore view (a list, a graph, a story's
package/dist/index.js CHANGED
@@ -701,6 +701,10 @@ function redirectProblem(uri) {
701
701
  async function beginSignIn(baseUrl, opts) {
702
702
  const { clientId, redirectUri, resume = null } = opts ?? {};
703
703
  if (typeof clientId !== "string" || clientId === "") throw new TypeError("signInWithOnlyWorlds needs clientId");
704
+ const scope = opts.scope;
705
+ if (scope !== void 0 && scope !== "world:read") {
706
+ throw new TypeError(`signInWithOnlyWorlds: scope is 'world:read' or left out, got ${JSON.stringify(scope)}. Nothing was sent.`);
707
+ }
704
708
  const why = redirectProblem(redirectUri);
705
709
  if (why !== null) {
706
710
  throw new TypeError(`signInWithOnlyWorlds: redirectUri ${why}. Pass the registered return address as a string: https://<host>/<path>, or for a native app http://127.0.0.1:<port>/<path> or http://[::1]:<port>/<path> with the port it bound, or its own scheme, <scheme>://<path>`);
@@ -709,13 +713,14 @@ async function beginSignIn(baseUrl, opts) {
709
713
  const state = randomToken(32);
710
714
  const verifier = randomToken(32);
711
715
  const challenge = await pkceChallenge(verifier);
712
- storage.set(RECORD_PREFIX + clientId, JSON.stringify({ state, verifier, redirectUri, resume }));
716
+ storage.set(RECORD_PREFIX + clientId, JSON.stringify({ state, verifier, redirectUri, resume, ...scope ? { scope } : {} }));
713
717
  const url = new URL(sitePage(baseUrl, "/signin/authorize"));
714
718
  url.searchParams.set("client_id", clientId);
715
719
  url.searchParams.set("redirect_uri", redirectUri);
716
720
  url.searchParams.set("state", state);
717
721
  url.searchParams.set("code_challenge", challenge);
718
722
  url.searchParams.set("code_challenge_method", "S256");
723
+ if (scope) url.searchParams.set("scope", scope);
719
724
  const href = url.toString();
720
725
  if (opts.navigate !== false) {
721
726
  const go = opts.navigate ?? globalThis.location?.assign?.bind(globalThis.location);
@@ -768,6 +773,9 @@ async function completeSignIn(baseUrl, fetchImpl, opts) {
768
773
  if (state !== record.state) {
769
774
  throw new OwSignInError("state_mismatch", "This page was not reached from the sign-in that was started here: start again.");
770
775
  }
776
+ if (record.scope === "world:read" && "ai_uses" in ai) {
777
+ throw new TypeError("completeSignIn: this sign-in asked for a read-only token (scope world:read), which gets no AI door token: leave aiUses out. Nothing was sent.");
778
+ }
771
779
  storage.remove(key);
772
780
  if (!code) {
773
781
  throw new OwSignInError("state_mismatch", "This page was not reached from the sign-in that was started here: start again.");
@@ -819,6 +827,7 @@ async function completeSignIn(baseUrl, fetchImpl, opts) {
819
827
  expiresAt: typeof ok.expires_at === "string" && ok.expires_at !== "" ? ok.expires_at : null,
820
828
  tokenType: "bearer",
821
829
  account: { id: ok.account.id, username: typeof ok.account.username === "string" ? ok.account.username : "" },
830
+ scope: ok.scope === "world:read" ? "world:read" : null,
822
831
  resume: record.resume ?? null,
823
832
  aiToken: "ai_uses" in ai ? readAiToken(ok.ai_token) : null
824
833
  };
@@ -2227,10 +2236,12 @@ var OwV2Client = class {
2227
2236
  * bound for this sign-in (`http://127.0.0.1:<port>/<path>` or `http://[::1]:<port>/<path>`,
2228
2237
  * registered without the port) or its own scheme as registered (`obsidian://onlyworlds-signin`),
2229
2238
  * and opens the URL in the system browser with `navigate`. `resume` is small JSON handed back by
2230
- * `completeSignIn`. No request is sent; any client, keyless included.
2239
+ * `completeSignIn`. `scope: 'world:read'` asks for a read-only token, for a tool that only reads:
2240
+ * every write but revoking it is refused with 403 `permission_error`, and `completeSignIn` answers
2241
+ * the scope granted. No request is sent; any client, keyless included.
2231
2242
  */
2232
2243
  async signInWithOnlyWorlds(opts) {
2233
- only("signInWithOnlyWorlds", opts, ["clientId", "redirectUri", "resume", "storage", "navigate"]);
2244
+ only("signInWithOnlyWorlds", opts, ["clientId", "redirectUri", "resume", "storage", "navigate", "scope"]);
2234
2245
  return beginSignIn(this.baseUrl, opts);
2235
2246
  }
2236
2247
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.163.0",
3
+ "version": "4.164.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {