@onlyworlds/sdk 4.148.0 → 4.150.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/CHANGELOG.md CHANGED
@@ -5,6 +5,18 @@ earlier history lives in git log only.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [4.150.0] - 2026-11-10
9
+
10
+ ### Added
11
+
12
+ - **`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.
13
+
14
+ ## [4.149.0] - 2026-11-10
15
+
16
+ ### Changed
17
+
18
+ - **`lenses_from` can be `none`** on `OwMe` and `OwMember`: a member or seat that never chose its lenses and that nothing brings a lens to (no Character, or Titles that name none), told apart from `chosen`, which an empty list chosen on purpose still reads. What a row reads is unchanged; the owner's row and a removed row are always `chosen`. A TypeScript switch over the field gains a case.
19
+
8
20
  ## [4.148.0] - 2026-11-10
9
21
 
10
22
  ### Added
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/dist/index.d.ts CHANGED
@@ -2491,6 +2491,30 @@ interface OwPage<T = OwElement> {
2491
2491
  has_more: boolean;
2492
2492
  next_cursor: string | null;
2493
2493
  }
2494
+ /** One element `search()` found: where the words were, and a short plain-text piece around the first match. */
2495
+ interface OwSearchResult {
2496
+ type: ElementType;
2497
+ id: string;
2498
+ name: string;
2499
+ supertype: string;
2500
+ subtype: string;
2501
+ /** 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. */
2502
+ field: string;
2503
+ /** Up to 160 characters of that field around the first match, as plain text. Never the whole field: read the element for its text. */
2504
+ snippet: string;
2505
+ /** Present, and true, only when the reader knows of the element without seeing it whole: it matched on what a known-of stub keeps. */
2506
+ known_of?: true;
2507
+ }
2508
+ /** search()'s answer: every element whose name or text holds every word of `q` as a whole word, up to `limit`. */
2509
+ interface OwSearchResults {
2510
+ /** `q` as searched (trimmed). */
2511
+ query: string;
2512
+ results: OwSearchResult[];
2513
+ /** How many results came back. */
2514
+ count: number;
2515
+ /** True when more elements matched than `limit` let through. There are no further pages: narrow `q` or `type`, or raise `limit`. */
2516
+ truncated: boolean;
2517
+ }
2494
2518
  /** /changes feed -- discriminated union on `op`. Apply in order -> convergence. */
2495
2519
  type OwChange = OwChangeUpsert | OwChangeDelete;
2496
2520
  /** A /changes item for an element written: the element whole, as GET returns it. */
@@ -3022,8 +3046,13 @@ interface OwMe {
3022
3046
  * and no policy.
3023
3047
  */
3024
3048
  lenses: string[];
3025
- /** Where `lenses` comes from: `chosen` (your own list, empty for none) or `titles` (you chose none, and your Character's Titles bring these). Saving a list makes it your choice. */
3026
- lenses_from: 'chosen' | 'titles';
3049
+ /**
3050
+ * Where `lenses` comes from: `chosen` (your own list; an empty one is a choice of none), `titles`
3051
+ * (you never chose, and your Character's Titles bring these) or `none` (you never chose and nothing
3052
+ * brings you a lens: no Character, or Titles that name none; `lenses` is empty). The owner's is
3053
+ * always `chosen`. Saving a list makes it your choice.
3054
+ */
3055
+ lenses_from: 'chosen' | 'titles' | 'none';
3027
3056
  /**
3028
3057
  * Served only, never written: present only when `lenses` was served with a lens left out, one this
3029
3058
  * key cannot see; then it names `lenses`. Saving the list you were shown keeps that lens where it stands.
@@ -3155,8 +3184,13 @@ interface OwMember {
3155
3184
  * left out of what it is shown.
3156
3185
  */
3157
3186
  lenses: string[];
3158
- /** Where `lenses` comes from: `chosen` (the row's own list, empty for none) or `titles` (it chose none, and its Character's Titles bring these). */
3159
- lenses_from: 'chosen' | 'titles';
3187
+ /**
3188
+ * Where `lenses` comes from: `chosen` (the row's own list; an empty one is a choice of none),
3189
+ * `titles` (it never chose, and its Character's Titles bring these) or `none` (it never chose and
3190
+ * nothing brings it a lens: no Character, or Titles that name none; `lenses` is empty). The owner
3191
+ * row and a removed row are always `chosen`.
3192
+ */
3193
+ lenses_from: 'chosen' | 'titles' | 'none';
3160
3194
  /**
3161
3195
  * Agent rows only: who answers for this AI, as the roster names them: the sponsor's membership id
3162
3196
  * (the `id` of their row here), `owner` when the world's owner answers for it, or null for a seat
@@ -4034,7 +4068,7 @@ interface OwClientConfig {
4034
4068
  /**
4035
4069
  * 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.
4036
4070
  * 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,
4037
- * previewJoin, redeemJoin and signInWithPassword (and with `world` set, list, listAll, get, getWorld and draught), and any
4071
+ * previewJoin, redeemJoin and signInWithPassword (and with `world` set, list, listAll, get, search, getWorld and draught), and any
4038
4072
  * other call is a TypeError before anything is sent.
4039
4073
  */
4040
4074
  apiKey?: string;
@@ -4769,6 +4803,25 @@ declare class OwV2Client {
4769
4803
  * it reads that world, sending `world=<id>`.
4770
4804
  */
4771
4805
  get(type: ElementType | string, id: string, opts?: Pick<ListParams, 'expand' | 'fields' | 'viewAs' | 'signal'>): Promise<OwElement>;
4806
+ /**
4807
+ * GET /search -- the world's elements whose `name` or text fields (`description` and the type's other prose
4808
+ * fields; never supertype, subtype or image_url) hold every word of `q` as a whole word, ignoring case. A word
4809
+ * is a run of letters, digits or underscores, so `APP-142` is searched as the two words `APP` and `142`: a
4810
+ * result's `snippet` is a piece of one field, so read the element to keep only those that hold the key whole.
4811
+ * No stemming, no pages: `truncated` says more matched than `limit` (1 to 200, the server's default 50) let
4812
+ * through. `type` searches one type; `viewAs` reads as another reader (the owner's keys). A guest's key finds
4813
+ * only what it may read. On a client with `world` set (an account token or no key), it searches that world.
4814
+ *
4815
+ * ```ts
4816
+ * const { results, truncated } = await client.search('APP-142', { limit: 200 });
4817
+ * ```
4818
+ */
4819
+ search(q: string, opts?: {
4820
+ type?: ElementType;
4821
+ limit?: number;
4822
+ viewAs?: string;
4823
+ signal?: AbortSignal;
4824
+ }): Promise<OwSearchResults>;
4772
4825
  /**
4773
4826
  * POST /{type}/ -- create one element, minting an id on the client when you leave id out.
4774
4827
  * With an `idempotencyKey`, the minted id is derived from the key (a UUIDv5, the same one the
@@ -7699,4 +7752,4 @@ declare class TokenResource {
7699
7752
  getEncryptionInfo(): Promise<EncryptionInfo>;
7700
7753
  }
7701
7754
 
7702
- 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 };
7755
+ 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
@@ -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
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.148.0",
3
+ "version": "4.150.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {