@btst/stack 1.0.1 → 1.1.1

package/dist/client/index.d.mts

@@ -1,9 +1,99 @@
-import { C as ClientPlugin, P as PluginRoutes, a as ClientLibConfig, b as ClientLib } from '../shared/stack.DORw_1ps.mjs';
-export { createRoute } from '@btst/yar';
-export { c as createApiClient } from '../shared/stack.DrUAVfIH.mjs';
+import { S as Sitemap, C as ClientPlugin, a as PluginRoutes, b as ClientLibConfig, c as ClientLib } from '../shared/stack.ByOugz9d.mjs';
+import '@btst/yar';
 import '@btst/db';
 import 'better-call';
-import 'better-call/client';
+
+/**
+ * Converts an array of sitemap entries into an XML string following the sitemap.org protocol.
+ *
+ * @param entries - Array of sitemap entries from `lib.generateSitemap()`
+ * @returns Complete XML string for the sitemap
+ *
+ * @example
+ * ```ts
+ * const entries = await lib.generateSitemap();
+ * const xml = sitemapEntryToXmlString(entries);
+ * return new Response(xml, {
+ *   headers: { "Content-Type": "application/xml; charset=utf-8" }
+ * });
+ * ```
+ */
+declare function sitemapEntryToXmlString(entries: Sitemap): string;
+
+interface Metadata {
+    title: string;
+    description?: string;
+    keywords?: string[];
+    applicationName?: string;
+    generator?: string;
+    referrer?: "no-referrer" | "origin" | "no-referrer-when-downgrade" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin";
+    themeColor?: string;
+    viewport?: string;
+    creator?: string;
+    publisher?: string;
+    authors?: {
+        name: string;
+    }[];
+    abstract?: string;
+    robots?: string;
+    alternates?: Partial<{
+        canonical: string;
+    }>;
+    twitter?: Partial<{
+        title: string;
+        description: string;
+        site: string;
+        creator: string;
+        images?: string[];
+    }>;
+    openGraph?: Partial<{
+        title: string;
+        description: string;
+        url: string;
+        siteName: string;
+        locale: string;
+        images?: string[];
+        videos?: string[];
+        audio?: string[];
+    }>;
+}
+/**
+ * Converts an array of meta elements to a metadata object
+ * @param metaElements - An array of meta elements
+ * @example
+ * ```ts
+ * const metaElements = [
+ *   { name: "title", content: "My Page" },
+ *   { name: "description", content: "This is my page" },
+ * ];
+ * const metadata = metaElementsToObject(metaElements);
+ * console.log(metadata);
+ * ```
+ */
+declare function metaElementsToObject(metaElements: Array<React.JSX.IntrinsicElements["meta"] | undefined>): Metadata;
+
+/**
+ * Normalizes path segments from framework route params into a consistent path string.
+ *
+ * Handles different framework param formats:
+ * - Next.js: `pathParams.all` (string[])
+ * - React Router: `params["*"]` (string)
+ * - TanStack Router: `params._splat` (string)
+ *
+ * @param path - Path segments as string, string array, or undefined
+ * @returns Normalized path string starting with "/" (or "/" for empty/undefined)
+ *
+ * @example
+ * ```ts
+ * // Next.js
+ * normalizePath(pathParams?.all) // ["blog", "post"] => "/blog/post"
+ *
+ * // React Router / TanStack Router
+ * normalizePath(params["*"]) // "blog/post" => "/blog/post"
+ * normalizePath(undefined) // => "/"
+ * ```
+ */
+declare function normalizePath(path?: string | Array<string> | undefined): string;
 
 /**
  * Creates the client library with plugin support
@@ -13,12 +103,39 @@ import 'better-call/client';
  * // For Next.js with SSR:
  * const lib = createStackClient({
  *   plugins: {
- *     messages: messagesPlugin.client
+ *     blog: blogPlugin.client
  *   }
  * });
  *
- * // Access router for page routing
- * const route = lib.router.getRoute('/messages');
+ * // SPA usage - just render the route
+ * function Page() {
+ *   return lib.resolveRoute('/blog');
+ * }
+ *
+ * // SSR usage - prefetch data with loader, then render
+ * async function Page({ params }) {
+ *   const path = '/blog';
+ *
+ *   // Load data server-side if loader exists
+ *   const loader = lib.getLoader(path);
+ *   if (loader) await loader(queryClient, baseURL, basePath);
+ *
+ *   // Render with built-in Suspense + Error Boundary
+ *   return lib.resolveRoute(path);
+ * }
+ *
+ * // Next.js with notFound() function
+ * import { notFound } from 'next/navigation';
+ *
+ * async function Page({ params }) {
+ *   const path = '/blog';
+ *   const loader = lib.getLoader(path);
+ *   if (loader) await loader(queryClient, baseURL);
+ *
+ *   return lib.resolveRoute(path, {
+ *     onNotFound: notFound // Calls Next.js notFound() instead of rendering
+ *   });
+ * }
  *
  * ```
  *
@@ -27,4 +144,4 @@ import 'better-call/client';
  */
 declare function createStackClient<TPlugins extends Record<string, ClientPlugin<any, any>>, TRoutes extends PluginRoutes<TPlugins> = PluginRoutes<TPlugins>>(config: ClientLibConfig<TPlugins>): ClientLib<TRoutes>;
 
-export { ClientLib, ClientLibConfig, ClientPlugin, createStackClient };
+export { ClientLib, ClientLibConfig, ClientPlugin, createStackClient, metaElementsToObject, normalizePath, sitemapEntryToXmlString };

package/dist/client/index.d.ts

@@ -1,9 +1,99 @@
-import { C as ClientPlugin, P as PluginRoutes, a as ClientLibConfig, b as ClientLib } from '../shared/stack.DORw_1ps.js';
-export { createRoute } from '@btst/yar';
-export { c as createApiClient } from '../shared/stack.DrUAVfIH.js';
+import { S as Sitemap, C as ClientPlugin, a as PluginRoutes, b as ClientLibConfig, c as ClientLib } from '../shared/stack.ByOugz9d.js';
+import '@btst/yar';
 import '@btst/db';
 import 'better-call';
-import 'better-call/client';
+
+/**
+ * Converts an array of sitemap entries into an XML string following the sitemap.org protocol.
+ *
+ * @param entries - Array of sitemap entries from `lib.generateSitemap()`
+ * @returns Complete XML string for the sitemap
+ *
+ * @example
+ * ```ts
+ * const entries = await lib.generateSitemap();
+ * const xml = sitemapEntryToXmlString(entries);
+ * return new Response(xml, {
+ *   headers: { "Content-Type": "application/xml; charset=utf-8" }
+ * });
+ * ```
+ */
+declare function sitemapEntryToXmlString(entries: Sitemap): string;
+
+interface Metadata {
+    title: string;
+    description?: string;
+    keywords?: string[];
+    applicationName?: string;
+    generator?: string;
+    referrer?: "no-referrer" | "origin" | "no-referrer-when-downgrade" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin";
+    themeColor?: string;
+    viewport?: string;
+    creator?: string;
+    publisher?: string;
+    authors?: {
+        name: string;
+    }[];
+    abstract?: string;
+    robots?: string;
+    alternates?: Partial<{
+        canonical: string;
+    }>;
+    twitter?: Partial<{
+        title: string;
+        description: string;
+        site: string;
+        creator: string;
+        images?: string[];
+    }>;
+    openGraph?: Partial<{
+        title: string;
+        description: string;
+        url: string;
+        siteName: string;
+        locale: string;
+        images?: string[];
+        videos?: string[];
+        audio?: string[];
+    }>;
+}
+/**
+ * Converts an array of meta elements to a metadata object
+ * @param metaElements - An array of meta elements
+ * @example
+ * ```ts
+ * const metaElements = [
+ *   { name: "title", content: "My Page" },
+ *   { name: "description", content: "This is my page" },
+ * ];
+ * const metadata = metaElementsToObject(metaElements);
+ * console.log(metadata);
+ * ```
+ */
+declare function metaElementsToObject(metaElements: Array<React.JSX.IntrinsicElements["meta"] | undefined>): Metadata;
+
+/**
+ * Normalizes path segments from framework route params into a consistent path string.
+ *
+ * Handles different framework param formats:
+ * - Next.js: `pathParams.all` (string[])
+ * - React Router: `params["*"]` (string)
+ * - TanStack Router: `params._splat` (string)
+ *
+ * @param path - Path segments as string, string array, or undefined
+ * @returns Normalized path string starting with "/" (or "/" for empty/undefined)
+ *
+ * @example
+ * ```ts
+ * // Next.js
+ * normalizePath(pathParams?.all) // ["blog", "post"] => "/blog/post"
+ *
+ * // React Router / TanStack Router
+ * normalizePath(params["*"]) // "blog/post" => "/blog/post"
+ * normalizePath(undefined) // => "/"
+ * ```
+ */
+declare function normalizePath(path?: string | Array<string> | undefined): string;
 
 /**
  * Creates the client library with plugin support
@@ -13,12 +103,39 @@ import 'better-call/client';
  * // For Next.js with SSR:
  * const lib = createStackClient({
  *   plugins: {
- *     messages: messagesPlugin.client
+ *     blog: blogPlugin.client
  *   }
  * });
  *
- * // Access router for page routing
- * const route = lib.router.getRoute('/messages');
+ * // SPA usage - just render the route
+ * function Page() {
+ *   return lib.resolveRoute('/blog');
+ * }
+ *
+ * // SSR usage - prefetch data with loader, then render
+ * async function Page({ params }) {
+ *   const path = '/blog';
+ *
+ *   // Load data server-side if loader exists
+ *   const loader = lib.getLoader(path);
+ *   if (loader) await loader(queryClient, baseURL, basePath);
+ *
+ *   // Render with built-in Suspense + Error Boundary
+ *   return lib.resolveRoute(path);
+ * }
+ *
+ * // Next.js with notFound() function
+ * import { notFound } from 'next/navigation';
+ *
+ * async function Page({ params }) {
+ *   const path = '/blog';
+ *   const loader = lib.getLoader(path);
+ *   if (loader) await loader(queryClient, baseURL);
+ *
+ *   return lib.resolveRoute(path, {
+ *     onNotFound: notFound // Calls Next.js notFound() instead of rendering
+ *   });
+ * }
  *
  * ```
  *
@@ -27,4 +144,4 @@ import 'better-call/client';
  */
 declare function createStackClient<TPlugins extends Record<string, ClientPlugin<any, any>>, TRoutes extends PluginRoutes<TPlugins> = PluginRoutes<TPlugins>>(config: ClientLibConfig<TPlugins>): ClientLib<TRoutes>;
 
-export { ClientLib, ClientLibConfig, ClientPlugin, createStackClient };
+export { ClientLib, ClientLibConfig, ClientPlugin, createStackClient, metaElementsToObject, normalizePath, sitemapEntryToXmlString };

package/dist/client/index.mjs

@@ -1,7 +1,7 @@
 import { createRouter } from '@btst/yar';
-export { createRoute } from '@btst/yar';
-export { c as createApiClient } from '../shared/stack.3OUyGp_E.mjs';
-import 'better-call/client';
+export { sitemapEntryToXmlString } from './sitemap-utils.mjs';
+export { metaElementsToObject } from './meta-utils.mjs';
+export { normalizePath } from './path-utils.mjs';
 
 function createStackClient(config) {
   const { plugins } = config;
@@ -12,7 +12,24 @@ function createStackClient(config) {
   }
   const router = createRouter(allRoutes);
   return {
-    router
+    router,
+    async generateSitemap() {
+      const sitemapEntries = [];
+      for (const plugin of Object.values(plugins)) {
+        if (typeof plugin.sitemap === "function") {
+          const entries = await plugin.sitemap();
+          if (Array.isArray(entries)) sitemapEntries.push(...entries);
+        }
+      }
+      const seen = /* @__PURE__ */ new Set();
+      const deduped = [];
+      for (const entry of sitemapEntries) {
+        if (!entry?.url || seen.has(entry.url)) continue;
+        seen.add(entry.url);
+        deduped.push(entry);
+      }
+      return deduped;
+    }
   };
 }
 

package/dist/client/meta-utils.cjs

@@ -0,0 +1,162 @@
+'use strict';
+
+function metaElementsToObject(metaElements) {
+  const metadata = { title: "" };
+  const nameHandlers = {
+    title: (c) => {
+      metadata.title = c;
+    },
+    description: (c) => {
+      metadata.description = c;
+    },
+    keywords: (c) => {
+      const parts = c.split(",").map((k) => k.trim()).filter(Boolean);
+      metadata.keywords = parts.length > 0 ? parts : void 0;
+    },
+    "application-name": (c) => {
+      metadata.applicationName = c;
+    },
+    generator: (c) => {
+      metadata.generator = c;
+    },
+    referrer: (c) => {
+      const allowedReferrers = /* @__PURE__ */ new Set([
+        "no-referrer",
+        "origin",
+        "no-referrer-when-downgrade",
+        "origin-when-cross-origin",
+        "same-origin",
+        "strict-origin",
+        "strict-origin-when-cross-origin",
+        "unsafe-url"
+      ]);
+      if (allowedReferrers.has(c)) {
+        metadata.referrer = c;
+      }
+    },
+    "theme-color": (c) => {
+      metadata.themeColor = c;
+    },
+    viewport: (c) => {
+      metadata.viewport = c;
+    },
+    creator: (c) => {
+      metadata.creator = c;
+    },
+    publisher: (c) => {
+      metadata.publisher = c;
+    },
+    author: (c) => {
+      metadata.authors = [{ name: c }];
+    },
+    abstract: (c) => {
+      metadata.abstract = c;
+    },
+    robots: (c) => {
+      metadata.robots = c;
+    },
+    // Twitter
+    "twitter:title": (c) => {
+      if (!metadata.twitter) metadata.twitter = {};
+      metadata.twitter.title = c;
+    },
+    "twitter:description": (c) => {
+      if (!metadata.twitter) metadata.twitter = {};
+      metadata.twitter.description = c;
+    },
+    "twitter:site": (c) => {
+      if (!metadata.twitter) metadata.twitter = {};
+      metadata.twitter.site = c;
+    },
+    "twitter:creator": (c) => {
+      if (!metadata.twitter) metadata.twitter = {};
+      metadata.twitter.creator = c;
+    },
+    "twitter:image": (c) => {
+      if (!metadata.twitter) metadata.twitter = {};
+      const currentImages = metadata.twitter.images;
+      if (!currentImages) {
+        metadata.twitter.images = [c];
+      } else if (Array.isArray(currentImages)) {
+        metadata.twitter.images = [...currentImages, c];
+      } else {
+        metadata.twitter.images = [currentImages, c];
+      }
+    }
+  };
+  const propertyHandlers = {
+    "og:title": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      metadata.openGraph.title = c;
+    },
+    "og:description": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      metadata.openGraph.description = c;
+    },
+    "og:url": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      metadata.openGraph.url = c;
+      metadata.alternates = {
+        ...metadata.alternates ?? {},
+        canonical: c
+      };
+    },
+    "og:site_name": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      metadata.openGraph.siteName = c;
+    },
+    "og:locale": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      metadata.openGraph.locale = c;
+    },
+    "og:image": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      const currentImages = metadata.openGraph.images;
+      if (!currentImages) {
+        metadata.openGraph.images = [c];
+      } else if (Array.isArray(currentImages)) {
+        metadata.openGraph.images = [...currentImages, c];
+      } else {
+        metadata.openGraph.images = [currentImages, c];
+      }
+    },
+    "og:video": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      const currentVideos = metadata.openGraph.videos;
+      if (!currentVideos) {
+        metadata.openGraph.videos = [c];
+      } else if (Array.isArray(currentVideos)) {
+        metadata.openGraph.videos = [...currentVideos, c];
+      } else {
+        metadata.openGraph.videos = [currentVideos, c];
+      }
+    },
+    "og:audio": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      const currentAudio = metadata.openGraph.audio;
+      if (!currentAudio) {
+        metadata.openGraph.audio = [c];
+      } else if (Array.isArray(currentAudio)) {
+        metadata.openGraph.audio = [...currentAudio, c];
+      } else {
+        metadata.openGraph.audio = [currentAudio, c];
+      }
+    }
+  };
+  for (const meta of metaElements) {
+    if (!meta) continue;
+    if ("name" in meta && "content" in meta) {
+      const handler = nameHandlers[String(meta.name)];
+      if (handler) handler(String(meta.content));
+      continue;
+    }
+    if ("property" in meta && "content" in meta) {
+      const handler = propertyHandlers[String(meta.property)];
+      if (handler) handler(String(meta.content));
+      continue;
+    }
+  }
+  return metadata;
+}
+
+exports.metaElementsToObject = metaElementsToObject;

package/dist/client/meta-utils.mjs

@@ -0,0 +1,160 @@
+function metaElementsToObject(metaElements) {
+  const metadata = { title: "" };
+  const nameHandlers = {
+    title: (c) => {
+      metadata.title = c;
+    },
+    description: (c) => {
+      metadata.description = c;
+    },
+    keywords: (c) => {
+      const parts = c.split(",").map((k) => k.trim()).filter(Boolean);
+      metadata.keywords = parts.length > 0 ? parts : void 0;
+    },
+    "application-name": (c) => {
+      metadata.applicationName = c;
+    },
+    generator: (c) => {
+      metadata.generator = c;
+    },
+    referrer: (c) => {
+      const allowedReferrers = /* @__PURE__ */ new Set([
+        "no-referrer",
+        "origin",
+        "no-referrer-when-downgrade",
+        "origin-when-cross-origin",
+        "same-origin",
+        "strict-origin",
+        "strict-origin-when-cross-origin",
+        "unsafe-url"
+      ]);
+      if (allowedReferrers.has(c)) {
+        metadata.referrer = c;
+      }
+    },
+    "theme-color": (c) => {
+      metadata.themeColor = c;
+    },
+    viewport: (c) => {
+      metadata.viewport = c;
+    },
+    creator: (c) => {
+      metadata.creator = c;
+    },
+    publisher: (c) => {
+      metadata.publisher = c;
+    },
+    author: (c) => {
+      metadata.authors = [{ name: c }];
+    },
+    abstract: (c) => {
+      metadata.abstract = c;
+    },
+    robots: (c) => {
+      metadata.robots = c;
+    },
+    // Twitter
+    "twitter:title": (c) => {
+      if (!metadata.twitter) metadata.twitter = {};
+      metadata.twitter.title = c;
+    },
+    "twitter:description": (c) => {
+      if (!metadata.twitter) metadata.twitter = {};
+      metadata.twitter.description = c;
+    },
+    "twitter:site": (c) => {
+      if (!metadata.twitter) metadata.twitter = {};
+      metadata.twitter.site = c;
+    },
+    "twitter:creator": (c) => {
+      if (!metadata.twitter) metadata.twitter = {};
+      metadata.twitter.creator = c;
+    },
+    "twitter:image": (c) => {
+      if (!metadata.twitter) metadata.twitter = {};
+      const currentImages = metadata.twitter.images;
+      if (!currentImages) {
+        metadata.twitter.images = [c];
+      } else if (Array.isArray(currentImages)) {
+        metadata.twitter.images = [...currentImages, c];
+      } else {
+        metadata.twitter.images = [currentImages, c];
+      }
+    }
+  };
+  const propertyHandlers = {
+    "og:title": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      metadata.openGraph.title = c;
+    },
+    "og:description": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      metadata.openGraph.description = c;
+    },
+    "og:url": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      metadata.openGraph.url = c;
+      metadata.alternates = {
+        ...metadata.alternates ?? {},
+        canonical: c
+      };
+    },
+    "og:site_name": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      metadata.openGraph.siteName = c;
+    },
+    "og:locale": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      metadata.openGraph.locale = c;
+    },
+    "og:image": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      const currentImages = metadata.openGraph.images;
+      if (!currentImages) {
+        metadata.openGraph.images = [c];
+      } else if (Array.isArray(currentImages)) {
+        metadata.openGraph.images = [...currentImages, c];
+      } else {
+        metadata.openGraph.images = [currentImages, c];
+      }
+    },
+    "og:video": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      const currentVideos = metadata.openGraph.videos;
+      if (!currentVideos) {
+        metadata.openGraph.videos = [c];
+      } else if (Array.isArray(currentVideos)) {
+        metadata.openGraph.videos = [...currentVideos, c];
+      } else {
+        metadata.openGraph.videos = [currentVideos, c];
+      }
+    },
+    "og:audio": (c) => {
+      if (!metadata.openGraph) metadata.openGraph = {};
+      const currentAudio = metadata.openGraph.audio;
+      if (!currentAudio) {
+        metadata.openGraph.audio = [c];
+      } else if (Array.isArray(currentAudio)) {
+        metadata.openGraph.audio = [...currentAudio, c];
+      } else {
+        metadata.openGraph.audio = [currentAudio, c];
+      }
+    }
+  };
+  for (const meta of metaElements) {
+    if (!meta) continue;
+    if ("name" in meta && "content" in meta) {
+      const handler = nameHandlers[String(meta.name)];
+      if (handler) handler(String(meta.content));
+      continue;
+    }
+    if ("property" in meta && "content" in meta) {
+      const handler = propertyHandlers[String(meta.property)];
+      if (handler) handler(String(meta.content));
+      continue;
+    }
+  }
+  return metadata;
+}
+
+export { metaElementsToObject };

package/dist/client/path-utils.cjs

@@ -0,0 +1,15 @@
+'use strict';
+
+function normalizePath(path) {
+  if (!path) {
+    return "/";
+  }
+  if (Array.isArray(path)) {
+    const segments2 = path.filter(Boolean);
+    return segments2.length > 0 ? `/${segments2.join("/")}` : "/";
+  }
+  const segments = path.split("/").filter(Boolean);
+  return segments.length > 0 ? `/${segments.join("/")}` : "/";
+}
+
+exports.normalizePath = normalizePath;

package/dist/client/path-utils.mjs

@@ -0,0 +1,13 @@
+function normalizePath(path) {
+  if (!path) {
+    return "/";
+  }
+  if (Array.isArray(path)) {
+    const segments2 = path.filter(Boolean);
+    return segments2.length > 0 ? `/${segments2.join("/")}` : "/";
+  }
+  const segments = path.split("/").filter(Boolean);
+  return segments.length > 0 ? `/${segments.join("/")}` : "/";
+}
+
+export { normalizePath };