@onlyworlds/sdk 4.44.0 → 4.46.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.46.0] - 2026-10-22
+
+### Added
+- **Sign in with OnlyWorlds** (keel PR 154, live 2026-10-22 01:50; the handoff sheet §3): `signInWithOnlyWorlds({ clientId, redirectUri, resume, storage, navigate })` mints `state` and a PKCE S256 verifier, keeps them under the client id in `storage` (sessionStorage by default; required in Node), refuses a `redirectUri` that is not an `https:` string before sending, and sends the browser to `/signin/authorize`. `completeSignIn({ clientId, storage, url })` on the callback page checks `state` and the page, takes `code` and `state` out of the address bar, trades the code once at `POST /api/v2/auth/token` with no credential, and returns `OwSignInResult` (`token`, `account`, `resume`); the record is cleared either way and the SDK keeps no token. `OwSignInError` gains `invalid_grant` and `state_mismatch`. `pkceChallenge` and `base64url` exported.
+
+## [4.45.0] - 2026-10-22
+
+### Added
+- `hide(type, id)` and `unhide(type, id)`: the hidden mark's writes, `PUT` and `DELETE /{type}/{id}/hidden` (keel #421), for the parlor (Temper, h66 #9720). 204; the element's body and `change_seq` do not move.
+- `listAccountWorlds()` (`GET /account/worlds`, `OwAccountWorld[]`: owned and shared worlds with their keys by name and last four) and `mintWorldKey(worldId, { scope, name })` (`POST /account/worlds/{id}/keys`, `OwMintedKey` with the full key once), the two account routes Atlas and the parlor hand-rolled. Account token only.
+
 ## [4.44.0] - 2026-10-22
 
 ### Added

package/dist/index.d.ts

@@ -2426,6 +2426,39 @@ interface OwSignedIn {
     last4: string;
 }
 /** One live agent seat, as GET /account/worlds/{id}/seats lists it (keel #355, D106). No key or secret. */
+/**
+ * One world of the account, from GET /account/worlds: owned (`role: 'owner'`) or shared
+ * (`'collaborator'`, with `member_role` the membership's role). Keys by name and last four only,
+ * never the key; on a shared world only the member's own keys (keel H8).
+ */
+interface OwAccountWorld {
+    id: string;
+    name: string;
+    role: 'owner' | 'collaborator';
+    member_role?: OwMemberRole;
+    public_read: boolean;
+    keys: Array<{
+        name: string;
+        last4: string;
+        scope: 'READ' | 'WRITE';
+        revoked: boolean;
+    }>;
+}
+/**
+ * A world key as minted by POST /account/worlds/{id}/keys: the row the account's key list shows,
+ * plus the full key once in `key` (never shown again). A member's key carries its `member` label
+ * (keel D72); an owner's row has no such field.
+ */
+interface OwMintedKey {
+    id: string;
+    name: string;
+    last4: string;
+    scope: 'READ' | 'WRITE';
+    last_used_at: string | null;
+    revoked: boolean;
+    key: string;
+    member?: Record<string, unknown>;
+}
 interface OwSeat {
     /** The seat's membership id: removeSeat takes it, and GET /members names the seat by it. */
     id: string;
@@ -2865,7 +2898,7 @@ declare class OwNetworkError extends Error {
  * - `mint_failed`: the password was right, but keel made no token; the session was still ended.
  * - `failed`: any other refusal; the message is keel's when it gave one.
  */
-type OwSignInReason = 'invalid_credentials' | 'email_unverified' | 'rate_limited' | 'offline' | 'mint_failed' | 'failed';
+type OwSignInReason = 'invalid_credentials' | 'invalid_grant' | 'state_mismatch' | 'email_unverified' | 'rate_limited' | 'offline' | 'mint_failed' | 'failed';
 /**
  * A refused `signInWithPassword`. `reason` is what to tell the user; `status` and `code` are
  * keel's answer when there was one (`code`: keel's error code, e.g. `email_password_mismatch`).
@@ -2925,6 +2958,65 @@ declare function kindCanWrite(kind: OwKeyKind): boolean;
  */
 declare function pinExpectation(kind: OwKeyKind): 'never' | 'optional' | 'required-for-private-reads';
 
+/**
+ * Sign in with OnlyWorlds: OAuth 2.1's authorization code with PKCE (S256) for public clients
+ * (keel PR 154, live 2026-10-22; the handoff sheet, Orrery `keel/signin-handoff.md` §3).
+ *
+ * Two calls. `beginSignIn` mints `state` and a PKCE verifier, keeps them under the client id in a
+ * storage the page shares with its callback (sessionStorage by default), and hands back the
+ * authorize URL (sending the browser there where a `location` exists). `completeSignIn` runs on the
+ * callback page: it checks `state` and that the page is the registered return address, takes the
+ * code out of the address bar, trades it at `POST /api/v2/auth/token` with no credential, and
+ * returns the token with the account and the `resume` the tool parked before the redirect. The
+ * SDK keeps nothing: the record is cleared on success and on refusal, and the token is the tool's
+ * to store.
+ */
+/** Where the pending sign-in's record lives between the two pages: string in, string out. */
+interface OwSignInStorage {
+    get(key: string): string | null | undefined;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+interface OwSignInBegin {
+    /** The `client_id` keel's registry lists the tool under (`GET /api/v2/auth/clients`). */
+    clientId: string;
+    /** The registered return address, the exact string, `https:` only; never built from `location.origin`. */
+    redirectUri: string;
+    /** Small JSON the tool wants back after the redirect (an open link, a pending join code). */
+    resume?: unknown;
+    /** Defaults to `globalThis.sessionStorage`; without one (Node) the option is required. */
+    storage?: OwSignInStorage;
+    /** How the browser is sent: a function taking the URL, or `false` to only return it. Default: `location.assign` where there is one. */
+    navigate?: ((url: string) => void) | false;
+}
+interface OwSignInBegun {
+    /** The authorize URL: `https://www.onlyworlds.com/signin/authorize?...`. */
+    url: string;
+    state: string;
+}
+interface OwSignInComplete {
+    clientId: string;
+    storage?: OwSignInStorage;
+    /** The callback page's address; defaults to `location.href`. */
+    url?: string;
+}
+/** What `completeSignIn` returns: the account token, shown only here, and what the tool parked. */
+interface OwSignInResult {
+    /** An `ow_a_` account token: keep it, it is the only copy (the SDK stores none). */
+    token: string;
+    tokenType: 'bearer';
+    account: {
+        id: string;
+        username: string;
+    };
+    /** The `resume` given to `beginSignIn`, or null. */
+    resume: unknown;
+}
+/** Base64url without padding (RFC 4648 §5), as PKCE wants it. */
+declare function base64url(bytes: Uint8Array): string;
+/** The S256 code challenge of a verifier (RFC 7636 §4.2). */
+declare function pkceChallenge(verifier: string): Promise<string>;
+
 /**
  * keel v2 engine absorbed from an earlier v2 client (ow-v2-client v0.9.0),
  * wire-corrected against live staging fixtures 2026-07-18.
@@ -3427,6 +3519,52 @@ declare class OwV2Client {
      * goes with it, any other stays. Needs the client's `ow_a_` token.
      */
     removeSeat(worldId: string, seatId: string): Promise<void>;
+    /**
+     * PUT /{type}/{id}/hidden -- hide an element (keel #421). The owner's key or a co-builder's
+     * (a person's or a seat's) with its PIN; hiding a hidden element again changes nothing, and
+     * the element's body and `change_seq` do not move. Hidden, it is seen only by the owner, the
+     * co-builders and the member who created it; to every other key it is a 404, left out of
+     * lists, search, counts and the link arrays that name it. 204, no body. No Idempotency-Key.
+     */
+    hide(type: ElementType | string, id: string): Promise<void>;
+    /** DELETE /{type}/{id}/hidden -- clear the mark; an element that is not hidden stays as it is. 204. */
+    unhide(type: ElementType | string, id: string): Promise<void>;
+    /**
+     * GET /account/worlds -- every world the account owns or is a member of, with its keys by
+     * name and last four (a member sees only their own keys on a shared world). Account token only.
+     */
+    listAccountWorlds(): Promise<OwAccountWorld[]>;
+    /**
+     * POST /account/worlds/{id}/keys -- mint a world key, `scope` `'write'` (the default) or
+     * `'read'`, `name` as the key list shows it (at most 255 characters). The full key comes back
+     * once in `key`. The owner mints a world key; a member mints their own member key, 409
+     * `pin_required` (`err.isPinRequired`) for a write key while the account has no PIN. Account
+     * token only; no Idempotency-Key.
+     */
+    mintWorldKey(worldId: string, opts?: {
+        scope?: 'read' | 'write';
+        name?: string;
+    }): Promise<OwMintedKey>;
+    /**
+     * Start Sign in with OnlyWorlds from a tool's page: mint `state` and a PKCE verifier, keep them
+     * under `clientId` in `storage` (sessionStorage by default; in Node pass one), and send the
+     * browser to `https://www.onlyworlds.com/signin/authorize` (or only return the URL with
+     * `navigate: false`). `redirectUri` is the registered return address as a string, `https:`
+     * only, never built from `location.origin`: a tool's registration is read at
+     * `GET /api/v2/auth/clients`. `resume` is small JSON handed back by `completeSignIn`. No request
+     * is sent; any client, keyless included. The handoff sheet: Orrery `keel/signin-handoff.md` §3.
+     */
+    signInWithOnlyWorlds(opts: OwSignInBegin): Promise<OwSignInBegun>;
+    /**
+     * Finish Sign in with OnlyWorlds on the callback page: check `state` against the record and the
+     * page against the registered address, take `code` and `state` out of the address bar, trade
+     * the code once at `POST /auth/token` with the PKCE verifier and no credential, and return the
+     * `ow_a_` token with the account and `resume`. The record is cleared on success and on refusal;
+     * the SDK keeps no token: the tool does. Refusals are `OwSignInError`: `state_mismatch` (no
+     * pending sign-in, a different state, or the wrong page; nothing sent), `invalid_grant` (keel's
+     * 400: used, expired, or another client's code), `rate_limited`, `offline`, `failed`.
+     */
+    completeSignIn(opts: OwSignInComplete): Promise<OwSignInResult>;
     /**
      * POST /account/ask -- a question about a world the account owns or is in, answered by
      * keel's AI proxy from `context` only (build it with buildAskContext from the elements
@@ -4469,4 +4607,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwDeleteReason, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, OwSignInError, type OwSignInReason, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };
+export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAccountWorld, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwDeleteReason, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, type OwMintedKey, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwSeat, type OwSeatCreated, type OwSignInBegin, type OwSignInBegun, type OwSignInComplete, OwSignInError, type OwSignInReason, type OwSignInResult, type OwSignInStorage, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isKnownOf, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, pkceChallenge, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -338,6 +338,159 @@ function pinExpectation(kind) {
   }
 }
 
+// src/v2/oauth.ts
+var RECORD_PREFIX = "ow_signin:";
+function defaultStorage(name) {
+  const ss = globalThis.sessionStorage;
+  if (!ss || typeof ss.getItem !== "function") {
+    throw new TypeError(`${name}: no sessionStorage here; pass storage ({get, set, remove}) to hold the pending sign-in`);
+  }
+  return { get: (k) => ss.getItem(k), set: (k, v) => ss.setItem(k, v), remove: (k) => ss.removeItem(k) };
+}
+function webCrypto() {
+  const c = globalThis.crypto;
+  if (!c || typeof c.getRandomValues !== "function" || !c.subtle) {
+    throw new TypeError("Sign in with OnlyWorlds needs Web Crypto (crypto.getRandomValues and crypto.subtle)");
+  }
+  return c;
+}
+function base64url(bytes) {
+  const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i], b1 = bytes[i + 1], b2 = bytes[i + 2];
+    const n = b0 << 16 | (b1 ?? 0) << 8 | (b2 ?? 0);
+    out += ALPHABET[n >> 18 & 63] + ALPHABET[n >> 12 & 63];
+    if (b1 !== void 0) out += ALPHABET[n >> 6 & 63];
+    if (b2 !== void 0) out += ALPHABET[n & 63];
+  }
+  return out;
+}
+async function pkceChallenge(verifier) {
+  const digest = await webCrypto().subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return base64url(new Uint8Array(digest));
+}
+function randomToken(bytes) {
+  const buf = new Uint8Array(bytes);
+  webCrypto().getRandomValues(buf);
+  return base64url(buf);
+}
+function sitePage(baseUrl, path) {
+  return `${new URL(baseUrl).origin}${path}`;
+}
+async function beginSignIn(baseUrl, opts) {
+  const { clientId, redirectUri, resume = null } = opts ?? {};
+  if (typeof clientId !== "string" || clientId === "") throw new TypeError("signInWithOnlyWorlds needs clientId");
+  if (typeof redirectUri !== "string" || !redirectUri.startsWith("https://")) {
+    throw new TypeError("signInWithOnlyWorlds: redirectUri must be the registered https: address, as a string");
+  }
+  const storage = opts.storage ?? defaultStorage("signInWithOnlyWorlds");
+  const state = randomToken(32);
+  const verifier = randomToken(32);
+  const challenge = await pkceChallenge(verifier);
+  storage.set(RECORD_PREFIX + clientId, JSON.stringify({ state, verifier, redirectUri, resume }));
+  const url = new URL(sitePage(baseUrl, "/signin/authorize"));
+  url.searchParams.set("client_id", clientId);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  const href = url.toString();
+  if (opts.navigate !== false) {
+    const go = opts.navigate ?? globalThis.location?.assign?.bind(globalThis.location);
+    if (go) go(href);
+  }
+  return { url: href, state };
+}
+function samePage(a, b) {
+  try {
+    const x = new URL(a), y = new URL(b);
+    return x.origin === y.origin && x.pathname.replace(/\/$/, "") === y.pathname.replace(/\/$/, "");
+  } catch {
+    return false;
+  }
+}
+async function completeSignIn(baseUrl, fetchImpl, opts) {
+  const { clientId } = opts ?? {};
+  if (typeof clientId !== "string" || clientId === "") throw new TypeError("completeSignIn needs clientId");
+  const storage = opts.storage ?? defaultStorage("completeSignIn");
+  const here = opts.url ?? globalThis.location?.href;
+  if (typeof here !== "string") throw new TypeError("completeSignIn: no location here; pass url (the callback page's address)");
+  const page = new URL(here);
+  const code = page.searchParams.get("code");
+  const state = page.searchParams.get("state");
+  const hist = globalThis.history;
+  if (hist && typeof hist.replaceState === "function" && (page.searchParams.has("code") || page.searchParams.has("state"))) {
+    const clean = new URL(here);
+    clean.searchParams.delete("code");
+    clean.searchParams.delete("state");
+    try {
+      hist.replaceState(hist.state, "", clean.toString());
+    } catch {
+    }
+  }
+  const key = RECORD_PREFIX + clientId;
+  const raw = storage.get(key);
+  storage.remove(key);
+  let record = null;
+  try {
+    record = raw ? JSON.parse(raw) : null;
+  } catch {
+    record = null;
+  }
+  if (!record || typeof record.state !== "string" || typeof record.verifier !== "string" || typeof record.redirectUri !== "string") {
+    throw new OwSignInError("state_mismatch", "No sign-in is pending for this tool here: start again from the sign-in button.");
+  }
+  if (!code || !state || state !== record.state) {
+    throw new OwSignInError("state_mismatch", "This page was not reached from the sign-in that was started here: start again.");
+  }
+  if (!samePage(here, record.redirectUri)) {
+    throw new OwSignInError("state_mismatch", "This page is not the return address the sign-in was started with.");
+  }
+  let res;
+  try {
+    res = await fetchImpl(`${baseUrl}/auth/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        grant_type: "authorization_code",
+        code,
+        code_verifier: record.verifier,
+        client_id: clientId,
+        redirect_uri: record.redirectUri
+      })
+    });
+  } catch {
+    throw new OwSignInError("offline", "OnlyWorlds could not be reached: signing in needs a connection.");
+  }
+  const retryAfter = parseRetryAfter(res.headers?.get?.("Retry-After") ?? null) ?? void 0;
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+  const err = body?.error;
+  const errCode = typeof err?.code === "string" ? err.code : void 0;
+  const errMessage = typeof err?.message === "string" ? err.message : void 0;
+  if (res.status === 429) {
+    throw new OwSignInError("rate_limited", errMessage ?? "Too many sign-in attempts. Wait a while, then try again.", { status: 429, code: errCode, retryAfter });
+  }
+  if (res.status === 400 && errCode === "invalid_grant") {
+    throw new OwSignInError("invalid_grant", errMessage ?? "The sign-in code could not be exchanged: it was used, expired, or made for another tool. Start again.", { status: 400, code: errCode });
+  }
+  const ok = body;
+  if (!res.ok || typeof ok?.token !== "string" || ok.token === "" || typeof ok.account?.id !== "string") {
+    throw new OwSignInError("failed", errMessage ?? `Signing in did not work (${res.status}).`, { status: res.status, code: errCode });
+  }
+  return {
+    token: ok.token,
+    tokenType: "bearer",
+    account: { id: ok.account.id, username: typeof ok.account.username === "string" ? ok.account.username : "" },
+    resume: record.resume ?? null
+  };
+}
+
 // src/v2/client.ts
 var DEFAULT_BASE_URL = "https://www.onlyworlds.com/api/v2";
 var DEFAULT_PAGE_SIZE = 100;
@@ -1134,6 +1287,74 @@ var OwV2Client = class {
     }
     await this.request("DELETE", `/account/worlds/${encodeURIComponent(worldId)}/seats/${encodeURIComponent(seatId)}`);
   }
+  // -- The hidden mark (keel #421) ------------------------------------------
+  /**
+   * PUT /{type}/{id}/hidden -- hide an element (keel #421). The owner's key or a co-builder's
+   * (a person's or a seat's) with its PIN; hiding a hidden element again changes nothing, and
+   * the element's body and `change_seq` do not move. Hidden, it is seen only by the owner, the
+   * co-builders and the member who created it; to every other key it is a 404, left out of
+   * lists, search, counts and the link arrays that name it. 204, no body. No Idempotency-Key.
+   */
+  async hide(type, id) {
+    await this.request("PUT", `/${type}/${id}/hidden`, { write: true, body: {}, allowEmpty: true });
+  }
+  /** DELETE /{type}/{id}/hidden -- clear the mark; an element that is not hidden stays as it is. 204. */
+  async unhide(type, id) {
+    await this.request("DELETE", `/${type}/${id}/hidden`, { write: true, allowEmpty: true });
+  }
+  // -- The account's worlds and keys (account token) -----------------------
+  /**
+   * GET /account/worlds -- every world the account owns or is a member of, with its keys by
+   * name and last four (a member sees only their own keys on a shared world). Account token only.
+   */
+  async listAccountWorlds() {
+    if (this.keyKind !== "account") {
+      throw new TypeError("listAccountWorlds needs an account token (ow_a_)");
+    }
+    const page = await this.request("GET", "/account/worlds");
+    return page.data;
+  }
+  /**
+   * POST /account/worlds/{id}/keys -- mint a world key, `scope` `'write'` (the default) or
+   * `'read'`, `name` as the key list shows it (at most 255 characters). The full key comes back
+   * once in `key`. The owner mints a world key; a member mints their own member key, 409
+   * `pin_required` (`err.isPinRequired`) for a write key while the account has no PIN. Account
+   * token only; no Idempotency-Key.
+   */
+  async mintWorldKey(worldId, opts = {}) {
+    if (this.keyKind !== "account") {
+      throw new TypeError("mintWorldKey needs an account token (ow_a_)");
+    }
+    const body = {};
+    if (opts.scope !== void 0) body.scope = opts.scope;
+    if (opts.name !== void 0) body.name = opts.name;
+    return this.request("POST", `/account/worlds/${encodeURIComponent(worldId)}/keys`, { write: true, body });
+  }
+  // -- Sign in with OnlyWorlds (OAuth 2.1 code + PKCE, keel PR 154) ---------
+  /**
+   * Start Sign in with OnlyWorlds from a tool's page: mint `state` and a PKCE verifier, keep them
+   * under `clientId` in `storage` (sessionStorage by default; in Node pass one), and send the
+   * browser to `https://www.onlyworlds.com/signin/authorize` (or only return the URL with
+   * `navigate: false`). `redirectUri` is the registered return address as a string, `https:`
+   * only, never built from `location.origin`: a tool's registration is read at
+   * `GET /api/v2/auth/clients`. `resume` is small JSON handed back by `completeSignIn`. No request
+   * is sent; any client, keyless included. The handoff sheet: Orrery `keel/signin-handoff.md` §3.
+   */
+  async signInWithOnlyWorlds(opts) {
+    return beginSignIn(this.baseUrl, opts);
+  }
+  /**
+   * Finish Sign in with OnlyWorlds on the callback page: check `state` against the record and the
+   * page against the registered address, take `code` and `state` out of the address bar, trade
+   * the code once at `POST /auth/token` with the PKCE verifier and no credential, and return the
+   * `ow_a_` token with the account and `resume`. The record is cleared on success and on refusal;
+   * the SDK keeps no token: the tool does. Refusals are `OwSignInError`: `state_mismatch` (no
+   * pending sign-in, a different state, or the wrong page; nothing sent), `invalid_grant` (keel's
+   * 400: used, expired, or another client's code), `rate_limited`, `offline`, `failed`.
+   */
+  async completeSignIn(opts) {
+    return completeSignIn(this.baseUrl, this.fetchImpl, opts);
+  }
   // -- Ask your world (keel #159) -------------------------------------------
   /**
    * POST /account/ask -- a question about a world the account owns or is in, answered by
@@ -3633,6 +3854,7 @@ export {
   absYearForEraYear,
   absoluteYear,
   approxYearLength,
+  base64url,
   breakdownStep,
   buildAskContext,
   buildWorldIndex,
@@ -3663,6 +3885,7 @@ export {
   parseDate,
   parseErrorEnvelope,
   pinExpectation,
+  pkceChallenge,
   planPhoto,
   preparePhoto,
   readCalendarConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.44.0",
+  "version": "4.46.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {