@onlyworlds/sdk 4.102.5 → 4.104.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 +1 -1
- package/CHANGELOG.md +22 -0
- package/SCHEMA.md +1 -1
- package/dist/index.d.ts +23 -7
- package/dist/index.js +77 -12
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# For AI agents using @onlyworlds/sdk
|
|
2
2
|
|
|
3
|
-
**Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.
|
|
3
|
+
**Current as of**: SDK **4.x** · schema-dist **v0.33.0-dist.89** (canonical 00.33.00).
|
|
4
4
|
This line is asserted by `codegen:check` in CI — if the pin moves and this file is not
|
|
5
5
|
re-read against it, the check fails rather than letting this document rot quietly.
|
|
6
6
|
|
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,28 @@ earlier history lives in git log only.
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [4.104.0] - 2026-10-29
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **Sign in with OnlyWorlds from a native app** (RFC 8252). A tool registered as native lists a loopback return without a port (`http://127.0.0.1/<path>` or `http://[::1]/<path>`) or its own scheme (`obsidian://onlyworlds-signin`). `signInWithOnlyWorlds` now takes, beside an `https:` address, the loopback address with the port the app bound for this sign-in (`http://127.0.0.1:53682/onlyworlds-signin`, 1 to 65535, written plainly), which the server matches against the portless one, and a custom scheme exactly as registered (lower-case, not `http`, `https`, `javascript`, `data` or `file`, something after `://`). It refuses `localhost`, a loopback without its port, and on any form userinfo, a query, a fragment and a dot segment (and an `https:` address with an upper-case host or no path, which it took before), with a TypeError naming the forms it takes: the server would refuse each of them at authorize. Whether the tool is registered as native is the server's to check; the SDK does not read the client list. A native app opens the authorize URL in the system browser through `navigate`, and passes the address its loopback server or scheme handler received to `completeSignIn` as `url`.
|
|
13
|
+
|
|
14
|
+
### Fixed
|
|
15
|
+
|
|
16
|
+
- **`completeSignIn` compares the return address exactly**: its scheme, its host with the port, and its path. It compared `URL.origin`, which is `"null"` for every scheme that is not special, so a page at `evil://onlyworlds-signin` would have matched a sign-in begun for `obsidian://onlyworlds-signin` (out of reach until now, since only `https:` could be begun). A trailing slash is still tolerated on `https:`, where a static host may answer `/callback` by sending the browser to `/callback/`; on a loopback or custom-scheme address it is not.
|
|
17
|
+
- **`completeSignIn` cleans the address bar only when it read the address from `location`.** With `url` given, the window's history is left alone: a native app's callback address is not the address of the window it runs in.
|
|
18
|
+
|
|
19
|
+
## [4.103.0] - 2026-10-29
|
|
20
|
+
|
|
21
|
+
### Changed
|
|
22
|
+
|
|
23
|
+
- **Schema repinned to schema-dist `v0.33.0-dist.89`** (from dist.88; the same canonical 00.33.00, so `ONLYWORLDS_VERSION` stays `'00.33.00'` and no type, field or constant moved). The calendar profile's fixture goes from 64 cases to 75 (209 steps, 41 values a reader must refuse) and the message profile's from 85 to 87; every case passes.
|
|
24
|
+
- **`readCalendarConfig` refuses more values, as the calendar profile now rules**, and `readCalendarValue`, `worldCalendars` and `resolveCalendar` follow (no calendar: show bare numbers):
|
|
25
|
+
- a `grain` with nothing left after trimming the room profile's White_Space set (`" "`, a tab, U+3000), where 4.102.5 refused only `""`. The trim is White_Space exactly, never JavaScript's `trim()`: a grain of U+FEFF still reads. `validateCalendarConfig` says `Grain is required` for the same values;
|
|
26
|
+
- an intercalary day whose `after_month` names a month the year does not have: past the last month (`after_month: 5` on a year of two months, which 4.102.5 read as a day in no month), below the first (`-1`), or any intercalary day on a calendar with no months. `after_month: 0` (before the first month) still reads, but only on a calendar that has months. With no months, `after_month` names a place between months and there are none, so even `after_month: 0` refuses there: this follows a ruling of the calendar profile that its fixture will carry later (serial 89's fixture refuses only an `after_month` above 0 there). An empty `intercalary` list still reads, and `validateCalendarConfig` already said `Festival days need months` for these values.
|
|
27
|
+
- **A `format` or `format_intercalary` that is not a string is ignored** and the default template prints. In 4.102.5 `formatStep` threw a TypeError on one.
|
|
28
|
+
- The calendar fixture's new case with a world's elements replays through `worldCalendars`: a calendar is found by the `atlas_calendar` field being present, never by type or supertype. The message fixture's two new cases, a `created_at` with an offset and a fraction of a second read as an instant, and the newest Note listed last, already passed: the message readers read times that way and keep the newest Note wherever it stands.
|
|
29
|
+
|
|
8
30
|
## [4.102.5] - 2026-10-29
|
|
9
31
|
|
|
10
32
|
### Fixed
|
package/SCHEMA.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# OnlyWorlds Schema Reference
|
|
2
2
|
|
|
3
|
-
**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.33.0-dist.
|
|
3
|
+
**Source**: https://github.com/OnlyWorlds/schema-dist @ **v0.33.0-dist.89** — canonical schema **00.33.00**, published 2026-10-29.
|
|
4
4
|
|
|
5
5
|
GENERATED from the canonical schema YAML — do not hand-edit (regenerate: `python codegen/generate_types.py`).
|
|
6
6
|
Written for both humans and AI agents reading this package locally.
|
package/dist/index.d.ts
CHANGED
|
@@ -3865,7 +3865,14 @@ interface OwSignInStorage {
|
|
|
3865
3865
|
interface OwSignInBegin {
|
|
3866
3866
|
/** The `client_id` keel's registry lists the tool under (`GET /api/v2/auth/clients`). */
|
|
3867
3867
|
clientId: string;
|
|
3868
|
-
/**
|
|
3868
|
+
/**
|
|
3869
|
+
* The registered return address, the exact string; never built from `location.origin`. A web tool's
|
|
3870
|
+
* is `https:`. A tool registered as a native app may also use a loopback address, registered without
|
|
3871
|
+
* a port (`http://127.0.0.1/<path>` or `http://[::1]/<path>`) and passed here with the port the app
|
|
3872
|
+
* bound for this sign-in (`http://127.0.0.1:53682/<path>`, 1 to 65535), or its own scheme, exactly as
|
|
3873
|
+
* registered (`obsidian://onlyworlds-signin`). `localhost`, a loopback without its port, userinfo, a
|
|
3874
|
+
* query and a fragment are refused.
|
|
3875
|
+
*/
|
|
3869
3876
|
redirectUri: string;
|
|
3870
3877
|
/** Small JSON the tool wants back after the redirect (an open link, a pending join code). */
|
|
3871
3878
|
resume?: unknown;
|
|
@@ -3882,7 +3889,11 @@ interface OwSignInBegun {
|
|
|
3882
3889
|
interface OwSignInComplete {
|
|
3883
3890
|
clientId: string;
|
|
3884
3891
|
storage?: OwSignInStorage;
|
|
3885
|
-
/**
|
|
3892
|
+
/**
|
|
3893
|
+
* The callback page's address; defaults to `location.href`, which is then cleaned of `code` and
|
|
3894
|
+
* `state`. A native app passes the address its loopback server or scheme handler received, and
|
|
3895
|
+
* the window's history is left alone.
|
|
3896
|
+
*/
|
|
3886
3897
|
url?: string;
|
|
3887
3898
|
}
|
|
3888
3899
|
/** What `completeSignIn` returns: the account token, shown only here, and what the tool parked. */
|
|
@@ -4702,15 +4713,20 @@ declare class OwV2Client {
|
|
|
4702
4713
|
* Start Sign in with OnlyWorlds from a tool's page: mint `state` and a PKCE verifier, keep them
|
|
4703
4714
|
* under `clientId` in `storage` (sessionStorage by default; in Node pass one), and send the
|
|
4704
4715
|
* browser to `https://www.onlyworlds.com/signin/authorize` (or only return the URL with
|
|
4705
|
-
* `navigate: false`). `redirectUri` is the registered return address as a string,
|
|
4706
|
-
*
|
|
4707
|
-
*
|
|
4708
|
-
*
|
|
4716
|
+
* `navigate: false`). `redirectUri` is the registered return address as a string, never built
|
|
4717
|
+
* from `location.origin`: a tool's registration is read at `GET /api/v2/auth/clients`. A web
|
|
4718
|
+
* tool's is `https:`; a tool registered as native may pass a loopback address with the port it
|
|
4719
|
+
* bound for this sign-in (`http://127.0.0.1:<port>/<path>` or `http://[::1]:<port>/<path>`,
|
|
4720
|
+
* registered without the port) or its own scheme as registered (`obsidian://onlyworlds-signin`),
|
|
4721
|
+
* and opens the URL in the system browser with `navigate`. `resume` is small JSON handed back by
|
|
4722
|
+
* `completeSignIn`. No request is sent; any client, keyless included.
|
|
4709
4723
|
*/
|
|
4710
4724
|
signInWithOnlyWorlds(opts: OwSignInBegin): Promise<OwSignInBegun>;
|
|
4711
4725
|
/**
|
|
4712
4726
|
* Finish Sign in with OnlyWorlds on the callback page: check `state` against the record and the
|
|
4713
|
-
* page against the registered address,
|
|
4727
|
+
* page against the registered address (scheme, host with port, and path, each exactly), take
|
|
4728
|
+
* `code` and `state` out of the address bar (only when `url` is not given: a native app passes
|
|
4729
|
+
* the address its loopback server or scheme handler received), trade
|
|
4714
4730
|
* the code once at `POST /auth/token` with the PKCE verifier and no credential, and return the
|
|
4715
4731
|
* `ow_a_` token with the account and `resume`. The record is cleared on success and on refusal;
|
|
4716
4732
|
* the SDK keeps no token: the tool does. Refusals are `OwSignInError`: `state_mismatch` (no
|
package/dist/index.js
CHANGED
|
@@ -501,11 +501,63 @@ function randomToken(bytes) {
|
|
|
501
501
|
function sitePage(baseUrl, path) {
|
|
502
502
|
return `${new URL(baseUrl).origin}${path}`;
|
|
503
503
|
}
|
|
504
|
+
var LOOPBACK_HOSTS = ["127.0.0.1", "[::1]"];
|
|
505
|
+
var REFUSED_SCHEMES = ["http", "https", "javascript", "data", "file"];
|
|
506
|
+
var SCHEME = /^[a-z][a-z0-9+.-]*$/;
|
|
507
|
+
var PORT = /^[1-9][0-9]{0,4}$/;
|
|
508
|
+
function pathProblem(path) {
|
|
509
|
+
const segments = path.split("/");
|
|
510
|
+
if (segments.includes(".") || segments.includes("..")) return "carries a dot segment";
|
|
511
|
+
return null;
|
|
512
|
+
}
|
|
513
|
+
function redirectProblem(uri) {
|
|
514
|
+
if (typeof uri !== "string" || uri === "") return "is not a string";
|
|
515
|
+
for (let i = 0; i < uri.length; i++) {
|
|
516
|
+
const c = uri.charCodeAt(i);
|
|
517
|
+
if (c < 33 || c > 126) return "carries whitespace or a character outside printable ASCII";
|
|
518
|
+
}
|
|
519
|
+
if (uri.includes("*")) return "carries a wildcard: a return address is exact";
|
|
520
|
+
if (uri.includes("#")) return "carries a fragment";
|
|
521
|
+
if (uri.includes("?")) return "carries a query: the code and state are the only query";
|
|
522
|
+
const sep = uri.indexOf("://");
|
|
523
|
+
if (sep < 0) return "is not <scheme>://<path>";
|
|
524
|
+
const scheme = uri.slice(0, sep);
|
|
525
|
+
const rest = uri.slice(sep + 3);
|
|
526
|
+
const slash = rest.indexOf("/");
|
|
527
|
+
const netloc = slash < 0 ? rest : rest.slice(0, slash);
|
|
528
|
+
const path = slash < 0 ? "" : rest.slice(slash);
|
|
529
|
+
if (scheme === "https") {
|
|
530
|
+
if (netloc.includes("@")) return "carries userinfo";
|
|
531
|
+
const host = netloc.split(":")[0];
|
|
532
|
+
if (host === "" || host.includes("[")) return "has no plain host";
|
|
533
|
+
if (host !== host.toLowerCase()) return "has an upper-case host";
|
|
534
|
+
if (path === "") return "has no path";
|
|
535
|
+
return pathProblem(path);
|
|
536
|
+
}
|
|
537
|
+
if (scheme === "http") {
|
|
538
|
+
if (netloc.includes("@")) return "carries userinfo";
|
|
539
|
+
if (netloc.split(":")[0].toLowerCase() === "localhost") return "names localhost: a loopback return is the literal 127.0.0.1 or [::1]";
|
|
540
|
+
if (LOOPBACK_HOSTS.includes(netloc)) return "names no port: a loopback return carries the port the app bound";
|
|
541
|
+
const host = LOOPBACK_HOSTS.find((h) => netloc.startsWith(h + ":"));
|
|
542
|
+
if (host === void 0) return "is http on a host that is not a loopback literal (127.0.0.1 or [::1])";
|
|
543
|
+
const port = netloc.slice(host.length + 1);
|
|
544
|
+
if (!PORT.test(port) || Number(port) > 65535) return "carries a port that is not a whole number from 1 to 65535, written plainly";
|
|
545
|
+
if (path === "") return "has no path";
|
|
546
|
+
return pathProblem(path);
|
|
547
|
+
}
|
|
548
|
+
if (scheme !== scheme.toLowerCase()) return "has an upper-case scheme: a custom scheme is lower-case";
|
|
549
|
+
if (!SCHEME.test(scheme)) return "has a scheme of characters a scheme may not hold";
|
|
550
|
+
if (REFUSED_SCHEMES.includes(scheme)) return "uses a scheme a return address may never use";
|
|
551
|
+
if (rest === "") return "has no path after the scheme";
|
|
552
|
+
if (rest.includes("@")) return "carries userinfo";
|
|
553
|
+
return pathProblem(rest);
|
|
554
|
+
}
|
|
504
555
|
async function beginSignIn(baseUrl, opts) {
|
|
505
556
|
const { clientId, redirectUri, resume = null } = opts ?? {};
|
|
506
557
|
if (typeof clientId !== "string" || clientId === "") throw new TypeError("signInWithOnlyWorlds needs clientId");
|
|
507
|
-
|
|
508
|
-
|
|
558
|
+
const why = redirectProblem(redirectUri);
|
|
559
|
+
if (why !== null) {
|
|
560
|
+
throw new TypeError(`signInWithOnlyWorlds: redirectUri ${why}. Pass the registered return address as a string: https://<host>/<path>, or for a native app http://127.0.0.1:<port>/<path> or http://[::1]:<port>/<path> with the port it bound, or its own scheme, <scheme>://<path>`);
|
|
509
561
|
}
|
|
510
562
|
const storage = opts.storage ?? defaultStorage("signInWithOnlyWorlds");
|
|
511
563
|
const state = randomToken(32);
|
|
@@ -528,7 +580,9 @@ async function beginSignIn(baseUrl, opts) {
|
|
|
528
580
|
function samePage(a, b) {
|
|
529
581
|
try {
|
|
530
582
|
const x = new URL(a), y = new URL(b);
|
|
531
|
-
|
|
583
|
+
if (x.protocol !== y.protocol || x.host !== y.host) return false;
|
|
584
|
+
if (x.protocol === "https:") return x.pathname.replace(/\/$/, "") === y.pathname.replace(/\/$/, "");
|
|
585
|
+
return x.pathname === y.pathname;
|
|
532
586
|
} catch {
|
|
533
587
|
return false;
|
|
534
588
|
}
|
|
@@ -542,7 +596,7 @@ async function completeSignIn(baseUrl, fetchImpl, opts) {
|
|
|
542
596
|
const page = new URL(here);
|
|
543
597
|
const code = page.searchParams.get("code");
|
|
544
598
|
const state = page.searchParams.get("state");
|
|
545
|
-
const hist = globalThis.history;
|
|
599
|
+
const hist = opts.url === void 0 ? globalThis.history : void 0;
|
|
546
600
|
if (hist && typeof hist.replaceState === "function" && (page.searchParams.has("code") || page.searchParams.has("state"))) {
|
|
547
601
|
const clean = new URL(here);
|
|
548
602
|
clean.searchParams.delete("code");
|
|
@@ -1868,10 +1922,13 @@ var OwV2Client = class {
|
|
|
1868
1922
|
* Start Sign in with OnlyWorlds from a tool's page: mint `state` and a PKCE verifier, keep them
|
|
1869
1923
|
* under `clientId` in `storage` (sessionStorage by default; in Node pass one), and send the
|
|
1870
1924
|
* browser to `https://www.onlyworlds.com/signin/authorize` (or only return the URL with
|
|
1871
|
-
* `navigate: false`). `redirectUri` is the registered return address as a string,
|
|
1872
|
-
*
|
|
1873
|
-
*
|
|
1874
|
-
*
|
|
1925
|
+
* `navigate: false`). `redirectUri` is the registered return address as a string, never built
|
|
1926
|
+
* from `location.origin`: a tool's registration is read at `GET /api/v2/auth/clients`. A web
|
|
1927
|
+
* tool's is `https:`; a tool registered as native may pass a loopback address with the port it
|
|
1928
|
+
* bound for this sign-in (`http://127.0.0.1:<port>/<path>` or `http://[::1]:<port>/<path>`,
|
|
1929
|
+
* registered without the port) or its own scheme as registered (`obsidian://onlyworlds-signin`),
|
|
1930
|
+
* and opens the URL in the system browser with `navigate`. `resume` is small JSON handed back by
|
|
1931
|
+
* `completeSignIn`. No request is sent; any client, keyless included.
|
|
1875
1932
|
*/
|
|
1876
1933
|
async signInWithOnlyWorlds(opts) {
|
|
1877
1934
|
only("signInWithOnlyWorlds", opts, ["clientId", "redirectUri", "resume", "storage", "navigate"]);
|
|
@@ -1879,7 +1936,9 @@ var OwV2Client = class {
|
|
|
1879
1936
|
}
|
|
1880
1937
|
/**
|
|
1881
1938
|
* Finish Sign in with OnlyWorlds on the callback page: check `state` against the record and the
|
|
1882
|
-
* page against the registered address,
|
|
1939
|
+
* page against the registered address (scheme, host with port, and path, each exactly), take
|
|
1940
|
+
* `code` and `state` out of the address bar (only when `url` is not given: a native app passes
|
|
1941
|
+
* the address its loopback server or scheme handler received), trade
|
|
1883
1942
|
* the code once at `POST /auth/token` with the PKCE verifier and no credential, and return the
|
|
1884
1943
|
* `ow_a_` token with the account and `resume`. The record is cleared on success and on refusal;
|
|
1885
1944
|
* the SDK keeps no token: the tool does. Refusals are `OwSignInError`: `state_mismatch` (no
|
|
@@ -6029,10 +6088,13 @@ function floorDiv2(a, b) {
|
|
|
6029
6088
|
function floorMod(a, b) {
|
|
6030
6089
|
return (a % b + b) % b;
|
|
6031
6090
|
}
|
|
6091
|
+
function hasGrain(grain) {
|
|
6092
|
+
return typeof grain === "string" && trimWhiteSpace(grain) !== "";
|
|
6093
|
+
}
|
|
6032
6094
|
function validateCalendarConfig(cfg) {
|
|
6033
6095
|
const errors = [];
|
|
6034
6096
|
if (cfg.version !== 1 && cfg.version !== 2) errors.push(`Unsupported calendar version: ${cfg.version}`);
|
|
6035
|
-
if (!cfg.grain
|
|
6097
|
+
if (!hasGrain(cfg.grain)) errors.push("Grain is required");
|
|
6036
6098
|
const months = cfg.bundles?.months;
|
|
6037
6099
|
if (months) {
|
|
6038
6100
|
if (!Array.isArray(months.names) || !Array.isArray(months.lengths) || months.names.length === 0 || months.names.length !== months.lengths.length) {
|
|
@@ -6094,7 +6156,7 @@ function validateCalendarConfig(cfg) {
|
|
|
6094
6156
|
function readCalendarConfig(value) {
|
|
6095
6157
|
if (typeof value !== "object" || value === null) return null;
|
|
6096
6158
|
const cfg = value;
|
|
6097
|
-
if (cfg.version !== 1 && cfg.version !== 2 ||
|
|
6159
|
+
if (cfg.version !== 1 && cfg.version !== 2 || !hasGrain(cfg.grain)) return null;
|
|
6098
6160
|
const months = cfg.bundles?.months;
|
|
6099
6161
|
if (months && (!Array.isArray(months.names) || !Array.isArray(months.lengths) || months.names.length !== months.lengths.length || months.names.length === 0 || !months.names.every(isString))) return null;
|
|
6100
6162
|
if (cfg.eras != null && !Array.isArray(cfg.eras)) return null;
|
|
@@ -6107,6 +6169,9 @@ function readCalendarConfig(value) {
|
|
|
6107
6169
|
if (week != null && (!isPositiveInt(week.length) || !Array.isArray(week.names) || !week.names.every(isString))) return null;
|
|
6108
6170
|
if (cfg.intercalary?.some((i) => i.every_years != null && !isPositiveInt(i.every_years))) return null;
|
|
6109
6171
|
if (cfg.version === 2 && cfg.intercalary?.some((i) => leapRuleProblem(i) != null)) return null;
|
|
6172
|
+
if (!months && cfg.intercalary != null && cfg.intercalary.length > 0) return null;
|
|
6173
|
+
const monthCount = months ? months.names.length : 0;
|
|
6174
|
+
if (cfg.intercalary?.some((i) => i.after_month < 0 || i.after_month > monthCount)) return null;
|
|
6110
6175
|
return cfg;
|
|
6111
6176
|
}
|
|
6112
6177
|
function leapRuleProblem(ic) {
|
|
@@ -6334,7 +6399,7 @@ function formatStep(cfg, step) {
|
|
|
6334
6399
|
step: String(step),
|
|
6335
6400
|
intercalary: b.intercalary
|
|
6336
6401
|
};
|
|
6337
|
-
const template = b.intercalary != null ? cfg.format_intercalary
|
|
6402
|
+
const template = b.intercalary != null ? typeof cfg.format_intercalary === "string" ? cfg.format_intercalary : DEFAULT_FORMAT_INTERCALARY : typeof cfg.format === "string" ? cfg.format : cfg.bundles?.months ? DEFAULT_FORMAT_MONTHS : DEFAULT_FORMAT_PLAIN;
|
|
6338
6403
|
return renderTemplate(template, values);
|
|
6339
6404
|
}
|
|
6340
6405
|
function formatYearLabel(cfg, step) {
|