@onlyworlds/sdk 4.30.0 → 4.31.0

package/AGENTS.md

@@ -57,6 +57,10 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
 - Who am I (since 4.22.0, a world key): `client.me()` is `{ world, scope, kind, role,
   membership, character }` (`membership` is what `created_by` holds for what you create; null
   for the owner); `client.members()` is the roster's rows. An account token is a TypeError.
+- Signing in (no key needed): `new OwV2Client().signInWithPassword({ email, password,
+  tokenName })` (or `username`) mints an `ow_a_` account token named for the device and ends
+  the sign-in session; only the token comes back. Refusals: `OwSignInError` with `reason`
+  (`invalid_credentials`, `email_unverified`, `rate_limited`, `offline`, `mint_failed`, `failed`).
 - Invite links (since 4.12.0): `previewJoin(code)` (no credential sent) shows who invites, to
   which world, in what role; `acceptJoin(code)` with an `ow_a_` account token joins. Bad code:
   `err.isNotFound`; `err.isAlreadyMember`, `err.isPinRequired` for the two 409s.

package/CHANGELOG.md

@@ -5,6 +5,35 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.31.0] — 2026-10-18
+
+### Added
+- **Signing in with a password** (keel #211): `signInWithPassword({ email | username, password, tokenName })`
+  turns an email address (or username) and password into a new account token (`ow_a_`) for this device,
+  named `tokenName`, the name the account's tokens page lists it under. It signs in at keel's sign-in service
+  (`{baseUrl}/auth/app/v1`), mints the token with that session at `POST /account/tokens`, then ends the
+  session, whether the mint worked or not. Only the token comes back (`OwSignedIn`: `token`, `id`, `name`,
+  `last4`); the password is sent once and held nowhere. Works on a client with no key, and sends no key
+  whatever the client holds. Exactly one of `email` and `username`, else a TypeError before sending.
+- `OwSignInError`, with a `reason`: `invalid_credentials`, `email_unverified`, `rate_limited` (with
+  `retryAfter` when keel sends it), `offline`, `mint_failed` or `failed`, plus keel's `status` and `code`.
+  The password is never in its message or properties. For Atlas's sign-in (atlas #387) and Lantern, which
+  carried its own copy. The session's end is cut off after five seconds, so a hung network never holds a
+  sign-in whose token is already made. Checked live on production (a sign-in, the token reading the
+  account's worlds, revoked and read back as `key_revoked`).
+
+### Changed
+- `me()`'s doc names the player kind (keel #353).
+
+## [4.30.1] — 2026-10-16
+
+### Fixed
+- **`changes()` and `changesAll()` hand back every cursor as a string**, as `OwChangesPage.cursor` has
+  always said. keel sends the cursor of a page at the head of the feed (an empty page, for any key but
+  a guest's) as a number, and it passed through as one: a walk of an up-to-date world returned
+  `{ cursor: 818 }`, so a cursor stored and compared as a string could miss. `changesHead()` already
+  did this. Found on production with a demo key.
+
 ## [4.30.0] — 2026-10-16
 
 ### Added

package/README.md

@@ -110,6 +110,19 @@ await writer.patch('character', id, { image_url: null });
 
 The image's uploader or the world's owner can remove an uploaded image; the space goes back to the uploader's storage. Removal leaves elements as they are, so clear their `image_url` yourself (`createRemovalTicket(key).referenced` says how many still show it). A copy the network already holds can keep answering for a while.
 
+## Signing in
+
+An app where people sign in with their OnlyWorlds email (or username) and password turns that into an account token for the device. A client with no key can do it:
+
+```typescript
+const { token } = await new OwV2Client().signInWithPassword({
+  email, password, tokenName: 'My app on iPhone', // the name the account's tokens page lists it under
+});
+const account = new OwV2Client({ apiKey: token }); // keep the token; the password is not kept anywhere
+```
+
+The SDK signs in, mints the token, and ends the sign-in session. A refusal is an `OwSignInError` whose `reason` is `invalid_credentials`, `email_unverified`, `rate_limited` (see `retryAfter`), `offline`, `mint_failed` or `failed`.
+
 ## Invite links
 
 A world's owner can invite a person with a link (`https://www.onlyworlds.com/join#ow_j_…`). The code is the part after `#`:

package/dist/index.d.ts

@@ -2317,6 +2317,17 @@ interface OwPlayerJoined {
 }
 /** POST /join's answer: tell the two apart by `kind`. */
 type OwJoined = OwAgentJoined | OwPlayerJoined;
+/** signInWithPassword's answer: the new account token, shown once, and its row on the account's tokens page. */
+interface OwSignedIn {
+    /** The account token (`ow_a_`): keep it, it is the only copy. */
+    token: string;
+    /** The token's id, for revoking it. */
+    id: string;
+    /** The name it was made under (`tokenName`). */
+    name: string;
+    /** Its last four characters, as the account's tokens page shows them. */
+    last4: string;
+}
 /** One live agent seat, as GET /account/worlds/{id}/seats lists it (keel #355, D106). No key or secret. */
 interface OwSeat {
     /** The seat's membership id: removeSeat takes it, and GET /members names the seat by it. */
@@ -2418,7 +2429,7 @@ interface OwClientConfig {
     /**
      * The key: an ow_w_ (write) or ow_r_ (read) world key, an ow_a_ account token (sent as a Bearer token, for the account routes), or a 10-digit legacy key.
      * Leave it out for a client that holds none, such as a friend with only a link (since 4.30.0): it can call health,
-     * previewJoin and redeemJoin, and any other call is a TypeError before anything is sent.
+     * previewJoin, redeemJoin and signInWithPassword, and any other call is a TypeError before anything is sent.
      */
     apiKey?: string;
     /**
@@ -2573,6 +2584,37 @@ declare class OwNetworkError extends Error {
     readonly cause2: unknown;
     constructor(message: string, cause: unknown);
 }
+/**
+ * Why `signInWithPassword` refused:
+ * - `invalid_credentials`: keel does not know that email (or username) with that password.
+ * - `email_unverified`: the account's email address is not confirmed yet; the link is in the
+ *   mail onlyworlds.com sent when the account was made.
+ * - `rate_limited`: too many sign-ins (a 429), or too many failed ones for this account
+ *   (`too_many_login_attempts`); wait `retryAfter` seconds when it is set.
+ * - `offline`: the request never reached keel.
+ * - `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';
+/**
+ * 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`).
+ * The password is never in the message or in any property.
+ */
+declare class OwSignInError extends Error {
+    readonly reason: OwSignInReason;
+    /** The HTTP status of the refusing answer; absent when nothing came back (`offline`). */
+    readonly status?: number;
+    /** keel's error code, when its answer carried one. */
+    readonly code?: string;
+    /** Seconds to wait before trying again, from `Retry-After` (on a 429). */
+    readonly retryAfter?: number;
+    constructor(reason: OwSignInReason, message: string, opts?: {
+        status?: number;
+        code?: string;
+        retryAfter?: number;
+    });
+}
 /** Parse a wire envelope into OwApiError parts (exported for the error type-tests). */
 /** Parse the platform ERROR envelope into an OwApiError. (Renamed from parseEnvelope in 4.0 —
  *  distinct from the world-export envelope, which is a different artifact entirely.) */
@@ -2596,7 +2638,7 @@ type OwKeyKind =
  | 'account'
 /** Grandfathered 10-digit key. Needs PIN to read private worlds. */
  | 'legacy' | 'unknown'
-/** No key: a client for the routes that send none (health, previewJoin, redeemJoin), as a friend with only a link has. */
+/** No key: a client for the routes that send none (health, previewJoin, redeemJoin, signInWithPassword), as a friend with only a link has. */
  | 'none';
 /** Demo range 0000000000-0000000009: read-only aliases, safe as live read gates. */
 declare function isDemoKey(key: string): boolean;
@@ -2645,7 +2687,7 @@ declare class OwV2Client {
     patchWorld(partial: Record<string, unknown>): Promise<OwWorldMeta>;
     /**
      * GET /me -- who this world key is: the world, read or write scope, the kind (owner,
-     * person, agent), the role, the membership id (what `created_by` holds for what this key
+     * person, agent, player), the role, the membership id (what `created_by` holds for what this key
      * creates; null for the owner) and the member's Character. A world key's call; an account
      * token is a TypeError before sending.
      */
@@ -2735,6 +2777,8 @@ declare class OwV2Client {
      * view changed (a guest's, or its role): drop the cursor, walk from zero, and
      * replace the local copy rather than merging into it.
      * Citizenship: heaviest route on the platform; default page size is polite.
+     * keel sends the cursor of a page at the head as a number (an empty page, for anyone
+     * but a guest); it is handed back as a string, like every cursor here.
      */
     changes(opts?: {
         since?: string;
@@ -2848,6 +2892,32 @@ declare class OwV2Client {
         name?: string;
         agentName?: string;
     }): Promise<OwJoined>;
+    /**
+     * Sign in with an email address (or a username) and password, and get a new account token
+     * (`ow_a_`) for this device, named `tokenName` (say, "Lantern on iPhone"): the name the
+     * account's tokens page lists it under, where it can be revoked. Pass exactly one of
+     * `email` and `username`; both or neither is a TypeError before anything is sent.
+     *
+     * Works on a client with no key, and sends no key whatever this client holds. Three
+     * requests: a sign-in at keel's sign-in service (`{baseUrl}/auth/app/v1/auth/login`), which
+     * answers with a short-lived session; `POST /account/tokens` with that session, which mints
+     * the token; then the session is ended, whether the mint worked or not. Only the token is
+     * kept: the password is sent once and held nowhere, and the session never leaves this call.
+     * Store the token as you would any account token, and make a client with it
+     * (`new OwV2Client({ apiKey: token })`).
+     *
+     * A refusal is an `OwSignInError` whose `reason` says why: `invalid_credentials` (wrong
+     * email, username or password), `email_unverified` (the account's email address is not
+     * confirmed yet), `rate_limited` (too many attempts; `retryAfter` when keel sent it),
+     * `offline` (keel was not reached), `mint_failed` (signed in, but no token was made) or
+     * `failed` (anything else, with keel's message). The password is never in an error.
+     */
+    signInWithPassword(opts: {
+        email?: string;
+        username?: string;
+        password: string;
+        tokenName: string;
+    }): Promise<OwSignedIn>;
     /**
      * POST /account/join -- accept an invite link's code as the account this client's
      * `ow_a_` token belongs to: 201 with the new membership. Refusals: 404 `not_found`
@@ -3925,4 +3995,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_SCHEMA, 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 OwElement, type OwElementBase, type OwErrorBody, 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 OwSeat, type OwSeatCreated, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, 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, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, 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_SCHEMA, 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 OwElement, type OwElementBase, type OwErrorBody, 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 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 OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, 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, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -182,6 +182,16 @@ var OwNetworkError = class extends Error {
     this.cause2 = cause;
   }
 };
+var OwSignInError = class extends Error {
+  constructor(reason, message, opts = {}) {
+    super(message);
+    this.name = "OwSignInError";
+    this.reason = reason;
+    if (opts.status !== void 0) this.status = opts.status;
+    if (opts.code !== void 0) this.code = opts.code;
+    if (opts.retryAfter !== void 0) this.retryAfter = opts.retryAfter;
+  }
+};
 function parseErrorEnvelope(status, body, retryAfter = null) {
   const env = body && typeof body === "object" ? body : {};
   const nested = typeof env.error === "object" && env.error !== null ? env.error : void 0;
@@ -282,7 +292,7 @@ var OwV2Client = class {
   // -- Who am I, and who is here ---------------------------------------------
   /**
    * GET /me -- who this world key is: the world, read or write scope, the kind (owner,
-   * person, agent), the role, the membership id (what `created_by` holds for what this key
+   * person, agent, player), the role, the membership id (what `created_by` holds for what this key
    * creates; null for the owner) and the member's Character. A world key's call; an account
    * token is a TypeError before sending.
    */
@@ -431,10 +441,13 @@ var OwV2Client = class {
    * view changed (a guest's, or its role): drop the cursor, walk from zero, and
    * replace the local copy rather than merging into it.
    * Citizenship: heaviest route on the platform; default page size is polite.
+   * keel sends the cursor of a page at the head as a number (an empty page, for anyone
+   * but a guest); it is handed back as a string, like every cursor here.
    */
   async changes(opts = {}) {
     const query = buildQuery({ since: opts.since, limit: opts.limit ?? this.changesPageSize });
-    return this.request("GET", "/changes/", { query });
+    const page = await this.request("GET", "/changes/", { query });
+    return { ...page, cursor: String(page.cursor) };
   }
   /**
    * GET /changes?head=true -- where the feed is now, without a page: no element is read.
@@ -585,6 +598,131 @@ var OwV2Client = class {
     if (opts.agentName !== void 0) body.agent_name = opts.agentName;
     return this.request("POST", "/join", { auth: false, body });
   }
+  // -- Signing in with a password (keel #211) --------------------------------
+  /**
+   * Sign in with an email address (or a username) and password, and get a new account token
+   * (`ow_a_`) for this device, named `tokenName` (say, "Lantern on iPhone"): the name the
+   * account's tokens page lists it under, where it can be revoked. Pass exactly one of
+   * `email` and `username`; both or neither is a TypeError before anything is sent.
+   *
+   * Works on a client with no key, and sends no key whatever this client holds. Three
+   * requests: a sign-in at keel's sign-in service (`{baseUrl}/auth/app/v1/auth/login`), which
+   * answers with a short-lived session; `POST /account/tokens` with that session, which mints
+   * the token; then the session is ended, whether the mint worked or not. Only the token is
+   * kept: the password is sent once and held nowhere, and the session never leaves this call.
+   * Store the token as you would any account token, and make a client with it
+   * (`new OwV2Client({ apiKey: token })`).
+   *
+   * A refusal is an `OwSignInError` whose `reason` says why: `invalid_credentials` (wrong
+   * email, username or password), `email_unverified` (the account's email address is not
+   * confirmed yet), `rate_limited` (too many attempts; `retryAfter` when keel sent it),
+   * `offline` (keel was not reached), `mint_failed` (signed in, but no token was made) or
+   * `failed` (anything else, with keel's message). The password is never in an error.
+   */
+  async signInWithPassword(opts) {
+    const { email, username, password, tokenName } = opts ?? {};
+    const login = typeof email === "string" ? email.trim() : "";
+    const user = typeof username === "string" ? username.trim() : "";
+    if (Boolean(login) === Boolean(user)) {
+      throw new TypeError("signInWithPassword takes exactly one of email and username");
+    }
+    if (typeof password !== "string" || password === "") {
+      throw new TypeError("signInWithPassword needs a password");
+    }
+    if (typeof tokenName !== "string" || tokenName.trim() === "") {
+      throw new TypeError("signInWithPassword needs a tokenName: the name the new token is listed under");
+    }
+    const auth = `${this.baseUrl}/auth/app/v1`;
+    const safe = (text, fallback) => typeof text === "string" && text !== "" && !text.includes(password) ? text : fallback;
+    let res;
+    try {
+      res = await this.fetchImpl(`${auth}/auth/login`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(login ? { email: login, password } : { username: user, password })
+      });
+    } 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;
+    if (res.status === 429) {
+      throw new OwSignInError("rate_limited", "Too many sign-in attempts. Wait a while, then try again.", {
+        status: 429,
+        retryAfter
+      });
+    }
+    const body = await readJsonBody(res);
+    const sessionToken = body?.meta?.session_token;
+    const session = typeof sessionToken === "string" && sessionToken !== "" ? sessionToken : void 0;
+    if (!res.ok || !session) {
+      if (session) await endAuthSession(this.fetchImpl, auth, session);
+      const errors = Array.isArray(body?.errors) ? body.errors : [];
+      const codes = errors.map((e) => e?.code).filter((c) => typeof c === "string");
+      const first = errors.find((e) => typeof e?.message === "string")?.message;
+      const code = codes.find((c) => !c.includes(password));
+      const status = res.status;
+      const mismatch = codes.find((c) => c === "email_password_mismatch" || c === "username_password_mismatch");
+      if (mismatch) {
+        throw new OwSignInError(
+          "invalid_credentials",
+          safe(first, "The email address and/or password you specified are not correct."),
+          { status, code: mismatch }
+        );
+      }
+      if (codes.includes("too_many_login_attempts")) {
+        throw new OwSignInError(
+          "rate_limited",
+          safe(first, "Too many failed sign-in attempts. Try again later."),
+          { status, code: "too_many_login_attempts", retryAfter }
+        );
+      }
+      const flows = Array.isArray(body?.data?.flows) ? body.data.flows : [];
+      if (status === 401 && flows.some((f) => f?.id === "verify_email" && f?.is_pending === true)) {
+        throw new OwSignInError(
+          "email_unverified",
+          "Confirm the account's email address first: the link is in the mail onlyworlds.com sent.",
+          { status, code }
+        );
+      }
+      throw new OwSignInError(
+        "failed",
+        safe(first, res.ok ? "Signing in did not work: onlyworlds.com sent no session." : `Signing in did not work (${status}).`),
+        { status, code }
+      );
+    }
+    try {
+      let minted;
+      try {
+        minted = await this.fetchImpl(`${this.baseUrl}/account/tokens`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "X-Session-Token": session },
+          body: JSON.stringify({ name: tokenName })
+        });
+      } catch {
+        throw new OwSignInError("offline", "The connection dropped after signing in: no token was made. Try again.");
+      }
+      const row = await readJsonBody(minted);
+      const token = row?.token;
+      if (minted.status !== 201 || typeof token !== "string" || token === "") {
+        const err = row && typeof row.error === "object" && row.error !== null ? row.error : void 0;
+        const said = err?.code;
+        const code = typeof said === "string" && !said.includes(password) ? said : void 0;
+        throw new OwSignInError(
+          "mint_failed",
+          safe(err?.message, `Signed in, but no token was made (${minted.status}). Try again.`),
+          { status: minted.status, code }
+        );
+      }
+      return {
+        token,
+        id: typeof row.id === "string" ? row.id : "",
+        name: typeof row.name === "string" ? row.name : tokenName,
+        last4: typeof row.last4 === "string" ? row.last4 : token.slice(-4)
+      };
+    } finally {
+      await endAuthSession(this.fetchImpl, auth, session);
+    }
+  }
   /**
    * POST /account/join -- accept an invite link's code as the account this client's
    * `ow_a_` token belongs to: 201 with the new membership. Refusals: 404 `not_found`
@@ -764,7 +902,7 @@ var OwV2Client = class {
       throw new TypeError(`ifMatch must be a whole number (an element's change_seq), got ${String(opts.ifMatch)}`);
     }
     if (opts.auth !== false && this.keyKind === "none") {
-      throw new TypeError(`${method} ${path} needs a key, and this client holds none: without one, only health, previewJoin and redeemJoin work`);
+      throw new TypeError(`${method} ${path} needs a key, and this client holds none: without one, only health, previewJoin, redeemJoin and signInWithPassword work`);
     }
     const url = `${this.baseUrl}${path}${opts.query ? `?${opts.query}` : ""}`;
     const headers = {};
@@ -809,6 +947,24 @@ function sanitizePayload(payload) {
   for (const field of READ_ONLY_FIELDS) delete rest[field];
   return rest;
 }
+async function endAuthSession(fetchImpl, auth, session) {
+  const abort = new AbortController();
+  const timer = setTimeout(() => abort.abort(), 5e3);
+  try {
+    await fetchImpl(`${auth}/auth/session`, { method: "DELETE", headers: { "X-Session-Token": session }, signal: abort.signal });
+  } catch {
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function readJsonBody(res) {
+  try {
+    const text = await res.text();
+    return text ? JSON.parse(text) : null;
+  } catch {
+    return null;
+  }
+}
 function readReplayHeader(headers) {
   const v = headers.get("Idempotent-Replay");
   return v != null && v.toLowerCase() === "true";
@@ -3033,6 +3189,7 @@ export {
   OwApiError,
   OwNetworkError,
   OwPreconditionFailedError,
+  OwSignInError,
   OwV2Client,
   OwWorldFileError,
   PHOTO_MAX_BYTES,

package/package.json

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