@heyo-sh/heyo-cms 0.0.0-stage → 0.1.0

package/dist/types/panel.d.ts

@@ -0,0 +1,249 @@
+import type { EditorSchemaDescription } from "./editor";
+import type { JsonValue } from "./json";
+/**
+ * What the panel is told about this deployment (stage 8).
+ *
+ * The panel is one static bundle serving every configuration, so everything
+ * it renders — which collections exist, which fields they carry, which
+ * languages are registered, whether there is a trash — has to arrive as data.
+ * `GET /panel` is that payload, and this file is its type.
+ *
+ * Two rules decide what may appear here:
+ *
+ * 1. **Only what survives JSON.** An access rule, a `condition` and a hook
+ *    are functions; they stay on the server and the panel is told *that they
+ *    exist* instead of being handed something it cannot run.
+ * 2. **Resolved, not raw.** `purgeAfter: "30d"` is also given in milliseconds
+ *    because a countdown should not re-implement the duration grammar, and a
+ *    locale arrives with the name of its language, because `pl` is not a
+ *    label a switcher can show.
+ */
+/** One entry in the AI menu next to a field. Keys come from `field.ai`. */
+export interface PanelFieldAiAction {
+    key: string;
+    label: string;
+    /** Present when the action overrides `ai.defaultModel`. */
+    model?: {
+        provider: string;
+        model: string;
+    };
+}
+/**
+ * Whether the caller may see and write a field.
+ *
+ * Evaluated with the actor but **without a record**, because the panel asks
+ * before a document is chosen — so a rule that reads `record` answers for the
+ * generic case and the engine remains the authority on the specific one. A
+ * rule that throws without a record counts as permitted here and is still
+ * enforced on the write.
+ */
+export interface PanelAccessFlags {
+    read: boolean;
+    update: boolean;
+}
+export interface PanelField {
+    name: string;
+    type: string;
+    label: string;
+    description?: string;
+    required: boolean;
+    localized: boolean;
+    readOnly: boolean;
+    unique: boolean;
+    /** Server-side deterministic generator is available for this field. */
+    generate: boolean;
+    defaultValue?: JsonValue;
+    /**
+     * The field type's own options, minus everything that is a function.
+     *
+     * `select` carries its choices here, `relation` its target, `media` its
+     * accept list — the panel reads them by field type, exactly as the field
+     * type's `Input` would.
+     */
+    options: Record<string, JsonValue>;
+    admin: {
+        placeholder?: string;
+        hidden: boolean;
+    };
+    ai: PanelFieldAiAction[];
+    access: PanelAccessFlags;
+}
+export interface PanelCollection {
+    name: string;
+    slug: string;
+    label: string;
+    kind: "collection" | "global";
+    group?: string;
+    description?: string;
+    /** Field used as the row title. Resolved here so the panel never guesses. */
+    useAsTitle: string | null;
+    defaultColumns: string[];
+    fields: PanelField[];
+    /**
+     * What this actor may do, evaluated without a record.
+     *
+     * Drives whether the panel offers a "New" button, not whether the write
+     * succeeds: a rule that depends on the document is answered properly by the
+     * engine when the document exists.
+     */
+    can: {
+        read: boolean;
+        create: boolean;
+        update: boolean;
+        delete: boolean;
+    };
+}
+export interface PanelLocale {
+    code: string;
+    /** The English name of the language, looked up from the code. */
+    name: string;
+    rtl: boolean;
+    isDefault: boolean;
+}
+/**
+ * The languages, as the switcher needs them.
+ *
+ * Configuration, not a registry: `i18n.locales` is a list of codes, so the
+ * panel renders it and never offers to edit it.
+ */
+export interface PanelI18n {
+    locales: PanelLocale[];
+    defaultLocale: string;
+}
+export interface PanelMedia {
+    enabled: boolean;
+    /** Declared sizes. Nothing else may be requested from a URL. */
+    variants: string[];
+    variantMode: "on-demand" | "pregenerate" | null;
+    focalPoint: boolean;
+    crop: boolean;
+    accept: string[];
+    maxFileSize: string | null;
+    maxFileSizeBytes: number | null;
+    /** How long an unused file keeps serving, for the countdown. */
+    purgeAfter: string | null;
+    purgeAfterMs: number | null;
+}
+export interface PanelTrash {
+    enabled: boolean;
+    purgeAfter: string | null;
+    purgeAfterMs: number | null;
+}
+export interface PanelAuth {
+    methods: string[];
+    twoFactor: boolean;
+    apiKeys: boolean;
+    sso: string | null;
+    /**
+     * Whether the magic-link and password-reset routes exist at all.
+     *
+     * They are registered only when `admin.auth.deliverToken` is configured, so
+     * a sign-in screen that offered them unconditionally would offer a 404.
+     */
+    magicLink: boolean;
+    passwordReset: boolean;
+    /**
+     * Whether this deployment has no account yet.
+     *
+     * `true` turns the sign-in screen into a "claim this CMS" screen: there is
+     * nobody to sign in as, and `POST /auth/setup` is open for exactly as long
+     * as that sentence stays true.
+     */
+    setupRequired: boolean;
+}
+export interface PanelRbac {
+    enabled: boolean;
+    roles: string[];
+    customRoles: boolean;
+}
+/**
+ * AI, as the panel sees it.
+ *
+ * `configured` is "there is an `ai` section"; `runtime` is "something answers
+ * the AI routes". They are still two flags rather than one because they fail
+ * for different reasons — no section, or no credentials for the provider the
+ * default model names — and a greyed-out button with no explanation is a bug
+ * report.
+ */
+export interface PanelAi {
+    configured: boolean;
+    runtime: boolean;
+    defaultModel: {
+        provider: string;
+        model: string;
+    } | null;
+    /**
+     * Whether the panel-wide assistant is switched on for this deployment.
+     *
+     * The composer is rendered either way. A disabled composer that names its
+     * reason is a feature somebody can fix; a composer that is simply not there
+     * is a feature nobody reports as missing.
+     */
+    assistant: boolean;
+    /** Effective assistant settings. Instructions themselves never leave the server. */
+    assistantSettings: {
+        model: {
+            provider: string;
+            model: string;
+        };
+        maxTurns: number;
+        maxToolCalls: number;
+        timeoutMs: number;
+        customInstructions: boolean;
+    } | null;
+    /** Every registered action id, including the ones plugins added. */
+    actions: string[];
+    /** Whether provider keys can be managed from the settings screen. */
+    managedKeys: boolean;
+}
+export interface PanelWebhooks {
+    enabled: boolean;
+    managedInAdmin: boolean;
+    /** Whether the delivery endpoints answer. */
+    runtime: boolean;
+    /** The event catalogue, so the subscription form is a picker. */
+    events: string[];
+}
+/**
+ * A plugin, as the panel can act on it.
+ *
+ * `scripts` is the whole of the client extension story: the panel is one
+ * static bundle compiled before any plugin existed, so a plugin that wants
+ * to render something ships a script the panel loads at boot, and that
+ * script registers a field control or a view against the global the panel
+ * exposes. The alternative — shipping React components through JSON — is not
+ * a thing that can work.
+ */
+export interface PanelPlugin {
+    id: string;
+    navItems: {
+        label: string;
+        path: string;
+        icon?: string;
+    }[];
+    /** URLs, relative to `basePath` unless absolute. Loaded in order. */
+    scripts: string[];
+    /** Field types the plugin says it renders, for a diagnostic when it fails. */
+    fields: string[];
+}
+export interface PanelConfig {
+    title: string;
+    /** Where the API is mounted, absolute: every request the panel makes. */
+    basePath: string;
+    /** Where the panel itself is mounted, absolute: its router's prefix. */
+    panelPath: string;
+    collections: PanelCollection[];
+    globals: PanelCollection[];
+    i18n: PanelI18n;
+    media: PanelMedia;
+    trash: PanelTrash;
+    auth: PanelAuth;
+    rbac: PanelRbac;
+    ai: PanelAi;
+    webhooks: PanelWebhooks;
+    /** Rich-text nodes and marks, including the ones plugins registered. */
+    editor: EditorSchemaDescription;
+    /** Installed plugins and what they contribute to this screen. */
+    plugins: PanelPlugin[];
+}
+//# sourceMappingURL=panel.d.ts.map

package/dist/types/panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel.d.ts","sourceRoot":"","sources":["../../src/types/panel.ts"],"names":[],"mappings":"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"}

package/dist/types/plugin.d.ts

@@ -0,0 +1,172 @@
+import type { Actor } from "./actor";
+import type { CollectionDefinition } from "./config";
+import type { DatabaseAdapter } from "./database";
+import type { FieldsConfig } from "./fields";
+import type { CollectionDatabaseHooks, HookContext, HookOperation, HookResult, MaybePromise, ScopedDb } from "./hooks";
+import type { CmsInstance } from "./instance";
+import type { ComponentType, JsonObject } from "./json";
+import type { MigrationStep, TableSnapshot } from "./schema";
+/**
+ * What a route handler receives.
+ *
+ * Deliberately not a third-party router's context. The router inside the core
+ * is the core's own (section 10): a plugin contract typed against a specific
+ * router version is a lock-in the plan's "zero framework coupling" promise
+ * cannot afford, and a route that only ever needs `Request` and the matched
+ * parameters has no business importing one.
+ *
+ * The pair `db`/`cms` is the same distinction hooks make, by name rather than
+ * by a flag: `db` bypasses access control, `cms` enforces it.
+ */
+export interface RouteContext {
+    request: Request;
+    /** Path parameters, e.g. `{ id: "doc_1" }` for `/posts/:id`. */
+    params: Record<string, string>;
+    query: URLSearchParams;
+    actor: Actor | null;
+    /** Access control enforced; the object hooks receive as `ctx.cms`. */
+    cms: CmsInstance;
+    /**
+     * Access-control-bypassing database handle, outside any transaction.
+     *
+     * Every call opens its own short transaction, because a route is not an
+     * operation: there is nothing for a second statement to be atomic with.
+     * A route that needs atomicity calls `cms.api`, or opens one itself through
+     * `database()`.
+     */
+    db: ScopedDb;
+    /**
+     * The adapter, built on first use.
+     *
+     * A function rather than a resolved value: a route that serves a bundled
+     * asset or the OpenAPI document must not open a connection pool, and a D1
+     * binding only exists inside a request in the first place.
+     */
+    database(): Promise<DatabaseAdapter>;
+    /** The parsed JSON body. Throws a 400 `CmsError` when it is not JSON. */
+    body(): Promise<unknown>;
+    /** Shared with the HTTP hooks that run around this request. */
+    meta: Record<string, unknown>;
+    json(body: unknown, status?: number): Response;
+    text(body: string, status?: number): Response;
+}
+export type RouteMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+/**
+ * An OpenAPI fragment carried by a route into the generated document.
+ *
+ * Attached to the route rather than written in a separate file, which is what
+ * makes an undocumented endpoint impossible: the generator reads the router,
+ * so a route that forgot its fragment shows up as one in the document.
+ */
+export interface OpenApiRouteSpec {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    /** Query and path parameters, as OpenAPI parameter objects. */
+    parameters?: JsonObject[];
+    requestBody?: JsonObject;
+    responses?: JsonObject;
+    /** `false` marks a route that needs no credentials, e.g. a sign-in. */
+    security?: boolean;
+}
+export interface RouteDefinition {
+    method: RouteMethod;
+    /** Relative to `basePath`, e.g. `/analytics/pageviews`. */
+    path: string;
+    handler: (context: RouteContext) => Response | Promise<Response>;
+    middleware?: ((context: RouteContext, next: () => Promise<Response>) => Promise<Response>)[];
+    openapi?: OpenApiRouteSpec;
+}
+/** Tables and collections a plugin brings with it. */
+export interface PluginSchema {
+    collections?: Record<string, CollectionDefinition>;
+    tables?: TableSnapshot[];
+}
+/**
+ * A plugin migration.
+ *
+ * Steps, not SQL: a plugin that shipped Postgres DDL would be unusable on
+ * MongoDB, and the whole point of the neutral step list is that the adapter
+ * decides how a change is expressed.
+ */
+export interface PluginMigration {
+    id: string;
+    steps: MigrationStep[];
+}
+/** Changes a plugin makes to collections the user declared. */
+export interface CollectionPatch {
+    collection: string;
+    fields?: FieldsConfig;
+    hooks?: CollectionDatabaseHooks;
+}
+export interface PluginContext {
+    collections: Record<string, CollectionDefinition>;
+    basePath: string;
+}
+/**
+ * A hook a plugin installs on a collection it does not own.
+ *
+ * Ordering is explicit rather than registration-dependent: plugin hooks run
+ * in `priority` order and the configuration's own hooks always run last, so a
+ * user can always override what a plugin decided (section 5).
+ */
+export interface HookRegistration {
+    collection: string;
+    operation: HookOperation;
+    timing: "before" | "after";
+    /** Lower runs first. Plugin hooks default to 0, user hooks always run last. */
+    priority?: number;
+    handler: (input: JsonObject, context: HookContext) => MaybePromise<HookResult<JsonObject>>;
+}
+/** Extra methods a plugin adds to the typed client. */
+export type ClientExtension<Ext> = (base: {
+    baseUrl: string;
+    request: (path: string, init?: RequestInit & {
+        query?: Record<string, string>;
+    }) => Promise<unknown>;
+}) => Ext;
+/**
+ * Panel surfaces a plugin can extend. Rendered by `@heyo-sh/heyo-cms-admin`.
+ *
+ * `views` and `fields` are components, and a component cannot cross HTTP —
+ * the panel is one static bundle, compiled before this plugin existed. They
+ * are useful to a deployment that builds its own panel bundle. For the
+ * shipped one, `scripts` is the mechanism: the panel loads each URL at boot
+ * and the script registers its controls against `window.heyoCmsPanel`.
+ */
+export interface AdminExtension {
+    navItems?: {
+        label: string;
+        path: string;
+        icon?: string;
+    }[];
+    views?: Record<string, ComponentType<Record<string, unknown>>>;
+    fields?: Record<string, ComponentType<Record<string, unknown>>>;
+    /**
+     * Scripts the panel loads before it renders.
+     *
+     * Relative URLs are resolved against `basePath`, so the usual arrangement
+     * is a plugin route serving its own bundle: `/analytics/panel.js`.
+     */
+    scripts?: string[];
+}
+/**
+ * A plugin.
+ *
+ * `Ext` is what the plugin adds to the typed client, and it is only ever in a
+ * return position — which is what lets a configuration hold
+ * `CmsPlugin<unknown>[]` while `heyoCmsClient({ plugins: [...] })` still
+ * recovers the concrete extension types from the tuple it is handed.
+ */
+export interface CmsPlugin<Ext = Record<string, never>> {
+    id: string;
+    schema?: PluginSchema;
+    migrations?: PluginMigration[];
+    extendCollections?: (context: PluginContext) => CollectionPatch[];
+    hooks?: HookRegistration[];
+    /** Registered under `basePath` automatically, exactly like core routes. */
+    routes?: RouteDefinition[];
+    client?: ClientExtension<Ext>;
+    admin?: AdminExtension;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/types/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/types/plugin.ts"],"names":[],"mappings":"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"}

package/dist/types/query.d.ts

@@ -0,0 +1,101 @@
+import type { JsonValue } from "./json";
+/**
+ * A value as it crosses the adapter boundary.
+ *
+ * `Date` is kept distinct from its serialisation: Postgres wants a timestamp,
+ * SQLite wants an integer, MongoDB wants a `Date`. Deciding that inside the
+ * adapter is the only way the engine can stay engine-agnostic.
+ */
+export type ColumnValue = JsonValue | Date | Uint8Array;
+export type Row = Record<string, ColumnValue>;
+/**
+ * A dotted path into a row: `id`, `created_at`, `data.title`, `data.title.pl`.
+ *
+ * Field names are validated to exclude dots, so splitting on `.` is lossless.
+ * The first segment names a column; the rest, when present, address a path
+ * inside that column's JSON document.
+ */
+export type FieldPath = string;
+export type Comparator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "like" | "ilike" | "contains" | "exists";
+/**
+ * The filter AST.
+ *
+ * This is the hard boundary from section 12: the engine builds `Where`, the
+ * adapter turns it into SQL or into a MongoDB filter document. If a feature
+ * cannot be expressed here, it cannot be expressed in the engine either —
+ * which is the constraint that keeps a third database adapter cheap.
+ */
+export type Where = {
+    kind: "and";
+    conditions: Where[];
+} | {
+    kind: "or";
+    conditions: Where[];
+} | {
+    kind: "not";
+    condition: Where;
+} | {
+    kind: "compare";
+    path: FieldPath;
+    operator: Comparator;
+    value: ColumnValue | ColumnValue[];
+};
+export interface OrderBy {
+    path: FieldPath;
+    direction: "asc" | "desc";
+}
+export interface Query {
+    table: string;
+    /** Omitted means every column. Paths may reach into the document body. */
+    select?: FieldPath[];
+    where?: Where;
+    orderBy?: OrderBy[];
+    limit?: number;
+    offset?: number;
+    /**
+     * Returns a single row `{ count }` instead of the matching rows. Counting
+     * belongs in the AST rather than in a second adapter method, so pagination
+     * never needs a code path the adapter contract does not cover.
+     */
+    count?: boolean;
+}
+export type Mutation = {
+    kind: "insert";
+    table: string;
+    values: Row;
+    returning?: boolean;
+} | {
+    kind: "update";
+    table: string;
+    where: Where;
+    set: Row;
+    returning?: boolean;
+} | {
+    kind: "delete";
+    table: string;
+    where: Where;
+    returning?: boolean;
+};
+/**
+ * What a mutation reports back.
+ *
+ * The plan sketched `Promise<Row>`, which cannot describe a delete or a
+ * multi-row update. `count` is always meaningful; `rows` is populated when the
+ * mutation asked for `returning`.
+ */
+export interface MutationResult {
+    rows: Row[];
+    count: number;
+}
+/**
+ * A transaction handle.
+ *
+ * `real` is false when the engine could not start a true transaction — MongoDB
+ * without a replica set. Hooks and the outbox read it to switch to the
+ * compensating path instead of silently losing atomicity (section 12).
+ */
+export interface Tx {
+    readonly id: string;
+    readonly real: boolean;
+}
+//# sourceMappingURL=query.d.ts.map

package/dist/types/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/types/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,IAAI,GAAG,UAAU,CAAC;AAExD,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B,MAAM,MAAM,UAAU,GAClB,IAAI,GACJ,IAAI,GACJ,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,KAAK,GACL,MAAM,GACN,OAAO,GACP,UAAU,GACV,QAAQ,CAAC;AAEb;;;;;;;GAOG;AACH,MAAM,MAAM,KAAK,GACb;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,KAAK,EAAE,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,KAAK,EAAE,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,KAAK,CAAA;CAAE,GACjC;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,UAAU,CAAC;IACrB,KAAK,EAAE,WAAW,GAAG,WAAW,EAAE,CAAC;CACpC,CAAC;AAEN,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,QAAQ,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GACnE;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,GAAG,CAAC;IACT,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEzE;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,EAAE;IACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB"}