@onlyworlds/sdk 4.129.2 → 4.131.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,19 @@ earlier history lives in git log only.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [4.131.0] - 2026-11-03
9
+
10
+ ### Added
11
+
12
+ - **Your own AI key.** An account can now save its own Anthropic or OpenAI key on its account page; once the day's token rating is spent, `ask` and `sort` run on that key, billed by its provider. `OwAskAnswer` and `OwSortAnswer` carry `paid_by` (`OwPaidBy`: `'rating'` or `'own_key'`), so a tool can say which paid. `OwAllowance` carries `own_key`: `{ provider: 'anthropic' | 'openai' }` when a key is saved, else `null`; the counts keep the rating's meaning.
13
+ - **`isOwnKeyRefused`** on `OwApiError`: 422 `own_key_refused`, the own key's provider refused it (revoked, wrong, or out of credit). Nothing was counted and the call was not retried on the platform's key: send the person to the account page, and do not retry. A 429 `quota_exceeded` now means the rating is spent and no own key is saved.
14
+
15
+ ## [4.130.0] - 2026-11-02
16
+
17
+ ### Changed
18
+
19
+ - **A signed-out visitor sees the tools that need an account, greyed.** `openersFor` with `audience: 'public'` now gives a row for a tool whose `open.needs` is `account`, with the new state word `"Needs an account"` (whatever `signedIn` says: the public is the signed-out reader); before, the public saw no such row. A tool that needs the device is still not there for the public. The word comes after "You are here" and "Needs a connection", and before "Opens the world". `OwOpenerState` gains the word, so a `switch` over it that lists every case meets a new one. `mountWaymark` draws the row like one that needs a connection: grey, a link with no href, `aria-disabled="true"`, in the arrow and Tab order, doing nothing when pressed. The shared openers fixture has 92 cases (from 90): seven public cases gain their account rows, and two are new (a visitor outside a browser, a visitor on a tool that needs an account).
20
+
8
21
  ## [4.129.2] - 2026-11-02
9
22
 
10
23
  ### Fixed
package/README.md CHANGED
@@ -473,7 +473,7 @@ const rows = openersFor(TOOLS, 'element', parseOwLink(link), { audience: 'member
473
473
 
474
474
  Pass the element as you were served it (`{ element }`): a tool whose element door does not open what it carries (a room element, a hidden or proposed one, a Map, Pin or Marker, a reading aid: the list's `open.element_skips`, each read as `worldGraph` reads it) has no row, rather than a link to a page that cannot open it. Without it, every row is there.
475
475
 
476
- `surface` says what the page knows and nothing is guessed: `audience` (`member` or `public`; the public sees only rows that need nothing first), `signedIn` (`null` when the page cannot know, and then no row says so), `browser` (false in a desktop app), `phone`, `online` (false with no connection: every row whose link is a web address then says "Needs a connection"), and `tool`, the page's own client name, whose row says "You are here". Draw the rows as given; the words are decided here, so every surface says the same.
476
+ `surface` says what the page knows and nothing is guessed: `audience` (`member` or `public`, the signed-out reader: the public sees the rows that need nothing, and a tool that needs an account as a row that says "Needs an account" and opens nothing; a tool that needs the device is not there), `signedIn` (`null` when the page cannot know, and then no row says so), `browser` (false in a desktop app), `phone`, `online` (false with no connection: every row whose link is a web address then says "Needs a connection"), and `tool`, the page's own client name, whose row says "You are here". Draw the rows as given; the words are decided here, so every surface says the same.
477
477
 
478
478
  ### The Waymark: Open with, beside a name
479
479
 
@@ -1287,6 +1287,7 @@ var NEEDS = ["account", "device", null];
1287
1287
  var PLACEHOLDER = /\{(world|type|id)\}/g;
1288
1288
  var WEB = /^https?:/i;
1289
1289
  var OFFLINE = "Needs a connection";
1290
+ var NO_ACCOUNT = "Needs an account";
1290
1291
  var fail = (what) => {
1291
1292
  throw new TypeError(`openersFor: ${what}`);
1292
1293
  };
@@ -1358,7 +1359,7 @@ function openersFor(tools, kind, address, surface, options = {}) {
1358
1359
  }
1359
1360
  if (elementDoor === null && skips.length > 0) fail(`tool ${r.id}: open.element_skips names what an element door leaves out, and the row has none`);
1360
1361
  if (r.rung !== "listed") continue;
1361
- if (audience === "public" && needs !== null) continue;
1362
+ if (audience === "public" && needs === "device") continue;
1362
1363
  const template = kind === "element" ? elementDoor ?? worldDoor : worldDoor;
1363
1364
  if (template === null) continue;
1364
1365
  if (kind === "element" && marks.some((m) => skips.includes(m))) continue;
@@ -1366,6 +1367,7 @@ function openersFor(tools, kind, address, surface, options = {}) {
1366
1367
  let state = null;
1367
1368
  if (tool !== null && r.client === tool) state = "You are here";
1368
1369
  else if (offline(href)) state = OFFLINE;
1370
+ else if (audience === "public" && needs === "account") state = NO_ACCOUNT;
1369
1371
  else if (needs === "account" && !browser) state = "Opens in your browser";
1370
1372
  else if (needs === "account" && signedIn === false) state = `Sign in to ${r.name} first`;
1371
1373
  else if (needs === "device" && phone) state = "Needs the world on this phone";
package/dist/index.d.ts CHANGED
@@ -2828,6 +2828,8 @@ interface OwRemovalTicket {
2828
2828
  * is the value; "co-builder" is only its label in prose. Open, so a new role still types.
2829
2829
  */
2830
2830
  type OwMemberRole = 'co_builder' | 'contributor' | 'guest' | (string & {});
2831
+ /** Who paid for an ask or a sort: the account's daily token rating, or its own AI key once the rating is spent. */
2832
+ type OwPaidBy = 'rating' | 'own_key';
2831
2833
  /** POST /account/ask: keel's AI proxy's answer. */
2832
2834
  interface OwAskAnswer {
2833
2835
  /** The answer, from the context only; "The world doesn't say." when it does not hold one. */
@@ -2845,6 +2847,9 @@ interface OwAskAnswer {
2845
2847
  tokens_remaining: number;
2846
2848
  /** The account's token rating: its daily budget in tokens, one meter with the Council (since keel a6244db). */
2847
2849
  token_rating: number;
2850
+ /** Who paid for this call: `rating`, the account's daily token rating; `own_key`, the account's own
2851
+ * AI key, once today's rating was spent (the rating's fields above are then as they were). */
2852
+ paid_by: OwPaidBy;
2848
2853
  [k: string]: unknown;
2849
2854
  }
2850
2855
  /**
@@ -2931,6 +2936,9 @@ interface OwSortAnswer {
2931
2936
  tokens_remaining: number;
2932
2937
  /** The account's token rating: its daily budget in tokens, one meter with the Council (since keel a6244db). */
2933
2938
  token_rating: number;
2939
+ /** Who paid for this call: `rating`, the account's daily token rating; `own_key`, the account's own
2940
+ * AI key, once today's rating was spent (the rating's fields above are then as they were). */
2941
+ paid_by: OwPaidBy;
2934
2942
  [k: string]: unknown;
2935
2943
  }
2936
2944
  /** GET /me: who this world key is. */
@@ -3113,6 +3121,11 @@ interface OwAllowance {
3113
3121
  tokens_remaining: number;
3114
3122
  /** When the day's tokens reset: the next midnight UTC (ISO 8601). */
3115
3123
  resets_at: string;
3124
+ /** The account's own AI key, saved on its account page, or null: once today's rating is spent, ask and
3125
+ * sort run on it, billed by its provider. Only the provider is shown; the counts above keep the rating's meaning. */
3126
+ own_key: {
3127
+ provider: 'anthropic' | 'openai';
3128
+ } | null;
3116
3129
  [k: string]: unknown;
3117
3130
  }
3118
3131
  /** POST /join/preview: what a join code holds, read without using it. */
@@ -4087,6 +4100,13 @@ declare class OwApiError extends Error {
4087
4100
  * the file's size. Remove a file, or ask the owner. Nothing was issued.
4088
4101
  */
4089
4102
  get isFilesFull(): boolean;
4103
+ /**
4104
+ * ask and sort: today's token rating is spent and the call ran on the account's own AI key, which its
4105
+ * provider refused (422 `own_key_refused`: a key revoked, wrong or out of credit). Nothing was counted
4106
+ * and nothing retried on the platform's key: send the person to the account page to check or replace
4107
+ * the key, and do not retry.
4108
+ */
4109
+ get isOwnKeyRefused(): boolean;
4090
4110
  /** ask: the proxy is switched off, or paused for the day by the server-wide cap (503 `ask_unavailable`). Not counted. */
4091
4111
  get isAskUnavailable(): boolean;
4092
4112
  /** ask: the model gave no answer (502 `ask_failed`). Not counted; try again in a moment. */
@@ -5176,10 +5196,14 @@ declare class OwV2Client {
5176
5196
  * keel's AI proxy from `context` only (build it with buildAskContext from the elements
5177
5197
  * the user sees; it leaves proposed, hidden and room elements out unless asked). The answer is "The world doesn't say." when the context does not hold
5178
5198
  * it. Needs the client's `ow_a_` token (a world key is a TypeError before sending).
5179
- * Refusals: 429 `quota_exceeded` (`err.isQuotaExceeded`, the account's token rating used up for the day;
5180
- * Retry-After runs to midnight UTC), 503 `ask_unavailable` (`err.isAskUnavailable`:
5181
- * switched off, or paused for the day), 502 `ask_failed` (`err.isAskFailed`); none of
5182
- * them counts. 422 for a question over 500 characters or context past its limits.
5199
+ * Once the day's token rating is spent, an account that saved its own AI key on its account page is
5200
+ * answered on that key, billed by its provider: the answer's `paid_by` says `own_key` (else `rating`).
5201
+ * Refusals: 429 `quota_exceeded` (`err.isQuotaExceeded`, the account's token rating used up for the day
5202
+ * and no own key saved; Retry-After runs to midnight UTC), 422 `own_key_refused`
5203
+ * (`err.isOwnKeyRefused`: the own key's provider refused it; not retried, send the person to the
5204
+ * account page), 503 `ask_unavailable` (`err.isAskUnavailable`: switched off, or paused for the
5205
+ * day), 502 `ask_failed` (`err.isAskFailed`); none of them counts. 422 for a question over 500
5206
+ * characters or context past its limits.
5183
5207
  */
5184
5208
  ask(req: {
5185
5209
  worldId: string;
@@ -5192,7 +5216,8 @@ declare class OwV2Client {
5192
5216
  * lookupWorld's hits), sorted by the same proxy as ask into rows to review: `make`, `add_to`,
5193
5217
  * `link`, `ask`. Nothing is written; the app applies what the user accepts. Every id in a
5194
5218
  * row is from the slice; keel moves any other row to `not_proposed` with its reason.
5195
- * The same account token, token rating (it spends the tokens it uses) and refusals as ask. 422
5219
+ * The same account token, token rating (it spends the tokens it uses), own AI key and `paid_by`,
5220
+ * and refusals as ask. 422
5196
5221
  * names the param: notes 1 to 8, each up to 4,000 characters and 16,000 in all (text
5197
5222
  * only), at most four pictures, each uploaded into this world; slice up to 100, names up
5198
5223
  * to 200 characters, anchors up to 120.
@@ -5205,7 +5230,9 @@ declare class OwV2Client {
5205
5230
  /**
5206
5231
  * GET /account/allowance -- the account's token rating, the one daily meter ask, sort and
5207
5232
  * the Council spend from (keel 872431f): the rating, what is used and left today, and
5208
- * when it resets (the next midnight UTC). Spends nothing. Needs the client's `ow_a_` token.
5233
+ * when it resets (the next midnight UTC), and `own_key` (`{provider}` when the account saved its own
5234
+ * AI key, which ask and sort use once the rating is spent; else null). Spends nothing. Needs the
5235
+ * client's `ow_a_` token.
5209
5236
  */
5210
5237
  allowance(): Promise<OwAllowance>;
5211
5238
  /**
@@ -5883,7 +5910,7 @@ interface OwToolOpen {
5883
5910
  world: string | null;
5884
5911
  /** The link that opens one element, holding `{id}` and, if it needs them, `{world}` and `{type}` (the type word); null without one. */
5885
5912
  element: string | null;
5886
- /** What the person needs first; null for nothing, which is the one kind of row a public page offers. */
5913
+ /** What the person needs first; null for nothing. A public page offers those rows, and an `account` row only as one that opens nothing ("Needs an account"). */
5887
5914
  needs: OwToolNeeds | null;
5888
5915
  /** What the element door does not open, in the graph section's words; [] or absent: it opens every element (a list older than the key has none). */
5889
5916
  element_skips?: readonly OwElementMark[];
@@ -5919,7 +5946,7 @@ interface OwOpenerSurface {
5919
5946
  online?: boolean;
5920
5947
  }
5921
5948
  /** The word a row says when it cannot open now, or says where it lands. Sentence case, exactly. */
5922
- type OwOpenerState = 'You are here' | 'Needs a connection' | `Sign in to ${string} first` | 'Opens in your browser' | 'Needs the world on this phone' | 'Opens the world';
5949
+ type OwOpenerState = 'You are here' | 'Needs a connection' | 'Needs an account' | `Sign in to ${string} first` | 'Opens in your browser' | 'Needs the world on this phone' | 'Opens the world';
5923
5950
  /** One row of the menu. */
5924
5951
  interface OwOpener {
5925
5952
  /** `onlyworlds` for the site's own row, else the tool's id in the list. */
@@ -5943,13 +5970,16 @@ interface OwOpener {
5943
5970
  * a world door is a row to its world door that says "Opens the world". On an element given as
5944
5971
  * `options.element`, a row whose `open.element_skips` names a mark the element carries (room, hidden,
5945
5972
  * proposed, map space, a reading aid, each read as `worldGraph` reads it) is not there: its door cannot
5946
- * open it. A world door alone opens the world, so it stays. For the `public` audience only
5947
- * rows whose `open.needs` is null are there: a row that needs anything does not exist for the public.
5973
+ * open it. A world door alone opens the world, so it stays. For the `public` audience (the signed-out
5974
+ * reader) a row whose `open.needs` is `device` is not there, since a visitor's device holds no world of
5975
+ * this one's, and a row whose `needs` is `account` is there and says it needs one.
5948
5976
  *
5949
5977
  * Each row's `state`, the first that holds: "You are here" for the surface's own tool (its `client` is
5950
5978
  * `surface.tool`); then, when `surface.online` is false, "Needs a connection" for a row whose href is a
5951
5979
  * web address (scheme `http:` or `https:`; a row whose link opens an app on the device is unaffected,
5952
- * and the href stays in the row either way); then what `needs` asks of this surface: `account` outside
5980
+ * and the href stays in the row either way); then, for the `public` audience, "Needs an account" for a
5981
+ * row whose `needs` is `account`, whatever `signedIn` says (the href stays in the row; a surface draws
5982
+ * it as a row that opens nothing); then what `needs` asks of this surface: `account` outside
5953
5983
  * a browser "Opens in your browser", in a browser signed out "Sign in to <name> first" (none when
5954
5984
  * `signedIn` is null: a word shows only when the surface knows it is true), `device` on a phone "Needs
5955
5985
  * the world on this phone"; then
@@ -7124,4 +7154,4 @@ declare class TokenResource {
7124
7154
  getEncryptionInfo(): Promise<EncryptionInfo>;
7125
7155
  }
7126
7156
 
7127
- 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 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 OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldGraph, type OwWorldIndex, 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, 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, senderStatus, simpleCaseFold, strandOf, threadOf, typeWord, unreadFor, validateCalendarConfig, weekdayForStep, worldCalendars, worldGraph, writeWorldFile, yearLength, yearStartStep };
7157
+ 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 OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWordPair, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldGraph, type OwWorldIndex, 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, 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, senderStatus, simpleCaseFold, strandOf, threadOf, typeWord, unreadFor, validateCalendarConfig, weekdayForStep, worldCalendars, worldGraph, writeWorldFile, yearLength, yearStartStep };
package/dist/index.js CHANGED
@@ -42,7 +42,7 @@ import {
42
42
  trimWhiteSpace,
43
43
  typeWord,
44
44
  unknownKey
45
- } from "./chunk-K7SQUXMR.js";
45
+ } from "./chunk-EDU36RUO.js";
46
46
 
47
47
  // src/v2/keyed-id.ts
48
48
  var KEYED_IDS = "0199b6a0-6f0e-7c2a-9d1e-3b5c7a8e4f21";
@@ -322,6 +322,15 @@ var OwApiError = class extends Error {
322
322
  get isFilesFull() {
323
323
  return this.status === 403 && this.code === "files_full";
324
324
  }
325
+ /**
326
+ * ask and sort: today's token rating is spent and the call ran on the account's own AI key, which its
327
+ * provider refused (422 `own_key_refused`: a key revoked, wrong or out of credit). Nothing was counted
328
+ * and nothing retried on the platform's key: send the person to the account page to check or replace
329
+ * the key, and do not retry.
330
+ */
331
+ get isOwnKeyRefused() {
332
+ return this.status === 422 && this.code === "own_key_refused";
333
+ }
325
334
  /** ask: the proxy is switched off, or paused for the day by the server-wide cap (503 `ask_unavailable`). Not counted. */
326
335
  get isAskUnavailable() {
327
336
  return this.status === 503 && this.code === "ask_unavailable";
@@ -2034,10 +2043,14 @@ var OwV2Client = class {
2034
2043
  * keel's AI proxy from `context` only (build it with buildAskContext from the elements
2035
2044
  * the user sees; it leaves proposed, hidden and room elements out unless asked). The answer is "The world doesn't say." when the context does not hold
2036
2045
  * it. Needs the client's `ow_a_` token (a world key is a TypeError before sending).
2037
- * Refusals: 429 `quota_exceeded` (`err.isQuotaExceeded`, the account's token rating used up for the day;
2038
- * Retry-After runs to midnight UTC), 503 `ask_unavailable` (`err.isAskUnavailable`:
2039
- * switched off, or paused for the day), 502 `ask_failed` (`err.isAskFailed`); none of
2040
- * them counts. 422 for a question over 500 characters or context past its limits.
2046
+ * Once the day's token rating is spent, an account that saved its own AI key on its account page is
2047
+ * answered on that key, billed by its provider: the answer's `paid_by` says `own_key` (else `rating`).
2048
+ * Refusals: 429 `quota_exceeded` (`err.isQuotaExceeded`, the account's token rating used up for the day
2049
+ * and no own key saved; Retry-After runs to midnight UTC), 422 `own_key_refused`
2050
+ * (`err.isOwnKeyRefused`: the own key's provider refused it; not retried, send the person to the
2051
+ * account page), 503 `ask_unavailable` (`err.isAskUnavailable`: switched off, or paused for the
2052
+ * day), 502 `ask_failed` (`err.isAskFailed`); none of them counts. 422 for a question over 500
2053
+ * characters or context past its limits.
2041
2054
  */
2042
2055
  async ask(req) {
2043
2056
  only("ask", req, ["worldId", "question", "context"]);
@@ -2054,7 +2067,8 @@ var OwV2Client = class {
2054
2067
  * lookupWorld's hits), sorted by the same proxy as ask into rows to review: `make`, `add_to`,
2055
2068
  * `link`, `ask`. Nothing is written; the app applies what the user accepts. Every id in a
2056
2069
  * row is from the slice; keel moves any other row to `not_proposed` with its reason.
2057
- * The same account token, token rating (it spends the tokens it uses) and refusals as ask. 422
2070
+ * The same account token, token rating (it spends the tokens it uses), own AI key and `paid_by`,
2071
+ * and refusals as ask. 422
2058
2072
  * names the param: notes 1 to 8, each up to 4,000 characters and 16,000 in all (text
2059
2073
  * only), at most four pictures, each uploaded into this world; slice up to 100, names up
2060
2074
  * to 200 characters, anchors up to 120.
@@ -2071,7 +2085,9 @@ var OwV2Client = class {
2071
2085
  /**
2072
2086
  * GET /account/allowance -- the account's token rating, the one daily meter ask, sort and
2073
2087
  * the Council spend from (keel 872431f): the rating, what is used and left today, and
2074
- * when it resets (the next midnight UTC). Spends nothing. Needs the client's `ow_a_` token.
2088
+ * when it resets (the next midnight UTC), and `own_key` (`{provider}` when the account saved its own
2089
+ * AI key, which ask and sort use once the rating is spent; else null). Spends nothing. Needs the
2090
+ * client's `ow_a_` token.
2075
2091
  */
2076
2092
  async allowance() {
2077
2093
  if (this.keyKind !== "account") {
package/dist/waymark.d.ts CHANGED
@@ -9,7 +9,7 @@ interface OwToolOpen {
9
9
  world: string | null;
10
10
  /** The link that opens one element, holding `{id}` and, if it needs them, `{world}` and `{type}` (the type word); null without one. */
11
11
  element: string | null;
12
- /** What the person needs first; null for nothing, which is the one kind of row a public page offers. */
12
+ /** What the person needs first; null for nothing. A public page offers those rows, and an `account` row only as one that opens nothing ("Needs an account"). */
13
13
  needs: OwToolNeeds | null;
14
14
  /** What the element door does not open, in the graph section's words; [] or absent: it opens every element (a list older than the key has none). */
15
15
  element_skips?: readonly OwElementMark[];
@@ -52,7 +52,7 @@ interface OwWaymarkOptions {
52
52
  name: string;
53
53
  [k: string]: unknown;
54
54
  } | null;
55
- /** `member`, `guest` or `public`. The public face shows the name line without the last door, the rows that need nothing first, and Copy link. */
55
+ /** `member`, `guest` or `public`. The public face shows the name line without the last door, the rows that need nothing, those that need an account as rows that open nothing ("Needs an account"), and Copy link. */
56
56
  reader: OwWaymarkReader;
57
57
  /** The client name of the surface's own tool; its row says "You are here". The site passes `onlyworlds`. */
58
58
  tool?: string | null;
@@ -100,6 +100,10 @@ interface OwWaymark {
100
100
  * nothing and the fan-out stays open. While the fan-out is open, the window's `online` and `offline`
101
101
  * events redraw the rows in place, and focus on a row stays on that row. Copy link is unaffected.
102
102
  *
103
+ * For the public reader, a tool that needs an account says "Needs an account" and is drawn the same
104
+ * way: grey, a link with no href, `aria-disabled="true"`, in the arrow and Tab order, doing nothing
105
+ * when pressed.
106
+ *
103
107
  * Keyboard: the mark is a button and the fan-out a menu; Tab goes from the mark through the rows in
104
108
  * order, the arrow keys, Home and End move within it, Escape closes it and returns focus to what opened
105
109
  * it: the mark, or for the entry `returnFocus` when given (the surface's "..." button, which stays
package/dist/waymark.js CHANGED
@@ -6,7 +6,7 @@ import {
6
6
  openersFor,
7
7
  refuseUnknownOptions,
8
8
  typeWord
9
- } from "./chunk-K7SQUXMR.js";
9
+ } from "./chunk-EDU36RUO.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";
@@ -55,13 +55,14 @@ var COPIED = "Link copied";
55
55
  var NOT_COPIED = "Could not copy the link.";
56
56
  var HERE = "You are here";
57
57
  var OFFLINE = "Needs a connection";
58
+ var NO_ACCOUNT = "Needs an account";
58
59
  var WEB_LINK = /^https?:/i;
59
60
  var mounted = 0;
60
61
  var fail = (what) => {
61
62
  throw new TypeError(`mountWaymark: ${what}`);
62
63
  };
63
64
  function cannotOpen(state) {
64
- return state !== null && (state.startsWith("Sign in to ") || state === "Needs the world on this phone" || state === OFFLINE);
65
+ return state !== null && (state.startsWith("Sign in to ") || state === "Needs the world on this phone" || state === OFFLINE || state === NO_ACCOUNT);
65
66
  }
66
67
  function shapedOn(at, now) {
67
68
  const d = new Date(at);
@@ -242,7 +243,7 @@ function mountWaymark(target, options) {
242
243
  a.type = "button";
243
244
  a.setAttribute("aria-current", "page");
244
245
  a.dataset.here = "";
245
- } else if (r.state === OFFLINE) {
246
+ } else if (r.state === OFFLINE || r.state === NO_ACCOUNT) {
246
247
  a = el("a", cls);
247
248
  a.tabIndex = 0;
248
249
  a.setAttribute("aria-disabled", "true");
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.129.2",
3
+ "version": "4.131.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {