@onlyworlds/sdk 4.140.0 → 4.142.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/AGENTS.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # For AI agents using @onlyworlds/sdk
2
2
 
3
- **Current as of**: SDK **4.x** · schema-dist **v0.34.0-dist.109** (canonical 00.34.00).
3
+ **Current as of**: SDK **4.x** · schema-dist **v0.34.0-dist.110** (canonical 00.34.00).
4
4
  This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
5
5
  re-read against it, the check fails rather than letting this document rot quietly.
6
6
 
package/CHANGELOG.md CHANGED
@@ -5,6 +5,26 @@ earlier history lives in git log only.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [4.142.0] - 2026-11-10
9
+
10
+ ### Added
11
+
12
+ - `layoutOf(map, maps, pins)` and its answer type `OwLayoutOf`: the map-space profile's layout reading (rules 8 to 10) for one Map, `{ layout, ground, hand }`. `layout` is `x_layout.method` when `x_layout` is an object whose `method` is a non-empty string (`"hand"` for a board; a method no page names answers itself), else null. `ground`, only on a layout map, is the id in `x_layout.settings.ground.map` when it names a Map in `maps` other than this one, else null; its size is not returned. `hand` is the ids, in code point order, of this Map's Pins a new lay-out keeps: every Pin on a board, the Pins whose `x_hand` is exactly `true` on any other layout map, none on a plain Map. `pins` may hold every Pin the caller has: the reader keeps those whose `map` names this Map, reads a row without an id as no Pin and the last row served for an id, and counts a Pin whose element it cannot see. The method's own settings are never returned. `mapSpace` is unchanged.
13
+
14
+ ### Tests
15
+
16
+ - The layout reading replays all 17 of the fixture's `layout_cases`, whole answers in key order, the count held; edge tests beyond the fixture hold code point order (ids above U+FFFF), the row readings and a ground row without an id. `layoutOf` joins the tree-shaking checks.
17
+
18
+ ### Changed
19
+
20
+ - Schema repinned to schema-dist v0.34.0-dist.110 (canonical 00.34.00 unchanged, no schema file moved): the map-space profile gains rules 8 to 10, `x_layout` on a Map, its ground and `x_hand` on a Pin, and a layout reading with its own fixture section, `layout_cases`. The map-space reading and its 34 cases do not change.
21
+
22
+ ## [4.141.0] - 2026-11-10
23
+
24
+ ### Added
25
+
26
+ - `OwSignInError.param`: the field the server named when it refused the code exchange, such as `ai_uses` or `ai_lifetime_minutes` on a 422 for an AI door token asked with `completeSignIn`, so that refusal can be told from any other 422 there.
27
+
8
28
  ## [4.140.0] - 2026-11-10
9
29
 
10
30
  ### Added
package/SCHEMA.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # OnlyWorlds Schema Reference
2
2
 
3
- **Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.34.0-dist.109** — canonical schema **00.34.00**, published 2026-11-07.
3
+ **Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.34.0-dist.110** — canonical schema **00.34.00**, published 2026-11-10.
4
4
 
5
5
  GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
6
6
  Written for both humans and AI agents reading this package locally.
package/dist/index.d.ts CHANGED
@@ -4369,11 +4369,15 @@ declare class OwSignInError extends Error {
4369
4369
  readonly status?: number;
4370
4370
  /** keel's error code, when its answer carried one. */
4371
4371
  readonly code?: string;
4372
+ /** The field the server's answer named, when it named one: `ai_uses` or `ai_lifetime_minutes` on a 422 that
4373
+ * refused the AI door token asked in the exchange (the code is spent either way). */
4374
+ readonly param?: string;
4372
4375
  /** Seconds to wait before trying again, from `Retry-After` (on a 429). */
4373
4376
  readonly retryAfter?: number;
4374
4377
  constructor(reason: OwSignInReason, message: string, opts?: {
4375
4378
  status?: number;
4376
4379
  code?: string;
4380
+ param?: string;
4377
4381
  retryAfter?: number;
4378
4382
  });
4379
4383
  }
