@onlyworlds/sdk 4.108.1 → 4.110.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/AGENTS.md CHANGED
@@ -115,9 +115,13 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
115
115
  `writeWorldFile(files, topDir, { includePrivateRecords: true })` (since 4.63.0; OW-8).
116
116
  Element files marked `hidden: true` travel by default (a copy); a share passes
117
117
  `{ includeHidden: false, report: r => r.hiddenLeftOut }` to leave them out whole and count
118
- them (since 4.70.0; §4.8). Two names are one after OW-18's fold: NFC, then simple case
119
- folding, both Unicode 15.1's from its own files (`nfc` since 4.71.0, `simpleCaseFold`), never
120
- the runtime's `normalize`, whose Unicode is its ICU's (Node 22: 16.0).
118
+ them (since 4.70.0; §4.8). Element files leave out the author fields (`created_by`,
119
+ `changed_by`, `changed_via`, `changed_client`, `doors`: which member and tool wrote it) by default,
120
+ counted in `r.authorFieldsLeftOut`; `{ includeAuthorFields: true }` writes every file byte
121
+ for byte, for an archive of your own world (since 4.109.0). Two names are one after OW-18's
122
+ fold: NFC, then simple case folding, both Unicode 15.1's from its own files (`nfc` since
123
+ 4.71.0, `simpleCaseFold`), never the runtime's `normalize`, whose Unicode is its ICU's (Node
124
+ 22: 16.0).
121
125
  - World calendars (since 4.20.0): `worldCalendars(elements)` finds the elements carrying
122
126
  `atlas_calendar` (Atlas owns the field: read it, never write it); `resolveCalendar` picks
123
127
  one; `formatStep(config, step)` names a point on the world's integer time line, `parseDate`
