sanity-plugin-seofields 1.8.0 → 1.10.0

package/dist/plugin-HFuWZsJu.d.cts

@@ -0,0 +1,516 @@
+import * as sanity from 'sanity';
+import { a as HreflangTranslation } from './hreflang-_VbSuWYD.cjs';
+import { ComponentType } from 'react';
+import { D as DocumentWithSeoHealth } from './types-DxlPXihz.cjs';
+
+type SeoGenField = 'title' | 'description' | 'focusKeyword' | 'keywords' | 'ogTitle' | 'ogDescription' | 'twitterTitle' | 'twitterDescription';
+type MetaContext = {
+    title?: string;
+    description?: string;
+    slug?: string;
+};
+
+/** Auto-populate configuration for the `hreflangs` field. */
+interface HreflangConfig {
+    /** Show the "Sync from translations" button on the hreflangs field. */
+    autoFill?: boolean;
+    /** Field holding the language tag on translated documents. Defaults to 'language'. */
+    localeField?: string;
+    /** Build the path for a translation. Defaults to `/${slug}`. */
+    resolvePath?: (t: HreflangTranslation) => string;
+}
+type AiIndustry = 'blog' | 'ecommerce' | 'healthcare' | 'pharmacy' | 'saas' | 'finance' | 'realestate' | 'education' | 'restaurant' | 'travel' | 'fitness' | 'hospitality' | 'nonprofit' | 'legal' | 'insurance' | 'automotive' | 'homeServices';
+/**
+ * All the generic document values the plugin extracts, handed to a custom prompt function so you can
+ * template your own prompt exactly the way the built-in prompts are built. `content` is the extracted
+ * document text (same output as the plugin's own content extraction).
+ */
+type CustomPromptValues = {
+    field: SeoGenField;
+    content: string;
+    focusKeyword: string;
+    keywords: string[];
+    meta?: MetaContext;
+    industry?: AiIndustry;
+};
+/** Receives all generic document values, returns the prompt string sent to the AI provider. */
+type CustomPromptFn = (values: CustomPromptValues) => string;
+interface AiConfig {
+    /** AI provider to use for text generation. */
+    provider?: 'openai' | 'anthropic' | 'groq' | 'gemini' | 'ollama';
+    /**
+     * API key for the provider. Not required for ollama or when using a proxy endpoint.
+     * Warning: this is bundled into Studio's client-side JS and readable by anyone with Studio
+     * access. For production, use `endpoint` instead — see `sanity-plugin-seofields/server`
+     * for ready-made proxy handlers (Next.js, Express, Node, Cloudflare Workers, etc.).
+     */
+    apiKey?: string;
+    /** Override the provider's default model. */
+    model?: string;
+    /** Override the provider's base URL. Accepts any OpenAI-compatible endpoint (DeepSeek, xAI Grok, Azure OpenAI, etc.). */
+    baseUrl?: string;
+    /**
+     * Proxy endpoint — POST { field, content, focusKeyword, keywords, meta } → { result: string }.
+     * Key stays server-side. Build one with `sanity-plugin-seofields/server`, e.g.
+     * `createNextRouteHandler({ provider: 'openai', apiKey: process.env.OPENAI_API_KEY })`.
+     */
+    endpoint?: string;
+    /** Sampling temperature. Defaults to 0.7. */
+    temperature?: number;
+    /**
+     * Root document field(s) used as content for the AI prompt. Defaults to 'body'.
+     *
+     * - `string` — one field, used for every document type
+     * - `string[]` — multiple fields in priority order, used for every document type
+     * - `Record<string, string | string[]>` — per-document-type field(s); use a `default`
+     *   key for unlisted types (falls back to `'body'` if omitted)
+     *
+     * @example
+     * content: ['title', 'excerpt', 'body']
+     *
+     * @example
+     * content: {
+     *   page: ['sections'],
+     *   news: 'content',
+     *   work: ['content', 'contentExtended'],
+     *   author: 'bio',
+     *   default: 'body',
+     * }
+     */
+    content?: string | string[] | Record<string, string | string[]>;
+    /** Industry context for prompts. When set, uses domain-specific vocabulary. Omit for generic prompts. */
+    industry?: AiIndustry;
+    /**
+     * FREE tier: a single custom prompt (generic or industry-specific — the function decides based on the
+     * `field`/`industry` it receives). Ignored if `customPrompts` is also set.
+     *
+     * In proxy mode (`endpoint`), custom prompts must be set on the **server** handler config
+     * (`createSeoAiHandler`) — a function cannot be sent over HTTP.
+     *
+     * @example
+     * customPrompt: (v) => `Write a 55-char SEO ${v.field} about: ${v.content.slice(0, 200)}`
+     */
+    customPrompt?: CustomPromptFn;
+    /**
+     * PAID tier: up to 5 generic + up to 5 per-industry custom prompts. The count and per-industry
+     * pools are unlocked only behind a validated license via `seofields-pro`; without a valid license
+     * this collapses to a single prompt (same as the free `customPrompt`).
+     *
+     * By default custom prompts **replace** the built-in angle pool for a field. Set `merge: true` to
+     * mix them into the built-in pool instead.
+     */
+    customPrompts?: {
+        generic?: CustomPromptFn[];
+        byIndustry?: Partial<Record<AiIndustry, CustomPromptFn[]>>;
+        /** Mix custom prompts with the built-in angle pool. Default false = replace. */
+        merge?: boolean;
+    };
+    /** Enable test mode — uses static pre-written outputs without any API call. Shows test warning in UI. */
+    testMode?: boolean;
+    /** Number of full generation attempts before giving up. Defaults to 2. */
+    maxRetries?: number;
+    /**
+     * Controls what is returned when all attempts fail validation:
+     * - true: returns the first raw response (before refinement passes)
+     * - false / undefined (default): returns the last attempt's output
+     */
+    keepFirstOnValidationFail?: boolean;
+    /**
+     * Width of the "Generate with AI" button.
+     * - 'full' (default): stretches to the field's full width.
+     * - 'auto': normal button width, left-aligned.
+     */
+    buttonWidth?: 'full' | 'auto';
+    /** @internal — forwarded from root licenseKey at plugin setup time. Do not set manually. */
+    _licenseKey?: string;
+    /** @internal — Sanity project ID used for pro feature validation. Do not set manually. */
+    _projectId?: string;
+}
+
+interface SeoFieldConfig {
+    title?: string;
+    description?: string;
+}
+type SeoFieldKeys = 'title' | 'description' | 'canonicalUrl' | 'metaImage' | 'keywords' | 'metaAttributes' | 'robots' | 'focusKeyword' | 'hreflangs' | 'geoChecklist' | 'metaTagsPreview';
+type openGraphFieldKeys = 'openGraphUrl' | 'openGraphTitle' | 'openGraphDescription' | 'openGraphSiteName' | 'openGraphType' | 'openGraphImageType' | 'openGraphImage' | 'openGraphImageUrl';
+type twitterFieldKeys = 'twitterCard' | 'twitterSite' | 'twitterCreator' | 'twitterTitle' | 'twitterDescription' | 'twitterImageType' | 'twitterImage' | 'twitterImageUrl';
+type AllFieldKeys = SeoFieldKeys | openGraphFieldKeys | twitterFieldKeys;
+/**
+ * Names of top-level fields inside the `seoFields` object type.
+ * Use these when assigning fields to groups in `fieldGroups`.
+ */
+type SeoObjectFieldName = 'robots' | 'preview' | 'title' | 'description' | 'metaImage' | 'metaAttributes' | 'keywords' | 'canonicalUrl' | 'openGraph' | 'twitter' | 'focusKeyword' | 'hreflangs' | 'geoChecklist' | 'metaTagsPreview';
+/**
+ * Defines a single tab/group within the `seoFields` object.
+ */
+interface SeoFieldGroup {
+    /** Unique key for this group (used internally by Sanity). */
+    name: string;
+    /** Human-readable label shown as the tab title. */
+    title: string;
+    /** Whether this tab is selected by default. Only one group should be `true`. */
+    default?: boolean;
+    /**
+     * Field names to include in this group.
+     * Use the top-level seoFields field names: `'title'`, `'description'`, `'metaImage'`,
+     * `'keywords'`, `'canonicalUrl'`, `'metaAttributes'`, `'robots'`, `'preview'`,
+     * `'openGraph'`, `'twitter'`.
+     */
+    fields: SeoObjectFieldName[];
+    /** Optional icon displayed next to the tab title. Must be a React component. */
+    icon?: ComponentType;
+}
+type ValidHiddenFieldKeys = Exclude<AllFieldKeys, 'openGraphImageUrl' | 'twitterImageUrl' | 'openGraphImageType' | 'twitterImageType'>;
+interface FieldVisibilityConfig {
+    hiddenFields?: ValidHiddenFieldKeys[];
+}
+/**
+ * Individual SEO fields that must be non-empty before publishing.
+ * Dot-notation for nested fields (e.g. 'openGraph.title').
+ */
+type PublishGateRequiredField = 'title' | 'description' | 'metaImage' | 'keywords' | 'canonicalUrl' | 'openGraph.title' | 'openGraph.description' | 'openGraph.image' | 'openGraph.type' | 'twitter.title' | 'twitter.description' | 'twitter.image' | 'twitter.card';
+interface SeoFieldsPluginConfig {
+    /**
+     * License key for pro features (SEO Health Dashboard, Publish Gate).
+     * Obtain at https://sanity-plugin-seofields.thehardik.in
+     */
+    licenseKey?: string;
+    /**
+     * Enable or configure the SEO preview feature.
+     * If set to `true`, the SEO preview will be enabled with default settings.
+     * If set to an object, you can provide a custom `prefix` function to modify the URL prefix
+     * and/or a `titleSuffix` to append text (e.g. a brand name) after the meta title in the preview.
+     * The plugin automatically adds a `|` separator — only provide the suffix text itself.
+     *
+     * Example:
+     * ```
+     * seoPreview: {
+     *   prefix: (doc) => `/${doc.slug?.current || 'untitled'}`,
+     *   titleSuffix: 'Acme Corp',
+     *   // or dynamically:
+     *   titleSuffix: (doc) => doc.brandName || 'Acme Corp',
+     * }
+     * ```
+     */
+    seoPreview?: boolean | {
+        prefix?: (doc: {
+            _type?: string;
+        } & Record<string, unknown>) => string;
+        /**
+         * A static string or function appended to the meta title in the Live Preview.
+         * Useful for showing a brand suffix (e.g. `'Acme Corp'`) that is added
+         * via your Next.js title template but not stored in the Sanity field.
+         * The plugin automatically prepends a `|` separator so only provide the
+         * text itself. The suffix is rendered in a muted style so editors can
+         * distinguish it from the typed title. The combined length (including the
+         * separator) is checked against the 60-character SERP limit.
+         */
+        titleSuffix?: string | ((doc: {
+            _type?: string;
+        } & Record<string, unknown>) => string);
+        /**
+         * When `true`, the `titleSuffix` is rendered in the same color and weight
+         * as the main title (`#1a0dab`, `fontWeight: 500`) instead of the default
+         * muted style (`#70757a`, `fontWeight: 400`).
+         *
+         * @default false
+         */
+        titleSuffixInheritColor?: boolean;
+        /**
+         * A GROQ query string whose result is used as the title suffix in the Live Preview.
+         * The query runs against your dataset at Studio load time, making it useful for
+         * fetching a dynamic value from another document (e.g. a settings singleton).
+         * Takes priority over `titleSuffix` when both are provided.
+         *
+         * @example
+         * ```ts
+         * titleSuffixQuery: '*[_type == "siteSettings"][0].siteName'
+         * ```
+         */
+        titleSuffixQuery?: string;
+    };
+    /**
+     * A mapping of field keys to their configuration settings.
+     * This allows customization of field titles and descriptions.
+     * For example, to change the title of the 'title' field:
+     */
+    fieldOverrides?: Partial<Record<AllFieldKeys, SeoFieldConfig>>;
+    /**
+     * A mapping of document types to field visibility configurations.
+     * This allows you to specify which fields should be hidden for specific document types.
+     */
+    fieldVisibility?: Record<string, FieldVisibilityConfig>;
+    /**
+     * A list of fields that should be hidden by default in all document types.
+     * This can be overridden by specific document type settings in `fieldVisibility`.
+     */
+    defaultHiddenFields?: ValidHiddenFieldKeys[];
+    /**
+     * Group the SEO fields into tabbed sections inside the `seoFields` object.
+     * When configured, the Studio shows tabs (Sanity groups) so editors can
+     * switch between e.g. "Meta", "Open Graph", and "Twitter Card" panels.
+     *
+     * @example
+     * fieldGroups: [
+     *   { name: 'meta',      title: 'Meta',         default: true,
+     *     fields: ['title', 'description', 'metaImage', 'keywords', 'canonicalUrl', 'metaAttributes', 'robots', 'preview'] },
+     *   { name: 'openGraph', title: 'Open Graph',   fields: ['openGraph'] },
+     *   { name: 'twitter',   title: 'Twitter Card', fields: ['twitter'] },
+     * ]
+     */
+    fieldGroups?: SeoFieldGroup[];
+    /**
+     * Show the GEO / AI Overview readiness checklist inside seoFields.
+     * Defaults to `true`.
+     */
+    geo?: boolean;
+    /**
+     * Show the Meta Tags HTML preview inside seoFields.
+     * Defaults to `true`.
+     */
+    metaTagsPreview?: boolean;
+    /**
+     * The base URL of your website, used for generating full URLs in the SEO preview.
+     * Defaults to 'https://www.example.com' if not provided.
+     */
+    baseUrl?: string;
+    /**
+     * The Sanity API version to use for all plugin clients (SEO Preview, Health Dashboard).
+     * Defaults to '2024-01-01'.
+     * @example '2024-01-01'
+     */
+    apiVersion?: string;
+    /**
+     * Auto-populate the `hreflangs` field from document translations. Designed for
+     * `@sanity/document-internationalization` — adds a "Sync from translations" button to the field
+     * that reads the `translation.metadata` references and fills alternate entries (still editable).
+     * URLs are built from the root `baseUrl` + each translation's slug.
+     *
+     * @example
+     * hreflang: { autoFill: true, resolvePath: (t) => `/${t.language}/${t.slug}` }
+     */
+    hreflang?: HreflangConfig;
+    /**
+     * Enable or configure the SEO Health Dashboard tool.
+     * If set to `true`, the dashboard is enabled with all defaults.
+     * If set to an object, you can customise the tool and dashboard settings.
+     * Defaults to `true`.
+     * Example:
+     * ```
+     * healthDashboard: {
+     *   toolTitle: 'SEO Overview',  // Studio nav tab label
+     *   content: {
+     *     icon: '🔍',               // Emoji icon shown before the page heading
+     *     title: 'My SEO Dashboard',// Page heading inside the tool (no emoji)
+     *     description: 'Track SEO across all documents', // Subtitle under the heading
+     *   },
+     *   display: {
+     *     typeColumn: false,        // Hide the document type column (default: true)
+     *     documentId: false,        // Hide the document ID under titles (default: true)
+     *   },
+     *   query: {
+     *     // Option 1 – filter by specific document types
+     *     types: ['post', 'page'],
+     *     // Option 2 – provide a full custom GROQ query (takes precedence over `types`)
+     *     // Must return documents with at least: _id, _type, title, seo, _updatedAt
+     *     groq: `*[seo != null && defined(slug.current)]{ _id, _type, title, slug, seo, _updatedAt }`,
+     *   },
+     * }
+     * ```
+     */
+    healthDashboard?: boolean | {
+        tool?: {
+            title?: string;
+            name?: string;
+        };
+        toolTitle?: string;
+        content?: {
+            icon?: string;
+            title?: string;
+            description?: string;
+            /** Text shown while the license key is being verified. Defaults to "Verifying license…" */
+            loadingLicense?: string;
+            /** Text shown while documents are being fetched. Defaults to "Loading documents…" */
+            loadingDocuments?: string;
+            /** Text shown when the query returns zero results. Defaults to "No documents found" */
+            noDocuments?: string;
+        };
+        /**
+         * Show or hide the document type column in the results table.
+         * Defaults to `true`.
+         */
+        showTypeColumn?: boolean;
+        /**
+         * Show or hide the Sanity document `_id` under each title.
+         * Defaults to `true`.
+         */
+        showDocumentId?: boolean;
+        query?: {
+            /**
+             * Limit the dashboard to specific document types.
+             * Example: `['post', 'page']`
+             */
+            types?: string[];
+            /**
+             * When using `types`, also require the `seo` field to be non-null.
+             * Set to `false` to include documents of those types even if `seo` is missing.
+             * Defaults to `true`.
+             */
+            requireSeo?: boolean;
+            /**
+             * Provide a fully custom GROQ query. Takes precedence over `types`.
+             * The query must return documents with at least: _id, _type, title, seo, _updatedAt
+             */
+            groq?: string;
+        };
+        /**
+         * The Sanity API version to use for the client (e.g. '2023-01-01').
+         * Defaults to '2023-01-01'.
+         * @deprecated Use the root-level `apiVersion` option instead.
+         * @example
+         * // Before (deprecated):
+         * healthDashboard: { apiVersion: '2024-01-01' }
+         * // After:
+         * apiVersion: '2024-01-01'
+         */
+        apiVersion?: string;
+        /**
+         * License key for the SEO Health Dashboard pro feature.
+         * @deprecated Use the root-level `licenseKey` option instead.
+         */
+        licenseKey?: string;
+        /**
+         * Map raw `_type` values to human-readable display labels.
+         * Used in both the Type column and the Type filter dropdown.
+         * Any type without an entry falls back to the raw `_type` string.
+         *
+         * @example
+         * typeDisplayLabels: { productDrug: 'Products', singleCondition: 'Condition' }
+         */
+        typeDisplayLabels?: Record<string, string>;
+        /**
+         * Controls how the document type is rendered in the Type column.
+         * - `'badge'` (default) — coloured pill
+         * - `'text'` — plain text, useful for dense layouts
+         */
+        typeColumnMode?: 'badge' | 'text';
+        /**
+         * The document field to use as the display title in the dashboard.
+         *
+         * - `string` — use this field for every document type (e.g. `'name'`)
+         * - `Record<string, string>` — per-type mapping; unmapped types fall back to `title`
+         *
+         * @example
+         * titleField: 'name'
+         *
+         * @example
+         * titleField: { post: 'title', product: 'name', category: 'label' }
+         */
+        titleField?: string | Record<string, string>;
+        /**
+         * Callback function to render a custom badge next to the document title.
+         * Receives the full document and should return badge data or undefined.
+         *
+         * @example
+         * getDocumentBadge: (doc) => {
+         *   if (doc.services === 'NHS')
+         *     return { label: 'NHS', bgColor: '#e0f2fe', textColor: '#0369a1' }
+         *   if (doc.services === 'Private')
+         *     return { label: 'Private', bgColor: '#fef3c7', textColor: '#92400e' }
+         * }
+         */
+        getDocumentBadge?: (doc: DocumentWithSeoHealth & Record<string, unknown>) => {
+            label: string;
+            bgColor?: string;
+            textColor?: string;
+            fontSize?: string;
+        } | undefined;
+        /**
+         * The `name` of the Sanity structure tool that contains the monitored documents.
+         * Required when you have multiple structure tools and the documents live in a
+         * non-default one. Clicking a title will navigate to
+         * `/{basePath}/{structureTool}/intent/edit/…` directly.
+         *
+         * @example
+         * structureTool: 'common'
+         */
+        structureTool?: string;
+        /**
+         * Enable preview/demo mode to show dummy data.
+         * Useful for testing, documentation, or showcasing the dashboard.
+         * When enabled, displays realistic sample documents with various SEO scores.
+         * Defaults to `false`.
+         *
+         * @example
+         * previewMode: true
+         */
+        previewMode?: boolean;
+        /**
+         * Export options for the SEO Health Dashboard.
+         * Set to `true` (default) to enable both CSV and JSON export,
+         * or configure per-format.
+         */
+        export?: boolean | {
+            enabled?: boolean;
+            formats?: Array<'csv' | 'json'>;
+        };
+        /**
+         * Show compact inline stat pills in the header row instead of the
+         * full 6-card stats grid. Useful for saving vertical space.
+         * Defaults to `false`.
+         */
+        compactStats?: boolean;
+    };
+    /**
+     * Gate publishing based on SEO score or required field presence.
+     * Requires a valid root-level `licenseKey` — silently disabled if key is absent or invalid.
+     *
+     * @example
+     * ```ts
+     * publishGate: {
+     *   mode: 'warn',
+     *   minScore: 70,
+     *   requiredFields: ['title', 'description', 'openGraph.title'],
+     *   types: ['post', 'page'],
+     * }
+     * ```
+     */
+    /**
+     * AI text generation configuration.
+     * Supports OpenAI, Anthropic, Groq, Gemini, Ollama, or a custom proxy endpoint.
+     * Set `testMode: true` to preview generation without an API key.
+     */
+    ai?: AiConfig;
+    publishGate?: {
+        /**
+         * 'block' — disables the Publish button with a tooltip reason (default).
+         * 'warn'  — shows a confirm dialog; editor can bypass and publish anyway.
+         * @default 'block'
+         */
+        mode?: 'block' | 'warn';
+        /**
+         * Minimum overall SEO health score (0–100) required to publish.
+         * Gate fires when the document's score is below this threshold.
+         * @default 60
+         */
+        minScore?: number;
+        /**
+         * Individual fields that MUST be non-empty. Gate fires if any are missing.
+         * Use dot-notation for nested fields: 'openGraph.title', 'twitter.image', etc.
+         */
+        requiredFields?: PublishGateRequiredField[];
+        /**
+         * Restrict the gate to specific document types.
+         * Omit to apply to all document types that have an `seo` field.
+         */
+        types?: string[];
+        /**
+         * Custom message shown in the block tooltip or warn dialog.
+         * Accepts a string or a function receiving (score, issues[]).
+         */
+        message?: string | ((score: number, issues: string[]) => string);
+    };
+}
+declare const seofields: sanity.Plugin<void | SeoFieldsPluginConfig>;
+
+export { type AiConfig as A, type CustomPromptFn as C, type FieldVisibilityConfig as F, type HreflangConfig as H, type MetaContext as M, type PublishGateRequiredField as P, type SeoGenField as S, type ValidHiddenFieldKeys as V, type AiIndustry as a, type SeoFieldsPluginConfig as b, type AllFieldKeys as c, type CustomPromptValues as d, type SeoFieldConfig as e, type SeoFieldGroup as f, type SeoFieldKeys as g, type SeoObjectFieldName as h, type openGraphFieldKeys as o, seofields as s, type twitterFieldKeys as t };