@elytracms/next 0.0.93 → 0.0.95

package/dist/index.d.ts

@@ -13,6 +13,7 @@ import { Clock } from '@elytracms/core/determinism';
 import { ResolvingMetadata, Metadata, ResolvedMetadata, MetadataRoute } from 'next';
 import { RevalidationEvent } from '@elytracms/core/revalidation';
 export { REVALIDATE_SIGNATURE_HEADER, RevalidationEvent, RevalidationEventKind, revalidationEventSchema, signRevalidationBody, signedRevalidationRequest } from '@elytracms/core/revalidation';
+import { IngestPayload } from '@elytracms/core/ingest';
 import { ImageLoader } from 'next/image';
 import { HostImageRenderer } from './host-image.js';
 export { z } from 'zod';
@@ -226,8 +227,13 @@ interface ContentSource {
      * backend outage. Optional so existing custom sources stay valid; without it,
      * asset-typed props fall back to their raw value (the renderer's visible
      * degradation), never a crash.
+     *
+     * EC-632: resolved in `locale` (absent → the source's default locale) — a localized
+     * asset-collection field (alt, …) carries its value in that locale, with the default
+     * locale as its fallback. The route helper passes the request's locale, so a page bakes
+     * its assets in the locale it renders in.
      */
-    assets?(): readonly ResolvedAsset[];
+    assets?(locale?: Locale): readonly ResolvedAsset[];
 }
 /**
  * Merge accessor cache tags into one deterministic set (sorted, deduplicated)
@@ -306,10 +312,14 @@ interface StaticContentData {
     documents?: readonly ContentDocumentSource[];
     assets?: readonly AssetRecord[];
     /**
-     * Resolve a serve URL for assets without a stored `url`. Defaults to an
-     * explicit unresolved-placeholder scheme (never a silent empty string).
+     * Resolve a serve URL for assets without a stored `url` (`undefined` when there is
+     * none). EC-633: no default — an asset with no URL is no resolved asset (the ONE
+     * constructor, `resolvedAsset`, decides it): it renders the canvas's empty state, its
+     * field resolves to `null` with an `asset-without-url` issue, and this source names it
+     * on `sourceIssues`. The placeholder this used to default to (`asset://unresolved/…`)
+     * rendered a broken image on the site.
      */
-    assetUrl?: (asset: AssetRecord) => string;
+    assetUrl?: (asset: AssetRecord) => string | undefined;
     /**
      * EC-585 — the stored rows the host could not read (`parseDeliveredDocuments`), handed
      * to every client of this source as its `sourceIssues` (and in the results they
@@ -378,6 +388,25 @@ interface CanvasWrapContext extends CanvasRequestInfo {
      */
     result: ResolvePageResult;
 }
+/**
+ * EC-618 — what the route's `analytics` slot is told about the page it renders on: the
+ * resolved document (the content model, not the URL — slug changes and locale paths then
+ * attribute correctly), the locale it rendered in, the request path and the status. Plain
+ * serializable values, so the slot may be a client component.
+ */
+interface CanvasBeaconProps {
+    /** The request path as served (including any locale prefix). */
+    path: string;
+    /** 200: the route renders the slot only on a rendered page (a 404 never reaches it). */
+    status: 200;
+    /** The locale the page rendered in. */
+    locale: string;
+    /** The resolved document's collection and id — absent when the URL resolved to no document. */
+    collection?: string;
+    documentId?: string;
+}
+/** PURE core (EC-618): the slot's props from a render outcome's resolution and the request info. */
+declare function canvasBeaconProps(result: ResolvePageResult, info: CanvasRequestInfo): CanvasBeaconProps;
 type CanvasPageOutcome = {
     kind: 'redirect';
     target: string;
@@ -729,6 +758,21 @@ interface CanvasRouteOptions {
      * the default.
      */
     wrap?: (children: ReactNode, ctx: CanvasWrapContext) => ReactNode;
+    /**
+     * The ANALYTICS slot (EC-618): a component the route renders inside every `render`
+     * outcome, AFTER the page (and outside `wrap`, so a wrapper cannot drop it), with the
+     * resolved document, the locale, the path and the status ({@link CanvasBeaconProps}).
+     * Published perspective only — a draft preview is an editor at work, not a visit.
+     *
+     * The engine supplies the slot and nothing else: its value is the beacon of the
+     * analytics addon, `@elytracms/analytics/next` — **unpublished, pending counsel's
+     * verdict on its consent-free claim** (EC-618) — or a host's own component. Absent, the
+     * route renders exactly what it rendered before, and sends nothing.
+     *
+     * A not-found page never reaches this slot (`notFound()` renders the host's
+     * `not-found.tsx`), so a 404 beacon lives in that file.
+     */
+    analytics?: ComponentType<CanvasBeaconProps>;
 }
 interface CanvasRouteProps {
     params: Promise<{
@@ -1058,6 +1102,177 @@ interface RevalidateRouteHandlers {
  */
 declare function createRevalidateRoute(options: RevalidateRouteOptions): RevalidateRouteHandlers;
 
+/**
+ * EC-617 — the pure decision core of the PUBLIC INGEST route (`createIngestRoute`, the
+ * Next wrapper in `ingest.ts`): no Next imports, no network, an injected clock — the
+ * house "pure core + thin wrapper" shape of `evaluateRevalidateRequest` /
+ * `createRevalidateRoute`.
+ *
+ * The route is a site's one public write path (ruling EC-565 § 6c). It runs, in order:
+ *
+ * 1. **method** — `POST` only (405);
+ * 2. **configured** — the server-held `INGEST_SECRET` and the receiver URL are set (503
+ *    otherwise: the route stays closed until deliberately configured, never a no-op);
+ * 3. **same-origin** — a browser request from another origin (`Origin` / `Sec-Fetch-Site`)
+ *    is refused (403). The route emits no CORS headers and reads no cookie;
+ * 4. **rate limit** — a fixed window per CLIENT KEY (429, `Retry-After`);
+ * 5. **size** — the raw body capped at `maxBodyBytes` (413), checked before parsing;
+ * 6. **shape** — JSON in the ingest envelope (400, with the issues);
+ * 7. **bot gate** — the host's own check, an injected seam (403, `{ gate: 'bot' }`): the
+ *    engine supplies the slot, never the vendor;
+ * 8. **enrichment** (EC-618) — an optional seam an ADDON fills (the analytics addon derives
+ *    a country and a visitor's sketch coordinates here, where the request is): it returns the
+ *    payload to forward, which is re-validated against the envelope and the receiver's cap
+ *    (500 — the site's own fault — when it throws or returns something invalid). Absent, the
+ *    route is exactly what it was;
+ *
+ * then the wrapper signs the payload with the server-held secret and forwards it to the
+ * one Convex receiver, relaying its answer. Only the PAYLOAD is forwarded — never a request
+ * header — so whatever an enrichment reads from the request (the client address, the user
+ * agent, a geo header) stays in this request's memory; only what it derives travels.
+ */
+/** The answer the core gives the wrapper. */
+type IngestEvaluation = {
+    ok: true;
+    payload: IngestPayload;
+} | {
+    ok: false;
+    status: 400 | 403 | 405 | 413 | 429 | 500 | 503;
+    body: Record<string, unknown>;
+    headers?: Record<string, string>;
+};
+/** What the host's bot gate answers (a Turnstile / hCaptcha / honeypot check the HOST implements). */
+type BotGateVerdict = {
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+};
+/**
+ * The bot-gate seam: called with the request and the parsed payload, AFTER the cheap
+ * checks (so a flood never reaches a paid verification API). Absent → no gate.
+ */
+type IngestBotGate = (input: {
+    request: Request;
+    payload: IngestPayload;
+}) => BotGateVerdict | Promise<BotGateVerdict>;
+/**
+ * EC-618 — the enrichment seam: called with the request and the parsed payload LAST (after
+ * the bot gate), it returns the payload the route signs and forwards. The engine supplies
+ * the slot, never the code: an addon fills it (`@elytracms/analytics/next`'s
+ * `analyticsEnrichment`), and a host may compose its own. Whatever it reads from the
+ * request is held for this request only — the route forwards the returned payload and
+ * nothing else. Absent → no enrichment, the payload forwarded as parsed.
+ */
+type IngestEnrich = (input: {
+    request: Request;
+    payload: IngestPayload;
+}) => IngestPayload | Promise<IngestPayload>;
+/**
+ * The fixed-window limiter — the AI route's pattern (EC-602), keyed per client. Holds,
+ * in memory only, one `{ windowStart, count }` per key seen in the current window; expired
+ * windows are dropped as the clock moves, so the map is bounded by the clients of one
+ * window. Each server instance holds its own windows (a serverless platform runs several),
+ * so the limit is per instance — the same documented limitation as the AI route.
+ */
+interface FixedWindowLimiter {
+    /** Count one request for `key`; `retryAfterSeconds` when it is over the limit. */
+    hit(key: string): {
+        allowed: true;
+    } | {
+        allowed: false;
+        retryAfterSeconds: number;
+    };
+    /** How many keys the limiter currently holds (for the bound test). */
+    size(): number;
+}
+declare function createFixedWindowLimiter(options: {
+    limit: number;
+    windowMs?: number;
+    now?: () => number;
+}): FixedWindowLimiter;
+/**
+ * The DEFAULT client key: the first hop of `x-forwarded-for` (what Vercel and most proxies
+ * set), else `x-real-ip`, else one shared `unknown` bucket. An IP address is personal
+ * data: it is held ONLY as a key of the in-memory window above, for at most one window,
+ * and is never stored, logged or forwarded to the receiver. A host that wants a different
+ * key (a hashed one, a session id) passes `clientKey`.
+ */
+declare function defaultIngestClientKey(request: Request): string;
+/** Is this a cross-origin BROWSER request? (A request with no browser headers is not judged here.) */
+declare function isCrossOrigin(request: Request): boolean;
+interface IngestEvaluationInput {
+    request: Request;
+    /** The raw body, read by the wrapper up to `maxBodyBytes + 1` bytes (`undefined` when over). */
+    rawBody: string | undefined;
+    configured: boolean;
+    limiter: FixedWindowLimiter;
+    clientKey: (request: Request) => string;
+    botGate?: IngestBotGate;
+    enrich?: IngestEnrich;
+}
+/** Evaluate one request (see the module header for the order). */
+declare function evaluateIngestRequest(input: IngestEvaluationInput): Promise<IngestEvaluation>;
+/**
+ * Read a request body as text, at most `maxBytes` (counted in UTF-8 bytes). `undefined`
+ * when it is longer — the over-size body is never buffered whole. A declared
+ * `Content-Length` over the cap is refused before a byte is read.
+ */
+declare function readCappedBody(request: Request, maxBytes?: number): Promise<string | undefined>;
+
+/**
+ * EC-617 — the PUBLIC INGEST route: a site's one write path into its project (form
+ * submissions, analytics events, upload URLs), mounted SAME-ORIGIN in the site's own
+ * App Router:
+ *
+ * ```ts
+ * // frontend/app/api/ingest/route.ts — through the delivery kit
+ * export const { POST } = elytra.ingestRoute()
+ * ```
+ *
+ * The decisions are the pure core's (`evaluateIngestRequest`: method, configured,
+ * same-origin, rate limit, size, shape, the host's bot gate); this wrapper then SIGNS the
+ * payload with the server-held `INGEST_SECRET` (it never reaches a browser) and forwards it
+ * to the deployment's ONE receiver (`<deployment>.convex.site/elytra/ingest`), relaying the
+ * receiver's answer. A receiver that rejects the signature is a SITE misconfiguration
+ * (the two secrets differ), answered 502 with that sentence — never a 401 a visitor could
+ * read as their fault.
+ *
+ * Uploads leave same-origin by design: an `upload` payload asks the receiver for ONE
+ * short-lived storage URL (the request rides this route's gate, limiter and bot gate), and
+ * the browser then sends the bytes straight to that URL; the submission that follows claims
+ * the stored file, which is checked against what the upload request declared.
+ */
+interface IngestRouteOptions {
+    /** The server-held HMAC secret (= the deployment's `ELYTRA_INGEST_SECRET`). Unset → 503. */
+    secret: string | undefined;
+    /** The deployment's HTTP origin (`https://<name>.convex.site`); the receiver path is appended. Unset → 503. */
+    siteUrl: string | undefined;
+    /** Cap on the raw JSON body, ≤ the receiver's `INGEST_MAX_BODY_BYTES` (default). */
+    maxBodyBytes?: number;
+    /** Requests per client key per minute (default 30). */
+    maxRequestsPerMinute?: number;
+    /** The rate limiter's key for a request (default: the client IP, in memory only — see `defaultIngestClientKey`). */
+    clientKey?: (request: Request) => string;
+    /** The host's bot check (Turnstile, hCaptcha, a honeypot …). The engine supplies the slot, never the vendor. */
+    botGate?: IngestBotGate;
+    /**
+     * EC-618 — an addon's enrichment, run last: it returns the payload to sign and forward
+     * (the analytics addon adds a country and the visitor's sketch coordinates, derived from
+     * the request here and never forwarded raw). Absent → the payload is forwarded as parsed.
+     */
+    enrich?: IngestEnrich;
+    /** Injected clock (tests). */
+    now?: () => number;
+    /** Injected transport (tests). */
+    fetchImpl?: typeof fetch;
+}
+interface IngestRouteHandlers {
+    POST(request: Request): Promise<Response>;
+}
+/** Create the ingest route handler (see the module header). */
+declare function createIngestRoute(options: IngestRouteOptions): IngestRouteHandlers;
+
 /**
  * Image delivery for the embedded runtime (EC-152).
  *
@@ -1253,6 +1468,8 @@ declare function elytraHostImage(options?: ElytraHostImageOptions): HostImageRen
  * |                       | equal the Convex deployment's own env var)           |
  * | `REVALIDATE_SECRET`   | Instant-publish webhook HMAC secret (must equal the  |
  * |                       | deployment's `CANVAS_REVALIDATE_SECRET`)             |
+ * | `INGEST_SECRET`       | Public-ingest HMAC secret (EC-617; must equal the    |
+ * |                       | deployment's `ELYTRA_INGEST_SECRET`)                 |
  *
  * EC-579 retired `STUDIO_ORIGIN` (the CORS origin of the studio's deleted browser
  * dispatcher): the one emitter is the Convex deployment, server to server.
@@ -1263,12 +1480,14 @@ declare const ELYTRA_HOST_ENV_KEYS: {
     readonly projectId: "ELYTRA_PROJECT_ID";
     readonly draftToken: "DRAFT_PREVIEW_TOKEN";
     readonly revalidateSecret: "REVALIDATE_SECRET";
+    readonly ingestSecret: "INGEST_SECRET";
 };
 interface ElytraHostEnv {
     convexUrl?: string;
     projectId?: string;
     draftToken?: string;
     revalidateSecret?: string;
+    ingestSecret?: string;
 }
 /**
  * Resolve the kit's env bag from a raw env record (`process.env` by default at
@@ -1585,6 +1804,12 @@ interface HostCanvasRouteOptions {
      * invalidation — a disagreement would drop nothing, silently.
      */
     published?: CanvasRouteOptions['published'];
+    /**
+     * EC-618 — the analytics slot (see `CanvasRouteOptions.analytics`): its value is an
+     * addon's beacon (`@elytracms/analytics/next`, unpublished pending counsel). Absent →
+     * nothing renders and nothing is sent.
+     */
+    analytics?: CanvasRouteOptions['analytics'];
 }
 interface LoadGlobalsOptions {
     /** Perspective of the chrome read. Default `'published'` (live is published-only). */
@@ -1705,6 +1930,15 @@ interface ElytraHost<Collections extends readonly CollectionDef[] = readonly Col
     previewRoute(): PreviewRouteHandlers;
     /** The draft-mode DISABLE route (no token — it only reduces visibility). */
     previewDisableRoute(): PreviewRouteHandlers;
+    /**
+     * EC-617 — the PUBLIC INGEST route for `app/api/ingest/route.ts`: the site's one write path
+     * (form submissions, analytics events, upload URLs), signed with `INGEST_SECRET` and
+     * forwarded to this deployment's receiver (its HTTP origin derived from
+     * `ELYTRA_CONVEX_URL`; pass `siteUrl` for a self-hosted backend). Unset secret or no
+     * backend = 503, closed. The rate limit, the client key and the bot gate are the host's to
+     * tune — the engine supplies the slots, never a vendor.
+     */
+    ingestRoute(options?: Partial<Omit<IngestRouteOptions, 'secret'>>): IngestRouteHandlers;
     /**
      * Does the page for this catch-all `slug` OPEN full-bleed? Manifest-driven
      * (`presentation.fullBleed`, EC-368) and draft-mode aware — the host lays out
@@ -1766,6 +2000,12 @@ interface LiveContentOptions {
 interface DeliverySnapshotPayload {
     projectId: string;
     redirects?: unknown[];
+    /**
+     * EC-628 — the stored redirects the deployment withheld because it could not read them
+     * (`invalid-redirect` issues from the one live rule). Absent from a deployment older than
+     * EC-628, which serves such rows in `redirects` instead (and this host names them there).
+     */
+    redirectIssues?: unknown[];
     documents: unknown[];
     assets: unknown[];
 }
@@ -1870,4 +2110,4 @@ declare function evaluatePreviewRequest(requestUrl: string | URL, expectedToken:
  */
 declare const PACKAGE = "@elytracms/next";
 
-export { type AssetImageLoaderOptions, type BakedListing, CANVAS_VALIDATION_SLUG, type CanvasCacheKey, type CanvasContentRequest, type CanvasPageOutcome, CanvasRenderer, type CanvasRendererProps, type CanvasRequestInfo, type CanvasRoute, type CanvasRouteOptions, type CanvasRouteProps, type CanvasSitemapOptions, type CanvasSitemapResult, type CanvasWrapContext, type ContentSnapshot, type ContentSnapshotOptions, type ContentSource, type CreateCanvasSitemapOptions, type DeliveryPresentation, ELYTRA_HOST_ENV_KEYS, type ElytraContentMode, type ElytraHost, type ElytraHostEnv, type ElytraHostImageOptions, type ElytraHostOptions, ElytraImage, type ElytraImageAsset, type ElytraImageProps, type GlobalsConventions, type HostCanvasRouteOptions, type HostComponent, type HostComponents, type LiveContentOptions, type LoadGlobalsOptions, type NextImageOptions, PACKAGE, type PreviewEvaluation, type PreviewRouteHandlers, type PreviewRouteOptions, type ResolveCanvasPageOptions, type ResolveGlobalsOptions, type ResolvedLink, type ResolvedNavEntry, type ResolvedNavLink, type RevalidateEvaluation, type RevalidateRouteHandlers, type RevalidateRouteOptions, type RevalidationProject, type SeoMetadataContext, type SiteGlobals, type SitemapSkippedRoute, type StaticContentData, assembleLiveSource, bodyItemsOf, canvasSitemapEntries, collectionCacheTag, createAssetImageLoader, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defineHostComponents, docCacheTag, elytraHostImage, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, loadLiveContent, mergeCacheTags, mergeMetadataOverParent, nextCacheTags, openGraphLocale, pathFromSlug, projectSweepTag, requestPerspective, resolveCanvasPage, resolveGlobals, resolveHostEnv, revalidationTags, routeCacheTag, safeRedirectTarget, scopeCacheTag, seoContextOf, seoMetadata, seoObjectOf, withNextImage };
+export { type AssetImageLoaderOptions, type BakedListing, type BotGateVerdict, CANVAS_VALIDATION_SLUG, type CanvasBeaconProps, type CanvasCacheKey, type CanvasContentRequest, type CanvasPageOutcome, CanvasRenderer, type CanvasRendererProps, type CanvasRequestInfo, type CanvasRoute, type CanvasRouteOptions, type CanvasRouteProps, type CanvasSitemapOptions, type CanvasSitemapResult, type CanvasWrapContext, type ContentSnapshot, type ContentSnapshotOptions, type ContentSource, type CreateCanvasSitemapOptions, type DeliveryPresentation, ELYTRA_HOST_ENV_KEYS, type ElytraContentMode, type ElytraHost, type ElytraHostEnv, type ElytraHostImageOptions, type ElytraHostOptions, ElytraImage, type ElytraImageAsset, type ElytraImageProps, type FixedWindowLimiter, type GlobalsConventions, type HostCanvasRouteOptions, type HostComponent, type HostComponents, type IngestBotGate, type IngestEnrich, type IngestEvaluation, type IngestRouteHandlers, type IngestRouteOptions, type LiveContentOptions, type LoadGlobalsOptions, type NextImageOptions, PACKAGE, type PreviewEvaluation, type PreviewRouteHandlers, type PreviewRouteOptions, type ResolveCanvasPageOptions, type ResolveGlobalsOptions, type ResolvedLink, type ResolvedNavEntry, type ResolvedNavLink, type RevalidateEvaluation, type RevalidateRouteHandlers, type RevalidateRouteOptions, type RevalidationProject, type SeoMetadataContext, type SiteGlobals, type SitemapSkippedRoute, type StaticContentData, assembleLiveSource, bodyItemsOf, canvasBeaconProps, canvasSitemapEntries, collectionCacheTag, createAssetImageLoader, createCanvasRoute, createCanvasSitemap, createContentSnapshot, createElytraHost, createFixedWindowLimiter, createIngestRoute, createPreviewDisableRoute, createPreviewRoute, createRevalidateRoute, createStaticContentSource, defaultIngestClientKey, defineHostComponents, docCacheTag, elytraHostImage, evaluateIngestRequest, evaluatePreviewRequest, evaluateRevalidateRequest, firstBlockFullBleed, isCrossOrigin, loadLiveContent, mergeCacheTags, mergeMetadataOverParent, nextCacheTags, openGraphLocale, pathFromSlug, projectSweepTag, readCappedBody, requestPerspective, resolveCanvasPage, resolveGlobals, resolveHostEnv, revalidationTags, routeCacheTag, safeRedirectTarget, scopeCacheTag, seoContextOf, seoMetadata, seoObjectOf, withNextImage };