@koona/kpin 0.0.0-stage → 0.1.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/src/address.js ADDED
@@ -0,0 +1,180 @@
1
+ // Addresses as the spec's Addresses and Repeats sections take them: links, feeds, web addresses,
2
+ // the refused feed hosts and the repeat key. Parsed with the WHATWG URL parser.
3
+ import { trimWhiteSpace } from "./text.js";
4
+
5
+ /** Any address: at most 2,048 bytes in UTF-8, as the file writes it (trimmed). */
6
+ export const URL_BYTES = 2048;
7
+
8
+ const encoder = new TextEncoder();
9
+ /** The length of a text in UTF-8. */
10
+ export const utf8Length = (text) => encoder.encode(text).length;
11
+
12
+ const WHITE_SPACE_OR_CONTROL = /[\p{White_Space}\p{Cc}]/u;
13
+
14
+ /** A WHATWG URL, or `null` for text that does not parse. Shared with the one-click link. */
15
+ export function parse(text) {
16
+ try {
17
+ return new URL(text);
18
+ } catch {
19
+ return null;
20
+ }
21
+ }
22
+
23
+ /** ASCII letters lowercased, nothing else: `K` becomes `k`, U+212A KELVIN SIGN stays. */
24
+ export const asciiLower = (text) => text.replace(/[A-Z]+/g, (s) => s.toLowerCase());
25
+
26
+ const isWeb = (url) => url.protocol === "http:" || url.protocol === "https:";
27
+
28
+ /** Drops a user name and password from an address; `true` when there were any. */
29
+ function withoutCredentials(url) {
30
+ if (url.username === "" && url.password === "") return false;
31
+ url.username = "";
32
+ url.password = "";
33
+ return true;
34
+ }
35
+
36
+ /**
37
+ * A link's address as it is kept, or why the link is skipped. Kept exactly as written (trimmed),
38
+ * unless it had credentials removed or holds white space or controls: then in its parsed form.
39
+ * @param {string} raw
40
+ * @returns {{ url: string } | { skip: "invalid" | "not_web" }}
41
+ */
42
+ export function linkUrl(raw) {
43
+ const href = trimWhiteSpace(raw);
44
+ if (utf8Length(href) > URL_BYTES) return { skip: "invalid" };
45
+ const url = parse(href);
46
+ if (!url) return { skip: "invalid" };
47
+ if (!isWeb(url)) return { skip: "not_web" };
48
+ if (url.hostname === "") return { skip: "invalid" };
49
+ if (withoutCredentials(url) || WHITE_SPACE_OR_CONTROL.test(href)) return { url: url.href };
50
+ return { url: href };
51
+ }
52
+
53
+ /**
54
+ * A feed's address in its parsed form, or why the feed is skipped: as a link, and one on this
55
+ * computer or the local network is invalid.
56
+ * @param {string} raw
57
+ * @returns {{ url: string } | { skip: "invalid" | "not_web" }}
58
+ */
59
+ export function feedUrl(raw) {
60
+ const href = trimWhiteSpace(raw);
61
+ if (utf8Length(href) > URL_BYTES) return { skip: "invalid" };
62
+ const url = parse(href);
63
+ if (!url) return { skip: "invalid" };
64
+ if (!isWeb(url)) return { skip: "not_web" };
65
+ if (!publicHost(url.hostname)) return { skip: "invalid" };
66
+ withoutCredentials(url);
67
+ return { url: url.href };
68
+ }
69
+
70
+ /**
71
+ * A web address (`homepage`, `author.url`, a feed's `site`): the link rule, or `null` when the
72
+ * field is dropped.
73
+ * @param {unknown} raw
74
+ * @returns {string | null}
75
+ */
76
+ export function webAddress(raw) {
77
+ if (typeof raw !== "string") return null;
78
+ const taken = linkUrl(raw);
79
+ return "url" in taken ? taken.url : null;
80
+ }
81
+
82
+ /**
83
+ * Whether a feed may be on this host, as a WHATWG parser writes it (`hostname`): not `localhost`,
84
+ * `*.localhost` or `*.local`, and not an IPv4 or IPv6 address of this computer or a local network.
85
+ * @param {string} hostname
86
+ */
87
+ export function publicHost(hostname) {
88
+ if (hostname === "") return false;
89
+ if (hostname.startsWith("[")) {
90
+ const segments = ipv6(hostname.slice(1, -1));
91
+ return segments !== null && publicV6(segments);
92
+ }
93
+ const v4 = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(hostname);
94
+ if (v4) return publicV4(v4.slice(1).map(Number));
95
+ const name = asciiLower(hostname.replace(/\.+$/, ""));
96
+ return !(name === "localhost" || name.endsWith(".localhost") || name.endsWith(".local"));
97
+ }
98
+
99
+ function publicV4([a, b, c]) {
100
+ return !(
101
+ a === 0 || // "this network"
102
+ a === 10 || // private
103
+ a === 127 || // loopback
104
+ (a === 100 && b >= 64 && b < 128) || // shared address space
105
+ (a === 169 && b === 254) || // link-local
106
+ (a === 172 && b >= 16 && b < 32) || // private
107
+ (a === 192 && b === 168) || // private
108
+ (a === 192 && b === 0 && c === 0) || // IETF protocol assignments
109
+ (a === 198 && b >= 18 && b < 20) || // benchmarking
110
+ a >= 224 // multicast, reserved, broadcast
111
+ );
112
+ }
113
+
114
+ /** The eight 16-bit segments of an IPv6 address as a WHATWG parser writes it (hex, `::`). */
115
+ function ipv6(text) {
116
+ const halves = text.split("::");
117
+ if (halves.length > 2) return null;
118
+ const groups = (part) => (part === "" ? [] : part.split(":").map((g) => parseInt(g, 16)));
119
+ const head = groups(halves[0]);
120
+ const tail = halves.length === 2 ? groups(halves[1]) : [];
121
+ const fill = 8 - head.length - tail.length;
122
+ if (fill < 0 || (halves.length === 1 && fill !== 0)) return null;
123
+ const segments = [...head, ...Array(fill).fill(0), ...tail];
124
+ return segments.some((s) => !(s >= 0 && s <= 0xffff)) ? null : segments;
125
+ }
126
+
127
+ function publicV6(s) {
128
+ const v4Of = (hi, lo) => [hi >> 8, hi & 0xff, lo >> 8, lo & 0xff];
129
+ const zeros = (n) => s.slice(0, n).every((x) => x === 0);
130
+ // An IPv4 address carried in IPv6 is judged as IPv4: mapped, or the NAT64 well-known prefix.
131
+ if (zeros(5) && s[5] === 0xffff) return publicV4(v4Of(s[6], s[7]));
132
+ if (s[0] === 0x64 && s[1] === 0xff9b && s.slice(2, 6).every((x) => x === 0)) return publicV4(v4Of(s[6], s[7]));
133
+ return !(
134
+ zeros(6) || // ::, ::1 and the deprecated IPv4-compatible ::a.b.c.d
135
+ (s[0] & 0xfe00) === 0xfc00 || // unique local fc00::/7
136
+ (s[0] & 0xffc0) === 0xfe80 || // link-local fe80::/10
137
+ (s[0] & 0xffc0) === 0xfec0 || // old site-local fec0::/10
138
+ (s[0] & 0xff00) === 0xff00 // multicast
139
+ );
140
+ }
141
+
142
+ const TRACKING = new Set(["fbclid", "gclid", "dclid", "gbraid", "wbraid", "msclkid", "yclid", "mc_eid", "mc_cid", "igshid"]);
143
+ const isTracking = (name) => {
144
+ const lower = asciiLower(name);
145
+ return lower.startsWith("utm_") || TRACKING.has(lower);
146
+ };
147
+
148
+ /** Compares two texts by code point, as UTF-8 bytes compare (not by UTF-16 unit). */
149
+ function byCodePoint(a, b) {
150
+ let i = 0;
151
+ while (i < a.length && i < b.length) {
152
+ const x = a.codePointAt(i);
153
+ const y = b.codePointAt(i);
154
+ if (x !== y) return x - y;
155
+ i += x > 0xffff ? 2 : 1;
156
+ }
157
+ return i < a.length ? 1 : i < b.length ? -1 : 0;
158
+ }
159
+
160
+ /**
161
+ * The repeat key of an address: what does not change the page set aside (`http` or `https`, one
162
+ * leading `www.`, the case of the host, a default port, every trailing slash, the fragment,
163
+ * tracking parameters, the order of the other parameters). Two links of one file are the same page
164
+ * when their keys are equal. `null` for an address that is not http(s). How the key is written is
165
+ * this reader's own business: compare keys, do not store them as a format.
166
+ * @param {string} raw
167
+ * @returns {string | null}
168
+ */
169
+ export function repeatKey(raw) {
170
+ const url = parse(trimWhiteSpace(raw));
171
+ if (!url || !isWeb(url) || url.hostname === "") return null;
172
+ const host = url.hostname.toLowerCase();
173
+ const name = host.startsWith("www.") ? host.slice(4) : host;
174
+ const port = url.port === "" ? "" : `:${url.port}`;
175
+ const path = url.pathname.replace(/\/+$/, "");
176
+ const pairs = [...url.searchParams].filter(([key]) => !isTracking(key));
177
+ pairs.sort((p, q) => byCodePoint(p[0], q[0]) || byCodePoint(p[1], q[1]));
178
+ const query = pairs.length === 0 ? "" : `?${new URLSearchParams(pairs).toString()}`;
179
+ return `${name}${port}${path}${query}`;
180
+ }
package/src/index.d.ts ADDED
@@ -0,0 +1,153 @@
1
+ // Types of the reference reader of the `.kpin` list format 1.x (reader rules of revision 2026-11).
2
+
3
+ /** The one answer a reader gives for a file. */
4
+ export type AnswerName = "ready" | "not_a_list" | "needs_newer_app" | "other_app" | "too_big" | "empty";
5
+
6
+ /** A file that is a list: what was read out of it. */
7
+ export interface Ready {
8
+ answer: "ready";
9
+ list: List;
10
+ }
11
+ /** A list for another Koona app, named by its `app`. */
12
+ export interface OtherApp {
13
+ answer: "other_app";
14
+ app: string;
15
+ /** Why, in a few words, for a person. Not part of the format: do not match on it. */
16
+ why: string;
17
+ }
18
+ /** Any other refusal. */
19
+ export interface Refused {
20
+ answer: "not_a_list" | "needs_newer_app" | "too_big" | "empty";
21
+ /** Why, in a few words, for a person. Not part of the format: do not match on it. */
22
+ why: string;
23
+ }
24
+ export type Answer = Ready | OtherApp | Refused;
25
+
26
+ /** What a reader reads out of a list, as the conformance suite's `list` names it. */
27
+ export interface List {
28
+ /** The list's title, cleaned and cut to 120 characters. */
29
+ title: string;
30
+ /** `"MAJOR.MINOR"` as the file writes it. */
31
+ version: string;
32
+ /** The file's MINOR is newer than 1.0: unknown fields were counted and skipped. */
33
+ newer: boolean;
34
+ /** How many sections have a name. */
35
+ sections: number;
36
+ meta: Meta;
37
+ counts: Counts;
38
+ /** In the file's order: each entry of `sections` in order, then the top-level items. */
39
+ links: Link[];
40
+ feeds: Feed[];
41
+ /** Every item and detail skipped, and why, in the file's order. Not tested by the suite. */
42
+ skipped: Skip[];
43
+ }
44
+
45
+ export interface Meta {
46
+ description: string | null;
47
+ /** `null` when neither the name nor the address is valid. */
48
+ author: { name: string | null; url: string | null } | null;
49
+ license: string | null;
50
+ language: string | null;
51
+ updated: string | null;
52
+ homepage: string | null;
53
+ id: string | null;
54
+ generator: string | null;
55
+ }
56
+
57
+ export interface Counts {
58
+ links: number;
59
+ feeds: number;
60
+ /** Links and feeds whose page came earlier in the file, in one count. */
61
+ repeated: number;
62
+ not_web: number;
63
+ invalid: number;
64
+ /** Items of an unknown type, or not objects. */
65
+ skipped_items: number;
66
+ /** Unknown fields, counted only in a newer MINOR. */
67
+ skipped_details: number;
68
+ }
69
+
70
+ export interface Link {
71
+ /** As kept: as written, or the parsed form (see the spec's Addresses). */
72
+ url: string;
73
+ title: string | null;
74
+ description: string | null;
75
+ /** Lowercased and cleaned, at most 20, with the tags of its repeats. */
76
+ tags: string[];
77
+ /** The names of the sections it is in, its first one first. */
78
+ sections: string[];
79
+ }
80
+
81
+ export interface Feed {
82
+ /** In its parsed form. */
83
+ url: string;
84
+ title: string | null;
85
+ site: string | null;
86
+ section: string | null;
87
+ }
88
+
89
+ export interface Skip {
90
+ /** Where in the file: `items[3]`, `sections[0].items[1]`, `author`, or `""` for the list itself. */
91
+ at: string;
92
+ reason: "repeated" | "not_web" | "invalid" | "unknown_type" | "not_an_object" | "unknown_field";
93
+ /** The address, for a link or feed skipped for it. */
94
+ url?: string;
95
+ /** The unknown item's `type`, when it is a string. */
96
+ type?: string;
97
+ /** The unknown field's name. */
98
+ field?: string;
99
+ }
100
+
101
+ /** Reads a `.kpin` file: its text, or its bytes as they came (bytes that are not UTF-8 are not a list). */
102
+ export function read(input: string | Uint8Array | ArrayBuffer | SharedArrayBuffer | ArrayBufferView): Answer;
103
+
104
+ /** A one-line field (titles, names, `author.name`, `license`, `generator`) cleaned and cut to `max` characters; `null` when nothing is left. */
105
+ export function line(raw: string, max: number): string | null;
106
+ /** A description cleaned, its line breaks kept, and cut to `max` characters (2,000 by default); `null` when nothing is left. */
107
+ export function description(raw: string, max?: number): string | null;
108
+ /** A tag: lowercased, one line, at most 64 characters; `null` when nothing is left. */
109
+ export function tag(raw: string): string | null;
110
+ /** The text without the invisible characters that are not seen (the flags and the joiners that stay are kept). */
111
+ export function withoutInvisible(raw: string): string;
112
+ /** Whether one character (a code point) is on the spec's list of invisible characters. */
113
+ export function isInvisible(c: string): boolean;
114
+ /** Whether a joiner (U+200D) or non-joiner (U+200C) stays between `before` and `after`. */
115
+ export function joinerStays(joiner: string, before: string | undefined, after: string | undefined): boolean;
116
+ /** Unicode White_Space trimmed off both ends. */
117
+ export function trimWhiteSpace(text: string): string;
118
+
119
+ export type Taken = { url: string } | { skip: "invalid" | "not_web" };
120
+ /** A link's address as kept, or why the link is skipped. */
121
+ export function linkUrl(raw: string): Taken;
122
+ /** A feed's address in its parsed form, or why the feed is skipped. */
123
+ export function feedUrl(raw: string): Taken;
124
+ /** A web address (`homepage`, `author.url`, a feed's `site`), or `null` when the field is dropped. */
125
+ export function webAddress(raw: unknown): string | null;
126
+ /** Whether a feed may be on this host (a WHATWG `hostname`). */
127
+ export function publicHost(hostname: string): boolean;
128
+ /** The repeat key of an address: equal keys are the same page. `null` for an address that is not http(s). */
129
+ export function repeatKey(raw: string): string | null;
130
+ /** The list address a `koonapin://import?url=…` link offers to download, or `null` when it is ignored. */
131
+ export function oneClick(link: string): string | null;
132
+
133
+ export const MAX_BYTES: number;
134
+ /** Arrays and objects nest at most 127 levels deep, the file's object being the first. */
135
+ export const MAX_DEPTH: number;
136
+ export const MAX_ITEMS: number;
137
+ export const MAX_SECTIONS: number;
138
+ export const TAGS_PER_LINK: number;
139
+ export const READER_MAJOR: number;
140
+ export const READER_MINOR: number;
141
+ export const TITLE_LEN: number;
142
+ export const ITEM_TITLE_LEN: number;
143
+ export const DESCRIPTION_LEN: number;
144
+ export const TAG_LEN: number;
145
+ export const LICENSE_LEN: number;
146
+ export const GENERATOR_LEN: number;
147
+ export const URL_BYTES: number;
148
+ export const LINK_BYTES: number;
149
+ export const JOINING_SCRIPTS: readonly string[];
150
+ /** The revision of the reader rules this reader follows: `"2026-11"`. */
151
+ export const REVISION: string;
152
+ /** The version of the format whose fields this reader knows: `"1.0"`. */
153
+ export const SPEC: string;
package/src/index.js ADDED
@@ -0,0 +1,10 @@
1
+ // The reference reader of the `.kpin` list format 1.x, reader rules of revision 2026-11.
2
+ export { read, MAX_DEPTH, MAX_BYTES, MAX_ITEMS, MAX_SECTIONS, TAGS_PER_LINK, READER_MAJOR, READER_MINOR } from "./read.js";
3
+ export { line, description, tag, withoutInvisible, isInvisible, joinerStays, trimWhiteSpace, JOINING_SCRIPTS, TITLE_LEN, ITEM_TITLE_LEN, DESCRIPTION_LEN, TAG_LEN, LICENSE_LEN, GENERATOR_LEN } from "./text.js";
4
+ export { linkUrl, feedUrl, webAddress, publicHost, repeatKey, URL_BYTES } from "./address.js";
5
+ export { oneClick, LINK_BYTES } from "./one-click.js";
6
+
7
+ /** The revision of the reader rules this reader follows. */
8
+ export const REVISION = "2026-11";
9
+ /** The version of the format whose fields this reader knows. */
10
+ export const SPEC = "1.0";
@@ -0,0 +1,29 @@
1
+ // The one-click link of the spec: `koonapin://import?url=…`.
2
+ import { trimWhiteSpace } from "./text.js";
3
+ import { utf8Length, parse, asciiLower } from "./address.js";
4
+
5
+ /** The whole link, trimmed, is at most 4,096 bytes in UTF-8. */
6
+ export const LINK_BYTES = 4096;
7
+
8
+ /**
9
+ * The list's address a `koonapin://import?url=…` link offers to download, in its parsed form, or
10
+ * `null` when the link is ignored. Only the address is read: nothing is downloaded, and an app
11
+ * still asks the person first.
12
+ * @param {string} link
13
+ * @returns {string | null}
14
+ */
15
+ export function oneClick(link) {
16
+ const text = trimWhiteSpace(link);
17
+ if (text === "" || utf8Length(text) > LINK_BYTES) return null;
18
+ if (asciiLower(text.slice(0, 9)) !== "koonapin:") return null;
19
+ const url = parse(text);
20
+ if (!url || url.protocol !== "koonapin:" || asciiLower(url.hostname) !== "import") return null;
21
+ // `import` alone: no user name, password or port, no path but `/`, no fragment (even an empty one).
22
+ if (url.username !== "" || url.password !== "" || url.port !== "") return null;
23
+ if ((url.pathname !== "" && url.pathname !== "/") || url.href.includes("#")) return null;
24
+ const values = url.searchParams.getAll("url");
25
+ if (values.length !== 1) return null;
26
+ const target = parse(trimWhiteSpace(values[0]));
27
+ const fine = target && target.protocol === "https:" && target.hostname !== "" && target.username === "" && target.password === "";
28
+ return fine ? target.href : null;
29
+ }