next-blogpanel 1.0.0

package/dist/index-BcNka7gK.d.cts

@@ -0,0 +1,475 @@
+import { f as BlogPanelUserConfig, d as BlockType, g as BlogPost, M as Media, e as BlogPanelConfig, i as CreateCategoryInput, C as Category, j as CreatePostInput, h as BlogSettings, k as MediaListQuery, P as PostListQuery, U as UpdateCategoryInput, r as UpdatePostInput, q as SEOScore } from './types-CgrBuig-.cjs';
+import { z } from 'zod';
+import { Document, Collection, Db } from 'mongodb';
+
+declare const envSchema: z.ZodObject<{
+    BLOGPANEL_MONGODB_URI: z.ZodString;
+    BLOGPANEL_API_KEY: z.ZodString;
+    BLOGPANEL_MONGODB_DB: z.ZodOptional<z.ZodString>;
+    BLOGPANEL_R2_ACCOUNT_ID: z.ZodOptional<z.ZodString>;
+    BLOGPANEL_R2_ACCESS_KEY: z.ZodOptional<z.ZodString>;
+    BLOGPANEL_R2_SECRET_KEY: z.ZodOptional<z.ZodString>;
+    BLOGPANEL_R2_BUCKET: z.ZodOptional<z.ZodString>;
+    BLOGPANEL_R2_PUBLIC_URL: z.ZodOptional<z.ZodString>;
+    BLOGPANEL_STORAGE: z.ZodOptional<z.ZodString>;
+    BLOGPANEL_SITE_URL: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    BLOGPANEL_SITE_NAME: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    BLOGPANEL_MONGODB_URI: string;
+    BLOGPANEL_API_KEY: string;
+    BLOGPANEL_SITE_URL: string;
+    BLOGPANEL_SITE_NAME: string;
+    BLOGPANEL_MONGODB_DB?: string | undefined;
+    BLOGPANEL_R2_ACCOUNT_ID?: string | undefined;
+    BLOGPANEL_R2_ACCESS_KEY?: string | undefined;
+    BLOGPANEL_R2_SECRET_KEY?: string | undefined;
+    BLOGPANEL_R2_BUCKET?: string | undefined;
+    BLOGPANEL_R2_PUBLIC_URL?: string | undefined;
+    BLOGPANEL_STORAGE?: string | undefined;
+}, {
+    BLOGPANEL_MONGODB_URI: string;
+    BLOGPANEL_API_KEY: string;
+    BLOGPANEL_MONGODB_DB?: string | undefined;
+    BLOGPANEL_R2_ACCOUNT_ID?: string | undefined;
+    BLOGPANEL_R2_ACCESS_KEY?: string | undefined;
+    BLOGPANEL_R2_SECRET_KEY?: string | undefined;
+    BLOGPANEL_R2_BUCKET?: string | undefined;
+    BLOGPANEL_R2_PUBLIC_URL?: string | undefined;
+    BLOGPANEL_STORAGE?: string | undefined;
+    BLOGPANEL_SITE_URL?: string | undefined;
+    BLOGPANEL_SITE_NAME?: string | undefined;
+}>;
+type EnvConfig = z.infer<typeof envSchema>;
+declare function getEnvConfig(): EnvConfig;
+declare function isR2Configured(): boolean;
+declare function defineConfig(config: BlogPanelUserConfig): BlogPanelUserConfig;
+/**
+ * Installs the user's `next-blogpanel.config.ts` into the server runtime.
+ *
+ * Called by the `next-blogpanel.setup` module that `init` scaffolds, which
+ * every generated route handler, layout and page imports. Calling it more
+ * than once is fine and expected — each bundled copy of the setup module
+ * installs the same object, and repeating an identical call is a no-op.
+ *
+ * The argument is merged over whatever is already installed: the defaults on
+ * the very first call in this process, and the previously installed config on
+ * every call after that. It is deliberately NOT always merged over the
+ * defaults — that would let a later *partial* call silently discard keys only
+ * an earlier call set. Concretely: the generated setup module installs the
+ * full config once; if application code then calls `setConfig({ theme: {...} })`
+ * on its own (`docs/configuration.md` shows exactly that pattern), merging
+ * over the defaults would reset `apiPath` back to `/api/blog` while leaving
+ * `installed` true — so `requireApiPath()` would wave the reset value
+ * straight through and persist it into GridFS media URLs. Merging over the
+ * installed config instead means a later partial call can only add or
+ * override the keys it actually mentions.
+ *
+ * A later call that explicitly sets a *different* `apiPath` than what is
+ * already installed is still honoured — this is not a lock — but it is
+ * reported with a console warning, once per distinct transition, because that
+ * value gets baked into already-persisted media URLs and post bodies.
+ */
+declare function setConfig(userConfig: BlogPanelUserConfig): BlogPanelConfig;
+/** True once a `setConfig()` call has installed a configuration in this process. */
+declare function isConfigInstalled(): boolean;
+declare function getConfig(userConfig?: BlogPanelUserConfig): BlogPanelConfig;
+/**
+ * Thrown by `requireApiPath()` when nothing has installed a configuration in
+ * this server runtime.
+ *
+ * A dedicated class rather than a string-matched `Error`: callers that need
+ * to tell "no config installed" apart from any other failure (e.g.
+ * `POST /media`, which passes this specific message through to the client
+ * instead of flattening it to a generic 500) should match on `instanceof`,
+ * not on `error.message.startsWith(...)`. A message-prefix check breaks the
+ * moment the wording changes for any reason — a typo fix, a translation, a
+ * clarification — and silently falls back to the generic branch instead of
+ * failing a test. `instanceof` cannot drift like that.
+ */
+declare class ConfigNotInstalledError extends Error {
+    constructor(context: string);
+}
+declare function getBlogConfig(): {
+    siteUrl: string;
+    siteName: string;
+    metadata: {
+        title: string;
+        description: string;
+        openGraph: {
+            title: string;
+            description: string;
+            url: string;
+            siteName: string;
+            type: string;
+        };
+    };
+    basePath: string;
+    adminPath: string;
+    apiPath: string;
+    postsPerPage: number;
+    excerptLength: number;
+    codeHighlighter: "shiki" | "prism";
+    editor: {
+        blocks: BlockType[];
+        maxImageSize: number;
+        maxUploadSize: number;
+        imageFormats: string[];
+        autosaveInterval: number;
+    };
+    seo: {
+        titleTemplate: string;
+        defaultOgImage?: string;
+        generateRSS: boolean;
+        generateSitemap: boolean;
+        structuredData: boolean;
+        minContentLength: number;
+    };
+    auth: {
+        strategy: "api-key" | "custom" | "credentials";
+        verify?: (request: Request) => Promise<boolean>;
+        admins?: string[];
+    };
+    features: {
+        search: boolean;
+        relatedPosts: boolean;
+        readingProgress: boolean;
+        tableOfContents: boolean;
+        shareButtons: boolean;
+        darkMode: boolean;
+        scheduling: boolean;
+        revisionHistory: boolean;
+        imageOptimization: boolean;
+    };
+    theme: {
+        variables?: Record<string, string>;
+        darkMode?: boolean;
+        components?: Record<string, React.ComponentType<unknown>>;
+    };
+    hooks: {
+        beforePublish?: (post: BlogPost) => Promise<void>;
+        afterPublish?: (post: BlogPost) => Promise<void>;
+        beforeDelete?: (post: BlogPost) => Promise<void>;
+        onMediaUpload?: (media: Media) => Promise<void>;
+    };
+};
+
+declare function getDb(): Promise<Db>;
+declare function getCollection<T extends Document = Document>(name: string): Promise<Collection<T>>;
+declare function ensureIndexes(): Promise<void>;
+declare function createPost(input: CreatePostInput, defaultAuthor?: BlogPost['author']): Promise<BlogPost>;
+declare function updatePost(id: string, input: UpdatePostInput): Promise<BlogPost | null>;
+declare function deletePost(id: string): Promise<boolean>;
+declare function getPostBySlug(slug: string): Promise<BlogPost | null>;
+declare function getPostById(id: string): Promise<BlogPost | null>;
+declare function listPosts(query?: PostListQuery): Promise<{
+    posts: BlogPost[];
+    total: number;
+}>;
+declare function createCategory(input: CreateCategoryInput): Promise<Category>;
+declare function updateCategory(id: string, input: UpdateCategoryInput): Promise<Category | null>;
+declare function deleteCategory(id: string): Promise<boolean>;
+declare function listCategories(): Promise<Category[]>;
+declare function getCategoryBySlug(slug: string): Promise<Category | null>;
+declare function createMedia(data: Omit<Media, '_id'>): Promise<Media>;
+declare function deleteMedia(id: string): Promise<Media | null>;
+declare function listMedia(query?: MediaListQuery): Promise<{
+    media: Media[];
+    total: number;
+}>;
+declare function getSettings(): Promise<BlogSettings>;
+declare function updateSettings(data: Partial<BlogSettings>): Promise<BlogSettings>;
+
+interface MediaUploadResult {
+    key: string;
+    url: string;
+    size: number;
+    contentType: string;
+}
+interface StorageObject {
+    key: string;
+    size: number;
+    lastModified: Date;
+}
+/**
+ * The contract every storage backend satisfies — public API, implementable
+ * from outside the package.
+ *
+ * `name` is deliberately a free-form string rather than a union of the two
+ * built-ins: it is written verbatim to `Media.provider` on every upload and
+ * read back to route the delete, so a third backend that cannot state its own
+ * name cannot have its objects deleted. See `registerStorageProvider()` for
+ * how a name is made resolvable, and docs/storage.md for what an
+ * implementation must guarantee.
+ */
+interface StorageProvider {
+    /**
+     * Stable identifier for this backend, persisted to `Media.provider`.
+     *
+     * Must be stable across deploys — changing it strands every object already
+     * recorded under the old name, because `getStorageProviderByName()` will no
+     * longer resolve it. `'gridfs'` and `'r2'` are reserved for the built-ins.
+     */
+    readonly name: string;
+    upload(file: Buffer, filename: string, contentType: string): Promise<MediaUploadResult>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<StorageObject[]>;
+}
+/**
+ * Names owned by the built-in providers. Reserved: registering over them
+ * would silently redirect deletes for every object already recorded under
+ * that name to a different backend.
+ */
+declare const BUILT_IN_PROVIDER_NAMES: readonly ["gridfs", "r2"];
+declare function generateKey(filename: string): string;
+declare class R2StorageProvider implements StorageProvider {
+    readonly name: "r2";
+    upload(file: Buffer, filename: string, contentType: string): Promise<MediaUploadResult>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<StorageObject[]>;
+}
+declare class GridFSStorageProvider implements StorageProvider {
+    readonly name: "gridfs";
+    private bucket;
+    upload(file: Buffer, filename: string, contentType: string): Promise<MediaUploadResult>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<StorageObject[]>;
+}
+/**
+ * Thrown when a provider name cannot be resolved to a backend.
+ *
+ * A dedicated class rather than a string-matched `Error`, for the same reason
+ * as `ConfigNotInstalledError`: `POST`/`DELETE /media` need to tell "this
+ * install never registered that provider" apart from any other failure so
+ * they can pass the actionable message through instead of flattening it to a
+ * generic 500, and an `error.message.startsWith(...)` check silently stops
+ * working the moment the wording changes.
+ *
+ * There is deliberately no fallback to the configured default in its place.
+ * `generateKey()` produces identically-shaped keys on every backend, so a
+ * default asked to delete a key it does not hold finds nothing and returns
+ * cleanly — the object is stranded and nothing reports it. Writing to the
+ * wrong backend is the same failure with the bytes going somewhere the stored
+ * URL does not point.
+ */
+declare class StorageProviderNotRegisteredError extends Error {
+    /** The unresolvable name, for callers that want to report it structurally. */
+    readonly providerName: string;
+    /** Every name that *is* resolvable in this process, built-ins included. */
+    readonly available: string[];
+    constructor(providerName: string, available: string[]);
+}
+/**
+ * Makes a custom backend resolvable by name for the lifetime of this process.
+ *
+ * Call it before any request is served. The generated `next-blogpanel.setup`
+ * module is the intended home: every scaffolded route imports it, so whichever
+ * route entry a request lands on first has already run registration.
+ *
+ * Calling it more than once with the same name is expected and is a silent
+ * last-write-wins overwrite, not an error — each per-route copy of the setup
+ * module evaluates its own `new MyProvider()`, so the duplicate registrations
+ * are a normal consequence of the bundling, exactly as repeated `setConfig()`
+ * calls are.
+ *
+ * The registered value is an instance, not a factory, and is shared by every
+ * concurrent request in the process — it must be safe to use that way.
+ */
+declare function registerStorageProvider(provider: StorageProvider): StorageProvider;
+/** Removes a previously registered custom provider. Built-in names are not removable. */
+declare function unregisterStorageProvider(name: string): boolean;
+/** Every provider name resolvable in this process, built-ins first. */
+declare function listStorageProviderNames(): string[];
+/** True when `name` resolves to a backend without throwing. */
+declare function isStorageProviderRegistered(name: string): boolean;
+/**
+ * Resolves the backend new uploads should go to.
+ *
+ * `BLOGPANEL_STORAGE` forces a specific one by name — including a registered
+ * custom provider — and an unresolvable value throws rather than quietly
+ * reverting to the automatic choice. Otherwise R2 is selected when all five
+ * of its variables are present, and GridFS is the zero-setup default.
+ */
+declare function getStorageProvider(): StorageProvider;
+/**
+ * Resolves the provider a specific object was stored under, by name — not by
+ * whatever backend happens to be configured right now.
+ *
+ * `getStorageProvider()` answers "what should new uploads use today?", which
+ * can diverge from "what actually holds this particular object?" once a
+ * deployment switches backends (e.g. GridFS -> R2). `generateKey()` produces
+ * identically-shaped keys on every provider, so asking the wrong one to
+ * delete a key doesn't error — it just finds nothing and returns cleanly,
+ * silently orphaning the real object. Callers that know which backend a
+ * document was written under (`Media.provider`) must use this instead.
+ *
+ * The two built-in names always resolve; anything else must have been handed
+ * to `registerStorageProvider()` in this process. An unknown name throws
+ * `StorageProviderNotRegisteredError` — it never degrades to a default,
+ * because that is the exact shape of the silent-stranding bug above.
+ */
+declare function getStorageProviderByName(name: string): StorageProvider;
+
+declare function generateSlug(text: string): string;
+declare function ensureUniqueSlug(slug: string, collection: Collection, excludeId?: string): Promise<string>;
+
+declare function calculateReadingTime(text: string): number;
+declare function countWords(text: string): number;
+declare function extractTextFromHTML(html: string): string;
+declare function extractTextFromBlocks(blocks: unknown[]): string;
+
+interface SearchResult {
+    slug: string;
+    title: string;
+    excerpt: string;
+    score: number;
+}
+declare function searchPosts(collection: Collection, query: string, limit?: number): Promise<SearchResult[]>;
+
+interface MetaTags {
+    title: string;
+    description: string;
+    canonical: string;
+    openGraph: {
+        title: string;
+        description: string;
+        url: string;
+        siteName: string;
+        type: string;
+        images: {
+            url: string;
+            width?: number;
+            height?: number;
+            alt?: string;
+        }[];
+        article?: {
+            publishedTime: string;
+            modifiedTime: string;
+            section?: string;
+            tags?: string[];
+        };
+    };
+    twitter: {
+        card: string;
+        title: string;
+        description: string;
+        images: string[];
+    };
+    robots?: string;
+}
+declare function generateMetaTags(post: BlogPost): MetaTags;
+interface ArticleStructuredData {
+    '@context': string;
+    '@type': string;
+    headline: string;
+    description: string;
+    image?: string;
+    datePublished?: string;
+    dateModified: string;
+    author: {
+        '@type': string;
+        name: string;
+        url?: string;
+    };
+    publisher: {
+        '@type': string;
+        name: string;
+    };
+    mainEntityOfPage: {
+        '@type': string;
+        '@id': string;
+    };
+    wordCount: number;
+    articleSection?: string;
+}
+declare function generateStructuredData(post: BlogPost): ArticleStructuredData;
+interface FAQStructuredData {
+    '@context': string;
+    '@type': string;
+    mainEntity: {
+        '@type': string;
+        name: string;
+        acceptedAnswer: {
+            '@type': string;
+            text: string;
+        };
+    }[];
+}
+declare function generateFAQStructuredData(faqItems: {
+    question: string;
+    answer: string;
+}[]): FAQStructuredData | null;
+interface BreadcrumbStructuredData {
+    '@context': string;
+    '@type': string;
+    itemListElement: {
+        '@type': string;
+        position: number;
+        name: string;
+        item?: string;
+    }[];
+}
+declare function generateBreadcrumbs(post: BlogPost, categoryName?: string): BreadcrumbStructuredData;
+
+declare function calculateSEOScore(post: BlogPost): SEOScore;
+
+declare function generateSitemap(): Promise<string>;
+
+declare function generateRSSFeed(fullContent?: boolean): Promise<string>;
+
+interface ProcessedImage {
+    original: MediaUploadResult;
+    width: number;
+    height: number;
+    format: string;
+    /**
+     * Every storage key this call wrote — the original plus every responsive
+     * derivative and the thumbnail. A caller that persists a reference
+     * afterward (e.g. createMedia) and then fails must roll all of these back,
+     * since none of them would otherwise be reachable through the UI.
+     */
+    uploadedKeys: string[];
+}
+declare class ImageTooLargeError extends Error {
+    readonly achievedBytes: number;
+    readonly limitBytes: number;
+    constructor(achievedBytes: number, limitBytes: number);
+}
+declare function processImage(file: Buffer, filename: string, storage: StorageProvider): Promise<ProcessedImage>;
+
+/**
+ * URL absolutisation for the contexts that require it.
+ *
+ * Deliberately free of any environment or configuration access, and free of
+ * any Node built-in, so it can be imported from client components as well as
+ * from server code. Callers supply the site URL; on the server that is
+ * `getEnvConfig().BLOGPANEL_SITE_URL`, in a component it is a prop.
+ *
+ * Why absolutise at the point of consumption rather than at write time: the
+ * stored URL has to survive the site moving. GridFS media URLs are persisted
+ * into `nbk_media` documents and into the body of every post that embeds the
+ * image, so anything baked into them is permanent — a localhost or staging
+ * origin captured at upload time would follow the content to production with
+ * no way back short of a database rewrite. `BLOGPANEL_SITE_URL` legitimately
+ * differs between environments; the storage key does not. Keeping stored URLs
+ * origin-relative and prefixing them in the handful of places that require an
+ * absolute URL (Open Graph, Twitter cards, JSON-LD, RSS enclosures) keeps the
+ * mutable part mutable.
+ */
+/** True for `https://…`, `data:…`, `//cdn…` — anything already resolvable without a base. */
+declare function isAbsoluteUrl(url: string): boolean;
+/**
+ * Returns `url` as an absolute URL, or `undefined` when it cannot be made one.
+ *
+ * Already-absolute inputs (R2 public URLs, `data:` URIs, protocol-relative
+ * hosts) are returned untouched. Root-relative inputs (the GridFS default,
+ * `/api/blog/media/file/…`) are prefixed with `siteUrl`. When `siteUrl` is
+ * empty the result is `undefined` — callers must then omit the field, which
+ * is the only honest option: emitting the bare relative path produces a
+ * malformed `og:image`/`<enclosure url>` that consumers resolve against their
+ * own origin, and emitting a half-formed absolute URL is worse still.
+ *
+ * Pass `context` to have the omission reported once per process.
+ */
+declare function absoluteUrl(url: string | null | undefined, siteUrl: string | null | undefined, context?: string): string | undefined;
+
+export { searchPosts as $, getCategoryBySlug as A, BUILT_IN_PROVIDER_NAMES as B, ConfigNotInstalledError as C, getCollection as D, getConfig as E, getDb as F, GridFSStorageProvider as G, getEnvConfig as H, ImageTooLargeError as I, getPostById as J, getPostBySlug as K, getSettings as L, type MediaUploadResult as M, getStorageProvider as N, getStorageProviderByName as O, type ProcessedImage as P, isAbsoluteUrl as Q, R2StorageProvider as R, type StorageObject as S, isConfigInstalled as T, isStorageProviderRegistered as U, listCategories as V, listMedia as W, listPosts as X, listStorageProviderNames as Y, processImage as Z, registerStorageProvider as _, type StorageProvider as a, setConfig as a0, unregisterStorageProvider as a1, updateCategory as a2, updatePost as a3, updateSettings as a4, isR2Configured as a5, StorageProviderNotRegisteredError as b, absoluteUrl as c, calculateReadingTime as d, calculateSEOScore as e, countWords as f, createCategory as g, createMedia as h, createPost as i, defineConfig as j, deleteCategory as k, deleteMedia as l, deletePost as m, ensureIndexes as n, ensureUniqueSlug as o, extractTextFromBlocks as p, extractTextFromHTML as q, generateBreadcrumbs as r, generateFAQStructuredData as s, generateKey as t, generateMetaTags as u, generateRSSFeed as v, generateSitemap as w, generateSlug as x, generateStructuredData as y, getBlogConfig as z };