package/CHANGELOG.md CHANGED
@@ -5,6 +5,22 @@ earlier history lives in git log only.
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [4.110.0] - 2026-10-30
9
+
10
+ ### Changed
11
+
12
+ - **`openersFor` checks the whole address.** It handed the address writer only the world, type and id, in the site's form, so a malformed `lens` or `moment`, or a `form` that is neither `human` nor `text`, still gave rows. The whole address now goes to `elementAddress` in its own form (the site's when it has none), so it refuses with the writer's own `OwAddressError`, `bad_lens`, `bad_moment` or `bad_form`, as it already did for the world, type and id; an address without a world still refuses `no_world`, the text form inside a world included. The rows are unchanged: a lens and a moment still ride on no href. The shared fixture gains four cases (45; the same bytes as the Python package's): the three refusals, and a well-formed lens and moment giving exactly the rows of the same address without them.
13
+
14
+ ## [4.109.0] - 2026-10-29
15
+
16
+ ### Changed
17
+
18
+ - **`writeWorldFile` leaves the author fields out of every element file by default.** `created_by`, `changed_by`, `changed_via`, `changed_client` and `doors` record which member and which tool wrote each element (a membership id, a door), which means nothing to someone the world is handed to. Each element file under `elements/<type>/` or `spatial/<type>/` holding any of the five is now written without them, in the folder's own form (two-space indent, a trailing newline, its other keys in their order); `created_at` and `updated_at` stay. A file holding none of them, or that is not a JSON object, travels byte for byte, and `world.json`, records, media and every other file are untouched; an `x_*` value that holds one of the names is the extension's and stays. A caller archiving their own world passes `{ includeAuthorFields: true }`, which writes the same bytes as 4.108.1.
19
+
20
+ ### Added
21
+
22
+ - **`includeAuthorFields`** on `writeWorldFile`, refused by name when it is not a boolean, as `includePrivateRecords` and `includeHidden` are; and **`authorFieldsLeftOut`** in its `report`, the element files written without their author fields (0 when the option is true). A shared fixture of five cases (`test/fixtures/author-fields.fixture.json`, the same bytes as the Python package's) holds both writers to the same entries.
23
+
8
24
  ## [4.108.1] - 2026-10-29
9
25
 
10
26
  ### Fixed
package/README.md CHANGED
@@ -320,6 +320,12 @@ const share = writeWorldFile(files, topDir, { includeHidden: false, report: r =>
320
320
 
321
321
  The two defaults differ on purpose: private records stay out unless you ask, hidden elements stay in unless the write is a share.
322
322
 
323
+ An element's author fields, `created_by`, `changed_by`, `changed_via`, `changed_client` and `doors`, record which member and which tool wrote it (a membership id, a door), which means nothing to someone the world is handed to. So by default every element file leaves them out (since 4.109.0). `created_at` and `updated_at` stay. A file holding any of the five is rewritten without them, two-space indented with a trailing newline and its other keys in their order; a file holding none travels byte for byte, and nothing outside `elements/<type>/` (or `spatial/<type>/`) changes. `report` counts the files rewritten in `r.authorFieldsLeftOut`. To archive your own world as it is on disk, pass `includeAuthorFields: true`:
324
+
325
+ ```typescript
326
+ const backup = writeWorldFile(files, topDir, { includeAuthorFields: true }); // every file byte for byte
327
+ ```
328
+
323
329
  ## World calendars
324
330
 
325
331
  A world's time is an integer line (`time_range_current` is a point on it, and so is an Event's `start_date`). A calendar names its points: months, days, eras. Atlas keeps a calendar on an element (a Construct by convention) in its `atlas_calendar` field, and the SDK reads it with Atlas's own calendar code (since 4.20.0). Atlas owns that field and is its only writer; read it, never write it.
package/dist/index.d.ts CHANGED
@@ -5631,8 +5631,10 @@ interface OwOpener {
5631
5631
  * only when the surface knows it is true), `device` on a phone "Needs the world on this phone"; then
5632
5632
  * "Opens the world" (a world door on an element: a sign-in the row needs is the more urgent word); else null.
5633
5633
  *
5634
- * Refuses with `OwAddressError` an address without a world (`no_world`) or with a slug or anything else
5635
- * for its id (`bad_world`), and a type, id or pairing `elementAddress` refuses. A TypeError names the
5634
+ * Refuses with `OwAddressError` whatever `elementAddress` refuses of the whole address, in its own form
5635
+ * (the site's when it has none): a form, type, id, pairing, moment or lens (`bad_moment`, `bad_lens`),
5636
+ * and a slug or anything else for the world's id (`bad_world`); and an address without a world
5637
+ * (`no_world`), the text form inside a world included, since every row needs one. A TypeError names the
5636
5638
  * rest: a `kind` that is neither, an element's openers asked of an address with no element, an unknown
5637
5639
  * key on the address or the surface, a missing or unknown `audience`, a surface value of the wrong type,
5638
5640
  * a tools row that is not one (a `needs` outside the list's format included).
@@ -5742,6 +5744,9 @@ declare function doorWhere(door: OwDoor): string;
5742
5744
  * producers `records/RECORDS.json` marks private, left out whole unless the
5743
5745
  * caller asks (OW-8, §4.5 rule 11). Element files marked hidden travel too,
5744
5746
  * unless the caller says the file is a share (`includeHidden: false`, §4.8).
5747
+ * Element files leave out the five author fields, which record which member
5748
+ * and which tool wrote each element, unless the caller asks
5749
+ * (`includeAuthorFields`).
5745
5750
  *
5746
5751
  * A tool's own `.<tool>/` folder is the tool's (spec §4): the reader returns
5747
5752
  * it like any file (a caller leaves files out with `skip`), and the writer
@@ -5804,6 +5809,16 @@ interface OwWriteWorldFileOptions {
5804
5809
  * default is the opposite of `includePrivateRecords`'s on purpose.
5805
5810
  */
5806
5811
  includeHidden?: boolean;
5812
+ /**
5813
+ * Carry the author fields of every element file: `created_by`,
5814
+ * `changed_by`, `changed_via`, `changed_client` and `doors`, which record
5815
+ * which member and which tool wrote it (a membership id, a door) and mean
5816
+ * nothing to someone the world is handed to. Left out or false, each
5817
+ * element file holding any of the five is rewritten without them
5818
+ * (two-space indent, a trailing newline, the other keys in their order),
5819
+ * and `report` counts them. Pass true for a byte copy of your own folder.
5820
+ */
5821
+ includeAuthorFields?: boolean;
5807
5822
  /** Called once with what the write left out, after the archive is made and before it is returned; never on a refusal. */
5808
5823
  report?: (report: OwWriteWorldFileReport) => void;
5809
5824
  }
@@ -5811,6 +5826,8 @@ interface OwWriteWorldFileOptions {
5811
5826
  interface OwWriteWorldFileReport {
5812
5827
  /** Element files left out for the hidden mark (`includeHidden: false`); 0 otherwise. */
5813
5828
  hiddenLeftOut: number;
5829
+ /** Element files written without their author fields (the default); 0 with `includeAuthorFields: true`. */
5830
+ authorFieldsLeftOut: number;
5814
5831
  }
5815
5832
  /**
5816
5833
  * Write a world file under one top-level folder `topDir`: the `mimetype`
@@ -5840,10 +5857,23 @@ interface OwWriteWorldFileReport {
5840
5857
  * hidden one keeps its id, which then names no file. Pass
5841
5858
  * `report: r => …` to learn `r.hiddenLeftOut`, the count left out.
5842
5859
  *
5860
+ * The author fields, `created_by`, `changed_by`, `changed_via`,
5861
+ * `changed_client` and `doors`, record which member and which tool wrote
5862
+ * each element (a membership id, a door), which means nothing to someone the
5863
+ * world is handed to. So by default every element file under
5864
+ * `elements/<type>/` or `spatial/<type>/` leaves them out; `created_at` and
5865
+ * `updated_at` stay. A file holding any of them is
5866
+ * rewritten without them in the folder's own form (two-space indent, a
5867
+ * trailing newline, the other keys in their order); one holding none, or
5868
+ * that is not a JSON object, travels byte for byte, and nothing outside the
5869
+ * element files is touched. `r.authorFieldsLeftOut` counts the files
5870
+ * rewritten. Pass `{ includeAuthorFields: true }` for a byte copy of your own
5871
+ * folder, as an archive of your own world.
5872
+ *
5843
5873
  * Throws a `TypeError`, having written nothing, for an unknown option, an
5844
- * `includePrivateRecords` or `includeHidden` that is not a boolean, a
5845
- * `report` that is not a function, and (unless private records
5846
- * are asked for) a `RECORDS.json` that is not a JSON array of objects or that
5874
+ * `includePrivateRecords`, `includeHidden` or `includeAuthorFields` that is
5875
+ * not a boolean, a `report` that is not a function, and (unless private
5876
+ * records are asked for) a `RECORDS.json` that is not a JSON array of objects or that
5847
5877
  * marks an entry private without a producer name. Refuses (`OwWorldFileError`)
5848
5878
  * an unsafe path or `topDir`, a duplicate path, a name some disk cannot hold,
5849
5879
  * two names that fold to one, and a world.json that is missing, will not parse
package/dist/index.js CHANGED
@@ -3769,14 +3769,15 @@ function carried(path) {
3769
3769
  return !segs.some((s) => s.startsWith(".")) && !path.endsWith(".meta");
3770
3770
  }
3771
3771
  var STAMP = new Date(1980, 0, 1, 0, 0, 0);
3772
- var WRITE_OPTION_KEYS = ["includePrivateRecords", "includeHidden", "report"];
3772
+ var WRITE_OPTION_KEYS = ["includePrivateRecords", "includeHidden", "includeAuthorFields", "report"];
3773
3773
  var RECORDS_MANIFEST = "records/RECORDS.json";
3774
+ var AUTHOR_FIELDS = ["created_by", "changed_by", "changed_via", "changed_client", "doors"];
3774
3775
  function writeOptions(opts) {
3775
- if (opts === void 0 || opts === null) return { includePrivate: false, includeHidden: true };
3776
+ if (opts === void 0 || opts === null) return { includePrivate: false, includeHidden: true, includeAuthorFields: false };
3776
3777
  if (typeof opts !== "object") throw new TypeError(`writeWorldFile: options must be an object, such as { includePrivateRecords: true }. Nothing was written.`);
3777
3778
  refuseUnknownOptions("writeWorldFile", opts, WRITE_OPTION_KEYS, "Nothing was written.");
3778
3779
  const o = opts;
3779
- for (const key of ["includePrivateRecords", "includeHidden"]) {
3780
+ for (const key of ["includePrivateRecords", "includeHidden", "includeAuthorFields"]) {
3780
3781
  const asked = o[key];
3781
3782
  if (asked !== void 0 && typeof asked !== "boolean") {
3782
3783
  throw new TypeError(`writeWorldFile: ${key} must be true or false; got ${JSON.stringify(asked) ?? String(asked)}. Nothing was written.`);
@@ -3785,21 +3786,39 @@ function writeOptions(opts) {
3785
3786
  if (o.report !== void 0 && typeof o.report !== "function") {
3786
3787
  throw new TypeError(`writeWorldFile: report must be a function; got ${JSON.stringify(o.report) ?? String(o.report)}. Nothing was written.`);
3787
3788
  }
3788
- return { includePrivate: o.includePrivateRecords === true, includeHidden: o.includeHidden !== false, report: o.report };
3789
+ return {
3790
+ includePrivate: o.includePrivateRecords === true,
3791
+ includeHidden: o.includeHidden !== false,
3792
+ includeAuthorFields: o.includeAuthorFields === true,
3793
+ report: o.report
3794
+ };
3789
3795
  }
3790
- function isHiddenElement(f) {
3796
+ function elementObject(f) {
3791
3797
  const segs = f.path.split("/");
3792
- if (segs.length !== 3 || segs[0] !== "elements" && segs[0] !== "spatial" || !/\.json$/i.test(segs[2])) return false;
3798
+ if (segs.length !== 3 || segs[0] !== "elements" && segs[0] !== "spatial" || !/\.json$/i.test(segs[2])) return null;
3793
3799
  let doc;
3794
3800
  try {
3795
3801
  doc = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(f.data));
3796
3802
  } catch {
3797
- return false;
3803
+ return null;
3798
3804
  }
3799
- if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return false;
3805
+ if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return null;
3806
+ return doc;
3807
+ }
3808
+ function isHiddenElement(f) {
3809
+ const doc = elementObject(f);
3810
+ if (!doc) return false;
3800
3811
  const mark = doc.hidden;
3801
3812
  return mark !== void 0 && mark !== null && mark !== false;
3802
3813
  }
3814
+ function withoutAuthorFields(f) {
3815
+ const doc = elementObject(f);
3816
+ if (!doc) return null;
3817
+ const present = AUTHOR_FIELDS.filter((k) => k in doc);
3818
+ if (!present.length) return null;
3819
+ for (const k of present) delete doc[k];
3820
+ return new TextEncoder().encode(JSON.stringify(doc, null, 2) + "\n");
3821
+ }
3803
3822
  function privateProducers(files) {
3804
3823
  const manifest = files.find((f) => f.path === RECORDS_MANIFEST);
3805
3824
  if (!manifest) return [];
@@ -3824,7 +3843,7 @@ function privateProducers(files) {
3824
3843
  return out;
3825
3844
  }
3826
3845
  function writeWorldFile(files, topDir, opts = {}) {
3827
- const { includePrivate, includeHidden, report } = writeOptions(opts);
3846
+ const { includePrivate, includeHidden, includeAuthorFields, report } = writeOptions(opts);
3828
3847
  if (pathFault(topDir) || topDir.includes("/")) throw new OwWorldFileError("unsafe_path");
3829
3848
  const seen = /* @__PURE__ */ new Set();
3830
3849
  for (const f of files) {
@@ -3857,13 +3876,22 @@ function writeWorldFile(files, topDir, opts = {}) {
3857
3876
  const input = {
3858
3877
  [MARKER_NAME]: [new TextEncoder().encode(WORLD_FILE_MEDIA_TYPE), { level: 0, mtime: STAMP }]
3859
3878
  };
3879
+ let authorFieldsLeftOut = 0;
3860
3880
  for (const f of [...kept].sort((a, b) => byCodePoint(a.path, b.path))) {
3861
3881
  let data = f.data;
3862
- if (f.path === WORLD_FILE) data = withoutLink(data, parseWorld(data)).data;
3882
+ if (f.path === WORLD_FILE) {
3883
+ data = withoutLink(data, parseWorld(data)).data;
3884
+ } else if (!includeAuthorFields) {
3885
+ const bare = withoutAuthorFields(f);
3886
+ if (bare) {
3887
+ data = bare;
3888
+ authorFieldsLeftOut++;
3889
+ }
3890
+ }
3863
3891
  input[`${topDir}/${f.path}`] = [data, { level: /\.json$/i.test(f.path) ? 6 : 0, mtime: STAMP }];
3864
3892
  }
3865
3893
  const zip = zipSync(input);
3866
- report?.({ hiddenLeftOut });
3894
+ report?.({ hiddenLeftOut, authorFieldsLeftOut });
3867
3895
  return zip;
3868
3896
  }
3869
3897
 
@@ -5260,6 +5288,7 @@ function openersFor(tools, kind, address, surface) {
5260
5288
  }
5261
5289
  refuseUnknownOptions("openersFor", address, ADDRESS_KEYS);
5262
5290
  const a = address;
5291
+ elementAddress({ ...a, form: a.form ?? "human" });
5263
5292
  const page = elementAddress({ form: "human", world: a.world, type: a.type, id: a.id });
5264
5293
  const world = a.world.toLowerCase();
5265
5294
  const hasElement = a.type !== void 0 && a.type !== null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onlyworlds/sdk",
3
- "version": "4.108.1",
3
+ "version": "4.110.0",
4
4
  "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
5
5
  "type": "module",
6
6
  "exports": {