@better-seo/core 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -20,6 +20,29 @@ interface SEOPlugin {
     readonly afterMerge?: (seo: SEO, ctx: {
         readonly config?: SEOConfig;
     }) => SEO;
+    /**
+     * Runs after built-in `renderTags` output; only invoked when `renderTags(seo, config)` is called with `config` (plugins come from `config.plugins`).
+     */
+    readonly onRenderTags?: (tags: readonly TagDescriptor[], ctx: {
+        readonly seo: SEO;
+        readonly config?: SEOConfig;
+    }) => readonly TagDescriptor[];
+}
+/**
+ * Search-console verification tokens (aligned with Next.js `Metadata.verification`).
+ * Renders `<meta name="…" content="…">` via {@link renderTags}.
+ */
+interface SEOVerification {
+    readonly google?: string;
+    readonly yahoo?: string;
+    readonly yandex?: string;
+    readonly me?: string;
+    readonly other?: Readonly<Record<string, string>>;
+}
+/** Pagination `rel="prev"` / `rel="next"` (aligned with Next.js `Metadata.pagination`). */
+interface SEOPagination {
+    readonly previous?: string;
+    readonly next?: string;
 }
 interface SEOConfig {
     readonly titleTemplate?: string;
@@ -34,6 +57,11 @@ interface SEOConfig {
     }>;
     /** Hooks run in order; prefer `createSEOContext` for request-scoped registration (future hardening). */
     readonly plugins?: readonly SEOPlugin[];
+    /**
+     * Route → partial input via {@link applyRules} / {@link createSEOForRoute} / {@link seoRoute} (Wave 6 / N9).
+     * Ignored by plain `createSEO` — use route-aware APIs when you need rules applied.
+     */
+    readonly rules?: readonly SEORule[];
 }
 /** hreflang → absolute or path URL (adapter maps to framework expectations). */
 interface SEOAlternates {
@@ -45,6 +73,8 @@ interface SEOMeta {
     readonly canonical?: string;
     readonly robots?: string;
     readonly alternates?: SEOAlternates;
+    readonly verification?: SEOVerification;
+    readonly pagination?: SEOPagination;
 }
 interface SEOImage {
     readonly url: string;
@@ -52,6 +82,14 @@ interface SEOImage {
     readonly height?: number;
     readonly alt?: string;
 }
+/** Open Graph `og:video` group — used when `openGraph.type` is `video.*` or for rich previews. */
+interface SEOOpenGraphVideo {
+    readonly url: string;
+    readonly secureUrl?: string;
+    readonly type?: string;
+    readonly width?: number;
+    readonly height?: number;
+}
 interface SEO {
     readonly meta: SEOMeta;
     readonly openGraph?: {
@@ -59,10 +97,31 @@ interface SEO {
         readonly description?: string;
         readonly url?: string;
         readonly type?: string;
+        /** `og:site_name` — brand shown in Facebook / LinkedIn / Slack previews. */
+        readonly siteName?: string;
+        /** `og:locale` — e.g. `en_US`. */
+        readonly locale?: string;
+        /** `article:published_time` (ISO-8601). */
+        readonly publishedTime?: string;
+        /** `article:modified_time` */
+        readonly modifiedTime?: string;
+        /** `article:expiration_time` */
+        readonly expirationTime?: string;
+        /** `article:author` (repeat per entry). */
+        readonly authors?: readonly string[];
+        /** `article:section` */
+        readonly section?: string;
+        /** `article:tag` (repeat per entry). */
+        readonly tags?: readonly string[];
         readonly images?: readonly SEOImage[];
+        readonly videos?: readonly SEOOpenGraphVideo[];
     };
     readonly twitter?: {
         readonly card?: "summary" | "summary_large_image";
+        /** `twitter:site` — @handle or numeric string per Twitter Card spec. */
+        readonly site?: string;
+        /** `twitter:creator` */
+        readonly creator?: string;
         readonly title?: string;
         readonly description?: string;
         readonly image?: string;
@@ -106,7 +165,7 @@ type TagDescriptor = {
 };
 
 /** Stable codes for programmatic handling (enterprise / observability). */
-type SEOErrorCode = "VALIDATION" | "ADAPTER_NOT_FOUND" | "MIGRATE_NOT_IMPLEMENTED" | "USE_SEO_NOT_AVAILABLE";
+type SEOErrorCode = "VALIDATION" | "ADAPTER_NOT_FOUND" | "USE_SEO_NOT_AVAILABLE" | "USE_SEO_NO_PROVIDER";
 declare class SEOError extends Error {
     readonly code: SEOErrorCode;
     readonly cause?: unknown;
@@ -187,11 +246,11 @@ declare function customSchema(node: JSONLD): JSONLD;
 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[];
+declare function renderTags(seo: SEO, config?: SEOConfig): 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";
+type ValidationIssueCode = "TITLE_EMPTY" | "TITLE_TOO_LONG" | "DESCRIPTION_MISSING" | "DESCRIPTION_REQUIRED" | "DESCRIPTION_TOO_LONG" | "OG_IMAGE_NARROW" | "ARTICLE_PUBLISHED_TIME_RECOMMENDED" | "SCHEMA_MISSING_TYPE";
 interface ValidationIssue {
     readonly code: ValidationIssueCode;
     readonly field: string;
@@ -236,6 +295,11 @@ declare function validateSEO(seo: SEO, options?: ValidateSEOOptions): readonly V
 declare function registerAdapter<T>(adapter: SEOAdapter<T>): void;
 declare function getAdapter<T = unknown>(id: string): SEOAdapter<T> | undefined;
 declare function listAdapterIds(): string[];
+/**
+ * Best-effort only (e.g. `NEXT_RUNTIME` under Next). Prefer explicit `registerAdapter` / `@better-seo/<framework>` imports in production.
+ */
+declare function detectFramework(): "next" | undefined;
+declare function getDefaultAdapter<T = unknown>(): SEOAdapter<T> | undefined;
 
 declare function defineSEOPlugin(plugin: SEOPlugin): SEOPlugin;
 
@@ -243,6 +307,8 @@ interface SEOContext {
     readonly config: SEOConfig;
     /** Request-scoped `createSEO` with bound config + plugins. */
     readonly createSEO: (input: SEOInput) => SEO;
+    /** Merges `config.rules` for `route`, then `createSEO` (N9 / Wave 6). */
+    readonly createSEOForRoute: (route: string, input: SEOInput) => SEO;
     readonly mergeSEO: (parent: SEO, child: SEOInput) => SEO;
 }
 /**
@@ -303,6 +369,11 @@ declare function seoForFramework<T>(adapterId: string, input: SEOInput, config?:
  * @throws {SEOError} USE_SEO_NOT_AVAILABLE
  */
 declare function useSEO(): never;
+/**
+ * V5 — explicit pathname for rules: merges {@link SEOConfig.rules} (via `applyRules`) then {@link createSEO}.
+ * Prefer this over “magic” route detection at runtime (FEATURES **V6** — document limits; no stable `seo.auto` in core).
+ */
+declare function seoRoute(route: string, input: SEOInput, config?: SEOConfig): SEO;
 
 /**
  * Pure rule matcher — `**` segment globs + legacy `prefix*` path match (ARCHITECTURE §11 subset).
@@ -314,9 +385,37 @@ declare function applyRulesToSEO(route: string, base: SEO, rules: readonly SEORu
 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
+ * Map next-seo **`DefaultSeo`** / **`NextSeo`**-style props → {@link SEOInput}.
+ * Covers common `title`, `description`, `canonical`, `openGraph`, `twitter`, `noindex`, `nofollow`.
+ * Use `createSEO(fromNextSeo(props), config)` — `titleTemplate` from next-seo is not applied; set `SEOConfig.titleTemplate` yourself.
+ */
+declare function fromNextSeo(nextSeoExport: unknown): SEOInput;
+
+interface FromContentOptions {
+    /** Truncate generated description (default 300). */
+    readonly maxDescriptionLength?: number;
+    /**
+     * When **`false`**, do not derive **title** from `# heading` or the first body line (description-only inference).
+     * Use when the caller already has a title (e.g. **gray-matter** frontmatter via **`@better-seo/compiler`**).
+     * @default true
+     */
+    readonly inferTitleFromBody?: boolean;
+}
+/**
+ * Wave 7 / **C16** — derive {@link SEOInput} from a string (plain text, Markdown, or MDX-ish).
+ * Does **not** compile MDX: treats `import` / JSX as text; use for metadata hints only.
+ * Optional YAML frontmatter (`---` … `---`) with `title` / `description` is supported.
+ */
+declare function fromContent(markdownOrPlain: string, options?: FromContentOptions): SEOInput;
+/**
+ * Wave 7 — convenience alias of {@link fromContent} (same zero-dep behavior).
+ * For **gray-matter** frontmatter + body merging, use **`fromMdx`** from **`@better-seo/compiler`** (**C17**).
+ */
+declare function fromMdxString(source: string, options?: FromContentOptions): SEOInput;
+
+/**
+ * **C18** — Preserves a typed {@link SEOInput} literal for templates / config snippets (no runtime transform).
  */
-declare function fromNextSeo(_nextSeoExport: unknown): never;
+declare function defineSEO<const T extends SEOInput>(input: T): T;
 
-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 };
+export { type FromContentOptions, type JSONLD, type JSONLDValue, type SEO, type SEOAdapter, type SEOAlternates, type SEOConfig, type SEOContext, SEOError, type SEOErrorCode, type SEOImage, type SEOInput, type SEOMeta, type SEOOpenGraphVideo, type SEOPagination, type SEOPlugin, type SEORule, type SEOVerification, type TagDescriptor, type ValidateSEOOptions, type ValidationIssue, type ValidationIssueCode, type ValidationSeverity, applyRules, applyRulesToSEO, article, breadcrumbList, createSEO, createSEOContext, createSEOForRoute, customSchema, defineSEO, defineSEOPlugin, detectFramework, faqPage, fromContent, fromMdxString, fromNextSeo, getAdapter, getDefaultAdapter, getGlobalSEOConfig, initSEO, isSEOError, listAdapterIds, mergeSEO, organization, person, product, registerAdapter, renderTags, resetSEOConfigForTests, seoForFramework, seoRoute, serializeJSONLD, techArticle, useSEO, validateSEO, webPage, withSEO };