@sealkeeper/schema 0.4.8 → 0.4.9

package/dist/blocks.d.ts

@@ -0,0 +1,21 @@
+export declare const BLOCK: {
+    readonly gapMinutes: 15;
+    readonly maxTasks: 50;
+    readonly latest: 10;
+    readonly confirmers: 3;
+};
+export declare const BLOCK_TITLE_BANDS: readonly [{
+    readonly fromHour: 5;
+    readonly title: 'Morning block';
+}, {
+    readonly fromHour: 12;
+    readonly title: 'Afternoon block';
+}, {
+    readonly fromHour: 18;
+    readonly title: 'Evening block';
+}, {
+    readonly fromHour: 23;
+    readonly title: 'Overnight block';
+}];
+export type BlockTitle = (typeof BLOCK_TITLE_BANDS)[number]['title'];
+export declare function blockTitle(startedAt: Date | string): BlockTitle;

package/dist/blocks.js

@@ -0,0 +1,43 @@
+/*
+ * Blocks (D-UI-9, VOU-550). A block is a run of verified tasks by one
+ * agent in one category, close together in time. The API writes it as a
+ * task verifies (apps/api/src/blocks.ts), and every time on it is a
+ * server time, the tasks' verified_at.
+ *
+ * A verified task joins the agent's latest block when that block is of
+ * the task's category, ended under gapMinutes before the task verified
+ * and holds fewer than maxTasks tasks. Otherwise it starts a new block. So
+ * a change of category ends a block, and so does the cap. latest is how
+ * many blocks GET /v1/blocks/latest returns, for the home page.
+ * confirmers is how many posters of its tasks a block keeps (VOU-583),
+ * the first to have a task of theirs join it, for its confirmed by line.
+ */
+export const BLOCK = {
+    gapMinutes: 15,
+    maxTasks: 50,
+    latest: 10,
+    confirmers: 3,
+};
+/*
+ * The title of a block, worked out from its start by the UTC time of day,
+ * so a block has one title for every visitor and in every link preview.
+ * Each band runs from its hour to the next band's. No text from the agent,
+ * and not stored, so a changed band needs no migration.
+ */
+export const BLOCK_TITLE_BANDS = [
+    { fromHour: 5, title: 'Morning block' },
+    { fromHour: 12, title: 'Afternoon block' },
+    { fromHour: 18, title: 'Evening block' },
+    { fromHour: 23, title: 'Overnight block' },
+];
+// The title of a block that started at startedAt. Before the first band's
+// hour it is still the night before, so overnight.
+export function blockTitle(startedAt) {
+    const hour = new Date(startedAt).getUTCHours();
+    let title = 'Overnight block';
+    for (const band of BLOCK_TITLE_BANDS) {
+        if (hour >= band.fromHour)
+            title = band.title;
+    }
+    return title;
+}

package/dist/cli-version.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export declare const CLI_VERSION_HEADER = "X-SealKeeper-CLI-Version";
+export declare const CLI_VERSION_MAX = 32;
+export declare const NO_CLI_VERSION = "none";
+export declare const CliVersion: z.ZodString;
+export type CliVersion = z.infer<typeof CliVersion>;
+export declare function compareCliVersions(a: string, b: string): number;

package/dist/cli-version.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+// Which CLI signed a request (VOU-454). The CLI sends its own version in
+// this header on every signed request, and the API keeps one row per agent
+// and version with the first and last UTC day it was seen, so it can tell
+// when no CLI older than SEAL_V3_FIRST_CLI is left. Defined once here so
+// the CLI and the API name the header and read its value the same way.
+//
+// The header is not signed, so the version is only what the caller says it
+// is. It measures a rollout, and no trust decision ever reads it.
+export const CLI_VERSION_HEADER = 'X-SealKeeper-CLI-Version';
+// The most characters a CLI version may have. Room for a prerelease tag,
+// and small, so a header can never grow a stored row.
+export const CLI_VERSION_MAX = 32;
+// What the API stores for a signed request with no valid version, a CLI
+// from before the header or a value CliVersion refuses. A version starts
+// with a digit, so this word can never be one.
+export const NO_CLI_VERSION = 'none';
+// A version as npm writes it, the semver.org grammar. Three numbers, an
+// optional prerelease after a hyphen and optional build metadata after a
+// plus. No number has a leading zero. Each of the three has at most 9
+// digits, so it stays exact as a JavaScript number.
+const NUM = '(?:0|[1-9]\\d{0,8})';
+const PRE = '(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)';
+const BUILD = '[0-9A-Za-z-]+';
+const VERSION = new RegExp(`^(${NUM})\\.(${NUM})\\.(${NUM})(?:-(${PRE}(?:\\.${PRE})*))?(?:\\+${BUILD}(?:\\.${BUILD})*)?$`);
+// The header's value. Anything else, an empty or over long value or one
+// with a space or a control character, fails, and the API then treats the
+// request as one with no header.
+export const CliVersion = z
+    .string()
+    .max(CLI_VERSION_MAX)
+    .regex(VERSION, 'Expected a version such as 0.4.14');
+function partsOf(version) {
+    const m = VERSION.exec(version);
+    if (!m)
+        throw new TypeError('Not a CLI version');
+    return {
+        core: [Number(m[1]), Number(m[2]), Number(m[3])],
+        pre: m[4] === undefined ? [] : m[4].split('.'),
+    };
+}
+const DIGITS = /^\d+$/;
+// Two prerelease identifiers. Numbers compare as numbers and come before
+// words, words compare in ASCII order. A number has no leading zero, so the
+// longer one is the larger.
+function compareIdentifiers(a, b) {
+    const an = DIGITS.test(a);
+    const bn = DIGITS.test(b);
+    if (an !== bn)
+        return an ? -1 : 1;
+    if (an && a.length !== b.length)
+        return a.length < b.length ? -1 : 1;
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+/*
+ * -1, 0 or 1 as version a comes before, with or after version b, by the
+ * semver.org precedence rules. The three numbers compare as numbers, so
+ * 0.4.9 comes before 0.4.11, which a text comparison gets wrong. A
+ * prerelease comes before its release, 0.4.11-rc.1 before 0.4.11, and
+ * build metadata is ignored. Both must be CliVersion values. Anything else,
+ * NO_CLI_VERSION included, throws a TypeError, so the caller decides what a
+ * missing version means.
+ */
+export function compareCliVersions(a, b) {
+    const x = partsOf(a);
+    const y = partsOf(b);
+    for (let i = 0; i < 3; i++) {
+        const d = x.core[i] - y.core[i];
+        if (d !== 0)
+            return Math.sign(d);
+    }
+    if (x.pre.length === 0 || y.pre.length === 0) {
+        return Math.sign(y.pre.length) - Math.sign(x.pre.length);
+    }
+    for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+        const p = x.pre[i];
+        const q = y.pre[i];
+        if (p === undefined)
+            return -1;
+        if (q === undefined)
+            return 1;
+        const d = compareIdentifiers(p, q);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}