@north-light/api 0.3.422 → 0.3.423

package/dist/api/__tests__/contract.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/__tests__/contract.test.js

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { CONTRACT_LEVEL, contractRefusal, contractSatisfies, parseContractLevel, parseServedContracts } from '../contract.js';
+test('CONTRACT_LEVEL is MAJOR.MINOR with MAJOR equal to the API_VERSION number', async () => {
+    const { API_VERSION } = await import('../routes.js');
+    assert.deepEqual(parseContractLevel(CONTRACT_LEVEL)?.major, Number(API_VERSION.replace(/^v/, '')));
+});
+test('parseContractLevel accepts only MAJOR.MINOR', () => {
+    assert.deepEqual(parseContractLevel('1.3'), { major: 1, minor: 3 });
+    assert.deepEqual(parseContractLevel(' 12.0 '), { major: 12, minor: 0 });
+    for (const bad of ['1', '1.2.3', 'v1.2', '1.x', '', '-1.0', '1.-2'])
+        assert.equal(parseContractLevel(bad), null, bad);
+});
+test('the rule: same major, served minor at or above the required one, compared numerically', () => {
+    assert.equal(contractSatisfies('1.3', '1.3'), true);
+    assert.equal(contractSatisfies('1.3', '1.10'), true);
+    assert.equal(contractSatisfies('1.10', '1.3'), false);
+    assert.equal(contractSatisfies('1.0', '1.0'), true);
+    assert.equal(contractSatisfies('1.3', '2.9'), false);
+    assert.equal(contractSatisfies('2.0', '1.9'), false);
+    assert.equal(contractSatisfies('1.3', '2.0, 1.4'), true);
+    assert.equal(contractSatisfies('1.3', '2.0, 1.2'), false);
+    assert.equal(contractSatisfies('1.3', null), false);
+    assert.equal(contractSatisfies('1.3', ''), false);
+    assert.equal(contractSatisfies('1.3', 'garbage'), false);
+    assert.equal(contractSatisfies('garbage', '1.3'), false);
+});
+test('a malformed served entry is dropped without hiding the rest', () => {
+    assert.deepEqual(parseServedContracts('x, 1.2 ,3'), [{ major: 1, minor: 2 }]);
+    assert.deepEqual(parseServedContracts(null), []);
+});
+test('contractRefusal: absent passes, malformed is 400, unsatisfied is 426 with both levels', () => {
+    assert.equal(contractRefusal(undefined, '1.0'), null);
+    assert.equal(contractRefusal('1.0', '1.0'), null);
+    const bad = contractRefusal('latest', '1.0');
+    assert.equal(bad?.status, 400);
+    assert.equal(bad?.status === 400 ? bad.param : '', 'Crouter-Required-Contract');
+    const refused = contractRefusal('1.4', '1.3', { legacyMinimum: '0.3.500', runtimeVersion: '0.3.600' });
+    assert.equal(refused?.status, 426);
+    assert.equal(refused?.code, 'runtime_version_unsupported');
+    assert.deepEqual(refused?.status === 426 ? refused.details : null, { sdk_version: '0.3.500', runtime_version: '0.3.600', required_contract: '1.4', runtime_contract: '1.3' });
+    const unnamed = contractRefusal('1.0', null);
+    assert.equal(unnamed?.status === 426 ? unnamed.details.runtime_contract : 'x', null);
+});

package/dist/api/contract.d.ts

@@ -0,0 +1,45 @@
+/** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
+export declare const CONTRACT_LEVEL = "1.0";
+/** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
+export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
+/** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */
+export declare const CONTRACT_HEADER = "Crouter-Contract";
+/** A parsed `MAJOR.MINOR` level. */
+export interface ContractLevel {
+    major: number;
+    minor: number;
+}
+/** Parses one `MAJOR.MINOR` level; `null` when it is anything else. */
+export declare function parseContractLevel(value: string): ContractLevel | null;
+/** Parses a `Crouter-Contract` response value into its well-formed levels, dropping anything malformed. */
+export declare function parseServedContracts(header: string | null | undefined): ContractLevel[];
+/** True when `required` (one `MAJOR.MINOR`) is satisfied by `served` (a `Crouter-Contract` value or its parsed levels):
+ *  some served level has the same major and a minor at or above the required one. A malformed `required` is never
+ *  satisfied. */
+export declare function contractSatisfies(required: string, served: string | null | undefined | readonly ContractLevel[]): boolean;
+/** The refusal a server answers instead of handling a request, or `null` when the request may be handled.
+ *  - `required` absent: handled.
+ *  - `required` not `MAJOR.MINOR`: 400 `invalid_request` (`param` is the header).
+ *  - `required` not satisfied by `served`: 426 `runtime_version_unsupported`, details
+ *    `{sdk_version, runtime_version, required_contract, runtime_contract}` (the SDK's `RuntimeVersionDetails`).
+ *    `sdk_version` is the legacy minimum-runtime header value the caller sent (empty when it sent none). */
+export type ContractRefusal = {
+    status: 400;
+    code: 'invalid_request';
+    message: string;
+    param: string;
+} | {
+    status: 426;
+    code: 'runtime_version_unsupported';
+    message: string;
+    details: {
+        sdk_version: string;
+        runtime_version: string | null;
+        required_contract: string;
+        runtime_contract: string | null;
+    };
+};
+export declare function contractRefusal(required: string | undefined, served: string | null, context?: {
+    legacyMinimum?: string | undefined;
+    runtimeVersion?: string | null | undefined;
+}): ContractRefusal | null;

package/dist/api/contract.js

@@ -0,0 +1,57 @@
+// The contract level: the compatibility number an SDK and a runtime agree on (design: SDK ↔ runtime contract gate).
+//
+// A level is `MAJOR.MINOR`. MAJOR is the number in `API_VERSION` (`v1` → 1). MINOR rises only when the `/v1` surface
+// changes in a way `scripts/contract.mjs` can see or a person declared; only that script's `release` mode writes
+// `CONTRACT_LEVEL`, and the SDK package manifest carries the same value as `crouterContract`. Package versions stay
+// lockstep auto-patch numbers and say nothing about compatibility.
+//
+// One rule, used by the runtime, the SDK, FakeCloud and the hosting router: a request requiring `M.n` is satisfied by a
+// server whose served list holds `M.k` with `k >= n`. The server answers `Crouter-Contract` on every HTTP answer as a
+// comma-separated list, one level per major served (today one element); the caller sends exactly one level in
+// `Crouter-Required-Contract`.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+/** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
+export const CONTRACT_LEVEL = '1.0';
+/** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
+export const REQUIRED_CONTRACT_HEADER = 'Crouter-Required-Contract';
+/** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */
+export const CONTRACT_HEADER = 'Crouter-Contract';
+/** Parses one `MAJOR.MINOR` level; `null` when it is anything else. */
+export function parseContractLevel(value) {
+    const match = /^(\d+)\.(\d+)$/.exec(value.trim());
+    return match === null ? null : { major: Number(match[1]), minor: Number(match[2]) };
+}
+/** Parses a `Crouter-Contract` response value into its well-formed levels, dropping anything malformed. */
+export function parseServedContracts(header) {
+    if (header === null || header === undefined)
+        return [];
+    return header.split(',').map((part) => parseContractLevel(part)).filter((level) => level !== null);
+}
+/** True when `required` (one `MAJOR.MINOR`) is satisfied by `served` (a `Crouter-Contract` value or its parsed levels):
+ *  some served level has the same major and a minor at or above the required one. A malformed `required` is never
+ *  satisfied. */
+export function contractSatisfies(required, served) {
+    const need = parseContractLevel(required);
+    if (need === null)
+        return false;
+    const levels = typeof served === 'string' || served === null || served === undefined ? parseServedContracts(served) : served;
+    return levels.some((level) => level.major === need.major && level.minor >= need.minor);
+}
+export function contractRefusal(required, served, context = {}) {
+    if (required === undefined)
+        return null;
+    if (parseContractLevel(required) === null) {
+        return { status: 400, code: 'invalid_request', param: REQUIRED_CONTRACT_HEADER, message: `${REQUIRED_CONTRACT_HEADER} must be a contract level like 1.0.` };
+    }
+    if (contractSatisfies(required, served))
+        return null;
+    const level = required.trim();
+    return {
+        status: 426, code: 'runtime_version_unsupported',
+        message: served === null || parseServedContracts(served).length === 0
+            ? `The runtime did not name its contract level; the caller requires contract ${level} or later. Roll the runtime forward.`
+            : `The runtime serves contract ${served}; the caller requires contract ${level} or later within the same major. Roll the runtime forward, or pin an SDK whose crouterContract the runtime serves.`,
+        details: { sdk_version: (context.legacyMinimum ?? '').trim(), runtime_version: context.runtimeVersion ?? null, required_contract: level, runtime_contract: served },
+    };
+}

package/dist/api/index.d.ts

@@ -7,6 +7,8 @@ export type { ErrorCode, ErrorEnvelope, ErrorOrigin, ErrorType } from './error-c
 export { API_VERSION, routes } from './routes.js';
 export { RUNTIME_VERSION_HEADER, MINIMUM_RUNTIME_VERSION_HEADER, compareReleaseVersions, minimumRuntimeRefusal } from './runtime-version.js';
 export type { MinimumRuntimeRefusal } from './runtime-version.js';
+export { CONTRACT_HEADER, CONTRACT_LEVEL, REQUIRED_CONTRACT_HEADER, contractRefusal, contractSatisfies, parseContractLevel, parseServedContracts } from './contract.js';
+export type { ContractLevel, ContractRefusal } from './contract.js';
 export { LONG_POLL_MAX_WAIT_SECONDS, LONG_POLL_ROUTES, longPollHoldSeconds, longPollRoute, requestedWait } from './long-poll.js';
 export type { LongPollName, LongPollRoute } from './long-poll.js';
 export * from '../shared/generated-context.js';

package/dist/api/index.js

@@ -6,6 +6,7 @@ export { APIError, ApiError, isErrorBody } from './errors.js';
 export { errorCodes } from './error-codes.js';
 export { API_VERSION, routes } from './routes.js';
 export { RUNTIME_VERSION_HEADER, MINIMUM_RUNTIME_VERSION_HEADER, compareReleaseVersions, minimumRuntimeRefusal } from './runtime-version.js';
+export { CONTRACT_HEADER, CONTRACT_LEVEL, REQUIRED_CONTRACT_HEADER, contractRefusal, contractSatisfies, parseContractLevel, parseServedContracts } from './contract.js';
 export { LONG_POLL_MAX_WAIT_SECONDS, LONG_POLL_ROUTES, longPollHoldSeconds, longPollRoute, requestedWait } from './long-poll.js';
 export * from '../shared/generated-context.js';
 export * from './dto/common.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.422",
+  "version": "0.3.423",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",