Skip to content

@onlyworlds/sdk 4.0.0

Choose a tag to compare

View all tags
@tmoosting tmoosting released this 20 Oct 14:23
· 134 commits to main since this release
v4.0.0
38706fa

v2-native only. See docs/migrating-3-to-4.md. 3.x stays published forever for
pinned consumers.

Removed (BREAKING)

  • The v1 client (OnlyWorldsClient), the v1 ElementType enum, icon-utils.
    ElementType at the root is now THE v2 slug union (was V2ElementType alias in 3.x).
  • CJS build — the package is ESM-only with a sealed exports map ("type": "module",
    sideEffects: false).

Changed

  • Metadata tables (ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, FIELD_SCHEMA,
    getElementIcon, getElementLabel) ported onto the v2 slug union — same export names,
    same shapes, contents byte-identical EXCEPT: FIELD_SCHEMA type: 'number' →
    'integer' (70 entries; 'number' dropped from FieldType). Migration: consumers
    switching on 'number' switch on 'integer'.
  • TokenResource now takes a structural TokenTransport ({ request<T>(method, path, body?) }) instead of the removed v1 client. Token surface retained pending the
    wire-fate ruling (RFC-001 §5) — may be removed in a later 4.x.

Added (post-alpha.0, same night)

  • ELEMENT_ICONS GENERATED from keel's icon: wrapper key (keel 56c124a).
  • ELEMENT_SECTIONS DERIVED from the canonical schema's own document structure
    (ruling: sections are the standard tier's property groups; document order is
    display order). Divergence check vs the old hand table found and fixed three fossils:
    creature "Behaviour"→"Behavior", pin's triple-listed generic link → element,
    relation "Involves" listing a nonexistent relations field. Canonical is truth.
  • SCHEMA.md — full generated schema reference (every field with its canonical
    description, link directions, families, icons, sections), ships in the tarball;
    covered by the codegen drift guard. AGENTS.md points agents at it first.
  • OwV2Client.request() is public (typed escape hatch; does not sanitize) and
    structurally satisfies TokenTransport — new TokenResource(client) just works.
    Token ruling: keel keeps /tokens/* long-term; ported, not deleted.
  • README rewritten v2-native (v1 sections, branded types, and the encrypted-key
    walkthrough removed; bulk partial-failure and idempotency-key hygiene promoted).

alpha.1 — consumer-pin fixes (atlas review, same night)

  • parseEnvelope → parseErrorEnvelope (it parses the platform error envelope;
    renamed before the 4.0 name freeze to avoid collision with the world-export envelope).
  • The never-whitelist LAW now lives as a comment on READ_ONLY_FIELDS itself.
  • Stale v1 example in the shipped d.ts fixed (TokenResource JSDoc).

Release gates — ALL GREEN (2026-07-23 night)

  • Gate 3 (wire-log v1-traffic query): GREEN — no unknown v1-SDK consumer on
    the wire; observed v1 traffic is pinned deployed builds (council proxy, legacy plugin
    walks) that an npm major cannot touch. The v1 API dialect stays served regardless.
  • /api/v2/tokens/ live on prod + staging (keel e181689; three-base byte
    agreement test-pinned). TokenResource annotates a 404 on token routes as
    "older server", not "no tokens". Requirement noted in the migration guide.
  • ONLYWORLDS_VERSION now GENERATED from canonical's VERSION file (carried
    into keel schema/ by the refresh script, keel 492168c) — the last hand-synced
    constant is dead. Consumer soak: the atlas app pinned the alpha against its full
    static surface — strict-clean compile, correct runtime, package shape approved.
  • No npm deprecate on 3.x (landscape research; 3.x stays plainly supported).
  • 4.x wishlist: account client (list/mint/create — atlas first consumer), world-export
    envelope reader (§8c), per-status error classes, richer codegen JSDoc, retry/backoff
    parity audit, FIELD_SCHEMA generation with required: from YAML.
Assets 2
Loading