@better-seo/core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,322 @@
+/** Strict JSON-LD values (no `any` on public surface). */
+type JSONLDValue = string | number | boolean | null | JSONLDValue[] | {
+    readonly [k: string]: JSONLDValue;
+};
+/**
+ * JSON-LD node. Helpers must ensure `@context` and `@type` before serialization when required by consumers.
+ */
+type JSONLD = {
+    readonly "@context"?: string | Record<string, unknown>;
+    readonly "@type": string;
+    readonly "@id"?: string;
+} & {
+    readonly [k: string]: JSONLDValue | Record<string, unknown> | undefined;
+};
+interface SEOPlugin {
+    readonly id: string;
+    readonly beforeMerge?: (draft: SEOInput, ctx: {
+        readonly config?: SEOConfig;
+    }) => SEOInput;
+    readonly afterMerge?: (seo: SEO, ctx: {
+        readonly config?: SEOConfig;
+    }) => SEO;
+}
+interface SEOConfig {
+    readonly titleTemplate?: string;
+    readonly baseUrl?: string;
+    readonly defaultRobots?: string;
+    readonly schemaMerge?: "concat" | {
+        readonly dedupeByIdAndType?: boolean;
+    };
+    readonly features?: Partial<{
+        readonly jsonLd: boolean;
+        readonly openGraphMerge: boolean;
+    }>;
+    /** Hooks run in order; prefer `createSEOContext` for request-scoped registration (future hardening). */
+    readonly plugins?: readonly SEOPlugin[];
+}
+/** hreflang → absolute or path URL (adapter maps to framework expectations). */
+interface SEOAlternates {
+    readonly languages?: Readonly<Record<string, string>>;
+}
+interface SEOMeta {
+    readonly title: string;
+    readonly description?: string;
+    readonly canonical?: string;
+    readonly robots?: string;
+    readonly alternates?: SEOAlternates;
+}
+interface SEOImage {
+    readonly url: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly alt?: string;
+}
+interface SEO {
+    readonly meta: SEOMeta;
+    readonly openGraph?: {
+        readonly title?: string;
+        readonly description?: string;
+        readonly url?: string;
+        readonly type?: string;
+        readonly images?: readonly SEOImage[];
+    };
+    readonly twitter?: {
+        readonly card?: "summary" | "summary_large_image";
+        readonly title?: string;
+        readonly description?: string;
+        readonly image?: string;
+    };
+    readonly schema: readonly JSONLD[];
+}
+type SEOAdapter<TOutput = unknown> = {
+    readonly id: string;
+    toFramework(seo: SEO): TOutput;
+};
+/** Loosely-accepted shape for `createSEO` / voilà entrypoints. */
+type SEOInput = Omit<Partial<SEO>, "meta" | "schema" | "openGraph" | "twitter"> & {
+    readonly meta?: Partial<SEOMeta>;
+    readonly title?: string;
+    readonly description?: string;
+    readonly canonical?: string;
+    readonly robots?: string;
+    readonly openGraph?: SEO["openGraph"];
+    readonly twitter?: SEO["twitter"];
+    readonly schema?: readonly JSONLD[];
+};
+/** Rule output merges into `Partial<SEOInput>` before `createSEO`. */
+interface SEORule {
+    readonly match: string;
+    readonly priority?: number;
+    readonly seo: Partial<SEOInput>;
+}
+type TagDescriptor = {
+    readonly kind: "meta";
+    readonly name?: string;
+    readonly property?: string;
+    readonly content: string;
+} | {
+    readonly kind: "link";
+    readonly rel: string;
+    readonly href: string;
+    readonly hreflang?: string;
+} | {
+    readonly kind: "script-jsonld";
+    readonly json: string;
+};
+
+/** Stable codes for programmatic handling (enterprise / observability). */
+type SEOErrorCode = "VALIDATION" | "ADAPTER_NOT_FOUND" | "MIGRATE_NOT_IMPLEMENTED" | "USE_SEO_NOT_AVAILABLE";
+declare class SEOError extends Error {
+    readonly code: SEOErrorCode;
+    readonly cause?: unknown;
+    constructor(code: SEOErrorCode, message?: string, options?: {
+        cause?: unknown;
+    });
+}
+declare function isSEOError(e: unknown): e is SEOError;
+
+/** Normalize partial + config into a canonical `SEO` document (Wave 1 baseline). */
+declare function createSEO(input: SEOInput, config?: SEOConfig): SEO;
+/** Merge parent `SEO` with child input (featured as `withSEO` in docs / Next package). */
+declare function withSEO(parent: SEO, child: SEOInput, config?: SEOConfig): SEO;
+declare function mergeSEO(parent: SEO, child: SEOInput, config?: SEOConfig): SEO;
+
+/** WebPage helper — ensures `@context` + `@type`. */
+declare function webPage(parts: {
+    readonly name: string;
+    readonly description?: string;
+    readonly url: string;
+}): JSONLD;
+declare function article(parts: {
+    readonly headline: string;
+    readonly description?: string;
+    readonly datePublished?: string;
+    readonly url: string;
+}): JSONLD;
+declare function organization(parts: {
+    readonly name: string;
+    readonly url?: string;
+    readonly logo?: string;
+}): JSONLD;
+declare function person(parts: {
+    readonly name: string;
+    readonly url?: string;
+}): JSONLD;
+declare function product(parts: {
+    readonly name: string;
+    readonly description?: string;
+    readonly sku?: string;
+    readonly image?: string;
+    readonly url: string;
+}): JSONLD;
+declare function breadcrumbList(parts: {
+    readonly items: ReadonlyArray<{
+        readonly name: string;
+        readonly url: string;
+    }>;
+}): JSONLD;
+declare function faqPage(parts: {
+    readonly questions: ReadonlyArray<{
+        readonly question: string;
+        readonly answer: string;
+    }>;
+}): JSONLD;
+/** Technical / how-to article (docs templates, PRD §2.5). */
+declare function techArticle(parts: {
+    readonly headline: string;
+    readonly description?: string;
+    readonly datePublished?: string;
+    readonly url: string;
+}): JSONLD;
+/** Escape hatch for custom `@type` graphs (caller owns validity). */
+declare function customSchema(node: JSONLD): JSONLD;
+
+/**
+ * Single JSON-LD serialization path — `JSON.stringify` on the whole graph only (ARCHITECTURE §7).
+ * Includes validation to prevent prototype pollution and XSS attacks.
+ * For multiple nodes, callers may pass an array; consumers typically emit one script tag per call.
+ *
+ * @param data - JSON-LD node or array of nodes to serialize
+ * @returns JSON string suitable for embedding in <script type="application/ld+json">
+ * @throws {SEOError} If validation fails
+ *
+ * @security Validates against prototype pollution, ensures @context is schema.org,
+ *           and properly escapes all user content via JSON.stringify
+ */
+declare function serializeJSONLD(data: JSONLD | readonly JSONLD[]): string;
+
+/** Vanilla tag list for snapshots and non-framework hosts (ARCHITECTURE §8). */
+declare function renderTags(seo: SEO): TagDescriptor[];
+
+type ValidationSeverity = "warning" | "error";
+/** Stable machine-readable codes (PRD §3.5 / observability). */
+type ValidationIssueCode = "TITLE_EMPTY" | "TITLE_TOO_LONG" | "DESCRIPTION_MISSING" | "DESCRIPTION_REQUIRED" | "DESCRIPTION_TOO_LONG" | "OG_IMAGE_NARROW" | "SCHEMA_MISSING_TYPE";
+interface ValidationIssue {
+    readonly code: ValidationIssueCode;
+    readonly field: string;
+    readonly message: string;
+    readonly severity: ValidationSeverity;
+}
+interface ValidateSEOOptions {
+    /** When false, validation is a no-op (production / Edge bundles). */
+    readonly enabled?: boolean;
+    /** When true, missing description is `error` instead of `warning`. */
+    readonly requireDescription?: boolean;
+    /** In non-production only: when not false, log each issue to console.warn (default: true). */
+    readonly log?: boolean;
+    readonly titleMaxLength?: number;
+    readonly descriptionMaxLength?: number;
+}
+/**
+ * Development-oriented checks — no heavy deps (ARCHITECTURE §12).
+ * Returns structured issues; set `log: false` to consume programmatically without console noise.
+ */
+declare function validateSEO(seo: SEO, options?: ValidateSEOOptions): readonly ValidationIssue[];
+
+/**
+ * Register an adapter implementation.
+ *
+ * ⚠️ **SECURITY**: Only register adapters from trusted sources.
+ * Malicious adapters can intercept and modify SEO data.
+ *
+ * @param adapter - The adapter to register
+ * @throws {SEOError} If adapter ID is invalid or adapter is not an object
+ *
+ * @example
+ * ```ts
+ * import { registerAdapter } from '@better-seo/core'
+ *
+ * registerAdapter({
+ *   id: 'my-framework',
+ *   toFramework: (seo) => { /* conversion logic *\/ }
+ * })
+ * ```
+ */
+declare function registerAdapter<T>(adapter: SEOAdapter<T>): void;
+declare function getAdapter<T = unknown>(id: string): SEOAdapter<T> | undefined;
+declare function listAdapterIds(): string[];
+
+declare function defineSEOPlugin(plugin: SEOPlugin): SEOPlugin;
+
+interface SEOContext {
+    readonly config: SEOConfig;
+    /** Request-scoped `createSEO` with bound config + plugins. */
+    readonly createSEO: (input: SEOInput) => SEO;
+    readonly mergeSEO: (parent: SEO, child: SEOInput) => SEO;
+}
+/**
+ * Preferred production pattern for multi-tenant / Edge — explicit config, no filesystem inference (ARCHITECTURE §13).
+ */
+declare function createSEOContext(config: SEOConfig): SEOContext;
+
+/**
+ * ⚠️ **SECURITY WARNING**: Global state is NOT safe for multi-tenant or serverless environments.
+ *
+ * This function stores config in module-level global state, which can leak between:
+ * - Different users in serverless functions (Vercel, Netlify, Cloudflare Workers)
+ * - Concurrent requests in Node.js servers
+ * - Different tenants in multi-tenant applications
+ *
+ * **DO NOT USE** in:
+ * - Server-side rendering (SSR) with multiple users
+ * - Edge functions or Workers
+ * - Multi-tenant SaaS applications
+ * - Any environment where config must be isolated per request
+ *
+ * **SAFE ALTERNATIVE:** Use `createSEOContext()` for request-scoped configuration.
+ *
+ * @deprecated Use `createSEOContext()` for production applications.
+ *             Only suitable for single-user, static sites or development.
+ *
+ * @param config - Global SEO configuration to store
+ *
+ * @see {@link createSEOContext} for request-scoped configuration
+ * @see {@link internal-docs/ARCHITECTURE.md} §10 for runtime matrix
+ * @see {@link internal-docs/USAGE.md} for security best practices
+ */
+declare function initSEO(config: SEOConfig): void;
+/**
+ * Gets the global SEO config.
+ *
+ * @deprecated Use `createSEOContext()` for production applications.
+ *
+ * @returns The global SEO config, or undefined if not initialized
+ *
+ * @see {@link createSEOContext} for request-scoped configuration
+ */
+declare function getGlobalSEOConfig(): SEOConfig | undefined;
+/**
+ * Resets the global SEO config.
+ *
+ * @internal Used for testing only
+ */
+declare function resetSEOConfigForTests(): void;
+
+/**
+ * Resolve via registered adapter — prefer `@better-seo/next`’s `seo()` for the Next voilà path.
+ * @throws {SEOError} ADAPTER_NOT_FOUND when the adapter id was never registered
+ */
+declare function seoForFramework<T>(adapterId: string, input: SEOInput, config?: SEOConfig): T;
+/**
+ * Stub until `@better-seo/react` (Wave 5 / V3). Calling this makes missing peer support obvious in dev.
+ * @throws {SEOError} USE_SEO_NOT_AVAILABLE
+ */
+declare function useSEO(): never;
+
+/**
+ * Pure rule matcher — `**` segment globs + legacy `prefix*` path match (ARCHITECTURE §11 subset).
+ */
+declare function applyRules(route: string, rules: readonly SEORule[]): Partial<SEOInput>;
+/** Merge rule output into a base document (helper for adapters). */
+declare function applyRulesToSEO(route: string, base: SEO, rules: readonly SEORule[], config?: SEOConfig): SEO;
+/** Convenience: rules → `createSEO`. */
+declare function createSEOForRoute(route: string, input: SEOInput, rules: readonly SEORule[], config?: SEOConfig): SEO;
+
+/**
+ * Codemod-oriented helpers — stub until Wave 12 / CLI `migrate` (FEATURES C15).
+ * @throws {SEOError} MIGRATE_NOT_IMPLEMENTED
+ */
+declare function fromNextSeo(_nextSeoExport: unknown): never;
+
+export { type JSONLD, type JSONLDValue, type SEO, type SEOAdapter, type SEOAlternates, type SEOConfig, type SEOContext, SEOError, type SEOErrorCode, type SEOImage, type SEOInput, type SEOMeta, type SEOPlugin, type SEORule, type TagDescriptor, type ValidateSEOOptions, type ValidationIssue, type ValidationIssueCode, type ValidationSeverity, applyRules, applyRulesToSEO, article, breadcrumbList, createSEO, createSEOContext, createSEOForRoute, customSchema, defineSEOPlugin, faqPage, fromNextSeo, getAdapter, getGlobalSEOConfig, initSEO, isSEOError, listAdapterIds, mergeSEO, organization, person, product, registerAdapter, renderTags, resetSEOConfigForTests, seoForFramework, serializeJSONLD, techArticle, useSEO, validateSEO, webPage, withSEO };