katanakit-js 2.1.5

package/dist/adapters/index.js

@@ -0,0 +1,2 @@
+export * from "./astro/index.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/adapters/nuxt/index.d.ts

@@ -0,0 +1,2 @@
+export { useEventResponse, useSafeResponse, useUnwrap } from "./nuxt.service.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/nuxt/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/nuxt/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/adapters/nuxt/index.js

@@ -0,0 +1,2 @@
+export { useEventResponse, useSafeResponse, useUnwrap } from "./nuxt.service.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/nuxt/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/nuxt/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/adapters/nuxt/nuxt.service.d.ts

@@ -0,0 +1,83 @@
+import type { FetchResult } from "../../types/index.js";
+/**
+ * Unwraps a KatanaKit Safe Result, throwing an H3-compatible error on failure.
+ * Returns the data directly on success.
+ *
+ * @param result - The Safe Result from `useFetch`, `useGet`, `usePost`, etc.
+ * @param context - Optional context prefix for the error message.
+ * @returns The data from the result.
+ * @throws H3-compatible error with the appropriate status code.
+ *
+ * @example
+ * ```ts
+ * // server/api/pokemon/[id].ts
+ * import { useGet } from "katanakit-js";
+ * import { useUnwrap } from "katanakit-js/adapters/nuxt";
+ *
+ * export default defineEventHandler(async (event) => {
+ *   const id = getRouterParam(event, "id");
+ *   const result = await useGet("pokeapi", "pokemonById", { params: { id } });
+ *   return useUnwrap(result, `Pokemon ${id}`);
+ * });
+ * ```
+ */
+export declare function useUnwrap<T>(result: FetchResult<T>, context?: string): T;
+/**
+ * Creates a Safe Result response for Nuxt API routes.
+ * Returns the data with proper status code on success,
+ * or an error response on failure.
+ *
+ * @param result - The Safe Result from any KatanaKit fetch method.
+ * @returns An H3-compatible response object.
+ *
+ * @example
+ * ```ts
+ * // server/api/users.ts
+ * import { useGet } from "katanakit-js";
+ * import { useSafeResponse } from "katanakit-js/adapters/nuxt";
+ *
+ * export default defineEventHandler(async () => {
+ *   const result = await useGet("api", "users");
+ *   return useSafeResponse(result);
+ * });
+ * ```
+ */
+export declare function useSafeResponse<T>(result: FetchResult<T>): {
+    data: T | null;
+    error: {
+        message: string;
+        status: number;
+    } | null;
+    ok: boolean;
+};
+/**
+ * Maps a KatanaKit Safe Result to an H3 event response.
+ * Sets the appropriate status code and returns the data or error.
+ *
+ * @param event - The H3 event object.
+ * @param result - The Safe Result from any KatanaKit fetch method.
+ * @returns The data on success.
+ *
+ * @example
+ * ```ts
+ * // server/api/products.ts
+ * import { useFetch } from "katanakit-js";
+ * import { useEventResponse } from "katanakit-js/adapters/nuxt";
+ *
+ * export default defineEventHandler(async (event) => {
+ *   const result = await useFetch("shop", "products");
+ *   return useEventResponse(event, result);
+ * });
+ * ```
+ */
+export declare function useEventResponse<T>(event: {
+    node: {
+        res: {
+            statusCode: number;
+        };
+    };
+}, result: FetchResult<T>): T | {
+    error: string;
+    status: number;
+};
+//# sourceMappingURL=nuxt.service.d.ts.map

package/dist/adapters/nuxt/nuxt.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nuxt.service.d.ts","sourceRoot":"","sources":["../../../src/adapters/nuxt/nuxt.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAYxE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG;IAC3D,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClD,EAAE,EAAE,OAAO,CAAC;CACZ,CAaA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EACjC,KAAK,EAAE;IAAE,IAAI,EAAE;QAAE,GAAG,EAAE;YAAE,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,EAChD,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GACpB,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAWvC"}

package/dist/adapters/nuxt/nuxt.service.js

@@ -0,0 +1,104 @@
+/**
+ * Unwraps a KatanaKit Safe Result, throwing an H3-compatible error on failure.
+ * Returns the data directly on success.
+ *
+ * @param result - The Safe Result from `useFetch`, `useGet`, `usePost`, etc.
+ * @param context - Optional context prefix for the error message.
+ * @returns The data from the result.
+ * @throws H3-compatible error with the appropriate status code.
+ *
+ * @example
+ * ```ts
+ * // server/api/pokemon/[id].ts
+ * import { useGet } from "katanakit-js";
+ * import { useUnwrap } from "katanakit-js/adapters/nuxt";
+ *
+ * export default defineEventHandler(async (event) => {
+ *   const id = getRouterParam(event, "id");
+ *   const result = await useGet("pokeapi", "pokemonById", { params: { id } });
+ *   return useUnwrap(result, `Pokemon ${id}`);
+ * });
+ * ```
+ */
+export function useUnwrap(result, context) {
+    if (result.ok) {
+        return result.data;
+    }
+    const message = context ? `${context}: ${result.error.message}` : result.error.message;
+    const statusCode = result.error.status || 500;
+    // Dynamic import to avoid hard dependency on h3.
+    // Consumers must have h3 installed (it comes with Nuxt).
+    throw createH3Error(statusCode, message);
+}
+/**
+ * Creates a Safe Result response for Nuxt API routes.
+ * Returns the data with proper status code on success,
+ * or an error response on failure.
+ *
+ * @param result - The Safe Result from any KatanaKit fetch method.
+ * @returns An H3-compatible response object.
+ *
+ * @example
+ * ```ts
+ * // server/api/users.ts
+ * import { useGet } from "katanakit-js";
+ * import { useSafeResponse } from "katanakit-js/adapters/nuxt";
+ *
+ * export default defineEventHandler(async () => {
+ *   const result = await useGet("api", "users");
+ *   return useSafeResponse(result);
+ * });
+ * ```
+ */
+export function useSafeResponse(result) {
+    if (result.ok) {
+        return { data: result.data, error: null, ok: true };
+    }
+    return {
+        data: null,
+        error: {
+            message: result.error.message,
+            status: result.error.status,
+        },
+        ok: false,
+    };
+}
+/**
+ * Maps a KatanaKit Safe Result to an H3 event response.
+ * Sets the appropriate status code and returns the data or error.
+ *
+ * @param event - The H3 event object.
+ * @param result - The Safe Result from any KatanaKit fetch method.
+ * @returns The data on success.
+ *
+ * @example
+ * ```ts
+ * // server/api/products.ts
+ * import { useFetch } from "katanakit-js";
+ * import { useEventResponse } from "katanakit-js/adapters/nuxt";
+ *
+ * export default defineEventHandler(async (event) => {
+ *   const result = await useFetch("shop", "products");
+ *   return useEventResponse(event, result);
+ * });
+ * ```
+ */
+export function useEventResponse(event, result) {
+    if (result.ok) {
+        event.node.res.statusCode = 200;
+        return result.data;
+    }
+    event.node.res.statusCode = result.error.status || 500;
+    return {
+        error: result.error.message,
+        status: result.error.status,
+    };
+}
+// Internal helper: creates an error that looks like an H3 error.
+// We don't import h3 directly to avoid a hard peer dependency.
+function createH3Error(statusCode, message) {
+    const error = new Error(message);
+    error.statusCode = statusCode;
+    return error;
+}
+//# sourceMappingURL=nuxt.service.js.map

package/dist/adapters/nuxt/nuxt.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nuxt.service.js","sourceRoot":"","sources":["../../../src/adapters/nuxt/nuxt.service.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,SAAS,CAAI,MAAsB,EAAE,OAAgB;IACpE,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,MAAM,CAAC,IAAI,CAAC;IACpB,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;IAEvF,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,GAAG,CAAC;IAE9C,iDAAiD;IACjD,yDAAyD;IACzD,MAAM,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,eAAe,CAAI,MAAsB;IAKxD,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACrD,CAAC;IAED,OAAO;QACN,IAAI,EAAE,IAAI;QACV,KAAK,EAAE;YACN,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;YAC7B,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;SAC3B;QACD,EAAE,EAAE,KAAK;KACT,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAC/B,KAAgD,EAChD,MAAsB;IAEtB,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC;QAChC,OAAO,MAAM,CAAC,IAAI,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,GAAG,CAAC;IACvD,OAAO;QACN,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;QAC3B,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;KAC3B,CAAC;AACH,CAAC;AAED,iEAAiE;AACjE,+DAA+D;AAC/D,SAAS,aAAa,CAAC,UAAkB,EAAE,OAAe;IACzD,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,OAAO,CAAmC,CAAC;IACnE,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC;IAC9B,OAAO,KAAK,CAAC;AACd,CAAC"}

package/dist/config/index.d.ts

@@ -0,0 +1,3 @@
+export { type SeoMeta, useGenerateMetaTags, useHeadTags, useRssHeadLink, useTitle, } from "./seo.service.js";
+export { type SiteConfig, siteConfig } from "./site.config.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,OAAO,EACZ,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,QAAQ,GACR,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/config/index.js

@@ -0,0 +1,3 @@
+export { useGenerateMetaTags, useHeadTags, useRssHeadLink, useTitle, } from "./seo.service.js";
+export { siteConfig } from "./site.config.js";
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,QAAQ,GACR,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAmB,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/config/seo.service.d.ts

@@ -0,0 +1,72 @@
+import type { SiteConfig } from "./site.config.js";
+/**
+ * SEO meta tag configuration for a single page.
+ */
+export interface SeoMeta {
+    /** Page title (will be suffixed with site title). */
+    title: string;
+    /** Page description (falls back to site description). */
+    description?: string;
+    /** Canonical URL (absolute). If omitted, derived from `url`. */
+    canonical?: string;
+    /** Page URL (absolute, e.g. "https://example.com/blog/post/"). */
+    url?: string;
+    /** OG image URL (absolute). Falls back to site config. */
+    ogImage?: string;
+    /** Content type: "website" | "article" | "profile" (default: "website"). */
+    ogType?: "website" | "article" | "profile";
+    /** Article published date (ISO string, for og:type=article). */
+    publishedTime?: string;
+    /** Article modified date (ISO string, for og:type=article). */
+    modifiedTime?: string;
+    /** Article author (for og:type=article). */
+    author?: string;
+    /** Article tags (for og:type=article). */
+    tags?: string[];
+    /** Whether to add noindex (default: false). */
+    noindex?: boolean;
+}
+/**
+ * Generates all `<head>` meta tags for SEO, Open Graph, Twitter Card,
+ * canonical URL, and JSON-LD structured data.
+ *
+ * @param config - Site-wide configuration.
+ * @param meta - Page-specific meta.
+ * @returns HTML string of meta tags to inject in `<head>`.
+ *
+ * @example
+ * ```astro
+ * ---
+ * import { siteConfig } from "@/config/site.config";
+ * import { useGenerateMetaTags } from "@/config/seo.service";
+ *
+ * const metaTags = useGenerateMetaTags(siteConfig, {
+ *   title: "My Blog Post",
+ *   description: "A great post about TypeScript",
+ *   url: "https://example.com/blog/my-post/",
+ *   ogType: "article",
+ *   publishedTime: "2024-01-15T00:00:00Z",
+ * });
+ * ---
+ * <head>
+ *   <Fragment set:html={metaTags} />
+ * </head>
+ * ```
+ */
+export declare function useGenerateMetaTags(config: SiteConfig, meta: SeoMeta): string;
+/**
+ * Generates a `<title>` tag string.
+ */
+export declare function useTitle(config: SiteConfig, pageTitle?: string): string;
+/**
+ * Generates the RSS `<link>` tag for the `<head>`.
+ */
+export declare function useRssHeadLink(config: SiteConfig): string;
+/**
+ * Generates all default `<head>` meta tags for a page (title, description,
+ * canonical, OG, Twitter, JSON-LD, RSS link).
+ *
+ * Convenience wrapper around `useGenerateMetaTags` + `useRssHeadLink`.
+ */
+export declare function useHeadTags(config: SiteConfig, meta: SeoMeta): string;
+//# sourceMappingURL=seo.service.d.ts.map

package/dist/config/seo.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo.service.d.ts","sourceRoot":"","sources":["../../src/config/seo.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,OAAO;IACvB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC3C,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAmG7E;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAKvE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAKzD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAIrE"}

package/dist/config/seo.service.js

@@ -0,0 +1,190 @@
+/**
+ * Generates all `<head>` meta tags for SEO, Open Graph, Twitter Card,
+ * canonical URL, and JSON-LD structured data.
+ *
+ * @param config - Site-wide configuration.
+ * @param meta - Page-specific meta.
+ * @returns HTML string of meta tags to inject in `<head>`.
+ *
+ * @example
+ * ```astro
+ * ---
+ * import { siteConfig } from "@/config/site.config";
+ * import { useGenerateMetaTags } from "@/config/seo.service";
+ *
+ * const metaTags = useGenerateMetaTags(siteConfig, {
+ *   title: "My Blog Post",
+ *   description: "A great post about TypeScript",
+ *   url: "https://example.com/blog/my-post/",
+ *   ogType: "article",
+ *   publishedTime: "2024-01-15T00:00:00Z",
+ * });
+ * ---
+ * <head>
+ *   <Fragment set:html={metaTags} />
+ * </head>
+ * ```
+ */
+export function useGenerateMetaTags(config, meta) {
+    const tags = [];
+    const fullTitle = meta.title === config.title ? config.title : `${meta.title} | ${config.title}`;
+    const description = meta.description ?? config.description;
+    const url = meta.url ?? config.site;
+    const ogImage = meta.ogImage ?? config.ogImage;
+    const ogImageUrl = ogImage
+        ? ogImage.startsWith("http")
+            ? ogImage
+            : `${config.site}${ogImage}`
+        : undefined;
+    // Basic meta tags.
+    tags.push(`<title>${escapeHtml(fullTitle)}</title>`);
+    tags.push(`<meta name="description" content="${escapeAttr(description)}" />`);
+    if (config.author) {
+        tags.push(`<meta name="author" content="${escapeAttr(config.author)}" />`);
+    }
+    // Canonical URL.
+    if (config.seo.canonical && url) {
+        const canonical = meta.canonical ?? url;
+        tags.push(`<link rel="canonical" href="${escapeAttr(canonical)}" />`);
+    }
+    // Noindex.
+    if (meta.noindex || config.seo.noindex) {
+        tags.push('<meta name="robots" content="noindex, nofollow" />');
+    }
+    // Open Graph.
+    if (config.seo.openGraph) {
+        tags.push(`<meta property="og:type" content="${meta.ogType ?? "website"}" />`);
+        tags.push(`<meta property="og:title" content="${escapeAttr(fullTitle)}" />`);
+        tags.push(`<meta property="og:description" content="${escapeAttr(description)}" />`);
+        tags.push(`<meta property="og:site_name" content="${escapeAttr(config.title)}" />`);
+        tags.push(`<meta property="og:locale" content="${escapeAttr(config.lang.replace("-", "_"))}" />`);
+        if (url) {
+            tags.push(`<meta property="og:url" content="${escapeAttr(url)}" />`);
+        }
+        if (ogImageUrl) {
+            tags.push(`<meta property="og:image" content="${escapeAttr(ogImageUrl)}" />`);
+            tags.push(`<meta property="og:image:alt" content="${escapeAttr(fullTitle)}" />`);
+        }
+        // Article-specific OG tags.
+        if (meta.ogType === "article") {
+            if (meta.publishedTime) {
+                tags.push(`<meta property="article:published_time" content="${escapeAttr(meta.publishedTime)}" />`);
+            }
+            if (meta.modifiedTime) {
+                tags.push(`<meta property="article:modified_time" content="${escapeAttr(meta.modifiedTime)}" />`);
+            }
+            if (meta.author) {
+                tags.push(`<meta property="article:author" content="${escapeAttr(meta.author)}" />`);
+            }
+            if (meta.tags) {
+                for (const tag of meta.tags) {
+                    tags.push(`<meta property="article:tag" content="${escapeAttr(tag)}" />`);
+                }
+            }
+        }
+    }
+    // Twitter Card.
+    if (config.seo.twitterCard) {
+        tags.push('<meta name="twitter:card" content="summary_large_image" />');
+        tags.push(`<meta name="twitter:title" content="${escapeAttr(fullTitle)}" />`);
+        tags.push(`<meta name="twitter:description" content="${escapeAttr(description)}" />`);
+        if (config.twitter) {
+            tags.push(`<meta name="twitter:site" content="@${escapeAttr(config.twitter)}" />`);
+            tags.push(`<meta name="twitter:creator" content="@${escapeAttr(config.twitter)}" />`);
+        }
+        if (ogImageUrl) {
+            tags.push(`<meta name="twitter:image" content="${escapeAttr(ogImageUrl)}" />`);
+        }
+    }
+    // JSON-LD structured data.
+    if (config.seo.jsonLd) {
+        const jsonLd = buildJsonLd(config, meta);
+        // Escape <, >, & to prevent XSS via </script> breakout.
+        const safeJson = JSON.stringify(jsonLd)
+            .replace(/</g, "\\u003c")
+            .replace(/>/g, "\\u003e")
+            .replace(/&/g, "\\u0026");
+        tags.push(`<script type="application/ld+json">${safeJson}</script>`);
+    }
+    return tags.join("\n");
+}
+/**
+ * Generates a `<title>` tag string.
+ */
+export function useTitle(config, pageTitle) {
+    if (!pageTitle || pageTitle === config.title) {
+        return `<title>${escapeHtml(config.title)}</title>`;
+    }
+    return `<title>${escapeHtml(`${pageTitle} | ${config.title}`)}</title>`;
+}
+/**
+ * Generates the RSS `<link>` tag for the `<head>`.
+ */
+export function useRssHeadLink(config) {
+    if (!config.rss.enabled)
+        return "";
+    const path = config.rss.path ?? "/rss.xml";
+    const title = config.rss.title ?? config.title;
+    return `<link rel="alternate" type="application/rss+xml" title="${escapeAttr(title)}" href="${escapeAttr(path)}" />`;
+}
+/**
+ * Generates all default `<head>` meta tags for a page (title, description,
+ * canonical, OG, Twitter, JSON-LD, RSS link).
+ *
+ * Convenience wrapper around `useGenerateMetaTags` + `useRssHeadLink`.
+ */
+export function useHeadTags(config, meta) {
+    const metaTags = useGenerateMetaTags(config, meta);
+    const rssLink = useRssHeadLink(config);
+    return rssLink ? `${metaTags}\n${rssLink}` : metaTags;
+}
+// --- Internal helpers ---
+function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeAttr(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+function buildJsonLd(config, meta) {
+    const url = meta.url ?? config.site;
+    if (meta.ogType === "article") {
+        return {
+            "@context": "https://schema.org",
+            "@type": "Article",
+            headline: meta.title,
+            description: meta.description ?? config.description,
+            url,
+            author: {
+                "@type": "Person",
+                name: meta.author ?? config.author,
+            },
+            publisher: {
+                "@type": "Organization",
+                name: config.title,
+            },
+            datePublished: meta.publishedTime,
+            dateModified: meta.modifiedTime ?? meta.publishedTime,
+            image: meta.ogImage ?? config.ogImage,
+            mainEntityOfPage: {
+                "@type": "WebPage",
+                "@id": url,
+            },
+        };
+    }
+    return {
+        "@context": "https://schema.org",
+        "@type": "WebSite",
+        name: config.title,
+        description: config.description,
+        url: config.site,
+        author: {
+            "@type": "Person",
+            name: config.author,
+        },
+    };
+}
+//# sourceMappingURL=seo.service.js.map

package/dist/config/seo.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo.service.js","sourceRoot":"","sources":["../../src/config/seo.service.ts"],"names":[],"mappings":"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"}

package/dist/config/site.config.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Site-wide configuration for KatanaKit-powered Astro projects.
+ *
+ * Import this in your layouts, RSS endpoint, and SEO components
+ * to keep everything consistent.
+ *
+ * @example
+ * ```ts
+ * // astro.config.mjs
+ * import { siteConfig } from "./src/config/site.config.js";
+ * export default defineConfig({ site: siteConfig.site });
+ * ```
+ */
+export interface SiteConfig {
+    /** Base URL of the site (no trailing slash). */
+    site: string;
+    /** Site title (used in <title>, RSS, Open Graph). */
+    title: string;
+    /** Default meta description. */
+    description: string;
+    /** Language code (e.g. "en", "es"). */
+    lang: string;
+    /** Author name for RSS and meta tags. */
+    author: string;
+    /** Social/OG image URL (absolute or relative to public/). */
+    ogImage?: string;
+    /** Twitter handle (without @). */
+    twitter?: string;
+    /** RSS feed configuration. */
+    rss: {
+        /** Whether to enable the RSS feed (default: true). */
+        enabled: boolean;
+        /** Output path (default: "/rss.xml"). */
+        path: string;
+        /** Feed title (defaults to site title). */
+        title?: string;
+        /** Feed description (defaults to site description). */
+        description?: string;
+        /** Number of items to include (default: 20). */
+        limit: number;
+    };
+    /** Default SEO settings. */
+    seo: {
+        /** Whether to add noindex to all pages (default: false). */
+        noindex: boolean;
+        /** Whether to add the canonical URL (default: true). */
+        canonical: boolean;
+        /** Whether to add Open Graph tags (default: true). */
+        openGraph: boolean;
+        /** Whether to add Twitter Card tags (default: true). */
+        twitterCard: boolean;
+        /** Whether to add JSON-LD structured data (default: true). */
+        jsonLd: boolean;
+    };
+    /** Navigation links (optional, for header/footer). */
+    nav?: Array<{
+        label: string;
+        href: string;
+        external?: boolean;
+    }>;
+}
+/**
+ * Default site configuration. Override in your project.
+ *
+ * @example
+ * ```ts
+ * // src/config/site.config.ts
+ * import { type SiteConfig } from "katanakit";
+ *
+ * export const siteConfig: SiteConfig = {
+ *   site: "https://myblog.com",
+ *   title: "My Blog",
+ *   description: "A blog about TypeScript",
+ *   lang: "en",
+ *   author: "John Doe",
+ *   ogImage: "/og-default.png",
+ *   twitter: "johndoe",
+ *   rss: { enabled: true, path: "/rss.xml", limit: 20 },
+ *   seo: { noindex: false, canonical: true, openGraph: true, twitterCard: true, jsonLd: true },
+ *   nav: [
+ *     { label: "Home", href: "/" },
+ *     { label: "Blog", href: "/blog" },
+ *     { label: "GitHub", href: "https://github.com/...", external: true },
+ *   ],
+ * };
+ * ```
+ */
+export declare const siteConfig: SiteConfig;
+//# sourceMappingURL=site.config.d.ts.map

package/dist/config/site.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site.config.d.ts","sourceRoot":"","sources":["../../src/config/site.config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,UAAU;IAC1B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,GAAG,EAAE;QACJ,sDAAsD;QACtD,OAAO,EAAE,OAAO,CAAC;QACjB,yCAAyC;QACzC,IAAI,EAAE,MAAM,CAAC;QACb,2CAA2C;QAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,uDAAuD;QACvD,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,gDAAgD;QAChD,KAAK,EAAE,MAAM,CAAC;KACd,CAAC;IACF,4BAA4B;IAC5B,GAAG,EAAE;QACJ,4DAA4D;QAC5D,OAAO,EAAE,OAAO,CAAC;QACjB,wDAAwD;QACxD,SAAS,EAAE,OAAO,CAAC;QACnB,sDAAsD;QACtD,SAAS,EAAE,OAAO,CAAC;QACnB,wDAAwD;QACxD,WAAW,EAAE,OAAO,CAAC;QACrB,8DAA8D;QAC9D,MAAM,EAAE,OAAO,CAAC;KAChB,CAAC;IACF,sDAAsD;IACtD,GAAG,CAAC,EAAE,KAAK,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,UAAU,EAAE,UAkBxB,CAAC"}