@ogify/core 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,400 @@
+import { FontWeight, FontStyle } from 'satori';
+
+/**
+ * Type definitions for the OGify core library.
+ *
+ * This module provides TypeScript types and interfaces for:
+ * - Font configuration and loading
+ * - Template definition and parameters
+ * - Template handler configuration
+ * - Emoji providers
+ */
+
+/**
+ * Supported emoji providers for rendering emoji characters in OG images.
+ *
+ * Each provider offers a different visual style:
+ * - `twemoji`: Twitter's emoji set (colorful, rounded)
+ * - `fluent`: Microsoft's Fluent emoji (3D style with color)
+ * - `fluentFlat`: Microsoft's Fluent emoji (flat 2D style)
+ * - `noto`: Google's Noto Color Emoji (current standard)
+ * - `blobmoji`: Google's blob-style emoji (deprecated but still available)
+ * - `openmoji`: Open-source emoji with outlined style
+ */
+type OgEmojiProvider = 'twemoji' | 'fluent' | 'fluentFlat' | 'noto' | 'blobmoji' | 'openmoji';
+/**
+ * Supported font file formats.
+ *
+ * - `woff`: Web Open Font Format (modern, compressed)
+ * - `ttf`: TrueType Font (legacy, larger file size)
+ */
+type OgFontFormat = 'woff' | 'ttf';
+/**
+ * Configuration for a font used in OG image templates.
+ *
+ * Fonts can be loaded from three sources (in priority order):
+ * 1. Pre-loaded binary data (via `data` property)
+ * 2. Remote URL (via `url` property)
+ * 3. Google Fonts API (automatic detection based on `name`)
+ *
+ * @example
+ * // Load from Google Fonts (automatic)
+ * const font1: OgFontConfig = {
+ *   name: 'Inter',
+ *   weight: 400,
+ *   style: 'normal'
+ * };
+ *
+ * @example
+ * // Load from custom URL
+ * const font2: OgFontConfig = {
+ *   name: 'CustomFont',
+ *   url: 'https://example.com/font.woff2',
+ *   weight: 700
+ * };
+ *
+ * @example
+ * // Load from pre-loaded data
+ * const font3: OgFontConfig = {
+ *   name: 'MyFont',
+ *   data: fontBuffer,
+ *   weight: 400
+ * };
+ */
+type OgFontConfig = {
+    /** The font family name (e.g., 'Inter', 'Roboto', 'Merriweather') */
+    name: string;
+    /** Font weight (100-900, default: 400) */
+    weight?: FontWeight;
+    /** Font style ('normal' or 'italic', default: 'normal') */
+    style?: FontStyle;
+    /** URL to the font file (for custom/self-hosted fonts) */
+    url?: string;
+    /** Pre-loaded font binary data (ArrayBuffer or Buffer) */
+    data?: Buffer | ArrayBuffer;
+    /** Font file format (default: 'woff') */
+    format?: OgFontFormat;
+};
+/**
+ * Props passed to template HTML rendering functions.
+ *
+ * Contains user-provided parameters and optional dimension overrides.
+ * Templates use these props to generate dynamic HTML content.
+ *
+ * @example
+ * const html = (props: OgTemplateOptions) => `
+ *   <div style="width: ${props.width}px; height: ${props.height}px">
+ *     <h1>${props.params.title}</h1>
+ *     <p>${props.params.description}</p>
+ *   </div>
+ * `;
+ */
+type OgTemplateOptions = {
+    /** User-provided parameters that populate the template (e.g., title, description, author) */
+    params: OgTemplateParams;
+    /** Optional custom width in pixels (default: 1200) */
+    width?: number;
+    /** Optional custom height in pixels (default: 630) */
+    height?: number;
+};
+/**
+ * Key-value pairs representing dynamic template parameters.
+ *
+ * Parameters are the data that gets injected into templates to create
+ * personalized OG images. Values can be:
+ * - Strings: Text content (titles, descriptions, names)
+ * - Numbers: Counts, dates, metrics
+ * - Booleans: Flags, toggles, states
+ *
+ * @example
+ * const params: OgTemplateParams = {
+ *   title: 'My Blog Post',
+ *   author: 'John Doe',
+ *   views: 1234,
+ *   published: true
+ * };
+ */
+type OgTemplateParams = Record<string, string | number | boolean>;
+/**
+ * Complete definition of an Open Graph image template.
+ *
+ * A template is a reusable blueprint for generating OG images.
+ * It defines:
+ * - How to render HTML from parameters
+ * - What fonts to use
+ * - Metadata for identification
+ */
+type OgTemplate = {
+    /** Unique identifier for this template (e.g., 'blog-post', 'product-card') */
+    id: string;
+    /** Human-readable name for display purposes */
+    name: string;
+    /** Brief description of what this template is used for */
+    description: string;
+    /**
+     * Function that generates HTML markup from template parameters.
+     *
+     * The HTML should use inline styles (Tailwind-like utilities are supported).
+     * Flexbox and basic CSS properties are supported by Satori.
+     */
+    renderer: (props: OgTemplateOptions) => string;
+    /**
+     * Custom fonts to use in this template.
+     *
+     * Fonts are loaded in the order specified and should cover
+     * all characters used in the template.
+     */
+    fonts: OgFontConfig[];
+    /**
+     * Optional emoji provider to use in this template.
+     *
+     * If not specified, defaults to 'noto'.
+     */
+    emojiProvider?: OgEmojiProvider;
+};
+/**
+ * Configuration for the TemplateRenderer class.
+ *
+ * Defines available templates, global defaults, and lifecycle hooks.
+ * The handler manages a registry of templates and provides a unified
+ * interface for rendering them to images.
+ */
+type OgTemplateRenderer = {
+    /** Array of template definitions to register */
+    templates: OgTemplate[];
+    /**
+     * Default parameter values applied to all templates.
+     *
+     * These values are merged with user-provided parameters,
+     * with user values taking precedence.
+     */
+    defaultParams?: OgTemplateParams;
+    /**
+     * Hook called before rendering.
+     *
+     * Useful for:
+     * - Logging and analytics
+     * - Parameter validation
+     * - Authentication checks
+     * - Rate limiting
+     */
+    beforeRender?: (templateId: string, params: OgTemplateParams) => void | Promise<void>;
+    /**
+     * Hook called after rendering.
+     *
+     * Useful for:
+     * - Caching generated images
+     * - Cleanup operations
+     * - Sending notifications
+     * - Updating metrics
+     */
+    afterRender?: (templateId: string, params: OgTemplateParams, imageBuffer: Buffer) => void | Promise<void>;
+};
+
+/**
+ * Template management and validation utilities.
+ *
+ * This module provides:
+ * - Template definition and validation
+ * - Template registry and lookup
+ * - Template rendering orchestration
+ *
+ * Templates are the core building blocks of the OGify library.
+ * They define how to convert parameters into OG images.
+ */
+
+/**
+ * Validates that a template configuration has all required fields.
+ *
+ * This function performs structural validation to ensure the template
+ * has all necessary properties. It does NOT validate:
+ * - Renderer function output
+ * - Font availability
+ *
+ * Those validations happen at render time.
+ *
+ * @param config - The template configuration to validate
+ * @returns true if validation passes
+ * @throws Error if any required field is missing or invalid
+ */
+declare function validateTemplate(config: OgTemplate): boolean;
+/**
+ * Defines and validates a new OG template.
+ *
+ * This is the primary way to create templates for use with the TemplateRenderer.
+ * It validates the template configuration and returns it for registration.
+ *
+ * **Benefits of using defineTemplate:**
+ * - Early validation catches configuration errors
+ * - Type safety ensures correct template structure
+ * - Clear intent in code (self-documenting)
+ *
+ * @param config - Complete template configuration including id, name, and renderer function
+ * @returns The validated template configuration
+ * @throws Error if validation fails
+ */
+declare function defineTemplate(config: OgTemplate): OgTemplate;
+/**
+ * Template Handler class for managing multiple templates and rendering them to images.
+ */
+declare class TemplateRenderer {
+    /** Configuration including global settings and lifecycle hooks */
+    private config;
+    /**
+     * Internal registry mapping template IDs to template definitions.
+     *
+     * Using a Map provides:
+     * - O(1) lookup performance
+     * - Guaranteed insertion order
+     * - Better memory efficiency than objects
+     */
+    private templates;
+    /**
+     * Creates a new TemplateRenderer instance.
+     *
+     * @param config - Handler configuration with templates and global settings
+     */
+    constructor(config: OgTemplateRenderer);
+    /**
+     * Registers multiple templates into the internal registry.
+     *
+     * Templates are indexed by their ID for fast lookup.
+     * If a template with the same ID already exists, it will be overwritten.
+     *
+     * @param templates - Array of template definitions to register
+     */
+    private registerTemplates;
+    /**
+     * Retrieves a template by its unique ID.
+     *
+     * This is useful for:
+     * - Checking if a template exists before rendering
+     * - Inspecting template configuration
+     * - Building template selection UIs
+     *
+     * @param id - The template ID to look up
+     * @returns The template definition, or undefined if not found
+     */
+    getTemplate(id: string): OgTemplate | undefined;
+    /**
+     * Gets all registered template IDs.
+     *
+     * Useful for:
+     * - Building template selection dropdowns
+     * - Listing available templates in documentation
+     * - Debugging template registration
+     *
+     * @returns Array of template IDs
+     */
+    getTemplateIds(): string[];
+    /**
+     * Renders a template to a PNG image buffer.
+     *
+     * This is the main method for generating OG images. It:
+     * 1. Looks up the template by ID
+     * 2. Merges default params with user params
+     * 3. Calls lifecycle hooks (if configured)
+     * 4. Delegates to the core rendering engine
+     *
+     * **Parameter Merging:**
+     * User-provided parameters take precedence over default parameters.
+     *
+     * **Custom Dimensions:**
+     * You can override the default 1200x630 dimensions by providing custom width/height.
+     * This is useful for platform-specific requirements (e.g., Twitter, Instagram).
+     *
+     * **Error Handling:**
+     * - Throws if template is not found
+     * - Throws if rendering fails (font loading, HTML generation, etc.)
+     *
+     * @param templateId - ID of the template to render
+     * @param params - Parameters to pass to the template
+     * @param options - Optional rendering options
+     * @param options.width - Custom image width in pixels (default: 1200)
+     * @param options.height - Custom image height in pixels (default: 630)
+     * @returns Promise resolving to a PNG image buffer
+     * @throws Error if template is not found or rendering fails
+     */
+    renderToImage(templateId: string, params: OgTemplateParams, options?: {
+        width: number;
+        height: number;
+    }): Promise<Buffer>;
+}
+/**
+ * Factory function to create a new TemplateRenderer instance.
+ *
+ * This is a convenience wrapper around the TemplateRenderer constructor.
+ * It provides a more functional API style for those who prefer it.
+ *
+ * @param config - Handler configuration with templates and settings
+ * @returns A new TemplateRenderer instance
+ */
+declare function createTemplateRenderer(config: OgTemplateRenderer): TemplateRenderer;
+
+/**
+ * OG image rendering engine.
+ *
+ * This module provides the core rendering pipeline that converts
+ * HTML templates into PNG images suitable for Open Graph meta tags.
+ *
+ * The rendering process uses:
+ * - Satori: Converts HTML/CSS to SVG
+ * - Resvg: Converts SVG to PNG with high quality
+ */
+
+/**
+ * Renders an OG template to a PNG image buffer.
+ *
+ * **Rendering Pipeline:**
+ *
+ * 1. **Font Loading**: Load all fonts specified in the template
+ * 2. **HTML Generation**: Execute the template's renderer function with parameters
+ * 3. **HTML to Element Tree**: Convert HTML string to React-like element tree
+ * 4. **SVG Rendering**: Render element tree to SVG using Satori
+ * 5. **PNG Conversion**: Convert SVG to PNG using Resvg
+ *
+ * @param template - The template definition to render
+ * @param params - Dynamic parameters to populate the template
+ * @param options - Optional rendering options
+ * @param options.width - Custom image width in pixels (default: 1200)
+ * @param options.height - Custom image height in pixels (default: 630)
+ * @returns Promise resolving to a PNG image buffer
+ *
+ * @throws Will throw if:
+ *   - Font loading fails
+ *   - HTML generation fails
+ *   - SVG rendering fails
+ *   - PNG conversion fails
+ */
+declare function renderTemplate(template: OgTemplate, params: OgTemplateParams, options?: {
+    width: number;
+    height: number;
+}): Promise<Buffer>;
+
+/**
+ * Network utility for fetching remote resources with caching.
+ *
+ * This module provides HTTP fetching functionality for loading font files
+ * and other binary assets from remote URLs, with built-in caching to avoid
+ * redundant network requests for the same resources.
+ */
+/**
+ * Fetches a font file from a URL and returns it as an ArrayBuffer, with caching.
+ *
+ * This function is used to download font files from CDNs (like Google Fonts)
+ * so they can be embedded in OG images during server-side rendering.
+ * @param url - The URL of the font file to download
+ * @returns Promise resolving to the font data as an ArrayBuffer
+ *
+ * @throws Will throw if the network request fails or the URL is invalid
+ *
+ * @example
+ * // First call - downloads from network
+ * const fontData1 = await loadFontFromUrl('https://fonts.gstatic.com/s/inter/v12/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZ9hiA.woff2');
+ *
+ * // Second call - returns cached data (no network request)
+ * const fontData2 = await loadFontFromUrl('https://fonts.gstatic.com/s/inter/v12/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZ9hiA.woff2');
+ */
+declare const loadFontFromUrl: (url: string) => Promise<ArrayBuffer>;
+
+export { type OgEmojiProvider, type OgFontConfig, type OgFontFormat, type OgTemplate, type OgTemplateOptions, type OgTemplateParams, type OgTemplateRenderer, TemplateRenderer, createTemplateRenderer, defineTemplate, loadFontFromUrl, renderTemplate, validateTemplate };