@agntcms/next 0.2.0

package/dist/rateLimit-CXptRM_K.d.ts

@@ -0,0 +1,391 @@
+import { S as SectionSchema, x as FieldValueFor, w as PageSummary, F as FormLookup, o as SubmissionStorageAdapter, P as Page } from './form-BqY0H1V5.js';
+import { C as ContentStorageAdapter } from './assets-P8OCigDG.js';
+import { G as Global } from './global-CV23g5Bn.js';
+
+/**
+ * Mode discriminator for `getContent`. `'published'` is the prod hot
+ * path (bare data). `'preview'` is the editor path (data wrapped with
+ * origin metadata).
+ */
+type PreviewMode = 'preview' | 'published';
+/**
+ * Origin metadata carried by every `PreviewField<T>` in preview mode.
+ *
+ * `pageSlug`, `sectionId`, and `fieldPath` together address the field in
+ * the content store uniquely enough for the save round-trip to write
+ * back to the correct draft file and the correct field inside its
+ * section payload.
+ *
+ * `source` tells the UI and save flow which bucket actually served the
+ * data: `'draft'` when a draft existed and was read, `'published'` when
+ * preview mode fell back to the published snapshot because no draft
+ * existed yet. This affects the first save: saving against a
+ * `'published'` source creates a new draft; saving against a `'draft'`
+ * source overwrites the existing one.
+ *
+ * `revision` is a content-addressable hash (SHA-256 hex) of the
+ * serialized page bytes from the source bucket at read time. See the
+ * file header for the rationale; the hash discriminates ACTUAL content
+ * drift without needing adapter-level bookkeeping.
+ *
+ * `kind` discriminates between a field that lives in a page section
+ * (`'page'`, the default) and a field that lives in a standalone global
+ * read via `getGlobal` (`'global'`). When `kind` is `'global'`,
+ * `globalName` carries the global's name so the save round-trip can
+ * route to `/api/agntcms/global/save` instead of the page draft
+ * endpoint. The discriminator is OPTIONAL for backward compatibility:
+ * existing call sites that don't set it are treated as page origins.
+ *
+ * Why not split into two unrelated origin types? Every editable widget
+ * already reads `origin.fieldPath` and (for the agent ✨ button)
+ * `origin.pageSlug`/`origin.sectionId`. Keeping a single shape with all
+ * fields present (populated with sentinel values on the global path,
+ * matching the convention `wrapGlobalData` introduced in AdminModal)
+ * avoids touching every editable component. Consumers that care about
+ * the routing decision branch on `origin.kind`.
+ */
+interface PreviewFieldOrigin {
+    readonly pageSlug: string;
+    readonly sectionId: string;
+    readonly fieldPath: string;
+    readonly source: 'draft' | 'published';
+    readonly revision: string;
+    /**
+     * Discriminator: `'page'` (default, when omitted) means the field
+     * lives inside a page draft; `'global'` means it lives inside a
+     * standalone global. New in v0.2 (Phase 2 globals work).
+     */
+    readonly kind?: 'page' | 'global';
+    /**
+     * The global's name. Present iff `kind === 'global'`. Consumers that
+     * route saves on the global endpoint read this value.
+     */
+    readonly globalName?: string;
+}
+/**
+ * A field value in preview mode: the bare value plus its origin metadata
+ * and a brand so downstream code can distinguish a wrapped preview field
+ * from a bare published value both at compile time and at runtime.
+ *
+ * The brand uses a regular property `__agntcmsPreview: true` rather
+ * than a `unique symbol`. The original T-007 design used a `declare`-only
+ * unique symbol for the brand, which is structurally unforgeable at
+ * compile time. However, `declare const` symbols exist only in the type
+ * system — they have no runtime identity, so the implementation (T-008)
+ * cannot actually SET a symbol-keyed property on the wrapper objects it
+ * constructs. Using a string-keyed property solves this: the runtime can
+ * set it, the `EditableText`/`EditableImage` components (T-016) can
+ * detect it with a cheap `'__agntcmsPreview' in field` check, and it is
+ * still unforgeable enough for v1 (no user type would accidentally have
+ * a `__agntcmsPreview` property). The double-underscore prefix signals
+ * "framework internal — do not depend on this key".
+ *
+ * The `value` key carries the underlying data (e.g. a `string` for
+ * `TextField` or `ImageField`). Client-side code unwraps by reading
+ * `field.value`; servers read `field.origin` to compute where a save
+ * must land.
+ */
+interface PreviewField<T> {
+    readonly __agntcmsPreview: true;
+    readonly value: T;
+    readonly origin: PreviewFieldOrigin;
+}
+/**
+ * `FieldIn<Mode, T>` is the mode-aware wrapper type. It is the SINGLE
+ * axiom on which everything else in this file depends:
+ *
+ *   - `FieldIn<'preview', T>`   → `PreviewField<T>`
+ *   - `FieldIn<'published', T>` → `T` (structurally identical, zero cost)
+ *
+ * Written as a distributive conditional over a naked `Mode` parameter so
+ * that when `Mode` is itself a union, `FieldIn<Mode, T>` distributes over
+ * it. This is what makes the single `getContent` call site correctly
+ * return `PreviewField<T> | T` (rather than a widened `never`) when the
+ * caller's `mode` is known only as `'preview' | 'published'`.
+ */
+type FieldIn<Mode extends PreviewMode, T> = Mode extends 'preview' ? PreviewField<T> : Mode extends 'published' ? T : never;
+/**
+ * Projects a section schema `S` into its mode-resolved field shape.
+ * Each key in `S` is mapped through `FieldValueFor<S[K]>` to its runtime
+ * value type, and then wrapped via `FieldIn<Mode, _>`.
+ *
+ * The double conditional keeps distribution working: `Mode` must remain
+ * naked in the outermost position so a union `Mode` distributes here.
+ * `S[K]` is passed through `FieldValueFor` separately (non-distributive)
+ * because each key resolves independently.
+ *
+ * Mapped type keys are preserved as-is (no `-readonly`, no `-?`) so the
+ * readonly-ness and optionality of the schema's own keys are not
+ * dropped.
+ */
+type PageContent<Mode extends PreviewMode, S extends SectionSchema> = Mode extends 'preview' ? {
+    readonly [K in keyof S]: PreviewField<FieldValueFor<S[K]>>;
+} : Mode extends 'published' ? {
+    readonly [K in keyof S]: FieldValueFor<S[K]>;
+} : never;
+/**
+ * Parameters for a single `getContent` call.
+ *
+ * `slug` identifies the page. `mode` is the dual-mode discriminator;
+ * keeping it as a generic `Mode extends PreviewMode` is what lets the
+ * return type narrow in lockstep with the caller's `mode` value.
+ *
+ * Additional fields (e.g. locale, draft id, preview token) are
+ * deliberately out of scope for T-007. They can be added additively
+ * without breaking the mode-resolution mechanism locked in here.
+ */
+interface GetContentOptions<Mode extends PreviewMode> {
+    readonly slug: string;
+    readonly mode: Mode;
+}
+/**
+ * The public `getContent` function type. Single call site, generic over
+ * `Mode` and over the section schema `S`, returning `null` when the
+ * requested page does not exist in the mode's resolved storage.
+ *
+ * T-008 ships the runtime implementation that satisfies this type.
+ * Typed as a function type (not an interface with a call signature) so
+ * callers using `typeof getContent` get a clean arrow-function shape in
+ * tooltips.
+ */
+type GetContent = <Mode extends PreviewMode, S extends SectionSchema>(options: GetContentOptions<Mode>) => Promise<PageContent<Mode, S> | null>;
+
+interface GetGlobalInput {
+    readonly name: string;
+    readonly mode: PreviewMode;
+}
+/**
+ * The runtime function shape for `getGlobal`. Returned as part of the
+ * `Runtime` surface from `createRuntime`. Returns `null` when the named
+ * global doesn't exist.
+ */
+type GetGlobal = (options: GetGlobalInput) => Promise<Global | null>;
+
+/** Sort direction for `listPages`. Defaults to `'newest'`. */
+type ListPagesSort = 'newest' | 'oldest';
+interface ListPagesInput {
+    /** Case-sensitive exact-match filter on `Page.tags`. */
+    readonly tag?: string;
+    /** Maximum number of results. No upper bound; passing `0` returns []. */
+    readonly limit?: number;
+    /** Sort direction. Defaults to `'newest'`. */
+    readonly sort?: ListPagesSort;
+}
+/**
+ * Read metadata-only summaries of every PUBLISHED page, optionally
+ * filtered by tag and capped by limit.
+ *
+ * V1 limitation: returns published pages only regardless of preview /
+ * published context. Drafts are not surfaced in lists. To see a draft
+ * in a `PostList`, the page must first be published. See file header
+ * and ARCHITECTURE.md §12 for the rationale and roadmap.
+ */
+type ListPages = (input?: ListPagesInput) => Promise<ReadonlyArray<PageSummary>>;
+interface CreateListPagesDeps {
+    readonly contentAdapter: ContentStorageAdapter;
+}
+/**
+ * Build the `listPages` runtime function.
+ *
+ * V1 limitation: the returned function reads PUBLISHED pages only. A
+ * draft-only page (never published) will not appear in the result, even
+ * when the surrounding request is in preview mode. See file header and
+ * ARCHITECTURE.md §12.
+ */
+declare const createListPages: ({ contentAdapter, }: CreateListPagesDeps) => ListPages;
+
+/** Result of a `submitForm` call. */
+type SubmitFormResult = {
+    readonly ok: true;
+    readonly stored: true;
+    readonly id: string;
+} | {
+    readonly ok: true;
+    readonly stored: false;
+    readonly suppressed: 'honeypot';
+} | {
+    readonly ok: false;
+    readonly error: 'unknown_form';
+} | {
+    readonly ok: false;
+    readonly error: 'validation_failed';
+    readonly errors: Record<string, string>;
+};
+/** Dependencies for `submitForm`. */
+interface SubmitFormDeps {
+    /**
+     * A `FormLookup`-shaped object: anything with `get(name)` returning a
+     * form definition. The concrete `FormRegistry` from `forms/registry.ts`
+     * structurally satisfies this interface, so the runtime can stay
+     * dependency-free of `forms/` (per ARCHITECTURE.md §8 dep graph).
+     */
+    readonly forms: FormLookup;
+    readonly submissionAdapter: SubmissionStorageAdapter;
+    /** Optional ID generator for tests; defaults to a ULID-like generator. */
+    readonly generateId?: () => string;
+    /** Optional clock for tests; defaults to `() => new Date().toISOString()`. */
+    readonly now?: () => string;
+}
+/** Input to `submitForm`. */
+interface SubmitFormInput {
+    readonly formName: string;
+    /** The raw payload from the request. Validated here, NOT in the handler. */
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+/**
+ * Build the runtime function that handles form submissions.
+ *
+ * Returns a `submitForm(input)` that:
+ *   1. Looks up the form definition.
+ *   2. Honors honeypot.
+ *   3. Validates payload.
+ *   4. Stamps id+submittedAt and stores via the adapter.
+ */
+declare function createSubmitForm(deps: SubmitFormDeps): (input: SubmitFormInput) => Promise<SubmitFormResult>;
+/** Type of the function returned by `createSubmitForm`. */
+type SubmitForm = ReturnType<typeof createSubmitForm>;
+
+/** Dependencies for the runtime. */
+interface RuntimeOptions {
+    readonly contentAdapter: ContentStorageAdapter;
+    /**
+     * Form registry — required for `submitForm` to look up form definitions.
+     * Accepts any `FormLookup`-shaped object (the concrete `FormRegistry`
+     * from `forms/registry.ts` satisfies this structurally). Optional for
+     * backward compatibility: when omitted, `submitForm` is wired to an
+     * empty lookup, so any submission attempt returns `unknown_form`.
+     * Templates that use forms (ARCHITECTURE.md §6.5) MUST pass a registry
+     * built from `defineConfig({ forms: [...] })`.
+     */
+    readonly forms?: FormLookup;
+    /**
+     * Submission storage adapter. Optional for backward compatibility: when
+     * omitted, `submitForm` is wired to a no-op adapter that throws on store.
+     * Templates that use forms MUST pass an adapter (FS or webhook).
+     */
+    readonly submissionAdapter?: SubmissionStorageAdapter;
+}
+/**
+ * The runtime surface returned by `createRuntime`. This is what
+ * `defineConfig` (T-019) will later wire up and what the handlers
+ * layer consumes.
+ */
+interface Runtime {
+    /**
+     * Read a page in the requested mode.
+     *
+     * In 'published' mode the bare `Page` from the adapter is returned
+     * as-is — zero allocation, no wrapping.
+     *
+     * In 'preview' mode every field value in every section is wrapped in
+     * a `PreviewField` carrying origin metadata. The runtime tries the
+     * draft bucket first and falls back to the published bucket.
+     *
+     * Returns `null` when neither bucket has a page for the given slug.
+     */
+    readonly getContent: (options: GetContentInput) => Promise<Page | null>;
+    /**
+     * Thin wrapper over the adapter's `publishDraft`. Git commits are
+     * T-009's scope — this function does NOT touch git.
+     */
+    readonly publishDraft: (slug: string) => Promise<Page>;
+    /**
+     * Read a named global in the requested mode.
+     *
+     * Mirrors `getContent`'s dual nature (ARCHITECTURE.md §6) for
+     * standalone globals. In `'published'` mode returns the bare
+     * `Global`; in `'preview'` mode wraps every field in `PreviewField`
+     * with a `kind: 'global'` origin so editable widgets route saves to
+     * `/api/agntcms/global/save`.
+     *
+     * Returns `null` when no global with `name` exists. Globals have no
+     * draft/publish cycle (see domain/global.ts) so there is no
+     * fall-back branch.
+     */
+    readonly getGlobal: GetGlobal;
+    /**
+     * Accept a form submission. See `runtime/submitForm.ts` for the full
+     * pipeline (form lookup, honeypot, validation, store). Rate limiting
+     * is handled at the handler layer, not here.
+     *
+     * When the runtime was built without a `forms` registry or a
+     * `submissionAdapter`, `submitForm` returns `{ ok: false, error: 'unknown_form' }`
+     * for every call so downstream code can fail closed without crashing.
+     */
+    readonly submitForm: SubmitForm;
+    /**
+     * Return metadata-only summaries of every published page, optionally
+     * filtered by a single tag and capped by `limit`. Used by user-defined
+     * listing sections (e.g. PostList) for blog-index-style queries.
+     *
+     * See `runtime/listPages.ts` for the sort and filter semantics
+     * (ARCHITECTURE.md §4).
+     */
+    readonly listPages: ListPages;
+}
+
+interface GetContentInput {
+    readonly slug: string;
+    readonly mode: PreviewMode;
+}
+/**
+ * Create the runtime that powers `getContent` and `publishDraft`.
+ *
+ * The adapter is injected — no global state, no singleton. This is the
+ * shape `defineConfig` (T-019) will later construct under the hood.
+ */
+declare function createRuntime(options: RuntimeOptions): Runtime;
+
+/** Result of a rate-limit check. */
+interface RateLimitResult {
+    /** When `false`, the caller MUST reject the request with HTTP 429. */
+    readonly allowed: boolean;
+    /** Number of requests counted in the current window after this call. */
+    readonly count: number;
+    /** Epoch milliseconds when the current window resets. */
+    readonly resetAt: number;
+}
+/** Options for `createRateLimit`. */
+interface RateLimitOptions {
+    /** Max requests per window per (ip, formName) key. Default: 5. */
+    readonly perWindow: number;
+    /** Window length in milliseconds. Default: 60_000 (1 minute). */
+    readonly windowMs: number;
+    /**
+     * Clock injection point for tests. Called once per check to read the
+     * current time. Defaults to `Date.now`.
+     */
+    readonly now?: () => number;
+    /**
+     * Maximum number of (ip, formName) buckets retained in memory. When
+     * the map reaches this size, `check()` lazily sweeps expired buckets;
+     * if still at the cap, the oldest-resetAt buckets are dropped to make
+     * room. Default: 10_000. Must be a positive integer.
+     *
+     * Why: a public submit endpoint with one-off IPs (CDN edges, mobile
+     * NAT pools, attack traffic) would otherwise grow the map without
+     * bound until process restart.
+     */
+    readonly maxBuckets?: number;
+}
+interface RateLimit {
+    /**
+     * Record one request and return whether it is allowed under the current
+     * window. Always counts (even rejected calls) — this matches the typical
+     * abuse-mitigation expectation: a flood that hits the limit shouldn't
+     * "free" itself by spinning down the counter.
+     */
+    check(ip: string, formName: string): RateLimitResult;
+    /**
+     * Test-only utility: clear all buckets. Useful between tests to keep
+     * them order-independent without recreating the limiter.
+     */
+    reset(): void;
+}
+/**
+ * Build an in-memory rate limiter. Each created limiter is independent
+ * (no module-level singleton).
+ */
+declare function createRateLimit(options: RateLimitOptions): RateLimit;
+
+export { type FieldIn as F, type GetGlobal as G, type ListPages as L, type PreviewMode as P, type RateLimit as R, type SubmitForm as S, type GetContent as a, type GetContentInput as b, type GetContentOptions as c, type GetGlobalInput as d, type ListPagesInput as e, type ListPagesSort as f, type PageContent as g, type PreviewField as h, type PreviewFieldOrigin as i, type RateLimitOptions as j, type RateLimitResult as k, type Runtime as l, type RuntimeOptions as m, type SubmitFormDeps as n, type SubmitFormInput as o, type SubmitFormResult as p, createListPages as q, createRateLimit as r, createRuntime as s, createSubmitForm as t };