@crombolo/common 0.0.0-stage → 0.37.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kineco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,69 @@
+crombolo
+Copyright (c) 2026 Kineco
+
+This product includes third-party software. crombolo is an independent project.
+It is not affiliated with, endorsed by, or sponsored by Umbraco A/S, which owns
+the Umbraco trademark.
+
+There are three places third-party material is redistributed, rather than merely
+depended on:
+
+  @crombolo/backoffice-dist   the built Umbraco backoffice and the browser
+                              packages bundled into it, produced by
+                              `bun run vendor:backoffice`
+  @crombolo/backoffice-dist   three CSS files copied unmodified from the Umbraco
+                              client source tree
+  @crombolo/contracts         the Umbraco Management API OpenAPI document,
+                              copied unmodified
+
+No Umbraco trademark is redistributed. The Umbraco wordmark, the "U" roundel
+favicon and the installer illustration are deliberately not carried in this
+repository: MIT grants copyright permission and says nothing about trademarks, so
+crombolo's own marks are served at those paths instead. See `BRANDED_ASSETS` in
+`@crombolo/backoffice-host`.
+
+The Umbraco backoffice
+----------------------
+@umbraco-cms/backoffice 18.2.0 — MIT — https://github.com/umbraco/Umbraco-CMS
+@umbraco-ui/uui 2.0.2 — MIT — https://github.com/umbraco/Umbraco.UI
+
+Static files from the Umbraco client source tree
+------------------------------------------------
+css/umb-css.css, css/rte-content.css, css/umbraco-blockgridlayout.css
+  — copied unmodified from Umbraco-CMS release-18.2.0 — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/backoffice-dist under `upstream-static/`.
+
+`rte-content.css` itself carries Tiptap's default editor styles, copied from
+tiptap v2.11.7 (MIT); the file records this in its own header.
+
+The Umbraco Management API contract
+-----------------------------------
+OpenApi.json — copied unmodified from Umbraco-CMS release-18.2.0
+  (src/Umbraco.Cms.Api.Management/OpenApi.json) — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/contracts, which also ships the TypeScript types generated
+from it.
+
+Browser runtime dependencies bundled into the backoffice build
+--------------------------------------------------------------
+@heximal/expressions 0.1.5 — BSD-3-Clause
+@microsoft/signalr 10.0.11 — MIT
+@tiptap/* 3.31.3 — MIT
+diff 9.0.0 — BSD-3-Clause
+dompurify 3.4.16 — Apache-2.0, elected from "MPL-2.0 OR Apache-2.0"
+element-internals-polyfill 3.0.2 — MIT
+lit 3.3.3 — BSD-3-Clause
+luxon 3.7.2 — MIT
+marked 18.0.14 — MIT
+monaco-editor 0.57.0 — MIT
+rxjs 7.8.2 — Apache-2.0
+uuid 14.0.2 — MIT
+
+dompurify is offered under either licence; Apache-2.0 is elected here, so no
+MPL-2.0 obligation attaches to the copy bundled into the backoffice build. Of the
+Apache-2.0 packages above, none ships a NOTICE file of its own, so Apache-2.0
+section 4(d) adds nothing to this file.
+
+Each package's own licence text ships inside its npm distribution and applies
+unchanged to the copies bundled here.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './middleware.ts';
+export * from './result.ts';
+export * from './routes.ts';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './middleware.js';
+export * from './result.js';
+export * from './routes.js';

package/dist/middleware.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The middleware chain's contract (story 210): what a site's own code, an npm
+ * package or a server bundle implements to be inserted into a site's chain.
+ * Plain web `Request` and `Response`, with crombolo's extras in `context`.
+ * docs/rendering.md, "Middleware".
+ */
+/** The request's cookies, read-only. Reading them marks the answer personal. */
+export interface ReadonlyRequestCookies extends Iterable<[string, RequestCookie]> {
+    get(name: string): RequestCookie | undefined;
+    getAll(name?: string): RequestCookie[];
+    has(name: string): boolean;
+    readonly size: number;
+}
+export interface RequestCookie {
+    name: string;
+    value: string;
+}
+/** Where in a site's handling a middleware runs. */
+export type MiddlewareStage = 'request' | 'route' | 'page';
+/** What crombolo gives a middleware besides the request. */
+export interface MiddlewareContext<Site = unknown, Page = unknown, Member = unknown> {
+    /** The request's address, parsed. */
+    url: URL;
+    /** The request's cookies; reading them makes the answer `private, no-store`. */
+    cookies: ReadonlyRequestCookies;
+    /** The site's services acting as the visitor (story 206). */
+    site(): Site;
+    /** The page found, in the `route` and `page` stages. */
+    page?: Page;
+    /** The signed-in member, in the `page` stage. */
+    member?: Member;
+    /** An editor is previewing a draft. */
+    preview: boolean;
+    /** Aborts when the chain's time limit runs out, or the visitor leaves. */
+    signal: AbortSignal;
+    /** The stage this middleware is running in. */
+    stage: MiddlewareStage;
+}
+/**
+ * One link in the chain. Answer outright by not calling `next`; change the
+ * request with `next(changed)`; change the answer by returning `next()`'s
+ * `Response` altered.
+ */
+export type MiddlewareHandler<Site = unknown, Page = unknown, Member = unknown> = (request: Request, next: (request?: Request) => Promise<Response>, context: MiddlewareContext<Site, Page, Member>) => Response | Promise<Response>;
+/** A condition on a header, cookie or query value, as Next.js's matcher takes. */
+export interface MatcherCondition {
+    type: 'header' | 'cookie' | 'query';
+    key: string;
+    /** A regular expression the value must match; any value when left out. */
+    value?: string;
+}
+/** A path pattern in Next.js's matcher syntax, with optional conditions. */
+export type Matcher = string | {
+    source: string;
+    has?: MatcherCondition[];
+    missing?: MatcherCondition[];
+};
+/** A middleware: a handler, or one with a name for logs and the paths it runs for. */
+export type Middleware<Site = unknown, Page = unknown, Member = unknown> = MiddlewareHandler<Site, Page, Member> | {
+    /** For logs and errors: `security-headers`, `region-redirect`. */
+    name: string;
+    /** The paths it runs for; every site path when left out. */
+    matcher?: Matcher | Matcher[];
+    handle: MiddlewareHandler<Site, Page, Member>;
+};
+/** A site's chain, by stage, each run in the order listed. */
+export interface MiddlewareChain<Site = unknown, Page = unknown, Member = unknown> {
+    /** First, before the redirect tables and content finding. */
+    request?: Middleware<Site, Page, Member>[];
+    /** After content finding, with `context.page`; a rewrite is resolved again. */
+    route?: Middleware<Site, Page, Member>[];
+    /** After public access, with `context.page` and `context.member`; no rewrites. */
+    page?: Middleware<Site, Page, Member>[];
+}
+/**
+ * The request for another path on this site, rendered at the address the
+ * visitor asked for. `path` may carry its own query; without one the
+ * request's query carries over.
+ */
+export declare function rewrite(request: Request, path: string): Request;
+/** A `Set-Cookie`'s attributes. */
+export interface CookieOptions {
+    path?: string;
+    maxAge?: number;
+    expires?: Date;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/** The response with a cookie set on it; `Max-Age=0` and an empty value delete one. */
+export declare function withCookie(response: Response, name: string, value: string, options?: CookieOptions): Response;

package/dist/middleware.js

@@ -0,0 +1,44 @@
+/**
+ * The middleware chain's contract (story 210): what a site's own code, an npm
+ * package or a server bundle implements to be inserted into a site's chain.
+ * Plain web `Request` and `Response`, with crombolo's extras in `context`.
+ * docs/rendering.md, "Middleware".
+ */
+/**
+ * The request for another path on this site, rendered at the address the
+ * visitor asked for. `path` may carry its own query; without one the
+ * request's query carries over.
+ */
+export function rewrite(request, path) {
+    if (!path.startsWith('/') || path.startsWith('//'))
+        throw new Error(`A rewrite goes to a path on this site, such as /about, not '${path}'.`);
+    const from = new URL(request.url);
+    const to = new URL(path, from);
+    if (!path.includes('?'))
+        to.search = from.search;
+    return new Request(to, request);
+}
+/** The response with a cookie set on it; `Max-Age=0` and an empty value delete one. */
+export function withCookie(response, name, value, options = {}) {
+    if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name))
+        throw new Error(`'${name}' is not a cookie name.`);
+    const parts = [`${name}=${encodeURIComponent(value)}`, `Path=${options.path ?? '/'}`];
+    if (options.maxAge !== undefined)
+        parts.push(`Max-Age=${Math.floor(options.maxAge)}`);
+    if (options.expires)
+        parts.push(`Expires=${options.expires.toUTCString()}`);
+    if (options.domain)
+        parts.push(`Domain=${options.domain}`);
+    if (options.secure ?? true)
+        parts.push('Secure');
+    if (options.httpOnly ?? true)
+        parts.push('HttpOnly');
+    parts.push(`SameSite=${options.sameSite ?? 'Lax'}`);
+    const headers = new Headers(response.headers);
+    headers.append('set-cookie', parts.join('; '));
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}

package/dist/result.d.ts

@@ -0,0 +1,136 @@
+/**
+ * A value, or the HTTP outcome a page answers instead (story 206; in
+ * `@crombolo/common` since story 210, so apps and packages share it).
+ *
+ * The site's own services return a `Result` so data code composes and its
+ * failures are typed. A component ends the chain with `unwrap()`, which returns
+ * the value or throws the outcome for the renderer to answer.
+ * docs/rendering.md, "Server code".
+ */
+/** A redirect a page may answer with. */
+export type RedirectStatus = 301 | 302 | 303 | 307 | 308;
+/** A refusal a page may answer with, rendered by the site's status pages. */
+export type RefusalStatus = 400 | 401 | 403 | 404 | 410 | 422;
+export type OutcomeStatus = RedirectStatus | RefusalStatus;
+/** One input that failed validation. */
+export interface FieldError {
+    field: string;
+    message: string;
+}
+/** The name each status goes by, as the helper that answers it. */
+export declare const OUTCOME_NAMES: Readonly<Record<OutcomeStatus, string>>;
+declare const BRAND: unique symbol;
+/**
+ * Throws unless a redirect target is safe to put in a `Location` header: a path,
+ * or an `http(s)` address. A protocol-relative address, another scheme such as
+ * `javascript:`, or anything that would break the header is a template error.
+ */
+export declare function assertSafeLocation(url: string): string;
+/** What every result can do, whichever side it is. */
+interface ResultMethods<T, S extends OutcomeStatus> {
+    isOk(): this is Ok<T>;
+    isOutcome(): this is Outcome<S>;
+    map<U>(f: (value: T) => U): Result<U, S>;
+    mapAsync<U>(f: (value: T) => Promise<U>): Promise<Result<U, S>>;
+    andThen<U, S2 extends OutcomeStatus = never>(f: (value: T) => Result<U, S2>): Result<U, S | S2>;
+    andThenAsync<U, S2 extends OutcomeStatus = never>(f: (value: T) => Promise<Result<U, S2>>): Promise<Result<U, S | S2>>;
+    match<R>(handlers: MatchHandlers<T, S, R>): R;
+    /** The value, or throws the outcome for the page to answer. */
+    unwrap(): T;
+    unwrapOr<U>(fallback: U): T | U;
+}
+/**
+ * `match`'s handlers: `ok`, and either one per status the result can hold or
+ * `outcome` for the rest.
+ */
+export type MatchHandlers<T, S extends OutcomeStatus, R> = {
+    ok: (value: T) => R;
+} & (({
+    [K in S]: (outcome: Outcome<K>) => R;
+} & {
+    outcome?: never;
+}) | ({
+    [K in S]?: (outcome: Outcome<K>) => R;
+} & {
+    outcome: (outcome: Outcome<S>) => R;
+}));
+/** A value. */
+export declare class Ok<T> implements ResultMethods<T, never> {
+    readonly value: T;
+    readonly ok: true;
+    constructor(value: T);
+    isOk(): this is Ok<T>;
+    isOutcome(): this is Outcome<never>;
+    map<U>(f: (value: T) => U): Ok<U>;
+    mapAsync<U>(f: (value: T) => Promise<U>): Promise<Ok<U>>;
+    andThen<U, S2 extends OutcomeStatus = never>(f: (value: T) => Result<U, S2>): Result<U, S2>;
+    andThenAsync<U, S2 extends OutcomeStatus = never>(f: (value: T) => Promise<Result<U, S2>>): Promise<Result<U, S2>>;
+    match<R>(handlers: MatchHandlers<T, never, R>): R;
+    unwrap(): T;
+    unwrapOr<U>(_fallback: U): T;
+}
+/**
+ * An HTTP outcome in place of a value: a redirect, or a refusal the site's
+ * status pages render. Built with `Outcome.notFound()` and its siblings; thrown
+ * by `unwrap()` and by `@crombolo/crombolo/navigation`'s functions.
+ */
+export declare class Outcome<S extends OutcomeStatus = OutcomeStatus> implements ResultMethods<never, S> {
+    readonly status: S;
+    readonly ok: false;
+    readonly [BRAND] = true;
+    /** The visitor-facing words for this case, shown by the status page. */
+    readonly message: string | undefined;
+    /** Inputs that failed, for 400 and 422. */
+    readonly errors: readonly FieldError[];
+    /** Where a redirect sends the visitor. */
+    readonly location: string | undefined;
+    private constructor();
+    /** The helper's name for this status: `notFound`, `foundAt`. */
+    get name(): string;
+    get isRedirect(): boolean;
+    isOk(): this is Ok<never>;
+    isOutcome(): this is Outcome<S>;
+    map<U>(_f: (value: never) => U): Outcome<S>;
+    mapAsync<U>(_f: (value: never) => Promise<U>): Promise<Outcome<S>>;
+    andThen<U, S2 extends OutcomeStatus = never>(_f: (value: never) => Result<U, S2>): Outcome<S>;
+    andThenAsync<U, S2 extends OutcomeStatus = never>(_f: (value: never) => Promise<Result<U, S2>>): Promise<Outcome<S>>;
+    match<R>(handlers: MatchHandlers<never, S, R>): R;
+    unwrap(): never;
+    unwrapOr<U>(fallback: U): U;
+    /** 307: the visitor is sent on, keeping the request's method. */
+    static redirect(url: string): Outcome<307>;
+    /** 308: the page has moved for good, keeping the request's method. */
+    static permanentRedirect(url: string): Outcome<308>;
+    /** 302: the everyday redirect, as `umbracoRedirect` answers. */
+    static foundAt(url: string): Outcome<302>;
+    /** 301: the page has moved for good. */
+    static movedPermanentlyTo(url: string): Outcome<301>;
+    /** 303: after a POST, look at this address with a GET. */
+    static seeOther(url: string): Outcome<303>;
+    static badRequest(message?: string, errors?: readonly FieldError[]): Outcome<400>;
+    static unauthorized(message?: string): Outcome<401>;
+    static forbidden(message?: string): Outcome<403>;
+    static notFound(message?: string): Outcome<404>;
+    static gone(message?: string): Outcome<410>;
+    /** 422: well-formed input that failed validation. */
+    static unprocessableContent(errors: readonly FieldError[], message?: string): Outcome<422>;
+}
+export type Result<T, S extends OutcomeStatus = OutcomeStatus> = Ok<T> | Outcome<S>;
+/** A value as a result. */
+export declare function ok<T>(value: T): Ok<T>;
+export declare function isOk<T, S extends OutcomeStatus>(result: Result<T, S>): result is Ok<T>;
+/** Whether a value, or something thrown, is an outcome; true across copies of this module. */
+export declare function isOutcome(value: unknown): value is Outcome;
+type ValuesOf<R extends readonly Result<unknown, OutcomeStatus>[]> = {
+    -readonly [K in keyof R]: R[K] extends Result<infer T, OutcomeStatus> ? T : never;
+};
+type StatusesOf<R extends readonly Result<unknown, OutcomeStatus>[]> = R[number] extends Result<unknown, infer S> ? S : never;
+/** Every value, or the first outcome among them. */
+declare function all<const R extends readonly Result<unknown, OutcomeStatus>[]>(results: R): Result<ValuesOf<R>, StatusesOf<R>>;
+export declare const Result: {
+    ok: typeof ok;
+    all: typeof all;
+    isOk: typeof isOk;
+    isOutcome: typeof isOutcome;
+};
+export {};

package/dist/result.js

@@ -0,0 +1,200 @@
+/**
+ * A value, or the HTTP outcome a page answers instead (story 206; in
+ * `@crombolo/common` since story 210, so apps and packages share it).
+ *
+ * The site's own services return a `Result` so data code composes and its
+ * failures are typed. A component ends the chain with `unwrap()`, which returns
+ * the value or throws the outcome for the renderer to answer.
+ * docs/rendering.md, "Server code".
+ */
+/** The name each status goes by, as the helper that answers it. */
+export const OUTCOME_NAMES = {
+    301: 'movedPermanentlyTo',
+    302: 'foundAt',
+    303: 'seeOther',
+    307: 'redirect',
+    308: 'permanentRedirect',
+    400: 'badRequest',
+    401: 'unauthorized',
+    403: 'forbidden',
+    404: 'notFound',
+    410: 'gone',
+    422: 'unprocessableContent',
+};
+const BRAND = Symbol.for('crombolo.outcome');
+/**
+ * Throws unless a redirect target is safe to put in a `Location` header: a path,
+ * or an `http(s)` address. A protocol-relative address, another scheme such as
+ * `javascript:`, or anything that would break the header is a template error.
+ */
+export function assertSafeLocation(url) {
+    if (typeof url !== 'string' || url.trim() === '')
+        throw new Error('A redirect needs an address to send the visitor to.');
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it refuses.
+    if (/[\u0000-\u001f\u007f]/.test(url))
+        throw new Error(`Refused to redirect to ${JSON.stringify(url)}: it would break the header.`);
+    const trimmed = url.trim();
+    if (/^[/\\]{2}/.test(trimmed) || /^\/\\/.test(trimmed))
+        throw new Error(`Refused to redirect to '${url}': an address starting '//' could lead to any site. Write the scheme, or a path.`);
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed)?.[1]?.toLowerCase();
+    if (scheme && scheme !== 'http' && scheme !== 'https')
+        throw new Error(`Refused to redirect to '${url}': only paths and http(s) addresses are allowed.`);
+    return trimmed;
+}
+/** A value. */
+export class Ok {
+    value;
+    ok = true;
+    constructor(value) {
+        this.value = value;
+    }
+    isOk() {
+        return true;
+    }
+    isOutcome() {
+        return false;
+    }
+    map(f) {
+        return new Ok(f(this.value));
+    }
+    async mapAsync(f) {
+        return new Ok(await f(this.value));
+    }
+    andThen(f) {
+        return f(this.value);
+    }
+    andThenAsync(f) {
+        return f(this.value);
+    }
+    match(handlers) {
+        return handlers.ok(this.value);
+    }
+    unwrap() {
+        return this.value;
+    }
+    unwrapOr(_fallback) {
+        return this.value;
+    }
+}
+/**
+ * An HTTP outcome in place of a value: a redirect, or a refusal the site's
+ * status pages render. Built with `Outcome.notFound()` and its siblings; thrown
+ * by `unwrap()` and by `@crombolo/crombolo/navigation`'s functions.
+ */
+export class Outcome {
+    status;
+    ok = false;
+    [BRAND] = true;
+    /** The visitor-facing words for this case, shown by the status page. */
+    message;
+    /** Inputs that failed, for 400 and 422. */
+    errors;
+    /** Where a redirect sends the visitor. */
+    location;
+    constructor(status, init = {}) {
+        this.status = status;
+        this.message = init.message;
+        this.errors = init.errors ?? [];
+        this.location = init.location;
+    }
+    /** The helper's name for this status: `notFound`, `foundAt`. */
+    get name() {
+        return OUTCOME_NAMES[this.status];
+    }
+    get isRedirect() {
+        return this.status < 400;
+    }
+    isOk() {
+        return false;
+    }
+    isOutcome() {
+        return true;
+    }
+    map(_f) {
+        return this;
+    }
+    async mapAsync(_f) {
+        return this;
+    }
+    andThen(_f) {
+        return this;
+    }
+    async andThenAsync(_f) {
+        return this;
+    }
+    match(handlers) {
+        const own = handlers[this.status];
+        if (own)
+            return own(this);
+        return handlers.outcome(this);
+    }
+    unwrap() {
+        throw this;
+    }
+    unwrapOr(fallback) {
+        return fallback;
+    }
+    /** 307: the visitor is sent on, keeping the request's method. */
+    static redirect(url) {
+        return new Outcome(307, { location: assertSafeLocation(url) });
+    }
+    /** 308: the page has moved for good, keeping the request's method. */
+    static permanentRedirect(url) {
+        return new Outcome(308, { location: assertSafeLocation(url) });
+    }
+    /** 302: the everyday redirect, as `umbracoRedirect` answers. */
+    static foundAt(url) {
+        return new Outcome(302, { location: assertSafeLocation(url) });
+    }
+    /** 301: the page has moved for good. */
+    static movedPermanentlyTo(url) {
+        return new Outcome(301, { location: assertSafeLocation(url) });
+    }
+    /** 303: after a POST, look at this address with a GET. */
+    static seeOther(url) {
+        return new Outcome(303, { location: assertSafeLocation(url) });
+    }
+    static badRequest(message, errors) {
+        return new Outcome(400, { message, errors });
+    }
+    static unauthorized(message) {
+        return new Outcome(401, { message });
+    }
+    static forbidden(message) {
+        return new Outcome(403, { message });
+    }
+    static notFound(message) {
+        return new Outcome(404, { message });
+    }
+    static gone(message) {
+        return new Outcome(410, { message });
+    }
+    /** 422: well-formed input that failed validation. */
+    static unprocessableContent(errors, message) {
+        return new Outcome(422, { message, errors });
+    }
+}
+/** A value as a result. */
+export function ok(value) {
+    return new Ok(value);
+}
+export function isOk(result) {
+    return result instanceof Ok;
+}
+/** Whether a value, or something thrown, is an outcome; true across copies of this module. */
+export function isOutcome(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[BRAND] === true);
+}
+/** Every value, or the first outcome among them. */
+function all(results) {
+    const values = [];
+    for (const result of results) {
+        if (!result.ok)
+            return result;
+        values.push(result.value);
+    }
+    return new Ok(values);
+}
+export const Result = { ok, all, isOk, isOutcome };

package/dist/routes.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The route handler contract (story 211): a site's own endpoints, and a server
+ * bundle's, at the paths they declare. Plain web `Request` and `Response`;
+ * a handler may also return a `Result`, whose value is sent as JSON and whose
+ * outcome answers its status. docs/rendering.md, "Route handlers".
+ */
+import type { CookieOptions, ReadonlyRequestCookies } from './middleware.ts';
+import type { Result } from './result.ts';
+export type RouteMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+/** The methods a route may declare a handler for; `HEAD` comes from `GET` when not given. */
+export declare const ROUTE_METHODS: readonly RouteMethod[];
+/** What a handler is given besides the request. */
+export interface RouteContext<Site = unknown, Member = unknown> {
+    /** The path's `:name` segments. */
+    params: Record<string, string>;
+    url: URL;
+    /** The request's cookies; reading them is fine, the answer is private by default. */
+    cookies: ReadonlyRequestCookies;
+    /** Sets a cookie on the answer. */
+    setCookie(name: string, value: string, options?: CookieOptions): void;
+    /** The site's services acting as the caller (story 206). */
+    site(): Site;
+    /** The signed-in member, by session cookie or bearer token; looked up when asked. */
+    member(): Promise<Member | undefined>;
+    /** Aborts when the route's time limit runs out, or the caller leaves. */
+    signal: AbortSignal;
+}
+/** One method's handler: a `Response`, or a `Result` (a value as JSON, an outcome as its status). */
+export type RouteHandler<Site = unknown, Member = unknown, Extra = unknown> = (request: Request, context: RouteContext<Site, Member> & Extra) => Response | Result<unknown> | Promise<Response | Result<unknown>>;
+/** A route's limits and checks. */
+export interface RouteOptions {
+    /**
+     * A cookie-authenticated `POST`, `PUT`, `PATCH` or `DELETE` must come from a
+     * page of this site, or carry the member's anti-forgery token. On by default;
+     * `false` for a webhook receiver. Bearer-token calls are never checked.
+     */
+    csrf?: boolean;
+    /** Its own limit, in place of the site's default; `false` for none. */
+    rateLimit?: {
+        perMinute: number;
+        by?: 'member' | 'caller';
+    } | false;
+    /**
+     * Answers pages on the Delivery API's allowed origins
+     * (`deliveryApi.cors.allowedOrigins`) with CORS headers, pre-flights included.
+     * Off by default: only this site's own pages may read the answer.
+     */
+    cors?: boolean;
+    /** Only for a signed-in member, or a member of one of these groups: 401 or 403 otherwise. */
+    members?: true | {
+        groups: readonly string[];
+    };
+    /**
+     * Where it answers. `site`, the default, at its path on the site; `backoffice`
+     * only for a bundle, below its back-office namespace, for users holding the
+     * bundle's section.
+     */
+    audience?: 'site' | 'backoffice';
+}
+/** A route as declared: a path, a handler per method, and its options. */
+export interface SiteRoute<Site = unknown, Member = unknown, Extra = unknown> {
+    path: string;
+    handlers: Partial<Record<RouteMethod, RouteHandler<Site, Member, Extra>>>;
+    options: RouteOptions;
+}
+/**
+ * A route: `route('/api/records/:species', { GET: list, POST: add })`. A site
+ * route's path starts with `/`; a bundle's back-office route's is relative to
+ * its namespace.
+ */
+export declare function route<Site = unknown, Member = unknown, Extra = unknown>(path: string, handlers: Partial<Record<RouteMethod, RouteHandler<Site, Member, Extra>>>, options?: RouteOptions): SiteRoute<Site, Member, Extra>;

package/dist/routes.js

@@ -0,0 +1,21 @@
+/** The methods a route may declare a handler for; `HEAD` comes from `GET` when not given. */
+export const ROUTE_METHODS = [
+    'GET',
+    'HEAD',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    'OPTIONS',
+];
+/**
+ * A route: `route('/api/records/:species', { GET: list, POST: add })`. A site
+ * route's path starts with `/`; a bundle's back-office route's is relative to
+ * its namespace.
+ */
+export function route(path, handlers, options = {}) {
+    const unknown = Object.keys(handlers).filter((method) => !ROUTE_METHODS.includes(method));
+    if (unknown.length > 0)
+        throw new Error(`The route ${path} names ${unknown.join(', ')}, which is not an HTTP method it can answer.`);
+    return { path, handlers, options };
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@crombolo/common",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.37.0",
+  "description": "The contracts code outside crombolo is written against: the Result a site's services return, and the middleware chain's contract. No dependencies.",
+  "license": "MIT",
+  "author": "Crombolo",
+  "homepage": "https://github.com/kineco-au/crombolo-cms#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kineco-au/crombolo-cms.git",
+    "directory": "packages/common"
+  },
+  "bugs": {
+    "url": "https://github.com/kineco-au/crombolo-cms/issues"
+  },
+  "keywords": [
+    "crombolo",
+    "result",
+    "middleware"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.