@@ -5422,7 +5426,9 @@ declare class OwV2Client {
5422
5426
  * state, on success and on refusal; a return with another state leaves the sign-in pending;
5423
5427
  * the SDK keeps no token: the tool does. Refusals are `OwSignInError`: `state_mismatch` (no
5424
5428
  * pending sign-in, a different state, or the wrong page; nothing sent), `invalid_grant` (keel's
5425
- * 400: used, expired, or another client's code), `rate_limited`, `offline`, `failed`.
5429
+ * 400: used, expired, or another client's code), `rate_limited`, `offline`, `failed`. Each carries the server's
5430
+ * `status`, `code` and, when its answer named a field, `param`: a 422 that refused the AI door token asked
5431
+ * here names `ai_uses` or `ai_lifetime_minutes` (the code is spent either way).
5426
5432
  */
5427
5433
  completeSignIn(opts: OwSignInComplete): Promise<OwSignInResult>;
5428
5434
  /**
@@ -6093,6 +6099,29 @@ interface OwMapSpace {
6093
6099
  */
6094
6100
  declare function mapSpace(elements: readonly unknown[]): OwMapSpace;
6095
6101
 
6102
+ interface OwLayoutOf {
6103
+ /** The `x_layout.method` string when the Map is a layout map (`"hand"` for a board), else null. A method no page names answers itself. */
6104
+ layout: string | null;
6105
+ /** When `layout` is not null: the id in `x_layout.settings.ground.map` when it names a served Map other than this one, else null. */
6106
+ ground: string | null;
6107
+ /** The ids of this Map's Pins a new lay-out keeps where they are, by id in code point order. */
6108
+ hand: string[];
6109
+ }
6110
+ /**
6111
+ * One Map's layout reading: `{layout, ground, hand}`, all three keys always present.
6112
+ *
6113
+ * `map` is the Map read, `maps` the Maps the reader is served, `pins` every Pin the caller holds, of any Map, as
6114
+ * served: the reader keeps the Pins whose `map` names this Map's id. A row without a non-empty string `id` is no
6115
+ * element, and of two rows with one id the last served is read, as `mapSpace` reads them.
6116
+ *
6117
+ * The Map is a layout map when `x_layout` is an object whose `method` is a non-empty string; anything else is no
6118
+ * layout, and its ground and Pins are not read. On a board (`method` `"hand"`) every Pin of the Map is in `hand`,
6119
+ * marked or not; on any other layout map only the Pins whose `x_hand` is exactly `true`; on a plain Map `hand` is
6120
+ * empty whatever its Pins carry. A Pin whose element the reader cannot see is still a Pin. The method's own settings,
6121
+ * and the ground's size, are not returned: the caller holds the served Map.
6122
+ */
6123
+ declare function layoutOf(map: unknown, maps: readonly unknown[], pins: readonly unknown[]): OwLayoutOf;
6124
+
6096
6125
  /** A place on the route, in travel order. Exactly one of `pin`, `between` or `parent` says where it sits. */
6097
6126
  interface OwTrailPlace {
6098
6127
  id: string;
@@ -7567,4 +7596,4 @@ declare class TokenResource {
7567
7596
  getEncryptionInfo(): Promise<EncryptionInfo>;
7568
7597
  }
7569
7598
 
7570
- export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, CHARTER_PAIRS, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, DATE_FIELD, ELEMENT_FAMILIES, ELEMENT_GROUPS, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementGroup, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GROUP_COLORS, GROUP_ORDER, GameTier, type ListParams, MESSAGE_PAIR, NOTE_PAIR, ONLYWORLDS_VERSION, type OwAccountToken, type OwAccountWorld, type OwAddress, OwAddressError, type OwAddressForm, type OwAddressReading, type OwAddressReason, type OwAddressingOptions, type OwAgentJoined, type OwAiAskAnswer, type OwAiAskBody, type OwAiMeter, type OwAiSortAnswer, type OwAiSortBody, type OwAiToken, type OwAiUse, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAskContextOptions, type OwAskLeftOut, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwCharterWorld, type OwClientConfig, type OwCreateAccountWorldInput, type OwCreatedAccountWorld, type OwCreatedWorldLink, type OwDeleteReason, type OwDoor, type OwDragField, type OwDraught, type OwDraughtCompact, type OwDraughtComponent, type OwDraughtItem, type OwDraughtLens, type OwDraughtPolicy, type OwEdited, type OwElement, type OwElementBase, type OwElementMark, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwGraphCutReason, type OwGraphEdge, type OwGraphMark, type OwGraphNode, type OwGraphOptions, type OwHiddenRow, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLanding, type OwLandingCluster, type OwLandingGap, type OwLandingGapKind, type OwLandingMember, type OwLandingMode, type OwLandingOptions, type OwLensCutReason, type OwLensMail, type OwLensOptions, type OwLensReader, type OwLensReading, type OwLensWorld, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMapSpace, type OwMapSpaceMap, type OwMapSpaceOutReason, type OwMapSpaceOutline, type OwMapSpacePin, type OwMapSpacePoint, type OwMe, type OwMediaTicket, type OwMember, type OwMemberLenses, type OwMemberRole, type OwMessageMember, type OwMintedAiToken, type OwMintedKey, type OwMySeat, type OwNamesMap, OwNetworkError, type OwOpener, type OwOpenerKind, type OwOpenerState, type OwOpenerSurface, type OwOpenersOptions, type OwPage, type OwPaidBy, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwProposedMark, type OwProposedNewElement, type OwReadWorldFile, type OwReadWorldFileOptions, type OwReadingAids, type OwReadingAidsCharter, type OwReadingAidsDomain, type OwReadingAidsGuide, type OwReadingAidsHub, type OwRecord, type OwRecordMark, type OwRecordStory, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwReviewInput, type OwReviewed, type OwSeat, type OwSeatCreated, type OwSender, type OwSenderStatus, type OwServedReadingAids, 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, OwStaleProposalError, type OwStrand, type OwStrandSlot, type OwStrandWorld, type OwTool, type OwToolNeeds, type OwToolOpen, type OwTrailGround, type OwTrailHanger, type OwTrailInput, type OwTrailLayout, type OwTrailPin, type OwTrailPlace, type OwTrailSettings, type OwTrailSpiral, type OwTrailTier, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldGraph, type OwWorldIndex, type OwWorldKeyMember, type OwWorldKeyRow, type OwWorldLens, type OwWorldLensReading, type OwWorldLenses, type OwWorldLink, type OwWorldMeta, type OwWorldOrigin, type OwWorldProducer, type OwWorldProposalList, type OwWorldProposalQuery, type OwWorldProposalRow, type OwWorldPublicPage, type OwWorldSource, type OwWriteDoor, type OwWriteWorldFileOptions, type OwWriteWorldFileReport, PHOTO_MAX_BYTES, PHOTO_TYPES, PROPOSED_MARK, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, RECORD_FIELD, REVIEW_PROPOSED_LABEL, ROOM_PAIRS, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, STRAND_FIELD, type SectionInfo, type StepBreakdown, TOOLS, TRAIL_TIERS, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, charterOf, dateOf, degreeOf, detectKeyKind, displayYear, domainsOf, doorWhere, doorsOf, dragField, draughtText, editedBy, elementAddress, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, groupOf, handsOnAsProposed, hasUnseenRecipients, intercalaryInYear, isAddressedTo, isAgentDoor, isCharterElement, isDemoKey, isKnownOf, isLeapYear, isLens, isMessage, isNote, isParseError, isRoomElement, isSentBy, isTemplate, isToEveryone, kindCanWrite, landingOf, lensesInUse, lookupWorld, mapSpace, monthStartSteps, nfc, noteOf, openersFor, outDegreeOf, parseDate, parseErrorEnvelope, parseOwLink, pinExpectation, pkceChallenge, planPhoto, preparePhoto, proposedMarkOf, readCalendarConfig, readCalendarValue, readMarkOf, readWorldFile, readingAidOf, recipientsOf, recordMarkOf, recordsOf, renderElement, resolveCalendar, resolveCalendarLens, resolveEraDomains, resolveLens, roundHalfEven, senderStatus, simpleCaseFold, strandOf, threadOf, trailByPlace, typeWord, unreadFor, validateCalendarConfig, weekdayForStep, worldCalendars, worldGraph, writeWorldFile, yearLength, yearStartStep };
7599
+ export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, CHARTER_PAIRS, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, DATE_FIELD, ELEMENT_FAMILIES, ELEMENT_GROUPS, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementGroup, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GROUP_COLORS, GROUP_ORDER, GameTier, type ListParams, MESSAGE_PAIR, NOTE_PAIR, ONLYWORLDS_VERSION, type OwAccountToken, type OwAccountWorld, type OwAddress, OwAddressError, type OwAddressForm, type OwAddressReading, type OwAddressReason, type OwAddressingOptions, type OwAgentJoined, type OwAiAskAnswer, type OwAiAskBody, type OwAiMeter, type OwAiSortAnswer, type OwAiSortBody, type OwAiToken, type OwAiUse, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAskContextOptions, type OwAskLeftOut, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwCharterWorld, type OwClientConfig, type OwCreateAccountWorldInput, type OwCreatedAccountWorld, type OwCreatedWorldLink, type OwDeleteReason, type OwDoor, type OwDragField, type OwDraught, type OwDraughtCompact, type OwDraughtComponent, type OwDraughtItem, type OwDraughtLens, type OwDraughtPolicy, type OwEdited, type OwElement, type OwElementBase, type OwElementMark, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwFrontDoor, type OwGraphCutReason, type OwGraphEdge, type OwGraphMark, type OwGraphNode, type OwGraphOptions, type OwHiddenRow, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLanding, type OwLandingCluster, type OwLandingGap, type OwLandingGapKind, type OwLandingMember, type OwLandingMode, type OwLandingOptions, type OwLayoutOf, type OwLensCutReason, type OwLensMail, type OwLensOptions, type OwLensReader, type OwLensReading, type OwLensWorld, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMapSpace, type OwMapSpaceMap, type OwMapSpaceOutReason, type OwMapSpaceOutline, type OwMapSpacePin, type OwMapSpacePoint, type OwMe, type OwMediaTicket, type OwMember, type OwMemberLenses, type OwMemberRole, type OwMessageMember, type OwMintedAiToken, type OwMintedKey, type OwMySeat, type OwNamesMap, OwNetworkError, type OwOpener, type OwOpenerKind, type OwOpenerState, type OwOpenerSurface, type OwOpenersOptions, type OwPage, type OwPaidBy, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwProposal, type OwProposalAccepted, type OwProposalConflict, type OwProposalList, type OwProposalQuery, type OwProposalState, type OwProposeInput, type OwProposed, OwProposedError, type OwProposedMark, type OwProposedNewElement, type OwReadWorldFile, type OwReadWorldFileOptions, type OwReadingAids, type OwReadingAidsCharter, type OwReadingAidsDomain, type OwReadingAidsGuide, type OwReadingAidsHub, type OwRecord, type OwRecordMark, type OwRecordStory, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwResyncReason, type OwReviewInput, type OwReviewed, type OwSeat, type OwSeatCreated, type OwSender, type OwSenderStatus, type OwServedReadingAids, 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, OwStaleProposalError, type OwStrand, type OwStrandSlot, type OwStrandWorld, type OwTool, type OwToolNeeds, type OwToolOpen, type OwTrailGround, type OwTrailHanger, type OwTrailInput, type OwTrailLayout, type OwTrailPin, type OwTrailPlace, type OwTrailSettings, type OwTrailSpiral, type OwTrailTier, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldGraph, type OwWorldIndex, type OwWorldKeyMember, type OwWorldKeyRow, type OwWorldLens, type OwWorldLensReading, type OwWorldLenses, type OwWorldLink, type OwWorldMeta, type OwWorldOrigin, type OwWorldProducer, type OwWorldProposalList, type OwWorldProposalQuery, type OwWorldProposalRow, type OwWorldPublicPage, type OwWorldSource, type OwWriteDoor, type OwWriteWorldFileOptions, type OwWriteWorldFileReport, PHOTO_MAX_BYTES, PHOTO_TYPES, PROPOSED_MARK, PUBLIC_FIELDS, type ParseError, type ParseOptions, type ParseResult, RECORD_FIELD, REVIEW_PROPOSED_LABEL, ROOM_PAIRS, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, STRAND_FIELD, type SectionInfo, type StepBreakdown, TOOLS, TRAIL_TIERS, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, WORLD_FILE_MEDIA_TYPE, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, base64url, breakdownStep, buildAskContext, buildWorldIndex, charterOf, dateOf, degreeOf, detectKeyKind, displayYear, domainsOf, doorWhere, doorsOf, dragField, draughtText, editedBy, elementAddress, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, groupOf, handsOnAsProposed, hasUnseenRecipients, intercalaryInYear, isAddressedTo, isAgentDoor, isCharterElement, isDemoKey, isKnownOf, isLeapYear, isLens, isMessage, isNote, isParseError, isRoomElement, isSentBy, isTemplate, isToEveryone, kindCanWrite, landingOf, layoutOf, lensesInUse, lookupWorld, mapSpace, monthStartSteps, nfc, noteOf, openersFor, outDegreeOf, parseDate, parseErrorEnvelope, parseOwLink, pinExpectation, pkceChallenge, planPhoto, preparePhoto, proposedMarkOf, readCalendarConfig, readCalendarValue, readMarkOf, readWorldFile, readingAidOf, recipientsOf, recordMarkOf, recordsOf, renderElement, resolveCalendar, resolveCalendarLens, resolveEraDomains, resolveLens, roundHalfEven, senderStatus, simpleCaseFold, strandOf, threadOf, trailByPlace, typeWord, unreadFor, validateCalendarConfig, weekdayForStep, worldCalendars, worldGraph, writeWorldFile, yearLength, yearStartStep };
package/dist/index.js CHANGED
@@ -469,12 +469,13 @@ var OwNetworkError = class extends Error {
469
469
  };
470
470
  var OwSignInError = class extends Error {
471
471
  constructor(reason, message, opts = {}) {
472
- refuseUnknownOptions("OwSignInError", opts, ["status", "code", "retryAfter"]);
472
+ refuseUnknownOptions("OwSignInError", opts, ["status", "code", "param", "retryAfter"]);
473
473
  super(message);
474
474
  this.name = "OwSignInError";
475
475
  this.reason = reason;
476
476
  if (opts.status !== void 0) this.status = opts.status;
477
477
  if (opts.code !== void 0) this.code = opts.code;
478
+ if (opts.param !== void 0) this.param = opts.param;
478
479
  if (opts.retryAfter !== void 0) this.retryAfter = opts.retryAfter;
479
480
  }
480
481
  };
@@ -764,16 +765,17 @@ async function completeSignIn(baseUrl, fetchImpl, opts) {
764
765
  }
765
766
  const err = body?.error;
766
767
  const errCode = typeof err?.code === "string" ? err.code : void 0;
768
+ const errParam = typeof err?.param === "string" && err.param !== "" ? err.param : void 0;
767
769
  const errMessage = typeof err?.message === "string" ? err.message : void 0;
768
770
  if (res.status === 429) {
769
- throw new OwSignInError("rate_limited", errMessage ?? "Too many sign-in attempts. Wait a while, then try again.", { status: 429, code: errCode, retryAfter });
771
+ throw new OwSignInError("rate_limited", errMessage ?? "Too many sign-in attempts. Wait a while, then try again.", { status: 429, code: errCode, param: errParam, retryAfter });
770
772
  }
771
773
  if (res.status === 400 && errCode === "invalid_grant") {
772
- 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 });
774
+ 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, param: errParam });
773
775
  }
774
776
  const ok = body;
775
777
  if (!res.ok || typeof ok?.token !== "string" || ok.token === "" || typeof ok.account?.id !== "string") {
776
- throw new OwSignInError("failed", errMessage ?? `Signing in did not work (${res.status}).`, { status: res.status, code: errCode });
778
+ throw new OwSignInError("failed", errMessage ?? `Signing in did not work (${res.status}).`, { status: res.status, code: errCode, param: errParam });
777
779
  }
778
780
  return {
779
781
  token: ok.token,
@@ -2184,7 +2186,9 @@ var OwV2Client = class {
2184
2186
  * state, on success and on refusal; a return with another state leaves the sign-in pending;
2185
2187
  * the SDK keeps no token: the tool does. Refusals are `OwSignInError`: `state_mismatch` (no
2186
2188
  * pending sign-in, a different state, or the wrong page; nothing sent), `invalid_grant` (keel's
2187
- * 400: used, expired, or another client's code), `rate_limited`, `offline`, `failed`.
2189
+ * 400: used, expired, or another client's code), `rate_limited`, `offline`, `failed`. Each carries the server's
2190
+ * `status`, `code` and, when its answer named a field, `param`: a 422 that refused the AI door token asked
2191
+ * here names `ai_uses` or `ai_lifetime_minutes` (the code is spent either way).
2188
2192
  */
2189
2193
  async completeSignIn(opts) {
2190
2194
  only("completeSignIn", opts, ["clientId", "storage", "url", "aiUses", "aiLifetimeMinutes"]);
@@ -4173,6 +4177,40 @@ function mapSpace(elements) {
4173
4177
  return { maps: mapRows, zones: outlines, pins, out: counted };
4174
4178
  }
4175
4179
 
4180
+ // src/layout-of.ts
4181
+ var isRow2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
4182
+ var idOf3 = (v) => typeof v === "string" && v !== "" ? v : null;
4183
+ function layoutOf(map, maps, pins) {
4184
+ if (!isRow2(map)) throw new TypeError("layoutOf: map is one Map element.");
4185
+ if (!Array.isArray(maps)) throw new TypeError("layoutOf: maps is a list of Map elements.");
4186
+ if (!Array.isArray(pins)) throw new TypeError("layoutOf: pins is a list of Pin elements.");
4187
+ const none = { layout: null, ground: null, hand: [] };
4188
+ const id = idOf3(map.id);
4189
+ if (id === null) return none;
4190
+ const recipe = map.x_layout;
4191
+ if (!isRow2(recipe)) return none;
4192
+ const method = recipe.method;
4193
+ if (typeof method !== "string" || method === "") return none;
4194
+ let ground = null;
4195
+ const settings = recipe.settings;
4196
+ const g = isRow2(settings) && isRow2(settings.ground) ? idOf3(settings.ground.map) : null;
4197
+ if (g !== null && g !== id && maps.some((m) => isRow2(m) && idOf3(m.id) === g)) ground = g;
4198
+ const held = /* @__PURE__ */ new Map();
4199
+ for (const p of pins) {
4200
+ if (!isRow2(p)) continue;
4201
+ const pid = idOf3(p.id);
4202
+ if (pid !== null) held.set(pid, p);
4203
+ }
4204
+ const board = method === "hand";
4205
+ const hand = [];
4206
+ for (const [pid, p] of held) {
4207
+ if (idOf3(p.map) !== id) continue;
4208
+ if (board || p.x_hand === true) hand.push(pid);
4209
+ }
4210
+ hand.sort(byCodePoint);
4211
+ return { layout: method, ground, hand };
4212
+ }
4213
+
4176
4214
  // src/layout-trail.ts
4177
4215
  var tier = (name, z, kinds) => /* @__PURE__ */ Object.freeze({ name, z, kinds: /* @__PURE__ */ Object.freeze(kinds) });
4178
4216
  var TRAIL_TIERS = /* @__PURE__ */ Object.freeze([
@@ -6679,6 +6717,7 @@ export {
6679
6717
  isToEveryone,
6680
6718
  kindCanWrite,
6681
6719
  landingOf,
6720
+ layoutOf,
6682
6721
  lensesInUse,
6683
6722
  lookupWorld,
6684
6723
  mapSpace,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.140.0",
3
+ "version": "4.142.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {