@entreprenoid/analytics 0.1.0

package/dist/serve/twin.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The markdown twin: the decision, as a pure function.
+ *
+ * ── Why the decision is separated from the serving ───────────────────────────
+ * Two adapters have to make the identical choice, and the choice is the part
+ * with consequences -- serve the wrong thing and a human gets a text file
+ * instead of a website. One function, one set of tests, two thin call sites.
+ */
+export interface Twin {
+    body: string;
+    /** Defaults to `text/markdown; charset=utf-8`. */
+    contentType?: string;
+    etag?: string;
+    lastModified?: string;
+}
+export interface TwinOptions {
+    /**
+     * Find the twin for a normalised path, or return null.
+     *
+     * ⚠️ **Registered, not derived.** Returning a twin for any path that "looks
+     * like" it should have one produces a site where every URL answers, including
+     * the typos -- caprail.dev returns a plain 404 for an unregistered `.md`, and
+     * that is the behaviour to match.
+     */
+    resolve: (path: string) => Twin | null | undefined | Promise<Twin | null | undefined>;
+    /** `Cache-Control` for a served twin. Edge-cacheable by default. */
+    cacheControl?: string;
+    /** Advertise an available twin on the HTML response. Default true. */
+    advertise?: boolean;
+    /**
+     * Serve `/llms.txt`, `/llms-full.txt` and `/install.md` from the same
+     * manifest that serves the twins.
+     *
+     * ⚠️ Derived, not written: a hand-maintained index is wrong the first time a
+     * page is added, and an index listing pages that no longer exist is worse
+     * than none -- an agent spends its budget on 404s and concludes the site is
+     * broken.
+     */
+    discovery?: import("./discovery.js").DiscoveryOptions;
+}
+/** Paths the discovery block answers, when it is configured. */
+export declare const DISCOVERY_PATHS: readonly ["/llms.txt", "/llms-full.txt", "/install.md"];
+export declare const DEFAULT_TWIN_CONTENT_TYPE = "text/markdown; charset=utf-8";
+export declare const DEFAULT_TWIN_CACHE_CONTROL = "public, max-age=3600, s-maxage=86400";
+export type TwinDecision = 
+/** Serve the twin for `lookupPath`. */
+{
+    action: "serve";
+    lookupPath: string;
+    reason: "md_path" | "accept_header";
+}
+/** Not ours to answer, but a twin may exist worth advertising. */
+ | {
+    action: "pass";
+    reason: "not_get" | "no_signal";
+};
+/**
+ * Map a request onto a decision. Nothing here touches I/O.
+ *
+ * Two gates, and only two:
+ *   1. the path ends in `.md`  -- a distinct resource, no negotiation at all;
+ *   2. `Accept` explicitly prefers markdown -- content negotiation, which owes
+ *      a `Vary: Accept`.
+ *
+ * ⚠️ Never the User-Agent. See `accept.ts`.
+ */
+export declare function decideTwin(input: {
+    method: string;
+    path: string;
+    accept: string | null | undefined;
+}): TwinDecision;
+/**
+ * `/docs/intro.md` -> `/docs/intro`, and `/index.md` -> `/`.
+ *
+ * The root is the case worth naming: a site's home page has no slug, so its
+ * twin is `/index.md` by convention -- the same convention caprail.dev uses.
+ */
+export declare function stripMdSuffix(path: string): string;
+/** `/docs/intro` -> `/docs/intro.md`, and `/` -> `/index.md`. */
+export declare function twinPathFor(path: string): string;
+export interface TwinResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export declare function buildTwinResponse(twin: Twin, decision: Extract<TwinDecision, {
+    action: "serve";
+}>, options: TwinOptions): TwinResponse;
+/**
+ * The advertisement for an available twin, as a `Link` header.
+ *
+ * ⚠️ **A header, not a tag injected into the HTML.** Caprail puts
+ * `<link rel="alternate">` in its own document head, which it can do because it
+ * owns the template. A middleware cannot: injecting into the body means
+ * buffering and rewriting somebody else's response, which is precisely what
+ * this package refuses to do. RFC 8288 makes the header the equivalent, it
+ * costs nothing, and it works for JSON and plain text as well as HTML.
+ *
+ * A customer who also wants the tag can add it to their own template, and
+ * should -- some crawlers read one and not the other.
+ */
+export declare function advertiseHeader(path: string): string;