@onlyworlds/sdk 4.33.1 → 4.35.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.35.0] - 2026-10-20
+
+### Added
+
+- **`createWorldLink(worldId, { preview })`** and `preview` on `OwWorldLink` (keel #422 PR 1, live 2026-10-20): a person or player link with `preview: true` is `/join/<world_id>#<code>`, so a chat that unfurls it shows the world's name and picture; the code stays in the fragment. Absent means off, as keel rules for the API; `true` on an agent link is 422, param `preview`. The wire gate failed on production's document until this release.
+
+## [4.34.0] - 2026-10-20
+
+### Added
+
+- **`fieldLabel(name)`** and **`FIELD_ACRONYMS`**: a field name as the words a tool shows, by the house rule (OW Style, the Captain 2026-10-20): sentence case, acronyms kept wherever they fall (`birth_date` → "Birth date", `image_url` → "Image URL"). Seeded from Atlas's `humanizeFieldName` as of 1.59.1, so Atlas, Lantern and Council read one copy (h63 #8109, #8119). The name is taken as given: a tool that hides an extension prefix drops it first.
+
 ## [4.33.1] - 2026-10-19
 
 ### Fixed

package/dist/index.d.ts

@@ -2249,6 +2249,8 @@ interface OwWorldLink {
     /** 0 or 1: a link works once. */
     uses: number;
     status: 'pending' | 'used' | 'revoked' | 'expired';
+    /** Whether the link shows the world's name and picture when it is pasted into a chat (keel #422): then the link is `/join/<world_id>#<code>`, else `/join#<code>`. Never on an agent link. */
+    preview?: boolean;
     /** A player link only: the Character the player reads as; null while a link for a fresh Character is unused. `name` is null if that Character was deleted (the redeem then makes a fresh one). */
     character?: {
         id: string;
@@ -2260,7 +2262,7 @@ interface OwWorldLink {
 interface OwCreatedWorldLink extends OwWorldLink {
     /** The `ow_j_` join code. Shown once; it can never be read again. */
     code: string;
-    /** The invite link: the /join page with the code after `#`. */
+    /** The invite link: the /join page (`/join/<world_id>` when `preview` is on) with the code after `#`. */
     link: string;
     /** The one line to send: who invites, to which world, and the link. */
     line: string;
@@ -3142,7 +3144,10 @@ declare class OwV2Client {
      * redeemJoin for a read key, keel #353); `role`, when left out, is keel's default: guest for a
      * person link, contributor for an agent link (a player link is guest, and refuses any other), `days` (1, 7 or 30) to 7; `withCharacter` (agent links
      * only) to true; `character` (player links only) a Character's id or `new` (the default):
-     * whoever opens the link first reads as it, until removed. 201 with the code, shown in this
+     * whoever opens the link first reads as it, until removed. `preview` (person and player links,
+     * keel #422) to false: true puts the world's id in the link's path, so a chat that unfurls it
+     * shows the world's name and picture (the code stays after `#`); true on an agent link is
+     * 422, param `preview`. 201 with the code, shown in this
      * answer only. Owner only: anyone else, and a world that doesn't exist, gets 404
      * `not_found` (`err.isNotFound`). A world key is a TypeError before anything is sent.
      */
@@ -3153,6 +3158,7 @@ declare class OwV2Client {
         inviterName?: string;
         withCharacter?: boolean;
         character?: string;
+        preview?: boolean;
     }): Promise<OwCreatedWorldLink>;
     /**
      * GET /account/worlds/{worldId}/links -- the world's invite links, without their codes:
@@ -3328,6 +3334,27 @@ declare function elementColor(type: ElementType, mode?: 'light' | 'dark'): strin
 /** All four families, in ruling order (the order IS the CVD-safety mechanism of the source palette). */
 declare const FAMILY_ORDER: readonly ElementFamily[];
 
+/**
+ * Field labels: the one rule for turning a field name into the words a tool shows.
+ *
+ * Presentation, not the standard: the schema never carries a label. The house rule
+ * (OW Style, the Captain 2026-10-20, h63 #8074; Studio/style/RULES.md) is sentence case
+ * with acronyms kept: "birth_date" → "Birth date", "image_url" → "Image URL". Seeded
+ * from Atlas's humanizeFieldName as of 1.59.1 (Temper, h63 #8119), so Atlas, Lantern
+ * and Council read one copy instead of three.
+ */
+/** Words shown in capitals wherever they fall in a label. */
+declare const FIELD_ACRONYMS: readonly string[];
+/**
+ * A field name as a label: split on `_`, the first word capitalised, every other word
+ * lowercase, an acronym in capitals wherever it falls ("image_url" → "Image URL",
+ * "url" → "URL", "time_range_current" → "Time range current").
+ *
+ * The name is taken as given: a tool that hides an extension prefix (`atlas_`, `x_`,
+ * `shadow_`) drops it before calling this.
+ */
+declare function fieldLabel(name: string): string;
+
 /**
  * Current OnlyWorlds version
  * Synced with https://github.com/OnlyWorlds/OnlyWorlds/blob/main/VERSION
@@ -4215,4 +4242,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwSeat, type OwSeatCreated, OwSignInError, type OwSignInReason, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, type ParseError, type ParseOptions, type ParseResult, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };
+export { AGENT_DOORS, ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_ACRONYMS, FIELD_SCHEMA, FILE_EXTENSIONS, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, type OwAgentJoined, type OwAllowance, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangeDelete, type OwChangeUpsert, type OwChangesPage, type OwClientConfig, type OwCreatedWorldLink, type OwElement, type OwElementBase, type OwErrorBody, type OwFileAddedBy, type OwFileDownload, type OwFileKind, type OwFileRow, type OwFileTicket, type OwJoinPreview, type OwJoined, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMe, type OwMediaTicket, type OwMember, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, type OwPlayerJoined, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwSeat, type OwSeatCreated, OwSignInError, type OwSignInReason, type OwSignedIn, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedFile, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldFileRow, type OwWorldFiles, type OwWorldIndex, type OwWorldLink, type OwWorldMeta, type OwWriteDoor, PHOTO_MAX_BYTES, PHOTO_TYPES, type ParseError, type ParseOptions, type ParseResult, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, fieldLabel, fileKindOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isAgentDoor, isDemoKey, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -902,7 +902,10 @@ var OwV2Client = class {
    * redeemJoin for a read key, keel #353); `role`, when left out, is keel's default: guest for a
    * person link, contributor for an agent link (a player link is guest, and refuses any other), `days` (1, 7 or 30) to 7; `withCharacter` (agent links
    * only) to true; `character` (player links only) a Character's id or `new` (the default):
-   * whoever opens the link first reads as it, until removed. 201 with the code, shown in this
+   * whoever opens the link first reads as it, until removed. `preview` (person and player links,
+   * keel #422) to false: true puts the world's id in the link's path, so a chat that unfurls it
+   * shows the world's name and picture (the code stays after `#`); true on an agent link is
+   * 422, param `preview`. 201 with the code, shown in this
    * answer only. Owner only: anyone else, and a world that doesn't exist, gets 404
    * `not_found` (`err.isNotFound`). A world key is a TypeError before anything is sent.
    */
@@ -916,6 +919,7 @@ var OwV2Client = class {
     if (opts.inviterName !== void 0) body.inviter_name = opts.inviterName;
     if (opts.withCharacter !== void 0) body.with_character = opts.withCharacter;
     if (opts.character !== void 0) body.character = opts.character;
+    if (opts.preview !== void 0) body.preview = opts.preview;
     return this.request("POST", `/account/worlds/${encodeURIComponent(worldId)}/links`, { body });
   }
   /**
@@ -1997,6 +2001,30 @@ function elementColor(type, mode = "dark") {
 }
 var FAMILY_ORDER = ["agents", "world", "abstract", "temporal"];
 
+// src/v2/labels.ts
+var FIELD_ACRONYMS = Object.freeze([
+  "url",
+  "id",
+  "api",
+  "ui",
+  "ip",
+  "html",
+  "http",
+  "dns",
+  "uuid",
+  "sdk",
+  "pin",
+  "gps"
+]);
+var ACRONYM_SET = new Set(FIELD_ACRONYMS);
+function fieldLabel(name) {
+  return name.split("_").map((word, i) => {
+    const lower = word.toLowerCase();
+    if (ACRONYM_SET.has(lower)) return lower.toUpperCase();
+    return i === 0 ? lower.charAt(0).toUpperCase() + lower.slice(1) : lower;
+  }).join(" ");
+}
+
 // src/v2/constants.ts
 var ELEMENT_LABELS = {
   ability: "Abilities",
@@ -3408,6 +3436,7 @@ export {
   ELEMENT_TYPES,
   FAMILY_COLORS,
   FAMILY_ORDER,
+  FIELD_ACRONYMS,
   FIELD_SCHEMA,
   FILE_EXTENSIONS,
   GameTier,
@@ -3436,6 +3465,7 @@ export {
   eraForStep,
   errorFromResponse,
   familyOf,
+  fieldLabel,
   fileKindOf,
   floorDiv,
   floorMod,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.33.1",
+  "version": "4.35.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {