@hkdigital/lib-core 0.5.12 → 0.5.14

package/dist/meta/README.md

@@ -0,0 +1,386 @@
+# Meta Utilities
+
+SEO and meta tag utilities for robots.txt and sitemap.xml generation.
+
+## Overview
+
+This module provides functions for generating robots.txt and sitemap.xml
+files dynamically based on configuration. The utilities are used by the
+`routes/(meta)` endpoints but can also be used independently in your own
+server routes.
+
+## Modules
+
+### Robots
+
+Generate robots.txt content with host filtering and sitemap references.
+
+```javascript
+import { generateRobotsTxt, isHostAllowed } from '$lib/meta/robots.js';
+```
+
+### Sitemap
+
+Generate sitemap.xml content from route configurations.
+
+```javascript
+import { generateSitemap } from '$lib/meta/sitemap.js';
+```
+
+## Usage
+
+### Robots.txt Generation
+
+The `generateRobotsTxt()` function creates robots.txt content based on the
+request URL and configuration.
+
+**Basic usage:**
+
+```javascript
+import { generateRobotsTxt } from '$lib/meta/robots.js';
+
+export const GET = async ({ url }) => {
+  const config = {
+    allowedHosts: ['example.com', 'www.example.com'],
+    disallowedPaths: ['/admin', '/api']
+  };
+
+  const robotsTxt = generateRobotsTxt(url, config);
+  return new Response(robotsTxt, {
+    headers: { 'Content-Type': 'text/plain' }
+  });
+};
+```
+
+**Configuration options:**
+
+```javascript
+/**
+ * @typedef {Object} RobotsConfig
+ * @property {string[] | '*'} [allowedHosts]
+ *   Allowed host patterns. Use '*' or omit to allow all hosts.
+ *   Supports wildcards (e.g., '*.example.com')
+ * @property {string[]} [disallowedPaths]
+ *   Paths to block from indexing (e.g., '/admin', '/api/*')
+ */
+```
+
+**Host filtering:**
+
+```javascript
+// Allow only production domain
+const config = {
+  allowedHosts: ['example.com']
+};
+
+// example.com → User-agent: *\nAllow: /\nSitemap: ...
+// test.example.com → User-agent: *\nDisallow: /
+```
+
+**Wildcard patterns:**
+
+```javascript
+// Allow all subdomains
+const config = {
+  allowedHosts: ['example.com', '*.example.com']
+};
+
+// example.com → allowed
+// test.example.com → allowed
+// staging.example.com → allowed
+```
+
+**Path blocking:**
+
+```javascript
+// Block specific paths
+const config = {
+  allowedHosts: ['example.com'],
+  disallowedPaths: ['/admin', '/api', '/private/*']
+};
+
+// Generates:
+// User-agent: *
+// Allow: /
+// Disallow: /admin
+// Disallow: /api
+// Disallow: /private/*
+// Sitemap: https://example.com/sitemap.xml
+```
+
+**Sitemap reference:**
+
+Sitemap reference is always included for allowed hosts:
+
+```
+User-agent: *
+Allow: /
+Sitemap: https://example.com/sitemap.xml
+```
+
+### Sitemap.xml Generation
+
+The `generateSitemap()` function creates sitemap.xml content from route
+configurations.
+
+**Basic usage:**
+
+```javascript
+import { generateSitemap } from '$lib/meta/sitemap.js';
+
+export const GET = async ({ url }) => {
+  const routes = ['/', '/about', '/contact'];
+
+  const sitemap = generateSitemap(url.origin, routes);
+  return new Response(sitemap, {
+    headers: { 'Content-Type': 'application/xml' }
+  });
+};
+```
+
+**Route configuration:**
+
+```javascript
+/**
+ * @typedef {string | SitemapRouteObject} SitemapRoute
+ *   Route can be a simple string path or an object with details
+ */
+
+/**
+ * @typedef {Object} SitemapRouteObject
+ * @property {string} path - Route path (e.g., '/about')
+ * @property {number} [priority] - Priority (0.0 to 1.0)
+ * @property {'always'|'hourly'|'daily'|'weekly'|'monthly'|'yearly'|'never'}
+ *   [changefreq] - Change frequency
+ */
+```
+
+**Simple format (recommended):**
+
+```javascript
+const routes = [
+  '/',        // priority: 1.0, changefreq: 'daily'
+  '/about',   // priority: 0.8, changefreq: 'weekly'
+  '/contact'  // priority: 0.8, changefreq: 'weekly'
+];
+```
+
+**Advanced format with custom settings:**
+
+```javascript
+const routes = [
+  '/',
+  '/about',
+  { path: '/blog', priority: 0.9, changefreq: 'daily' },
+  { path: '/legal', priority: 0.3, changefreq: 'yearly' }
+];
+```
+
+**Mixed format:**
+
+```javascript
+const routes = [
+  '/',
+  '/about',
+  { path: '/blog', priority: 0.9, changefreq: 'daily' },
+  '/contact'
+];
+```
+
+**Default values:**
+
+- Root path (`/`): priority `1.0`, changefreq `daily`
+- Other paths: priority `0.8`, changefreq `weekly`
+- Root path is always included (added automatically if missing)
+
+## Helper Functions
+
+### isHostAllowed()
+
+Check if a hostname matches the allowed hosts configuration.
+
+```javascript
+import { isHostAllowed } from '$lib/meta/robots.js';
+
+// Exact match
+isHostAllowed('example.com', ['example.com']); // true
+isHostAllowed('test.example.com', ['example.com']); // false
+
+// Wildcard match
+isHostAllowed('test.example.com', ['*.example.com']); // true
+isHostAllowed('example.com', ['*.example.com']); // false
+
+// Allow all
+isHostAllowed('anything.com', '*'); // true
+isHostAllowed('anything.com', undefined); // true
+
+// Multiple patterns
+isHostAllowed('example.com', ['example.com', '*.staging.com']); // true
+isHostAllowed('app.staging.com', ['example.com', '*.staging.com']); // true
+```
+
+**Case insensitive:**
+
+```javascript
+isHostAllowed('Example.COM', ['example.com']); // true
+```
+
+**String or array:**
+
+```javascript
+// Single string
+isHostAllowed('example.com', 'example.com'); // true
+
+// Array
+isHostAllowed('example.com', ['example.com']); // true
+```
+
+## Real-World Examples
+
+### Production-only indexing
+
+```javascript
+// Only allow production domain to be indexed
+const robotsConfig = {
+  allowedHosts: ['mysite.com', 'www.mysite.com'],
+  disallowedPaths: ['/admin', '/api']
+};
+
+// Production: mysite.com → Allow + Sitemap
+// Staging: staging.mysite.com → Disallow
+// Development: localhost → Disallow
+```
+
+### Staging and production indexing
+
+```javascript
+// Allow both production and staging subdomains
+const robotsConfig = {
+  allowedHosts: ['mysite.com', '*.mysite.com'],
+  disallowedPaths: ['/admin', '/api']
+};
+
+// Production: mysite.com → Allow + Sitemap
+// Staging: staging.mysite.com → Allow + Sitemap
+// Development: localhost → Disallow
+```
+
+### Allow all hosts (development)
+
+```javascript
+// Allow all hosts - useful during development
+const robotsConfig = {
+  allowedHosts: '*',
+  disallowedPaths: ['/admin']
+};
+
+// All hosts → Allow + Sitemap
+```
+
+### Complex sitemap configuration
+
+```javascript
+const routes = [
+  '/',
+  '/about',
+  '/contact',
+
+  // Blog updated frequently
+  { path: '/blog', priority: 0.9, changefreq: 'daily' },
+
+  // Legal pages rarely change
+  { path: '/privacy', priority: 0.3, changefreq: 'yearly' },
+  { path: '/terms', priority: 0.3, changefreq: 'yearly' },
+
+  // Documentation moderately important
+  { path: '/docs', priority: 0.7, changefreq: 'monthly' }
+];
+```
+
+## Integration with Routes
+
+These utilities are used by the `routes/(meta)` endpoints:
+
+### robots.txt endpoint
+
+```javascript
+// routes/(meta)/robots.txt/+server.js
+import { text } from '@sveltejs/kit';
+import { generateRobotsTxt } from '$lib/meta/robots.js';
+import { robotsConfig } from '../config.js';
+
+export const GET = async ({ url }) => {
+  const robotsTxt = generateRobotsTxt(url, robotsConfig);
+  return text(robotsTxt);
+};
+```
+
+### sitemap.xml endpoint
+
+```javascript
+// routes/(meta)/sitemap.xml/+server.js
+import { generateSitemap } from '$lib/meta/sitemap.js';
+import { siteRoutes } from '../config.js';
+
+export const GET = async ({ url }) => {
+  const sitemap = generateSitemap(url.origin, siteRoutes);
+
+  return new Response(sitemap, {
+    headers: {
+      'Content-Type': 'application/xml',
+      'Cache-Control': 'max-age=0, s-maxage=3600'
+    }
+  });
+};
+```
+
+## Reverse Proxy Configuration
+
+If your app is deployed behind a reverse proxy (nginx, Cloudflare, etc.),
+ensure your SvelteKit adapter is configured to trust proxy headers for
+correct origin detection:
+
+```javascript
+// svelte.config.js
+import adapter from '@sveltejs/adapter-node';
+
+export default {
+  kit: {
+    adapter: adapter({
+      // Trust X-Forwarded-* headers from proxy
+      trustProxy: true
+    })
+  }
+};
+```
+
+Without this, `url.origin` may be `http://localhost` instead of your actual
+domain, and the sitemap directive will point to the wrong URL.
+
+## Testing
+
+Unit tests are included for all functions:
+
+```bash
+# Run meta utility tests
+pnpm test:file src/lib/meta/
+
+# Test coverage includes:
+# - Host pattern matching (exact, wildcard, multiple)
+# - Robots.txt generation (allowed/blocked hosts, paths, sitemap)
+# - Sitemap generation (simple/advanced routes, defaults, mixed formats)
+```
+
+## Type Definitions
+
+TypeScript-style JSDoc type definitions are available:
+
+```javascript
+// robots.js
+import './robots/typedef.js';  // RobotsConfig
+
+// sitemap.js
+import './sitemap/typedef.js';  // SitemapRoute, SitemapRouteObject
+```
+
+See `typedef.js` files in each subdirectory for complete type definitions.

package/dist/meta/robots/index.d.ts

@@ -0,0 +1,37 @@
+/** @typedef {import('./typedef.js').RobotsConfig} RobotsConfig */
+/**
+ * Check if hostname matches allowed hosts pattern
+ *
+ * @param {string} hostname - Hostname to check (e.g., test.mysite.com)
+ * @param {string[] | '*' | undefined} allowedHosts - Allowed host patterns
+ *
+ * @returns {boolean} True if host is allowed
+ */
+export function isHostAllowed(hostname: string, allowedHosts: string[] | "*" | undefined): boolean;
+/**
+ * Generate robots.txt with sitemap reference
+ *
+ * NOTE: If deployed behind a reverse proxy (nginx, Cloudflare, etc.),
+ * ensure your adapter is configured to trust proxy headers for correct
+ * origin detection:
+ *
+ * // svelte.config.js
+ * export default {
+ *   kit: {
+ *     adapter: adapter({
+ *       // Trust X-Forwarded-* headers from proxy
+ *       trustProxy: true
+ *     })
+ *   }
+ * };
+ *
+ * Without this, url.origin may be http://localhost instead of your
+ * actual domain, and the sitemap directive will be omitted.
+ *
+ * @param {URL} url - Request URL object
+ * @param {RobotsConfig} [config] - Robots configuration object
+ *
+ * @returns {string} robots.txt content
+ */
+export function generateRobotsTxt(url: URL, config?: RobotsConfig): string;
+export type RobotsConfig = import("./typedef.js").RobotsConfig;

package/dist/meta/robots/index.js

@@ -0,0 +1,83 @@
+/** @typedef {import('./typedef.js').RobotsConfig} RobotsConfig */
+
+/**
+ * Check if hostname matches allowed hosts pattern
+ *
+ * @param {string} hostname - Hostname to check (e.g., test.mysite.com)
+ * @param {string[] | '*' | undefined} allowedHosts - Allowed host patterns
+ *
+ * @returns {boolean} True if host is allowed
+ */
+export function isHostAllowed(hostname, allowedHosts) {
+  // If not configured or set to '*', allow all hosts
+  if (!allowedHosts || allowedHosts === '*') {
+    return true;
+  }
+
+  if (typeof allowedHosts === 'string') {
+    allowedHosts = [allowedHosts];
+  }
+
+  // Check if hostname matches any allowed pattern
+  return allowedHosts.some((pattern) => {
+    // Convert wildcard pattern to regex
+    // Example: *.mysite.com -> ^.*\.mysite\.com$
+    const regexPattern = pattern
+      .replace(/\./g, '\\.') // Escape dots
+      .replace(/\*/g, '.*'); // * becomes .*
+
+    const regex = new RegExp(`^${regexPattern}$`, 'i');
+    return regex.test(hostname);
+  });
+}
+
+/**
+ * Generate robots.txt with sitemap reference
+ *
+ * NOTE: If deployed behind a reverse proxy (nginx, Cloudflare, etc.),
+ * ensure your adapter is configured to trust proxy headers for correct
+ * origin detection:
+ *
+ * // svelte.config.js
+ * export default {
+ *   kit: {
+ *     adapter: adapter({
+ *       // Trust X-Forwarded-* headers from proxy
+ *       trustProxy: true
+ *     })
+ *   }
+ * };
+ *
+ * Without this, url.origin may be http://localhost instead of your
+ * actual domain, and the sitemap directive will be omitted.
+ *
+ * @param {URL} url - Request URL object
+ * @param {RobotsConfig} [config] - Robots configuration object
+ *
+ * @returns {string} robots.txt content
+ */
+export function generateRobotsTxt(url, config = {}) {
+  const hostAllowed = isHostAllowed(url.hostname, config.allowedHosts);
+
+  // Block entire site if host is not allowed
+  if (!hostAllowed) {
+    return 'User-agent: *\nDisallow: /';
+  }
+
+  // Allow site, but add specific path blocks
+  let content = 'User-agent: *\nAllow: /';
+
+  // Add disallowed paths
+  if (config.disallowedPaths && config.disallowedPaths.length > 0) {
+    config.disallowedPaths.forEach((path) => {
+      content += `\nDisallow: ${path}`;
+    });
+  }
+
+  // Always add sitemap reference
+  if (url.origin) {
+    content += `\nSitemap: ${url.origin}/sitemap.xml`;
+  }
+
+  return content;
+}

package/dist/meta/robots/typedef.d.ts

@@ -0,0 +1,13 @@
+declare const _default: {};
+export default _default;
+export type RobotsConfig = {
+    /**
+     * Allowed host patterns. Use '*' or omit to allow all hosts.
+     * Supports wildcards (e.g., '*.example.com')
+     */
+    allowedHosts?: string[] | "*" | undefined;
+    /**
+     * Paths to block from indexing (e.g., '/admin', '/api/*')
+     */
+    disallowedPaths?: string[] | undefined;
+};

package/dist/meta/robots/typedef.js

@@ -0,0 +1,10 @@
+/**
+ * @typedef {Object} RobotsConfig
+ * @property {string[] | '*'} [allowedHosts]
+ *   Allowed host patterns. Use '*' or omit to allow all hosts.
+ *   Supports wildcards (e.g., '*.example.com')
+ * @property {string[]} [disallowedPaths]
+ *   Paths to block from indexing (e.g., '/admin', '/api/*')
+ */
+
+export default {};

package/dist/meta/robots.d.ts

@@ -0,0 +1 @@
+export { generateRobotsTxt, isHostAllowed } from "./robots/index.js";

package/dist/meta/robots.js

@@ -0,0 +1,5 @@
+/**
+ * Public exports for robots.txt utilities
+ */
+
+export { generateRobotsTxt, isHostAllowed } from './robots/index.js';

package/dist/meta/sitemap/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generate sitemap XML
+ *
+ * @param {string} origin - Base URL (e.g., https://example.com)
+ * @param {SitemapRoute[]} [routes=[]] - Array of routes
+ *
+ * @returns {string} XML sitemap
+ */
+export function generateSitemap(origin: string, routes?: SitemapRoute[]): string;
+export type SitemapRoute = import("./typedef.js").SitemapRoute;
+export type SitemapRouteObject = import("./typedef.js").SitemapRouteObject;

package/dist/meta/sitemap/index.js

@@ -0,0 +1,63 @@
+// @see https://www.sitemaps.org/protocol.html
+
+/** @typedef {import('./typedef.js').SitemapRoute} SitemapRoute */
+/** @typedef {import('./typedef.js').SitemapRouteObject} SitemapRouteObject */
+
+/**
+ * Normalize route to full route object with defaults
+ *
+ * @param {import('./typedef.js').SitemapRoute} route - Route path string or route object
+ *
+ * @returns {SitemapRouteObject} Normalized route object
+ */
+function normalizeRoute(route) {
+  // Handle simple string format
+  if (typeof route === 'string') {
+    return {
+      path: route,
+      priority: route === '/' ? 1.0 : 0.8,
+      changefreq: route === '/' ? 'daily' : 'weekly'
+    };
+  }
+
+  // Handle object format with defaults
+  return {
+    priority: 0.8,
+    changefreq: 'weekly',
+    ...route
+  };
+}
+
+/**
+ * Generate sitemap XML
+ *
+ * @param {string} origin - Base URL (e.g., https://example.com)
+ * @param {SitemapRoute[]} [routes=[]] - Array of routes
+ *
+ * @returns {string} XML sitemap
+ */
+export function generateSitemap(origin, routes = []) {
+  // Ensure root path is always included (failsafe)
+  const hasRoot = routes.some((route) => {
+    const path = typeof route === 'string' ? route : route.path;
+    return path === '/';
+  });
+
+  const normalizedRoutes = hasRoot ? routes : ['/', ...routes];
+
+  const urls = normalizedRoutes
+    .map(normalizeRoute)
+    .map(
+      (route) => `
+  <url>
+    <loc>${origin}${route.path}</loc>
+    <changefreq>${route.changefreq}</changefreq>
+    <priority>${route.priority}</priority>
+  </url>`
+    )
+    .join('');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${urls}
+</urlset>`;
+}

package/dist/meta/sitemap/typedef.d.ts

@@ -0,0 +1,20 @@
+declare const _default: {};
+export default _default;
+export type SitemapRouteObject = {
+    /**
+     * - Route path (e.g., '/about')
+     */
+    path: string;
+    /**
+     * - Priority (0.0 to 1.0)
+     */
+    priority?: number | undefined;
+    /**
+     * - Change frequency
+     */
+    changefreq?: "hourly" | "daily" | "weekly" | "always" | "monthly" | "yearly" | "never" | undefined;
+};
+/**
+ * Route can be a simple string path or an object with details
+ */
+export type SitemapRoute = string | SitemapRouteObject;

package/dist/meta/sitemap/typedef.js

@@ -0,0 +1,14 @@
+/**
+ * @typedef {Object} SitemapRouteObject
+ * @property {string} path - Route path (e.g., '/about')
+ * @property {number} [priority] - Priority (0.0 to 1.0)
+ * @property {'always'|'hourly'|'daily'|'weekly'|'monthly'|'yearly'|'never'}
+ *   [changefreq] - Change frequency
+ */
+
+/**
+ * @typedef {string | SitemapRouteObject} SitemapRoute
+ *   Route can be a simple string path or an object with details
+ */
+
+export default {};

package/dist/meta/sitemap.d.ts

@@ -0,0 +1 @@
+export { generateSitemap } from "./sitemap/index.js";

package/dist/meta/sitemap.js

@@ -0,0 +1,5 @@
+/**
+ * Public exports for sitemap utilities
+ */
+
+export { generateSitemap } from './sitemap/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.5.12",
+	"version": "0.5.14",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"