@ogify/core 0.1.1

package/dist/index.mjs

@@ -0,0 +1,481 @@
+import satori from 'satori';
+import { html } from 'satori-html';
+
+// src/template.ts
+
+// src/utils/google-font-detector.ts
+var USER_AGENTS = {
+  ttf: "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.20) Gecko/20081217 Firefox/2.0.0.20",
+  woff: "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:27.0) Gecko/20100101 Firefox/27.0"
+};
+var utils = {
+  /**
+   * Converts a CSS unicode-range string to an array of code points and ranges.
+   *
+   * @param input - CSS unicode-range value (e.g., "U+0041, U+0061-007A")
+   * @returns Array of code points and ranges
+   *
+   * @example
+   * toUnicodeRange("U+0041, U+0061-007A, U+20AC")
+   * // Returns: [65, [97, 122], 8364]
+   * // Represents: 'A', 'a-z', '€'
+   */
+  toUnicodeRange: (input) => {
+    return input.split(", ").map((range) => {
+      range = range.replaceAll("U+", "");
+      const [start, end] = range.split("-").map((hex) => parseInt(hex, 16));
+      if (isNaN(end)) {
+        return start;
+      }
+      return [start, end];
+    });
+  },
+  /**
+   * Checks if a character's code point falls within a Unicode range.
+   *
+   * @param segment - The character to check
+   * @param range - Array of code points and ranges to check against
+   * @returns true if the character is in the range, false otherwise
+   *
+   * @example
+   * checkSegmentInRange('A', [65, [97, 122]]) // true (65 is in the range)
+   * checkSegmentInRange('a', [65, [97, 122]]) // true (97 is in [97, 122])
+   * checkSegmentInRange('€', [65, [97, 122]]) // false (8364 is not in the range)
+   */
+  checkSegmentInRange: (segment, range) => {
+    if (range.length === 0) {
+      return false;
+    }
+    const codePoint = segment.codePointAt(0);
+    if (!codePoint) return false;
+    return range.some((val) => {
+      if (typeof val === "number") {
+        return codePoint === val;
+      } else {
+        const [start, end] = val;
+        return start <= codePoint && codePoint <= end;
+      }
+    });
+  }
+};
+var GoogleFontDetector = class {
+  /**
+   * Maps font URLs to their Unicode ranges.
+   * Key: Font file URL
+   * Value: Array of Unicode code points/ranges that the font supports
+   */
+  rangesByUrl = {};
+  /** The font configuration to detect */
+  font;
+  constructor(font) {
+    this.font = font;
+  }
+  /**
+   * Detects which Google Font URLs are needed to render the given text.
+   *
+   * This method:
+   * 1. Loads the font CSS from Google Fonts (if not already loaded)
+   * 2. Splits the text into individual characters
+   * 3. Finds the font URL for each character based on Unicode ranges
+   * 4. Returns unique URLs (no duplicates)
+   *
+   * @param text - The text to analyze
+   * @returns Promise resolving to an array of unique font file URLs
+   *
+   * @example
+   * const urls = await detector.detect('Hello 世界');
+   * // Returns: [
+   * //   'https://fonts.gstatic.com/.../latin.woff2',
+   * //   'https://fonts.gstatic.com/.../chinese.woff2'
+   * // ]
+   */
+  async detect(text) {
+    await this.load();
+    const detectedUrls = text.split("").map((segment) => {
+      return this.detectSegment(segment);
+    }).filter((url) => url !== null);
+    const uniqueUrls = [...new Set(detectedUrls)];
+    return uniqueUrls;
+  }
+  /**
+   * Finds the font URL that supports rendering a specific character.
+   *
+   * @param segment - A single character to check
+   * @returns The font URL that supports this character, or null if not found
+   */
+  detectSegment(segment) {
+    for (const url of Object.keys(this.rangesByUrl)) {
+      const range = this.rangesByUrl[url];
+      if (range.length === 0 || utils.checkSegmentInRange(segment, range)) {
+        return url;
+      }
+    }
+    return null;
+  }
+  /**
+   * Fetches and parses the Google Fonts CSS to extract font URLs and Unicode ranges.
+   *
+   * This method:
+   * 1. Constructs the Google Fonts API URL with the font family, weight, and style
+   * 2. Fetches the CSS with an appropriate User-Agent to get the desired format
+   * 3. Parses each @font-face rule to extract URLs and unicode-range values
+   * 4. Stores the mapping in `rangesByUrl` for later character matching
+   */
+  async load() {
+    const { name, style, weight, format = "woff" } = this.font;
+    const apiUrl = `https://fonts.googleapis.com/css2?display=swap&family=${name.split(" ").join("+")}:${style === "italic" ? "ital," : ""}wght@${style === "italic" ? "1," : ""}${weight || 400}`;
+    const content = await (await fetch(apiUrl, {
+      headers: {
+        "User-Agent": format === "ttf" ? USER_AGENTS.ttf : USER_AGENTS.woff
+      }
+    })).text();
+    content.split("@font-face").forEach((fontFace) => {
+      this.extractUrlAndRange(fontFace);
+    });
+  }
+  /**
+   * Extracts the font URL and Unicode range from a @font-face CSS rule.
+   *
+   * @param input - A @font-face CSS rule as a string
+   *
+   * @example
+   * Input:
+   * ```
+   * {
+   *   font-family: 'Inter';
+   *   src: url(https://fonts.gstatic.com/.../inter.woff2) format('woff2');
+   *   unicode-range: U+0041-005A, U+0061-007A;
+   * }
+   * ```
+   *
+   * Stores: rangesByUrl['https://fonts.gstatic.com/.../inter.woff2'] = [[65, 90], [97, 122]]
+   */
+  extractUrlAndRange(input) {
+    if (input && input.includes("url") && input.includes("format")) {
+      const [, url] = input.match(/url\((.*?)\)/) || [];
+      const [, format] = input.match(/format\(['"](.+?)['"]\)/) || [];
+      const [, unicodeRange] = input.match(/unicode-range:\s*(.*?);/) || [];
+      if (!["woff", "woff2", "truetype"].includes(format)) {
+        console.warn(`[Warning] Unsupported font format: ${format}`);
+      }
+      if (url) {
+        if (unicodeRange) {
+          this.rangesByUrl[url] = [...utils.toUnicodeRange(unicodeRange)];
+        } else {
+          this.rangesByUrl[url] = [];
+        }
+      }
+    }
+  }
+};
+
+// src/utils/emoji-loader.ts
+var ZERO_WIDTH_JOINER = String.fromCharCode(8205);
+var VARIATION_SELECTOR_REGEX = /\uFE0F/g;
+function getIconCode(char) {
+  const normalizedChar = char.indexOf(ZERO_WIDTH_JOINER) < 0 ? char.replace(VARIATION_SELECTOR_REGEX, "") : char;
+  return toCodePoint(normalizedChar);
+}
+function toCodePoint(unicodeSurrogates) {
+  const codePoints = [];
+  let currentChar = 0;
+  let highSurrogate = 0;
+  let index = 0;
+  while (index < unicodeSurrogates.length) {
+    currentChar = unicodeSurrogates.charCodeAt(index++);
+    if (highSurrogate) {
+      const codePoint = 65536 + (highSurrogate - 55296 << 10) + (currentChar - 56320);
+      codePoints.push(codePoint.toString(16));
+      highSurrogate = 0;
+    } else if (currentChar >= 55296 && currentChar <= 56319) {
+      highSurrogate = currentChar;
+    } else {
+      codePoints.push(currentChar.toString(16));
+    }
+  }
+  return codePoints.join("-");
+}
+var apis = {
+  twemoji: (code) => `https://cdnjs.cloudflare.com/ajax/libs/twemoji/14.0.2/svg/${code.toLowerCase()}.svg`,
+  openmoji: "https://cdn.jsdelivr.net/npm/@svgmoji/openmoji@2.0.0/svg/",
+  blobmoji: "https://cdn.jsdelivr.net/npm/@svgmoji/blob@2.0.0/svg/",
+  noto: "https://cdn.jsdelivr.net/gh/svgmoji/svgmoji/packages/svgmoji__noto/svg/",
+  fluent: (code) => `https://cdn.jsdelivr.net/gh/shuding/fluentui-emoji-unicode/assets/${code.toLowerCase()}_color.svg`,
+  fluentFlat: (code) => `https://cdn.jsdelivr.net/gh/shuding/fluentui-emoji-unicode/assets/${code.toLowerCase()}_flat.svg`
+};
+var cache = {};
+async function loadEmoji(type, text) {
+  const code = getIconCode(text);
+  const cacheKey = `${type}:${code}`;
+  if (cacheKey in cache) {
+    return cache[cacheKey];
+  }
+  if (!type || !apis[type]) {
+    type = "noto";
+  }
+  const api = apis[type];
+  const baseUrl = typeof api === "function" ? api(code) : api;
+  const fullUrl = typeof api === "function" ? baseUrl : `${baseUrl}${code.toUpperCase()}.svg`;
+  const emojiPromise = fetch(fullUrl).then((response) => response.text()).then((svgContent) => `data:image/svg+xml;base64,${btoa(svgContent)}`);
+  cache[cacheKey] = emojiPromise;
+  return emojiPromise;
+}
+
+// src/utils/fetcher.ts
+var cache2 = {};
+var loadFontFromUrl = async (url) => {
+  if (url in cache2) {
+    return cache2[url];
+  }
+  const fontData = fetch(url).then((response) => response.arrayBuffer());
+  cache2[url] = fontData;
+  return fontData;
+};
+
+// src/utils/additional-asset-loader.ts
+var loadAdditionalAsset = async (options) => {
+  const { code, segment, fonts, emojiProvider } = options;
+  if (code === "emoji") {
+    return await loadEmoji(emojiProvider, segment);
+  }
+  const fallbackFonts = [];
+  await Promise.all(
+    fonts.map(async (fontConfig) => {
+      const detector = new GoogleFontDetector(fontConfig);
+      const detectedFontUrls = await detector.detect(segment);
+      const fontDataArray = await Promise.all(
+        detectedFontUrls.map(async (fontUrl) => {
+          return await loadFontFromUrl(fontUrl);
+        })
+      );
+      fontDataArray.forEach((fontData, index) => {
+        fallbackFonts.push({
+          // Generate unique name: e.g., "Inter-Fallback-0", "Inter-Fallback-1"
+          name: `${fontConfig.name}-Fallback-${index}`,
+          // The downloaded font binary data
+          data: fontData,
+          // Inherit style from the original font config (default: 'normal')
+          style: fontConfig.style || "normal",
+          // Inherit weight from the original font config (default: 400)
+          weight: fontConfig.weight || 400
+        });
+      });
+    })
+  );
+  return fallbackFonts;
+};
+
+// src/utils/font-loader.ts
+var loadFonts = async (fonts) => {
+  const loadedFonts = await Promise.all(fonts.map((font) => loadFont(font)));
+  return loadedFonts.filter((font) => font !== null);
+};
+var loadFont = async (font) => {
+  if (font.data) {
+    return {
+      name: font.name,
+      data: font.data,
+      style: font.style || "normal",
+      weight: font.weight || 400
+    };
+  }
+  if (font.url) {
+    const buffer = await loadFontFromUrl(font.url);
+    return {
+      name: font.name,
+      data: Buffer.from(buffer),
+      style: font.style || "normal",
+      weight: font.weight || 400
+    };
+  }
+  const detector = new GoogleFontDetector(font);
+  const detectedFonts = await detector.detect("a");
+  if (detectedFonts.length === 0) {
+    return null;
+  }
+  return {
+    name: font.name,
+    data: await loadFontFromUrl(detectedFonts[0]),
+    style: font.style || "normal",
+    weight: font.weight || 400
+  };
+};
+
+// src/template.ts
+var DEFAULT_WIDTH = 1200;
+var DEFAULT_HEIGHT = 630;
+async function renderTemplate(template, params, options) {
+  const width = options?.width || DEFAULT_WIDTH;
+  const height = options?.height || DEFAULT_HEIGHT;
+  const satoriFonts = await loadFonts(template.fonts);
+  const htmlString = template.renderer({
+    params,
+    width,
+    height
+  });
+  const element = html(htmlString);
+  const svg = await satori(element, {
+    // Image dimensions (customizable via options parameter)
+    width,
+    height,
+    // Loaded fonts for text rendering
+    fonts: satoriFonts,
+    // Embed fonts in the SVG for portability
+    embedFont: true,
+    // Dynamic asset loader for emojis and fallback fonts
+    // This is called when Satori encounters characters that need special handling
+    loadAdditionalAsset: async (code, segment) => {
+      return loadAdditionalAsset({
+        code,
+        // Asset type ('emoji' or other)
+        segment,
+        // The character(s) to load
+        fonts: template.fonts,
+        // Available fonts for fallback detection
+        emojiProvider: template.emojiProvider || "noto"
+        // Emoji provider (default: noto)
+      });
+    }
+  });
+  const { renderAsync } = await import('@resvg/resvg-js');
+  const pngData = await renderAsync(svg, {
+    fitTo: {
+      mode: "width",
+      // Scale based on width, maintain aspect ratio
+      value: width
+    }
+  });
+  return Buffer.from(pngData.asPng());
+}
+
+// src/renderer.ts
+function validateTemplate(config) {
+  if (!config.id) {
+    throw new Error("Template must have an id");
+  }
+  if (!config.name) {
+    throw new Error("Template must have a name");
+  }
+  if (typeof config.renderer !== "function") {
+    throw new Error("Template must have a renderer function");
+  }
+  return true;
+}
+function defineTemplate(config) {
+  validateTemplate(config);
+  return config;
+}
+var TemplateRenderer = class {
+  /** Configuration including global settings and lifecycle hooks */
+  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
+   */
+  templates = /* @__PURE__ */ new Map();
+  /**
+   * Creates a new TemplateRenderer instance.
+   *
+   * @param config - Handler configuration with templates and global settings
+   */
+  constructor(config) {
+    this.config = config;
+    this.registerTemplates(config.templates);
+  }
+  /**
+   * 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
+   */
+  registerTemplates(templates) {
+    for (const template of templates) {
+      this.templates.set(template.id, template);
+    }
+  }
+  /**
+   * 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) {
+    return this.templates.get(id);
+  }
+  /**
+   * 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() {
+    return Array.from(this.templates.keys());
+  }
+  /**
+   * 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
+   */
+  async renderToImage(templateId, params, options) {
+    const template = this.getTemplate(templateId);
+    if (!template) {
+      throw new Error(`Template '${templateId}' not found`);
+    }
+    const mergedParams = {
+      ...this.config.defaultParams,
+      ...params
+    };
+    if (this.config.beforeRender) {
+      await this.config.beforeRender(templateId, mergedParams);
+    }
+    const imageBuffer = await renderTemplate(template, mergedParams, options);
+    if (this.config.afterRender) {
+      await this.config.afterRender(templateId, mergedParams, imageBuffer);
+    }
+    return imageBuffer;
+  }
+};
+function createTemplateRenderer(config) {
+  return new TemplateRenderer(config);
+}
+/*! Copyright Twitter Inc. and other contributors. Licensed under MIT */
+
+export { TemplateRenderer, createTemplateRenderer, defineTemplate, loadFontFromUrl, renderTemplate, validateTemplate };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ogify/core",
+  "version": "0.1.1",
+  "description": "Core types and utilities for OGify Open Graph image generator",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "author": {
+    "name": "Hung Pham - @revolabs-io",
+    "email": "info@revolabs.io"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "satori": "^0.18.3",
+    "satori-html": "^0.3.2",
+    "@resvg/resvg-js": "^2.6.2"
+  },
+  "devDependencies": {
+    "@types/node": "^18",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}