@onlyworlds/sdk 4.45.0 → 4.47.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.47.0] - 2026-10-22
+
+### Added
+- `draught(characterId, policy)`: `GET /character/{id}/context` (keel PR 155, D143, live 2026-10-22 02:05), one Character's context in one read, typed as `OwDraught` with the policy's seven keys (`components`, `mode`, `asOf`, `undated`, `since`, `budget`, `depth`) as `OwDraughtPolicy`.
+- `list` takes `ids` (1 to 200, the list's own order; one the key cannot see is absent) and `createdBy` (a membership id, or `'owner'`), the two list filters of the same PR; both were already reachable through `filter`.
+
+## [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

package/dist/index.d.ts

@@ -2431,6 +2431,83 @@ interface OwSignedIn {
  * (`'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).
  */
+/** The draught's policy (keel PR 155, D143): what GET /character/{id}/context serves and how. */
+interface OwDraughtPolicy {
+    /** Sections to serve; default every one but `messages`. */
+    components?: OwDraughtComponent[];
+    /** `voice`: her slice, as she would read (default). `act`: through the caller's own view. */
+    mode?: 'voice' | 'act';
+    /** The horizon in the world's time unit; default the world's `time_range_current`. */
+    asOf?: number;
+    /** Undated Events: `include` (default, marked `dated: false`, after the dated) or `exclude`. */
+    undated?: 'include' | 'exclude';
+    /** For `recent`: a /changes cursor, or an ISO 8601 time (as /changes' `after`). Absent, `recent` is empty. */
+    since?: string;
+    /** Items per section, 1 to 1000, default 50; `cut` says what was dropped. */
+    budget?: number;
+    /** The sheet's reach: 1 (default) what her own element links to, 0 none. */
+    depth?: 0 | 1;
+}
+type OwDraughtComponent = 'self' | 'role' | 'work' | 'style' | 'events' | 'knowledge' | 'names' | 'sheet' | 'recent' | 'messages' | 'roster';
+/** An element as the draught serves it: the list route's body plus how it got here. */
+type OwDraughtItem = OwElement & {
+    /** The link fields that brought it (on the element, or on her own element in `sheet`). */
+    via: string[];
+    /** How many of the packet's elements link to it. */
+    her_links: number;
+    grade: 'whole' | 'known_of';
+    /** On an Event: false when it carries no date (ranked after the dated). */
+    dated?: boolean;
+};
+/** One Character's context in one read, GET /character/{id}/context (keel PR 155, D143; the draught). */
+interface OwDraught {
+    world: {
+        id: string;
+        name: string;
+        description: string;
+    };
+    /** The world's own time fields, as it carries them. */
+    calendar: Record<string, unknown>;
+    as_of: number | null;
+    now: number | null;
+    mode: 'voice' | 'act';
+    /** The policy served under, every key resolved. */
+    policy: Record<string, unknown>;
+    /** {section: items the budget dropped}; empty when whole. */
+    cut: Record<string, number>;
+    recent_cursor: string | null;
+    recent_more: boolean | null;
+    /** Her own element (`self: true`), or a stub when this reader knows her only as known of. */
+    character: (OwElement & {
+        self: true;
+        grade: 'whole' | 'known_of';
+    }) | null;
+    role?: OwDraughtItem[];
+    work?: OwDraughtItem[];
+    style?: OwDraughtItem | null;
+    events?: OwDraughtItem[];
+    knowledge?: OwDraughtItem[];
+    /** Everything else that names her, by type. */
+    names?: Record<string, OwDraughtItem[]>;
+    sheet?: OwDraughtItem[];
+    messages?: OwDraughtItem[];
+    recent?: Array<{
+        op: 'upsert' | 'delete';
+        type: string;
+        id: string;
+        when: string | null;
+        who: string | null;
+        [k: string]: unknown;
+    }>;
+    roster?: Array<{
+        id: string | null;
+        kind: string;
+        role: string;
+        character: string | null;
+        status: string;
+        name: string;
+    }>;
+}
 interface OwAccountWorld {
     id: string;
     name: string;
@@ -2639,6 +2716,10 @@ interface OwFileDownload {
 interface ListParams {
     limit?: number;
     cursor?: string;
+    /** Only these ids (1 to 200), in the list's own order; one this key cannot see is simply absent (keel PR 155). */
+    ids?: string[];
+    /** A membership id, or `'owner'` for the owner's own writes: only what that member created (keel PR 155). */
+    createdBy?: string;
     /** One-level stub expansion, e.g. ['friends', 'location']. */
     expand?: string[];
     /** Sparse include-set of field names. */
@@ -2898,7 +2979,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`).
@@ -2958,6 +3039,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.
@@ -3006,6 +3146,18 @@ declare class OwV2Client {
     members(): Promise<OwMember[]>;
     /** GET /{type}/ -- one cursor page. */
     list(type: ElementType | string, params?: ListParams): Promise<OwPage>;
+    /**
+     * GET /character/{id}/context -- the draught (keel PR 155, D143): what one Character knows, as the
+     * recorded world holds it, in one read: her element, what she holds and sits in, her open work,
+     * how she works, the Events she was in, the Narratives she knows, everything else that names
+     * her, her sheet, what changed around her (`since`), and who plays whom; the world's name and
+     * calendar beside. Every body is the list route's for the same reader, with `via`, `her_links`
+     * and `grade`; nothing is inferred. The owner's keys, co-builders and contributors for any
+     * Character they can see; a player seat or a guest for its own Character only (another id is
+     * 404). `asOf` is a filter on the elements' own dates, not time travel. A `cut` that is not
+     * empty means the serving is partial. Served `Cache-Control: private, no-store`.
+     */
+    draught(characterId: string, policy?: OwDraughtPolicy): Promise<OwDraught>;
     /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
     listAll(type: ElementType | string, params?: Omit<ListParams, 'cursor'>): AsyncGenerator<OwElement>;
     /**
@@ -3486,6 +3638,26 @@ declare class OwV2Client {
         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
@@ -4528,4 +4700,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 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, 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 OwDraught, type OwDraughtComponent, type OwDraughtItem, type OwDraughtPolicy, 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;
@@ -406,11 +559,36 @@ var OwV2Client = class {
       cursor: params.cursor,
       expand: params.expand?.join(","),
       fields: params.fields?.join(","),
+      ids: params.ids?.join(","),
+      created_by: params.createdBy,
       ...params.filter,
       as: params.viewAs
     });
     return this.request("GET", `/${type}/`, { query });
   }
+  /**
+   * GET /character/{id}/context -- the draught (keel PR 155, D143): what one Character knows, as the
+   * recorded world holds it, in one read: her element, what she holds and sits in, her open work,
+   * how she works, the Events she was in, the Narratives she knows, everything else that names
+   * her, her sheet, what changed around her (`since`), and who plays whom; the world's name and
+   * calendar beside. Every body is the list route's for the same reader, with `via`, `her_links`
+   * and `grade`; nothing is inferred. The owner's keys, co-builders and contributors for any
+   * Character they can see; a player seat or a guest for its own Character only (another id is
+   * 404). `asOf` is a filter on the elements' own dates, not time travel. A `cut` that is not
+   * empty means the serving is partial. Served `Cache-Control: private, no-store`.
+   */
+  async draught(characterId, policy = {}) {
+    const query = buildQuery({
+      components: policy.components?.join(","),
+      mode: policy.mode,
+      as_of: policy.asOf,
+      undated: policy.undated,
+      since: policy.since,
+      budget: policy.budget,
+      depth: policy.depth
+    });
+    return this.request("GET", `/character/${characterId}/context`, { query });
+  }
   /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
   async *listAll(type, params = {}) {
     let cursor;
@@ -1177,6 +1355,31 @@ var OwV2Client = class {
     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
@@ -3676,6 +3879,7 @@ export {
   absYearForEraYear,
   absoluteYear,
   approxYearLength,
+  base64url,
   breakdownStep,
   buildAskContext,
   buildWorldIndex,
@@ -3706,6 +3910,7 @@ export {
   parseDate,
   parseErrorEnvelope,
   pinExpectation,
+  pkceChallenge,
   planPhoto,
   preparePhoto,
   readCalendarConfig,

package/package.json

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