@onlyworlds/sdk 4.149.0 → 4.151.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.113** (canonical 00.34.00).
3
+ **Current as of**: SDK **4.x** · schema-dist **v0.34.0-dist.114** (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.151.0] - 2026-11-10
9
+
10
+ ### Added
11
+
12
+ - **`viewOf` returns `order`: the fields an element's page draws, in the order drawn** (`views.json` version 2): the row's `lead`, then the rest of the type's section fields in the schema's own order, then each `fold`; each field once, and only a field that holds something (not absent, null, a string with nothing after trimming, an empty list or an empty object), so an empty lead field is skipped and an empty fold draws no fold. The base fields are the page's head and appear only where a row names one. With no row, the type's section fields.
13
+
14
+ ### Changed
15
+
16
+ - **The `x_served_trimmed` banner shows only when the list names a field**: at least one string with something left after trimming. A list of blanks, or of anything but strings, shows none (4.147.0 showed it for any non-empty list).
17
+ - **`VIEWS.version` is `2`**, the version of `views.json` baked at this release; codegen reads version 2 only.
18
+ - Where two rows match on one rung, the first in the table wins and the page is drawn, as before; the file now says so, and the fixture holds the case.
19
+ - **A lens's short rows carry `supertype` and `subtype`**: a `name` or `first_line` row from `resolveLens` now holds each where the element as served holds it as a string with something left after trimming White_Space, as stored (never trimmed); absent, null, empty, White_Space alone or a value that is not a string adds no key. A known-of stub's row carries them too, since a stub is served both. Rows under `full` are unchanged.
20
+ - **Schema repinned to schema-dist v0.34.0-dist.114** (from dist.113; same canonical 00.34.00, no schema file moved): `views.json` version 2 and its 41 cases; the lens fixture at 210 cases (nine for the short rows), all replayed; the review profile's rule 5 (an object with at least one key is a mark, whatever its keys: `proposedMarkOf` already read it so, and its tests now name the rule's two examples); the report profile's rule 8 (no reader here reads a report's `consequences`).
21
+
22
+ ## [4.150.0] - 2026-11-10
23
+
24
+ ### Added
25
+
26
+ - **`search(q, { type, limit, viewAs })`**: the world's elements whose name or text fields hold every word of `q` as a whole word, ignoring case, as `GET /search` finds them (`OwSearchResults`: `query`, `results`, `count`, `truncated`; each `OwSearchResult` with its `type`, `id`, `name`, `supertype`, `subtype`, the `field` the words were found in, a `snippet` of it, and `known_of` on a row the reader knows of without seeing it whole). A word is a run of letters, digits or underscores, so `APP-142` is searched as two words; a snippet is a piece of one field, so read the element to keep only those that hold a key whole. No pages: `truncated` says more matched than `limit` (1 to 200) let through. On a client with `world` set it searches that world, like the other world reads. An unknown option or a `q` that is not a string sends nothing.
27
+
8
28
  ## [4.149.0] - 2026-11-10
9
29
 
10
30
  ### Changed
package/README.md CHANGED
@@ -230,6 +230,15 @@ A world's owner can have agent seats propose instead of write (`agent_writes_pro
230
230
 
231
231
  ## Finding elements in a world
232
232
 
233
+ To ask onlyworlds.com, `search` finds the elements whose name or text holds every word you give, as whole words:
234
+
235
+ ```typescript
236
+ const { results, truncated } = await client.search('APP-142', { limit: 200 });
237
+ results[0].field; results[0].snippet; // where the words were, and a piece of that field
238
+ ```
239
+
240
+ A word is a run of letters, digits or underscores, so `APP-142` is two words; read an element before relying on a key it must hold whole. There are no pages: `truncated` means more matched than `limit` (at most 200) let through.
241
+
233
242
  When you hold a world's elements in memory (from a sync, or a world file), `lookupWorld` finds the ones a plain question is about, with no model and no network:
234
243
 
235
244
  ```typescript
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.113** — canonical schema **00.34.00**, published 2026-11-10.
3
+ **Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.34.0-dist.114** — 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.
@@ -337,7 +337,7 @@ var CHARTER_PAIRS = [
337
337
  { type: "construct", supertype: "Domain", aid: "domain" }
338
338
  ];
339
339
  var VIEWS_TABLE = {
340
- "version": 1,
340
+ "version": 2,
341
341
  "banners": [
342
342
  {
343
343
  "mark": "known_of",
@@ -361,8 +361,8 @@ var VIEWS_TABLE = {
361
361
  }
362
362
  ],
363
363
  "layouts": {
364
- "document": "the fields in the row's order: lead open, then the rest in the standard's sections, then fold; a kind with no row is a document",
365
- "conversation": "the element within its chain by the named link, oldest first by created_at, stopping at an id already visited"
364
+ "document": "the fields in the row's order, each drawn once: lead open, then the rest, then fold; a field the row names in both lead and fold is drawn in the lead. The rest are the type's section fields in the schema's own order (schema/<type>.yaml: its sections as listed, and each section's fields as listed) that the row puts in neither lead nor fold. A field that holds nothing (absent, null, a string with nothing left after trimming, a list with no items, an object with no keys; a list of blank strings holds something here, whatever a banner reads of one) is not drawn: an empty lead field is skipped, and a fold whose field holds nothing draws no fold. A tool that draws empty fields to be filled draws them at their own place in this order; it never moves a field. The base fields outside every section (name, description, supertype, subtype, image_url) are the page's head, unless the row names one in lead or fold, where it is drawn, and only there. A row names only the type's base and section fields, never an extension key, and extension keys and a world's own fields are not in the order. A kind with no row is a document.",
365
+ "conversation": "the element within its chain by the named link, oldest first by created_at, stopping at an id already visited; each line's own fields drawn as a document draws them"
366
366
  },
367
367
  "rows": [
368
368
  {
package/dist/index.d.ts CHANGED
@@ -162,7 +162,7 @@ interface OwViewRow {
162
162
  }
163
163
  /** views.json without its `_meta`: the banners every page shows, the layouts, the rows. */
164
164
  interface OwViewsTable {
165
- readonly version: 1;
165
+ readonly version: 2;
166
166
  readonly banners: readonly {
167
167
  readonly mark: string;
168
168
  readonly defined_by: string;
@@ -2221,7 +2221,10 @@ interface OwLensReading {
2221
2221
  * The kept elements as `show` makes them, in the same order; an anchor's row carries its `note`, and only an anchor
2222
2222
  * the reader can see: a note on one it cannot see (an id of another type than its field's too) goes with the
2223
2223
  * anchor, though another path keeps the element. Under `full` a row is the body as served to this reader, so the
2224
- * owner's row of a hidden element carries `hidden: true`; a `name` or `first_line` row never carries it.
2224
+ * owner's row of a hidden element carries `hidden: true`; a `name` or `first_line` row never carries it. A `name`
2225
+ * row is `id`, `type`, `name`, and `supertype` and `subtype` each where the served body holds it as a string with
2226
+ * something left after trimming White_Space, as stored; a `first_line` row adds `description` up to its first line
2227
+ * break.
2225
2228
  */
2226
2229
  rows: Record<string, unknown>[];
2227
2230
  /** The cut, counted by reason; a reason with no count is absent, and a reader that is not the owner never carries the owner's two. */
@@ -2491,6 +2494,30 @@ interface OwPage<T = OwElement> {
2491
2494
  has_more: boolean;
2492
2495
  next_cursor: string | null;
2493
2496
  }
2497
+ /** One element `search()` found: where the words were, and a short plain-text piece around the first match. */
2498
+ interface OwSearchResult {
2499
+ type: ElementType;
2500
+ id: string;
2501
+ name: string;
2502
+ supertype: string;
2503
+ subtype: string;
2504
+ /** Where the words were found: `name`, or the first text field (in the type's schema order) that holds them all, else the first that holds any. */
2505
+ field: string;
2506
+ /** Up to 160 characters of that field around the first match, as plain text. Never the whole field: read the element for its text. */
2507
+ snippet: string;
2508
+ /** Present, and true, only when the reader knows of the element without seeing it whole: it matched on what a known-of stub keeps. */
2509
+ known_of?: true;
2510
+ }
2511
+ /** search()'s answer: every element whose name or text holds every word of `q` as a whole word, up to `limit`. */
2512
+ interface OwSearchResults {
2513
+ /** `q` as searched (trimmed). */
2514
+ query: string;
2515
+ results: OwSearchResult[];
2516
+ /** How many results came back. */
2517
+ count: number;
2518
+ /** True when more elements matched than `limit` let through. There are no further pages: narrow `q` or `type`, or raise `limit`. */
2519
+ truncated: boolean;
2520
+ }
2494
2521
  /** /changes feed -- discriminated union on `op`. Apply in order -> convergence. */
2495
2522
  type OwChange = OwChangeUpsert | OwChangeDelete;
2496
2523
  /** A /changes item for an element written: the element whole, as GET returns it. */
@@ -4044,7 +4071,7 @@ interface OwClientConfig {
4044
4071
  /**
4045
4072
  * 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, and with `world` set for that world's reads), or a 10-digit legacy key.
4046
4073
  * 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,
4047
- * previewJoin, redeemJoin and signInWithPassword (and with `world` set, list, listAll, get, getWorld and draught), and any
4074
+ * previewJoin, redeemJoin and signInWithPassword (and with `world` set, list, listAll, get, search, getWorld and draught), and any
4048
4075
  * other call is a TypeError before anything is sent.
4049
4076
  */
4050
4077
  apiKey?: string;
@@ -4779,6 +4806,25 @@ declare class OwV2Client {
4779
4806
  * it reads that world, sending `world=<id>`.
4780
4807
  */
4781
4808
  get(type: ElementType | string, id: string, opts?: Pick<ListParams, 'expand' | 'fields' | 'viewAs' | 'signal'>): Promise<OwElement>;
4809
+ /**
4810
+ * GET /search -- the world's elements whose `name` or text fields (`description` and the type's other prose
4811
+ * fields; never supertype, subtype or image_url) hold every word of `q` as a whole word, ignoring case. A word
4812
+ * is a run of letters, digits or underscores, so `APP-142` is searched as the two words `APP` and `142`: a
4813
+ * result's `snippet` is a piece of one field, so read the element to keep only those that hold the key whole.
4814
+ * No stemming, no pages: `truncated` says more matched than `limit` (1 to 200, the server's default 50) let
4815
+ * through. `type` searches one type; `viewAs` reads as another reader (the owner's keys). A guest's key finds
4816
+ * only what it may read. On a client with `world` set (an account token or no key), it searches that world.
4817
+ *
4818
+ * ```ts
4819
+ * const { results, truncated } = await client.search('APP-142', { limit: 200 });
4820
+ * ```
4821
+ */
4822
+ search(q: string, opts?: {
4823
+ type?: ElementType;
4824
+ limit?: number;
4825
+ viewAs?: string;
4826
+ signal?: AbortSignal;
4827
+ }): Promise<OwSearchResults>;
4782
4828
  /**
4783
4829
  * POST /{type}/ -- create one element, minting an id on the client when you leave id out.
4784
4830
  * With an `idempotencyKey`, the minted id is derived from the key (a UUIDv5, the same one the
@@ -6617,23 +6663,34 @@ interface OwView {
6617
6663
  sentence: string | null;
6618
6664
  /** The marks to show at the head of its page, in order: the table's banners the element carries, then the row's own. */
6619
6665
  banners: string[];
6666
+ /**
6667
+ * The fields its page draws, in the order drawn (the file's document layout): the row's `lead`, then the
6668
+ * rest of the type's section fields in the standard's section order, then each `fold`; each field once,
6669
+ * and only a field that holds something (not absent, null, a string with nothing after trimming, or an
6670
+ * empty list), so an empty lead field is skipped and an empty fold draws no fold. The base fields (name,
6671
+ * description, supertype, subtype, image_url) are the page's head and appear here only where the row
6672
+ * names one in `lead` or `fold`. With no row, the type's section fields. A conversation draws each line's
6673
+ * own fields this way.
6674
+ */
6675
+ order: string[];
6620
6676
  }
6621
6677
  /** views.json as baked at this release, without its `_meta`, frozen throughout. Read one element's view with viewOf. */
6622
6678
  declare const VIEWS: OwViewsTable;
6623
6679
  /**
6624
6680
  * How an element is shown, by the views table baked at this release (`views.json`): the row that matches
6625
- * it, its one sentence, and the marks to show at the head of its page.
6681
+ * it, its one sentence, the marks to show at the head of its page, and the fields its page draws in order.
6626
6682
  *
6627
6683
  * A row matches by its kind: a profile's pair only with that profile's mark, by the profile's own reader;
6628
6684
  * a type with a supertype; a type alone; types and supertypes trimmed and folded as the room profile
6629
- * defines. The most specific row wins. The sentence is the first field the row names in `sentence` that
6685
+ * defines. The most specific row wins, and where two match on one rung the first in the table does: a
6686
+ * page is never refused over the table. The sentence is the first field the row names in `sentence` that
6630
6687
  * holds text after trimming, cut at its first line break and trimmed. Pass the element as the reader is
6631
6688
  * served it: the banners read what was served (a known-of stub, the hidden mark, a trimmed list).
6632
6689
  *
6633
6690
  * ```ts
6634
6691
  * viewOf({ type: 'narrative', supertype: 'Message', story: 'See you at the gate.\nBring the map.' });
6635
- * // { row: <the message row>, sentence: 'See you at the gate.', banners: [] }
6636
- * viewOf({ type: 'character', name: 'Ilse' }); // { row: null, sentence: null, banners: [] }
6692
+ * // { row: <the message row>, sentence: 'See you at the gate.', banners: [], order: ['story'] }
6693
+ * viewOf({ type: 'character', name: 'Ilse' }); // { row: null, sentence: null, banners: [], order: [] }
6637
6694
  * ```
6638
6695
  */
6639
6696
  declare function viewOf(element: unknown): OwView;
@@ -7709,4 +7766,4 @@ declare class TokenResource {
7709
7766
  getEncryptionInfo(): Promise<EncryptionInfo>;
7710
7767
  }
7711
7768
 
7712
- 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 OwAiRefusal, 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 OwView, type OwViewRow, type OwViewsTable, 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, VIEWS, 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, viewOf, weekdayForStep, worldCalendars, worldGraph, writeWorldFile, yearLength, yearStartStep };
7769
+ 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 OwAiRefusal, 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 OwSearchResult, type OwSearchResults, 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 OwView, type OwViewRow, type OwViewsTable, 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, VIEWS, 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, viewOf, weekdayForStep, worldCalendars, worldGraph, writeWorldFile, yearLength, yearStartStep };
package/dist/index.js CHANGED
@@ -44,7 +44,7 @@ import {
44
44
  trimWhiteSpace,
45
45
  typeWord,
46
46
  unknownKey
47
- } from "./chunk-GWJ3SOZQ.js";
47
+ } from "./chunk-TFS5P63Z.js";
48
48
 
49
49
  // src/v2/keyed-id.ts
50
50
  var KEYED_IDS = "0199b6a0-6f0e-7c2a-9d1e-3b5c7a8e4f21";
@@ -1024,6 +1024,25 @@ var OwV2Client = class {
1024
1024
  const query = buildQuery({ expand: opts.expand?.join(","), fields: opts.fields?.join(","), as: opts.viewAs });
1025
1025
  return this.request("GET", `/${seg("type", type)}/${seg("id", id)}/`, { query, worldRead: true, ...withSignal(opts.signal) });
1026
1026
  }
1027
+ /**
1028
+ * GET /search -- the world's elements whose `name` or text fields (`description` and the type's other prose
1029
+ * fields; never supertype, subtype or image_url) hold every word of `q` as a whole word, ignoring case. A word
1030
+ * is a run of letters, digits or underscores, so `APP-142` is searched as the two words `APP` and `142`: a
1031
+ * result's `snippet` is a piece of one field, so read the element to keep only those that hold the key whole.
1032
+ * No stemming, no pages: `truncated` says more matched than `limit` (1 to 200, the server's default 50) let
1033
+ * through. `type` searches one type; `viewAs` reads as another reader (the owner's keys). A guest's key finds
1034
+ * only what it may read. On a client with `world` set (an account token or no key), it searches that world.
1035
+ *
1036
+ * ```ts
1037
+ * const { results, truncated } = await client.search('APP-142', { limit: 200 });
1038
+ * ```
1039
+ */
1040
+ async search(q, opts = {}) {
1041
+ only("search", opts, ["type", "limit", "viewAs", "signal"]);
1042
+ if (typeof q !== "string") throw new TypeError("search: `q` is the words to find, a string of 2 to 200 characters. Nothing was sent.");
1043
+ const query = buildQuery({ q, type: opts.type, limit: opts.limit, as: opts.viewAs });
1044
+ return this.request("GET", "/search", { query, worldRead: true, ...withSignal(opts.signal) });
1045
+ }
1027
1046
  /**
1028
1047
  * POST /{type}/ -- create one element, minting an id on the client when you leave id out.
1029
1048
  * With an `idempotencyKey`, the minted id is derived from the key (a UUIDv5, the same one the
@@ -2338,14 +2357,14 @@ var OwV2Client = class {
2338
2357
  const worldRead = opts.auth !== false && opts.worldRead === true && method.toUpperCase() === "GET";
2339
2358
  const accountToken = opts.auth !== false && this.keyKind === "account" ? opts.accountToken : void 0;
2340
2359
  if (opts.auth !== false && this.keyKind === "none" && !(worldRead && this.world !== void 0)) {
2341
- throw new TypeError(`${method} ${path} needs a key, and this client holds none: without one, only health, previewJoin, redeemJoin and signInWithPassword work, and list, listAll, get, getWorld and draught with \`world\` set`);
2360
+ throw new TypeError(`${method} ${path} needs a key, and this client holds none: without one, only health, previewJoin, redeemJoin and signInWithPassword work, and list, listAll, get, search, getWorld and draught with \`world\` set`);
2342
2361
  }
2343
2362
  if (opts.auth !== false && this.keyKind === "account" && !ACCOUNT_ROUTE.test(path)) {
2344
2363
  if (!worldRead && accountToken === void 0) {
2345
- throw new TypeError(`${method} ${path} needs a world key: an account token sends the /account routes, worldLenses, setMyLenses and members, and with \`world\` set reads a world through list, listAll, get, getWorld and draught only. Nothing was sent.`);
2364
+ throw new TypeError(`${method} ${path} needs a world key: an account token sends the /account routes, worldLenses, setMyLenses and members, and with \`world\` set reads a world through list, listAll, get, search, getWorld and draught only. Nothing was sent.`);
2346
2365
  }
2347
2366
  if (worldRead && this.world === void 0) {
2348
- throw new TypeError(`${method} ${path}: an account token reads a world only with \`world\` set (new OwV2Client({ apiKey, world })), through list, listAll, get, getWorld and draught. Nothing was sent.`);
2367
+ throw new TypeError(`${method} ${path}: an account token reads a world only with \`world\` set (new OwV2Client({ apiKey, world })), through list, listAll, get, search, getWorld and draught. Nothing was sent.`);
2349
2368
  }
2350
2369
  if (accountToken === "world" && this.world === void 0) {
2351
2370
  throw new TypeError(`${method} ${path}: an account token names the world it sends to with \`world\`: set it (new OwV2Client({ apiKey, world })). Nothing was sent.`);
@@ -2611,10 +2630,10 @@ var CLIENT_CONFIG_KEYS = ["apiKey", "apiPin", "baseUrl", "pageSize", "changesPag
2611
2630
  function worldOf(value, keyKind) {
2612
2631
  if (value === void 0) return void 0;
2613
2632
  if (typeof value !== "string" || value.trim() === "") {
2614
- throw new TypeError(`OwV2Client: world is a world's id, a non-empty string; got ${JSON.stringify(value) ?? String(value)}. With it, an account token or no key reads that world through list, listAll, get, getWorld and draught.`);
2633
+ throw new TypeError(`OwV2Client: world is a world's id, a non-empty string; got ${JSON.stringify(value) ?? String(value)}. With it, an account token or no key reads that world through list, listAll, get, search, getWorld and draught.`);
2615
2634
  }
2616
2635
  if (keyKind !== "account" && keyKind !== "none") {
2617
- throw new TypeError("OwV2Client: a world key reads its own world; `world` is for an account token or no key, which read the world it names through list, listAll, get, getWorld and draught.");
2636
+ throw new TypeError("OwV2Client: a world key reads its own world; `world` is for an account token or no key, which read the world it names through list, listAll, get, search, getWorld and draught.");
2618
2637
  }
2619
2638
  return value;
2620
2639
  }
@@ -3432,6 +3451,10 @@ var Reading = class {
3432
3451
  if (show === "full") row = copy(b);
3433
3452
  else {
3434
3453
  row = { id: b.id, type: b.type, name: b.name ?? null };
3454
+ for (const k of ["supertype", "subtype"]) {
3455
+ const v = b[k];
3456
+ if (typeof v === "string" && trimWhiteSpace(v) !== "") row[k] = v;
3457
+ }
3435
3458
  if (show === "first_line" && typeof b.description === "string") {
3436
3459
  const cut2 = b.description.search(/[\r\n]/);
3437
3460
  row.description = cut2 < 0 ? b.description : b.description.slice(0, cut2);
@@ -4486,26 +4509,51 @@ function score(row, el) {
4486
4509
  function carries2(el, mark) {
4487
4510
  const v = own2(el, mark);
4488
4511
  if (mark === "hidden" || mark === "known_of") return v === true;
4489
- if (mark === "x_served_trimmed") return Array.isArray(v) && v.length > 0;
4512
+ if (mark === "x_served_trimmed") return Array.isArray(v) && v.some((x) => typeof x === "string" && trimWhiteSpace(x) !== "");
4490
4513
  if (mark === "x_review_proposed" || mark === "x_review_checked") {
4491
4514
  return v !== null && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length > 0;
4492
4515
  }
4493
4516
  return hasMark(el, mark);
4494
4517
  }
4518
+ function holds(v) {
4519
+ if (v === void 0 || v === null) return false;
4520
+ if (typeof v === "string") return trimWhiteSpace(v) !== "";
4521
+ if (Array.isArray(v)) return v.length > 0;
4522
+ if (typeof v === "object") return Object.keys(v).length > 0;
4523
+ return true;
4524
+ }
4525
+ function drawOrder(row, el) {
4526
+ const type = own2(el, "type");
4527
+ const slug = typeof type === "string" ? fold(type) : "";
4528
+ const sections = Object.prototype.hasOwnProperty.call(ELEMENT_SECTIONS, slug) ? [...ELEMENT_SECTIONS[slug]].sort((a, b) => a.order - b.order).flatMap((s) => s.fields) : [];
4529
+ const lead = row?.lead ?? [];
4530
+ const folds = (row?.fold ?? []).map((f) => f.field);
4531
+ const drawn = [];
4532
+ const draw = (f) => {
4533
+ if (!drawn.includes(f) && holds(own2(el, f))) drawn.push(f);
4534
+ };
4535
+ lead.forEach(draw);
4536
+ sections.filter((f) => !lead.includes(f) && !folds.includes(f)).forEach(draw);
4537
+ folds.forEach(draw);
4538
+ return drawn;
4539
+ }
4495
4540
  function viewOf(element) {
4496
- if (element === null || typeof element !== "object" || Array.isArray(element)) return { row: null, sentence: null, banners: [] };
4541
+ return viewIn(VIEWS, element);
4542
+ }
4543
+ function viewIn(table, element) {
4544
+ if (element === null || typeof element !== "object" || Array.isArray(element)) return { row: null, sentence: null, banners: [], order: [] };
4497
4545
  const el = element;
4498
4546
  let row = null;
4499
4547
  let best = 0;
4500
- for (const r of VIEWS.rows) {
4548
+ for (const r of table.rows) {
4501
4549
  const s = score(r, el);
4502
4550
  if (s > best) {
4503
4551
  best = s;
4504
4552
  row = r;
4505
4553
  }
4506
4554
  }
4507
- const banners = VIEWS.banners.map((b) => b.mark).filter((m) => carries2(el, m));
4508
- if (!row) return { row: null, sentence: null, banners };
4555
+ const banners = table.banners.map((b) => b.mark).filter((m) => carries2(el, m));
4556
+ if (!row) return { row: null, sentence: null, banners, order: drawOrder(null, el) };
4509
4557
  for (const m of row.banner ?? []) if (carries2(el, m)) banners.push(m);
4510
4558
  let sentence = null;
4511
4559
  for (const f of row.sentence ?? []) {
@@ -4517,7 +4565,7 @@ function viewOf(element) {
4517
4565
  sentence = trimWhiteSpace(cut2 < 0 ? text2 : text2.slice(0, cut2));
4518
4566
  break;
4519
4567
  }
4520
- return { row, sentence, banners };
4568
+ return { row, sentence, banners, order: drawOrder(row, el) };
4521
4569
  }
4522
4570
 
4523
4571
  // src/world-file.ts
package/dist/waymark.js CHANGED
@@ -6,7 +6,7 @@ import {
6
6
  openersFor,
7
7
  refuseUnknownOptions,
8
8
  typeWord
9
- } from "./chunk-GWJ3SOZQ.js";
9
+ } from "./chunk-TFS5P63Z.js";
10
10
 
11
11
  // src/waymark/glyphs.ts
12
12
  var MARK_PATH = "M48.8 0.0 43.8 0.4 39.0 1.2 36.0 2.0 33.2 2.9 29.3 4.5 24.8 6.8 20.6 9.5 17.0 12.4 13.6 15.7 10.4 19.4 7.8 23.1 5.8 26.6 4.5 29.3 3.3 32.1 1.8 36.8 0.8 41.2 0.1 46.3 0.0 51.1 0.4 56.2 1.2 61.0 2.0 63.9 2.9 66.8 4.5 70.7 6.8 75.2 9.5 79.4 12.4 82.9 15.7 86.3 19.4 89.5 23.1 92.1 26.6 94.2 29.3 95.5 32.1 96.7 36.8 98.2 41.2 99.2 46.3 99.8 51.1 100.0 56.2 99.6 61.0 98.8 63.9 98.0 66.8 97.1 70.7 95.5 75.2 93.2 79.4 90.4 82.9 87.6 86.3 84.3 89.5 80.5 92.1 76.9 94.2 73.4 95.5 70.7 96.7 67.9 98.2 63.2 99.2 58.7 99.8 53.7 100.0 48.8 99.6 43.8 98.6 38.4 97.1 33.2 95.5 29.3 93.2 24.8 90.4 20.6 87.6 17.0 84.3 13.6 80.5 10.4 76.9 7.8 73.4 5.8 70.7 4.5 67.9 3.3 63.2 1.8 58.7 0.8 53.7 0.1ZM77.5 80.7 74.1 83.4 70.7 85.7 67.0 87.5 64.5 88.6 64.1 88.7 65.7 86.3 67.1 83.9 68.7 80.7 69.9 77.6 72.7 78.5 73.0 78.4ZM22.5 80.7 25.6 79.0 27.3 78.3 30.0 77.6 31.3 80.7 32.8 83.9 34.2 86.3 35.9 88.7 32.9 87.5 29.3 85.7 25.8 83.4ZM51.2 74.5 55.1 74.7 59.9 75.2 64.2 76.0 67.5 76.9 66.0 80.5 64.2 84.0 62.0 87.4 59.6 90.1 55.1 90.9 52.2 91.2 51.2 91.1ZM48.7 74.5 48.8 91.1 47.7 91.2 44.9 90.9 40.3 90.1 38.2 87.8 36.3 85.0 34.2 81.2 32.5 77.0 35.8 76.0 40.5 75.2 44.5 74.7ZM91.1 51.2 91.1 52.9 90.8 56.3 90.1 59.7 89.3 62.5 88.5 64.8 87.2 67.7 85.7 70.7 83.9 73.4 82.0 75.9 79.4 78.9 76.3 77.2 73.8 76.1 76.2 68.8 77.8 62.7 78.7 56.8 79.0 51.2ZM55.8 51.2 67.7 51.2 67.6 55.1 67.2 59.0 66.7 61.5 65.7 65.0 61.0 64.2 55.7 63.6ZM32.5 51.2 44.5 51.2 44.4 63.6 39.7 64.1 34.5 65.0 33.5 61.3 32.9 58.1 32.5 54.2ZM8.8 51.2 21.0 51.2 21.0 53.3 21.4 56.6 22.7 64.0 23.8 68.4 25.0 72.1 26.6 75.9 23.7 77.2 20.6 78.9 18.5 76.7 16.5 74.1 14.8 71.5 13.4 69.1 12.1 66.3 11.0 63.6 10.1 60.5 9.4 57.3 8.9 53.5 8.8 51.3ZM36.2 27.0 39.5 27.5 44.5 28.2 44.4 48.8 32.4 48.7 32.8 44.5 33.6 39.1 35.0 32.0ZM63.9 26.9 65.2 32.1 66.6 39.2 67.4 44.8 67.7 48.7 55.8 48.8 55.7 28.1 60.5 27.5ZM74.8 23.4 76.9 22.5 79.4 21.1 82.0 24.0 84.8 27.8 86.2 30.3 87.5 32.9 88.6 35.4 89.5 38.1 90.3 41.2 90.8 44.0 91.1 47.0 91.1 48.8 79.0 48.7 78.7 44.6 78.0 39.3 76.5 31.2 74.7 23.5ZM25.5 23.5 25.5 23.7 24.5 26.8 23.7 30.2 22.4 36.6 21.5 42.5 21.1 48.7 8.8 48.8 8.8 47.0 9.2 43.7 9.8 40.8 10.5 38.1 11.5 35.2 12.4 32.9 13.8 30.2 15.2 27.8 17.9 24.0 20.6 21.1 23.1 22.5ZM64.1 11.3 67.0 12.4 70.7 14.3 74.1 16.5 77.5 19.3 75.6 20.3 73.2 21.5 70.0 22.6 68.7 19.2 67.1 16.1 65.7 13.6ZM35.9 11.3 34.2 13.6 32.8 16.1 31.3 19.2 30.0 22.5 27.9 21.9 26.4 21.3 22.5 19.3 25.8 16.5 29.3 14.3 32.9 12.4 35.4 11.4ZM51.2 8.8 52.2 8.8 55.1 9.0 59.6 9.9 61.7 12.2 64.2 16.0 66.0 19.5 67.6 23.3 64.3 24.3 59.4 25.2 56.2 25.6 51.2 25.5ZM48.8 8.8 48.7 25.5 44.2 25.6 40.6 25.2 36.4 24.5 32.4 23.2 33.9 19.5 35.7 16.0 38.2 12.2 40.3 9.9 44.9 9.0 47.7 8.8Z";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.149.0",
3
+ "version": "4.151.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {