@tekki-forge/runtime-api 0.1.0 → 0.3.0

package/dist/site.d.ts

@@ -0,0 +1,410 @@
+import { type AppIR, type SiteChrome, type SiteIR, type SitePageIR } from "@tekki-forge/compiler";
+import type { ForgeRequestContext } from "./extension.js";
+import type { ForgeService } from "./service.js";
+type Row = Record<string, any>;
+type Issue = {
+    path: string;
+    message: string;
+};
+export type PostKind = "post" | "guide" | "webinar" | "case-study";
+export interface SiteSectionData {
+    id: string;
+    key: string;
+    type: string;
+    variant: string;
+    hidden: boolean;
+    props: Record<string, unknown>;
+    data?: SectionData;
+}
+export type SectionData = {
+    kind: "stats";
+    values: (string | null)[];
+} | {
+    kind: "records";
+    entity: string;
+    fields: string[];
+    rows: Record<string, unknown>[];
+} | {
+    kind: "posts";
+    posts: SitePostSummary[];
+} | {
+    kind: "plans";
+    plans: {
+        id: string;
+        name: string;
+        price: string | null;
+        description: string | null;
+        features: string[];
+    }[];
+};
+export interface SitePostSummary {
+    id: string;
+    kind: PostKind;
+    slug: string;
+    title: string;
+    excerpt: string | null;
+    coverImage: string | null;
+    authorName: string | null;
+    publishedAt: string | null;
+    tags: string[];
+    url: string | null;
+}
+export interface SitePostData extends SitePostSummary {
+    body: string;
+    seo: {
+        title?: string;
+        description?: string;
+        image?: string;
+    };
+}
+export interface SitePageData {
+    id: string;
+    key: string | null;
+    path: string;
+    title: string;
+    template: string | null;
+    status: "published" | "draft";
+    seo: {
+        title?: string;
+        description?: string;
+        image?: string;
+    };
+    sections: SiteSectionData[];
+    updatedAt: string;
+}
+export interface SiteRender {
+    kind: "page" | "post" | "redirect";
+    page?: SitePageData;
+    post?: SitePostData;
+    redirect?: string;
+    chrome: SiteChrome;
+    blog: Partial<Record<PostKind, string>>;
+}
+export interface SitePageListItem {
+    id: string;
+    key: string | null;
+    path: string;
+    title: string;
+    template: string | null;
+    status: "published" | "draft";
+    origin: "config" | "admin";
+    edited: boolean;
+    conflict: boolean;
+    sectionConflicts: number;
+    sections: number;
+    redirect: string | null;
+    updatedAt: string;
+}
+export interface SiteSectionDetail extends SiteSectionData {
+    origin: "config" | "admin";
+    edited: boolean;
+    conflict: boolean;
+    removed: boolean;
+    position: number;
+    config: {
+        variant: string;
+        hidden: boolean;
+        props: Record<string, unknown>;
+    } | null;
+}
+export interface SitePageDetail extends Omit<SitePageData, "sections"> {
+    origin: "config" | "admin";
+    edited: boolean;
+    conflict: boolean;
+    nav: {
+        group?: string;
+        label?: string;
+        footerOnly?: boolean;
+    } | false | null;
+    redirect: string | null;
+    config: {
+        title: string;
+        path: string;
+        seo: object;
+        status: string;
+        nav: unknown;
+        redirect: string | null;
+    } | null;
+    sections: SiteSectionDetail[];
+}
+export interface SitePostAdmin extends SitePostData {
+    status: "draft" | "published";
+    authorId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A signed-in person (never an API key) whose global roles include one of `site.editors`. */
+export declare function canEditSite(app: AppIR, ctx: ForgeRequestContext): boolean;
+/** Prisma "table/column does not exist" (P2021/P2022), or a client generated before the site models. */
+export declare function siteTablesMissing(e: unknown): boolean;
+export interface SiteSyncReport {
+    created: number;
+    updated: number;
+    conflicts: number;
+    removed: number;
+}
+export interface SyncSectionRow {
+    id: string;
+    key: string;
+    origin: string;
+    configHash: string | null;
+    edited: boolean;
+    conflict: boolean;
+    removed: boolean;
+    position: number;
+}
+export interface SyncPageRow {
+    id: string;
+    key: string | null;
+    path: string;
+    origin: string;
+    configHash: string | null;
+    edited: boolean;
+    conflict: boolean;
+    orderEdited: boolean;
+    position: number;
+    publishedAt?: Date | null;
+    sections: SyncSectionRow[];
+}
+export type SyncOp = {
+    op: "createPage";
+    data: Row;
+    sections: Row[];
+} | {
+    op: "updatePage";
+    id: string;
+    data: Row;
+} | {
+    op: "deletePage";
+    id: string;
+} | {
+    op: "createSection";
+    data: Row;
+} | {
+    op: "updateSection";
+    id: string;
+    data: Row;
+} | {
+    op: "deleteSection";
+    id: string;
+};
+/**
+ * What to do with a row that comes from the config and is still in it:
+ * - keep: nothing changed since the last sync (or the conflict is already flagged);
+ * - apply: the config changed and nobody edited the row in the admin → take the config version;
+ * - conflict: both changed (or the admin deleted it) → keep the admin version, flag it;
+ * - resolve: the config went back to the version last applied → the conflict is gone.
+ */
+export declare function syncDecision(row: {
+    configHash: string | null;
+    edited: boolean;
+    conflict: boolean;
+    removed?: boolean;
+}, hash: string): "keep" | "apply" | "conflict" | "resolve";
+/** The page columns a config page sets. */
+export declare function configPageFields(p: SitePageIR): Row;
+/**
+ * Pure part of the sync: compare the config (SiteIR) with the stored pages and list the writes to make.
+ * Admin work always wins over the config; conflicts are flagged, never overwritten.
+ */
+export declare function planSiteSync(site: SiteIR, rows: SyncPageRow[], now?: Date): {
+    ops: SyncOp[];
+    report: SiteSyncReport;
+};
+/**
+ * Seed the website from forge.config.ts (idempotent): new pages and sections are inserted, untouched ones follow
+ * the config, admin edits are kept (and flagged when the config changed too). Runs at API start and in `forge db seed`,
+ * under a transaction-level advisory lock so several API processes starting together don't race. Never throws:
+ * returns null when there is no site or the tables are missing (with a "run forge db migrate" warning).
+ */
+export declare function syncSite(app: AppIR, prisma: any, options?: {
+    log?: boolean;
+}): Promise<SiteSyncReport | null>;
+export interface ContactInput {
+    name: string;
+    email: string;
+    company?: string;
+    message: string;
+    page?: string;
+}
+/** Bot traps: the hidden "website" field is filled, or the form was sent less than 2 s after it was shown. */
+export declare function looksLikeSpam(body: Row, now?: number): boolean;
+export declare function validateContact(body: unknown): {
+    issues: Issue[];
+    value: ContactInput;
+};
+export declare function validateNewsletter(body: unknown): {
+    issues: Issue[];
+    value: {
+        email: string;
+        source?: string;
+    };
+};
+/** Forget every contact/newsletter rate limit (tests). */
+export declare function resetSiteRateLimits(): void;
+/** "Hello, World!" → "hello-world" (accents dropped, at most 100 characters). */
+export declare function slugify(input: string): string;
+/** A few published posts per post kind with a public listing, when there are no posts yet (`forge db seed`). */
+export declare function seedSitePosts(app: AppIR, prisma: any, userId: string | null): Promise<number>;
+/**
+ * The public website: rendering for visitors (pages, posts, sitemap), the contact form and newsletter, and the
+ * admin API of site editors (pages, sections, posts, messages, subscribers). Visitors only ever see published
+ * content and data of public, non-tenant entities, computed with an anonymous context.
+ */
+export declare class SiteService {
+    private readonly service;
+    constructor(service: ForgeService);
+    private get app();
+    private get prisma();
+    private get site();
+    /** The site models of the Prisma client (absent when it was generated before the site existed). */
+    private get db();
+    /** Admin routes: a signed-in site editor, never an API key. */
+    private editor;
+    /** Turn "tables missing" into a clear 503 on admin and form routes. */
+    private guard;
+    private checkApp;
+    private templateCtx;
+    private takenPaths;
+    private configPage;
+    /** Live values of a section (stats, records, posts, plans); undefined for sections without data or on failure. */
+    sectionData(type: string, variant: string, props: Record<string, unknown>): Promise<SectionData | undefined>;
+    /** Static values as typed; live ones aggregated like dashboard metrics, as an anonymous visitor (public entities only). */
+    private stats;
+    /** Read scope of an anonymous visitor + the section's filter (same rules as the dashboard and the list API). */
+    private publicWhere;
+    private records;
+    private postSummary;
+    private postData;
+    private sections;
+    private pageData;
+    private chrome;
+    /** `?path=/pricing[&preview=1]` → the page, the post or the redirect at that path, with the header and footer. */
+    render(query: Row, ctx: ForgeRequestContext): Promise<SiteRender>;
+    /** Until `forge db migrate` creates the tables, pages are rendered straight from the config. */
+    private renderFromConfig;
+    private publishedPosts;
+    /** `?kind=post&limit=20&page=1&tag=x`: published posts, newest first. */
+    posts(query: Row): Promise<{
+        data: SitePostSummary[];
+        total: number;
+    }>;
+    sitemap(): Promise<{
+        pages: {
+            path: string;
+            updatedAt: string;
+        }[];
+        posts: {
+            path: string;
+            updatedAt: string;
+        }[];
+    }>;
+    /** Users whose global roles make them site editors (contact form notifications). */
+    private editorIds;
+    contact(body: unknown, meta: {
+        ip?: string;
+        userAgent?: string;
+    }): Promise<{
+        ok: true;
+    }>;
+    newsletter(body: unknown, meta: {
+        ip?: string;
+    }): Promise<{
+        ok: true;
+    }>;
+    private listItem;
+    overview(ctx: ForgeRequestContext): Promise<{
+        pages: SitePageListItem[];
+        conflicts: number;
+        messages: {
+            new: number;
+        };
+        subscribers: number;
+        storage: boolean;
+        payments: boolean;
+        blogKinds: {
+            post?: string | undefined;
+            guide?: string | undefined;
+            webinar?: string | undefined;
+            "case-study"?: string | undefined;
+        };
+    }>;
+    private findPage;
+    private pathTaken;
+    private detail;
+    page(id: string, ctx: ForgeRequestContext): Promise<SitePageDetail>;
+    /** Validated page fields (title, path, seo, nav, status, redirect); only the keys present in `body`. */
+    private pageFields;
+    /** New admin page, optionally from a template (sections with placeholder copy). Starts as a draft. */
+    createPage(body: unknown, ctx: ForgeRequestContext): Promise<SitePageDetail>;
+    updatePage(id: string, body: unknown, ctx: ForgeRequestContext): Promise<SitePageDetail>;
+    deletePage(id: string, ctx: ForgeRequestContext): Promise<void>;
+    revertPage(id: string, ctx: ForgeRequestContext): Promise<SitePageDetail>;
+    private checkSection;
+    private findSection;
+    private configSection;
+    /** `after`: index (among the visible order) of the section the new one follows; -1 = first; default: last. */
+    addSection(pageId: string, body: unknown, ctx: ForgeRequestContext): Promise<SitePageDetail>;
+    reorder(pageId: string, body: unknown, ctx: ForgeRequestContext): Promise<SitePageDetail>;
+    updateSection(id: string, body: unknown, ctx: ForgeRequestContext): Promise<SiteSectionDetail>;
+    private sectionDetail;
+    /** Config sections are only marked removed (so the next seed doesn't bring them back); admin sections are deleted. */
+    deleteSection(id: string, ctx: ForgeRequestContext): Promise<void>;
+    revertSection(id: string, ctx: ForgeRequestContext): Promise<SiteSectionDetail>;
+    /** Live data for unsaved sections of the editor's preview; an entry is null when the section is invalid or has no data. */
+    preview(body: unknown, ctx: ForgeRequestContext): Promise<{
+        data: (SectionData | null)[];
+    }>;
+    private postAdmin;
+    private postFields;
+    private findPost;
+    listPosts(query: Row, ctx: ForgeRequestContext): Promise<{
+        data: SitePostAdmin[];
+        total: number;
+    }>;
+    getPost(id: string, ctx: ForgeRequestContext): Promise<SitePostAdmin>;
+    createPost(body: unknown, ctx: ForgeRequestContext): Promise<SitePostAdmin>;
+    updatePost(id: string, body: unknown, ctx: ForgeRequestContext): Promise<SitePostAdmin>;
+    deletePost(id: string, ctx: ForgeRequestContext): Promise<void>;
+    private message;
+    messages(query: Row, ctx: ForgeRequestContext): Promise<{
+        data: {
+            id: any;
+            name: any;
+            email: any;
+            company: any;
+            message: any;
+            page: any;
+            status: any;
+            createdAt: string;
+        }[];
+        total: number;
+    }>;
+    updateMessage(id: string, body: unknown, ctx: ForgeRequestContext): Promise<{
+        id: any;
+        name: any;
+        email: any;
+        company: any;
+        message: any;
+        page: any;
+        status: any;
+        createdAt: string;
+    }>;
+    deleteMessage(id: string, ctx: ForgeRequestContext): Promise<void>;
+    private subscriber;
+    subscribers(query: Row, ctx: ForgeRequestContext): Promise<{
+        data: {
+            id: any;
+            email: any;
+            status: any;
+            source: any;
+            createdAt: string;
+            updatedAt: string;
+        }[];
+        total: number;
+    }>;
+    /** Subscribed addresses as CSV (cells that a spreadsheet would run as formulas are neutralized). */
+    exportSubscribers(ctx: ForgeRequestContext): Promise<string>;
+    deleteSubscriber(id: string, ctx: ForgeRequestContext): Promise<void>;
+}
+export {};