@onlyworlds/sdk 4.135.2 → 4.137.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,22 @@ earlier history lives in git log only.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [4.137.0] - 2026-11-09
9
+
10
+ ### Added
11
+
12
+ - `aiUses()`: `GET /account/ai`, the AI uses onlyworlds.com runs, each a named call a tool makes: its owner, provider, model and effort, the hash of its system prompt, what its body may hold, its answer cap, its price, its daily ceiling, this account's calls left today, and whether it is on (`OwAiUse`). Reading it spends nothing. Needs an account token.
13
+ - `ai(use, body, { idempotencyKey, signal })`: `POST /account/ai/{use}`, one call of a listed use, metered on the account's token rating and then its own saved AI key, as `ask()` and `sort()` are. The body is the use's own, in its wire spelling, sent as given (`{world_id, question, context}` for `ask`, `{world_id, notes, slice}` for `sort`); typed for those two (`OwAiAskBody`, `OwAiSortBody`, answered as `OwAiAskAnswer` and `OwAiSortAnswer`) and open for any other use. The answer adds `use_remaining` (null when the use has no daily ceiling) and `wasReplay`, read from `Idempotent-Replay`. The use's name is checked as one path segment and the key as 1 to 200 characters before anything is sent; the client's name goes as `X-OW-Client`.
14
+ - With an `idempotencyKey`, a retry is safe: the same key and body answer the first answer again and bill nothing. A key whose first call is still running answers 409 `idempotency_in_flight`; retry with the same key and body a few times at most, and never mint a new key to get past it, since a key whose answer could not be stored stays in flight for a day although the call ran and was billed. The client never retries on its own.
15
+ - `OwApiError.isUseCeiling` (429 `use_ceiling`: the use's calls for the day are made) and `isUseInFlight` (429 `use_in_flight`: another call to this use is running; wait `retryAfter`). A 503 `ask_unavailable` with `param` `use` is still `isAskUnavailable`.
16
+ - `ask()` and `sort()` keep calling their own routes, unchanged.
17
+
18
+ ## [4.136.0] - 2026-11-09
19
+
20
+ ### Added
21
+
22
+ - `trailByPlace`: the ground Map's element id, `ground.map`, travels in the recipe: given in the input, the recipe's `settings.ground` carries it back as `{map, width, height}`, so a tool reading a laid-out Map finds the picture its pins stand on. Optional; a ground given without it carries none. A `map` that is not a non-empty string is refused. The shared fixture's whole-world case now names its ground map. The type is `OwTrailGround`.
23
+
8
24
  ## [4.135.2] - 2026-11-09
9
25
 
10
26
  ### Fixed
package/dist/index.d.ts CHANGED
@@ -3128,6 +3128,78 @@ interface OwAllowance {
3128
3128
  } | null;
3129
3129
  [k: string]: unknown;
3130
3130
  }
3131
+ /**
3132
+ * One AI use, as GET /account/ai lists it: a named call a tool may make at POST /account/ai/{slug}.
3133
+ * A tool calls a use by its name and sends the use's own body; it never sends a prompt.
3134
+ */
3135
+ interface OwAiUse {
3136
+ /** The use's name in its route: POST /account/ai/{slug}. */
3137
+ slug: string;
3138
+ /** The tool that answers for its prompt and caps. */
3139
+ owner: string;
3140
+ provider: string;
3141
+ /** The model a call on the platform's key runs. */
3142
+ model: string;
3143
+ effort: string;
3144
+ /** The sha256 of the use's system prompt, hex: two calls with the same hash ran the same prompt. */
3145
+ prompt_sha256: string;
3146
+ /** The body names a world this account owns or is a member of. */
3147
+ needs_world: boolean;
3148
+ /** What the body may hold, by name. */
3149
+ input_caps: Record<string, number>;
3150
+ /** The most tokens one answer may take; a call needs at least this much rating left (or a saved own key). */
3151
+ output_cap: number;
3152
+ /** The answer is checked JSON, not text. */
3153
+ structured: boolean;
3154
+ /** A fixed price per call in rating tokens, or null: the call's actual tokens are spent. */
3155
+ price_tokens: number | null;
3156
+ /** Calls per account per UTC day, or null. Past it, 429 `use_ceiling` until midnight UTC; a use with a
3157
+ * ceiling runs one call at a time, and a second call while one runs is 429 `use_in_flight`. */
3158
+ ceiling: number | null;
3159
+ /** This account's calls left today, or null when the use has no ceiling. */
3160
+ calls_left: number | null;
3161
+ /** False while the use is switched off or has spent its own budget for today (its calls answer 503
3162
+ * `ask_unavailable` with param `use`). */
3163
+ on: boolean;
3164
+ [k: string]: unknown;
3165
+ }
3166
+ /** What every answer of an AI use adds to the use's own answer. */
3167
+ interface OwAiMeter {
3168
+ /** Calls to this use this account has left today; null when the use has no daily ceiling (the token
3169
+ * rating is then the only limit). */
3170
+ use_remaining: number | null;
3171
+ /** Read from the `Idempotent-Replay` header: true when this answer is the stored first answer for the
3172
+ * call's idempotency key, billed nothing this time. Set by the client, never sent by the server. */
3173
+ wasReplay: boolean;
3174
+ }
3175
+ /** POST /account/ai/ask: the ask use's answer, the same as ask()'s, with the use's meter. */
3176
+ interface OwAiAskAnswer extends OwAskAnswer {
3177
+ /** Calls to this use this account has left today; null when the use has no daily ceiling. */
3178
+ use_remaining: number | null;
3179
+ /** True when this answer is the stored first answer for the call's idempotency key (billed nothing). */
3180
+ wasReplay: boolean;
3181
+ }
3182
+ /** POST /account/ai/sort: the sort use's answer, the same as sort()'s, with the use's meter. */
3183
+ interface OwAiSortAnswer extends OwSortAnswer {
3184
+ /** Calls to this use this account has left today; null when the use has no daily ceiling. */
3185
+ use_remaining: number | null;
3186
+ /** True when this answer is the stored first answer for the call's idempotency key (billed nothing). */
3187
+ wasReplay: boolean;
3188
+ }
3189
+ /** The `ask` use's body (POST /account/ai/ask), in its own wire spelling: the same fields as ask(). */
3190
+ interface OwAiAskBody {
3191
+ world_id: string;
3192
+ /** 1 to 500 characters. */
3193
+ question: string;
3194
+ /** 1 to 8 elements as text, each up to 2,000 characters, 12,000 in all (buildAskContext makes it). */
3195
+ context: string[];
3196
+ }
3197
+ /** The `sort` use's body (POST /account/ai/sort), in its own wire spelling: the same fields as sort(). */
3198
+ interface OwAiSortBody {
3199
+ world_id: string;
3200
+ notes: OwSortNote[];
3201
+ slice?: OwSortRef[];
3202
+ }
3131
3203
  /** POST /join/preview: what a join code holds, read without using it. */
3132
3204
  interface OwJoinPreview {
3133
3205
  /** `person`: an invite link, accepted with acceptJoin. `agent`: redeemed by an AI agent at POST /join. `player`: a friend with no account redeems it with redeemJoin for a read key. */
@@ -4139,6 +4211,16 @@ declare class OwApiError extends Error {
4139
4211
  get isOwnKeyRefused(): boolean;
4140
4212
  /** ask: the proxy is switched off, or paused for the day by the server-wide cap (503 `ask_unavailable`). Not counted. */
4141
4213
  get isAskUnavailable(): boolean;
4214
+ /**
4215
+ * ai: this use's calls for the day are made (429 `use_ceiling`, param `use`): the use's own daily
4216
+ * ceiling per account, not the token rating (isQuotaExceeded). Retry-After runs to midnight UTC.
4217
+ */
4218
+ get isUseCeiling(): boolean;
4219
+ /**
4220
+ * ai: another call to this use is running for this account (429 `use_in_flight`, param `use`): a use
4221
+ * with a ceiling runs one call at a time. Wait `retryAfter` seconds (a short wait) and send again.
4222
+ */
4223
+ get isUseInFlight(): boolean;
4142
4224
  /** ask: the model gave no answer (502 `ask_failed`). Not counted; try again in a moment. */
4143
4225
  get isAskFailed(): boolean;
4144
4226
  /**
@@ -5302,6 +5384,52 @@ declare class OwV2Client {
5302
5384
  * client's `ow_a_` token.
5303
5385
  */
5304
5386
  allowance(): Promise<OwAllowance>;
5387
+ /**
5388
+ * GET /account/ai -- the AI uses onlyworlds.com runs, each a named call a tool makes with ai():
5389
+ * its owner, provider, model and effort, the hash of its system prompt, what its body may hold, its
5390
+ * answer cap, its price, its daily ceiling, this account's calls left today, and whether it is on.
5391
+ * Reading it spends nothing. Needs the client's `ow_a_` token.
5392
+ */
5393
+ aiUses(opts?: {
5394
+ signal?: AbortSignal;
5395
+ }): Promise<OwAiUse[]>;
5396
+ /**
5397
+ * POST /account/ai/{use} -- one call of an AI use (aiUses lists them), metered on the account's
5398
+ * daily token rating, then its own saved AI key, as ask and sort are. `body` is the use's own body in
5399
+ * its wire spelling, sent as given: `{world_id, question, context}` for `ask`, `{world_id, notes,
5400
+ * slice}` for `sort`; another use's body is the one its listing describes. The answer is the use's
5401
+ * own, its meter whole (`paid_by`, `model`, `usage`, `remaining`, `tokens_remaining`, `token_rating`),
5402
+ * with `use_remaining` (null when the use has no daily ceiling) and `wasReplay`. The use's name is
5403
+ * checked as one path segment before sending. Needs the client's `ow_a_` token.
5404
+ *
5405
+ * With an `idempotencyKey`, a retry is safe: the same key and body answer the first answer again
5406
+ * (`wasReplay` true) and bill nothing; the same key with another body is 409 `idempotency_error`, and
5407
+ * a key whose first call is still running is 409 `idempotency_in_flight` (retry after `retryAfter`).
5408
+ * Retry with the same key and body, a few times at most, and never mint a new key to get past an
5409
+ * in-flight answer: when the server cannot store an answer, the key is held for a day and keeps
5410
+ * answering `idempotency_in_flight` although the call ran and was billed. The client never retries
5411
+ * on its own.
5412
+ *
5413
+ * Refusals, none of them counted: 429 `use_ceiling` (`err.isUseCeiling`: the use's calls for the day
5414
+ * are made), 429 `use_in_flight` (`err.isUseInFlight`: another call to this use is running; wait
5415
+ * `retryAfter`), 429 `quota_exceeded` (`err.isQuotaExceeded`: the token rating is spent and no own key
5416
+ * is saved), 422 `own_key_refused` (`err.isOwnKeyRefused`), 503 `ask_unavailable`
5417
+ * (`err.isAskUnavailable`; with `param` `use`, this use is switched off or spent its own budget
5418
+ * today), 502 `ask_failed` (`err.isAskFailed`), 404 `not_found` (a use that is not listed, `param`
5419
+ * `use`, or a world the account is not in), 422 for a body past the use's limits (`param` names it).
5420
+ */
5421
+ ai(use: 'ask', body: OwAiAskBody, opts?: {
5422
+ idempotencyKey?: string;
5423
+ signal?: AbortSignal;
5424
+ }): Promise<OwAiAskAnswer>;
5425
+ ai(use: 'sort', body: OwAiSortBody, opts?: {
5426
+ idempotencyKey?: string;
5427
+ signal?: AbortSignal;
5428
+ }): Promise<OwAiSortAnswer>;
5429
+ ai(use: string, body: Record<string, unknown>, opts?: {
5430
+ idempotencyKey?: string;
5431
+ signal?: AbortSignal;
5432
+ }): Promise<Record<string, unknown> & OwAiMeter>;
5305
5433
  /**
5306
5434
  * Raw authenticated request against this client's baseUrl. Public since 4.0
5307
5435
  * so auxiliary resources can ride the same transport — it structurally
@@ -5319,7 +5447,7 @@ declare class OwV2Client {
5319
5447
  /** A `change_seq` to send as `If-Match`; a whole number, else TypeError before sending. */
5320
5448
  /** A write keel's document lists X-OW-Agent on (the element writes, the links route, bulk, adopt, the file ticket): where an agent client sends it. Hide, unhide, setMyCharacter and mintWorldKey are not, and keel reads no agent there. */
5321
5449
  write?: boolean;
5322
- /** One of the writes keel reads X-OW-Client on (create, put, patch, delete, links, bulk, adopt, propose, accept): where the client's name goes. */
5450
+ /** One of the writes keel reads X-OW-Client on (create, put, patch, delete, links, bulk, adopt, propose, accept, review, and an AI use's call): where the client's name goes. */
5323
5451
  elementWrite?: boolean;
5324
5452
  /**
5325
5453
  * A write keel may answer 202 with `{proposal}` (put, patch, links): a 202 then
@@ -5909,11 +6037,11 @@ interface OwTrailSpiral {
5909
6037
  }
5910
6038
  /** The method's settings: what a Map's recipe carries, so the layout can be run again from the Map alone. */
5911
6039
  interface OwTrailSettings {
5912
- /** The ground map's own frame; the layout's frame is it plus `margin` on every side. */
5913
- ground: {
5914
- width: number;
5915
- height: number;
5916
- };
6040
+ /**
6041
+ * The ground map's own frame; the layout's frame is it plus `margin` on every side. `map` is the ground Map's element
6042
+ * id in the same world, so a tool reading the recipe finds its picture (left out when the caller gives none).
6043
+ */
6044
+ ground: OwTrailGround;
5917
6045
  margin: number;
5918
6046
  depth: number;
5919
6047
  tiers: OwTrailTier[];
@@ -5921,11 +6049,13 @@ interface OwTrailSettings {
5921
6049
  /** How far a place sits from the place it is inside. */
5922
6050
  parentRing: number;
5923
6051
  }
6052
+ interface OwTrailGround {
6053
+ map?: string;
6054
+ width: number;
6055
+ height: number;
6056
+ }
5924
6057
  interface OwTrailInput extends Partial<Omit<OwTrailSettings, 'ground' | 'depth'>> {
5925
- ground: {
5926
- width: number;
5927
- height: number;
5928
- };
6058
+ ground: OwTrailGround;
5929
6059
  depth: number;
5930
6060
  places: OwTrailPlace[];
5931
6061
  hangers: OwTrailHanger[];
@@ -7341,4 +7471,4 @@ declare class TokenResource {
7341
7471
  getEncryptionInfo(): Promise<EncryptionInfo>;
7342
7472
  }
7343
7473
 
7344
- 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 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 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 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 };
7474
+ 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 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 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 };
package/dist/index.js CHANGED
@@ -335,6 +335,20 @@ var OwApiError = class extends Error {
335
335
  get isAskUnavailable() {
336
336
  return this.status === 503 && this.code === "ask_unavailable";
337
337
  }
338
+ /**
339
+ * ai: this use's calls for the day are made (429 `use_ceiling`, param `use`): the use's own daily
340
+ * ceiling per account, not the token rating (isQuotaExceeded). Retry-After runs to midnight UTC.
341
+ */
342
+ get isUseCeiling() {
343
+ return this.status === 429 && this.code === "use_ceiling";
344
+ }
345
+ /**
346
+ * ai: another call to this use is running for this account (429 `use_in_flight`, param `use`): a use
347
+ * with a ceiling runs one call at a time. Wait `retryAfter` seconds (a short wait) and send again.
348
+ */
349
+ get isUseInFlight() {
350
+ return this.status === 429 && this.code === "use_in_flight";
351
+ }
338
352
  /** ask: the model gave no answer (502 `ask_failed`). Not counted; try again in a moment. */
339
353
  get isAskFailed() {
340
354
  return this.status === 502 && this.code === "ask_failed";
@@ -2152,6 +2166,40 @@ var OwV2Client = class {
2152
2166
  }
2153
2167
  return this.request("GET", "/account/allowance");
2154
2168
  }
2169
+ /**
2170
+ * GET /account/ai -- the AI uses onlyworlds.com runs, each a named call a tool makes with ai():
2171
+ * its owner, provider, model and effort, the hash of its system prompt, what its body may hold, its
2172
+ * answer cap, its price, its daily ceiling, this account's calls left today, and whether it is on.
2173
+ * Reading it spends nothing. Needs the client's `ow_a_` token.
2174
+ */
2175
+ async aiUses(opts = {}) {
2176
+ only("aiUses", opts, ["signal"]);
2177
+ if (this.keyKind !== "account") {
2178
+ throw new TypeError("aiUses needs an account token (ow_a_): the uses and their calls left are per account");
2179
+ }
2180
+ const body = await this.request("GET", "/account/ai", { signal: opts.signal });
2181
+ return body.uses;
2182
+ }
2183
+ async ai(use, body, opts = {}) {
2184
+ only("ai", opts, ["idempotencyKey", "signal"]);
2185
+ if (this.keyKind !== "account") {
2186
+ throw new TypeError("ai needs an account token (ow_a_): every AI use is metered per account");
2187
+ }
2188
+ const path = `/account/ai/${seg("use", use)}`;
2189
+ if (body === null || typeof body !== "object" || Array.isArray(body)) {
2190
+ throw new TypeError(`ai: the body is the use's own object, got ${body === null ? "null" : Array.isArray(body) ? "an array" : typeof body}. Nothing was sent.`);
2191
+ }
2192
+ if (opts.idempotencyKey !== void 0 && (typeof opts.idempotencyKey !== "string" || opts.idempotencyKey === "" || opts.idempotencyKey.length > 200)) {
2193
+ throw new TypeError(`ai: idempotencyKey is a string of 1 to 200 characters, got ${JSON.stringify(opts.idempotencyKey)}. Nothing was sent.`);
2194
+ }
2195
+ return this.request("POST", path, {
2196
+ body,
2197
+ idempotencyKey: opts.idempotencyKey,
2198
+ signal: opts.signal,
2199
+ elementWrite: true,
2200
+ replayAware: true
2201
+ });
2202
+ }
2155
2203
  // -- Core request machinery ----------------------------------------------
2156
2204
  /**
2157
2205
  * Raw authenticated request against this client's baseUrl. Public since 4.0
@@ -4075,7 +4123,8 @@ function trailByPlace(input) {
4075
4123
  const { places, hangers, hero } = input;
4076
4124
  const g = input.ground;
4077
4125
  if (!g || typeof g !== "object") fail("no ground");
4078
- refuseUnknownOptions("trailByPlace: ground", g, ["width", "height"]);
4126
+ refuseUnknownOptions("trailByPlace: ground", g, ["map", "width", "height"]);
4127
+ if (g.map !== void 0 && (typeof g.map !== "string" || !g.map)) fail("ground.map is the ground Map's element id, a non-empty string");
4079
4128
  if (!wholeAbove(g.width, 0) || !wholeAbove(g.height, 0)) fail("the ground's width and height are whole numbers above 0");
4080
4129
  const margin = input.margin ?? 0;
4081
4130
  if (!Number.isSafeInteger(margin) || margin < 0) fail("margin is a whole number, 0 or more");
@@ -4223,7 +4272,7 @@ function trailByPlace(input) {
4223
4272
  recipe: {
4224
4273
  method: "trail-by-place",
4225
4274
  settings: {
4226
- ground: { width: g.width, height: g.height },
4275
+ ground: g.map !== void 0 ? { map: g.map, width: g.width, height: g.height } : { width: g.width, height: g.height },
4227
4276
  margin: M,
4228
4277
  depth: D,
4229
4278
  tiers: tiers.map((t) => ({ name: t.name, z: t.z, kinds: [...t.kinds] })),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.135.2",
3
+ "version": "4.137.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {