@btst/stack 1.0.0

package/dist/context/index.mjs

@@ -0,0 +1,50 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { createContext, useContext } from 'react';
+
+const BetterStackContext = createContext(
+  null
+);
+function BetterStackProvider({
+  children,
+  overrides
+}) {
+  const value = {
+    overrides
+  };
+  return /* @__PURE__ */ jsx(BetterStackContext.Provider, { value, children });
+}
+function useBetterStack() {
+  const context = useContext(
+    BetterStackContext
+  );
+  if (!context) {
+    throw new Error(
+      "useBetterStack must be used within BetterStackProvider. Wrap your app with <BetterStackProvider> in your layout file."
+    );
+  }
+  return context;
+}
+function usePluginOverrides(pluginName) {
+  const context = useBetterStack();
+  const overrides = context.overrides[pluginName];
+  if (!overrides) {
+    throw new Error(
+      `Plugin "${pluginName}" not found in BetterStackProvider. Available plugins: ${Object.keys(context.overrides).join(", ")}`
+    );
+  }
+  return overrides;
+}
+function usePluginOverride(pluginName, overrideKey) {
+  const overrides = usePluginOverrides(pluginName);
+  const override = overrides[overrideKey];
+  if (override === void 0) {
+    const availableKeys = overrides && typeof overrides === "object" ? Object.keys(overrides).join(", ") : "none";
+    throw new Error(
+      `Override "${overrideKey}" not found for plugin "${pluginName}". Available overrides: ${availableKeys}`
+    );
+  }
+  return override;
+}
+
+export { BetterStackProvider, useBetterStack, usePluginOverride, usePluginOverrides };

package/dist/index.cjs

@@ -0,0 +1,9 @@
+'use strict';
+
+const api_index = require('./api/index.cjs');
+require('better-call');
+require('@btst/db');
+
+
+
+exports.betterStack = api_index.betterStack;

package/dist/index.d.cts

@@ -0,0 +1,5 @@
+export { betterStack } from './api/index.cjs';
+export { g as BackendLib, f as BackendLibConfig, B as BackendPlugin } from './shared/stack.Dva9muUy.cjs';
+import '@btst/yar';
+import '@btst/db';
+import 'better-call';

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+export { betterStack } from './api/index.mjs';
+export { g as BackendLib, f as BackendLibConfig, B as BackendPlugin } from './shared/stack.Dva9muUy.mjs';
+import '@btst/yar';
+import '@btst/db';
+import 'better-call';

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { betterStack } from './api/index.js';
+export { g as BackendLib, f as BackendLibConfig, B as BackendPlugin } from './shared/stack.Dva9muUy.js';
+import '@btst/yar';
+import '@btst/db';
+import 'better-call';

package/dist/index.mjs

@@ -0,0 +1,3 @@
+export { betterStack } from './api/index.mjs';
+import 'better-call';
+import '@btst/db';

package/dist/plugins/index.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+const utils = require('../shared/stack.Br2KMECJ.cjs');
+require('better-call/client');
+
+function defineClientPlugin(plugin) {
+  return plugin;
+}
+function defineBackendPlugin(plugin) {
+  return plugin;
+}
+
+exports.createApiClient = utils.createApiClient;
+exports.getServerBaseURL = utils.getServerBaseURL;
+exports.defineBackendPlugin = defineBackendPlugin;
+exports.defineClientPlugin = defineClientPlugin;

package/dist/plugins/index.d.cts

@@ -0,0 +1,64 @@
+import { C as ClientPlugin, B as BackendPlugin } from '../shared/stack.Dva9muUy.cjs';
+export { I as InferPluginOverrides, d as PluginOverrides } from '../shared/stack.Dva9muUy.cjs';
+import { Endpoint } from 'better-call';
+export { Endpoint, Router } from 'better-call';
+export { c as createApiClient, g as getServerBaseURL } from '../shared/stack.DvFqFlOV.cjs';
+export { Adapter, DatabaseDefinition, DbPlugin } from '@btst/db';
+export { Route } from '@btst/yar';
+import 'better-call/client';
+
+/**
+ * Plugin utilities and types for building standalone plugins
+ *
+ * This module exports everything needed to create custom plugins
+ * for Better Stack outside of this package.
+ *
+ * Note: Backend and Client plugins are separate to prevent SSR issues
+ * and enable better code splitting. Import them separately:
+ * - Backend: import type { BackendPlugin } from "@btst/stack/plugins"
+ * - Client: import type { ClientPlugin } from "@btst/stack/plugins"
+ */
+
+/**
+ * Helper to define a client plugin with full type inference
+ *
+ * Automatically infers route keys, hook names, and their types without needing casts.
+ *
+ * @example
+ * ```ts
+ * const messagesPlugin = defineClientPlugin({
+ *   name: "messages",
+ *   routes: () => ({
+ *     messagesList: createRoute("/messages", () => ({ ... }))
+ *   }),
+ *   hooks: () => ({
+ *     useMessages: () => { ... }
+ *   })
+ * });
+ * // No casts needed - route keys, hook names, and types are all preserved!
+ * ```
+ *
+ * @template TPlugin - The exact plugin definition (auto-inferred)
+ */
+declare function defineClientPlugin<TPlugin extends ClientPlugin<any, any>>(plugin: TPlugin): TPlugin;
+/**
+ * Helper to define a backend plugin with full type inference
+ *
+ * @example
+ * ```ts
+ * const messagesPlugin = defineBackendPlugin({
+ *   name: "messages",
+ *   dbPlugin: createDbPlugin("messages", messagesSchema),
+ *   routes: (adapter) => ({
+ *     list: endpoint("/messages", { method: "GET" }, async () => { ... }),
+ *     create: endpoint("/messages", { method: "POST" }, async () => { ... })
+ *   })
+ * });
+ * // Route keys "list" and "create" are preserved in types!
+ * ```
+ *
+ * @template TRoutes - The exact shape of routes (auto-inferred from routes function)
+ */
+declare function defineBackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>>(plugin: BackendPlugin<TRoutes>): BackendPlugin<TRoutes>;
+
+export { BackendPlugin, ClientPlugin, defineBackendPlugin, defineClientPlugin };

package/dist/plugins/index.d.mts

@@ -0,0 +1,64 @@
+import { C as ClientPlugin, B as BackendPlugin } from '../shared/stack.Dva9muUy.mjs';
+export { I as InferPluginOverrides, d as PluginOverrides } from '../shared/stack.Dva9muUy.mjs';
+import { Endpoint } from 'better-call';
+export { Endpoint, Router } from 'better-call';
+export { c as createApiClient, g as getServerBaseURL } from '../shared/stack.DvFqFlOV.mjs';
+export { Adapter, DatabaseDefinition, DbPlugin } from '@btst/db';
+export { Route } from '@btst/yar';
+import 'better-call/client';
+
+/**
+ * Plugin utilities and types for building standalone plugins
+ *
+ * This module exports everything needed to create custom plugins
+ * for Better Stack outside of this package.
+ *
+ * Note: Backend and Client plugins are separate to prevent SSR issues
+ * and enable better code splitting. Import them separately:
+ * - Backend: import type { BackendPlugin } from "@btst/stack/plugins"
+ * - Client: import type { ClientPlugin } from "@btst/stack/plugins"
+ */
+
+/**
+ * Helper to define a client plugin with full type inference
+ *
+ * Automatically infers route keys, hook names, and their types without needing casts.
+ *
+ * @example
+ * ```ts
+ * const messagesPlugin = defineClientPlugin({
+ *   name: "messages",
+ *   routes: () => ({
+ *     messagesList: createRoute("/messages", () => ({ ... }))
+ *   }),
+ *   hooks: () => ({
+ *     useMessages: () => { ... }
+ *   })
+ * });
+ * // No casts needed - route keys, hook names, and types are all preserved!
+ * ```
+ *
+ * @template TPlugin - The exact plugin definition (auto-inferred)
+ */
+declare function defineClientPlugin<TPlugin extends ClientPlugin<any, any>>(plugin: TPlugin): TPlugin;
+/**
+ * Helper to define a backend plugin with full type inference
+ *
+ * @example
+ * ```ts
+ * const messagesPlugin = defineBackendPlugin({
+ *   name: "messages",
+ *   dbPlugin: createDbPlugin("messages", messagesSchema),
+ *   routes: (adapter) => ({
+ *     list: endpoint("/messages", { method: "GET" }, async () => { ... }),
+ *     create: endpoint("/messages", { method: "POST" }, async () => { ... })
+ *   })
+ * });
+ * // Route keys "list" and "create" are preserved in types!
+ * ```
+ *
+ * @template TRoutes - The exact shape of routes (auto-inferred from routes function)
+ */
+declare function defineBackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>>(plugin: BackendPlugin<TRoutes>): BackendPlugin<TRoutes>;
+
+export { BackendPlugin, ClientPlugin, defineBackendPlugin, defineClientPlugin };

package/dist/plugins/index.d.ts

@@ -0,0 +1,64 @@
+import { C as ClientPlugin, B as BackendPlugin } from '../shared/stack.Dva9muUy.js';
+export { I as InferPluginOverrides, d as PluginOverrides } from '../shared/stack.Dva9muUy.js';
+import { Endpoint } from 'better-call';
+export { Endpoint, Router } from 'better-call';
+export { c as createApiClient, g as getServerBaseURL } from '../shared/stack.DvFqFlOV.js';
+export { Adapter, DatabaseDefinition, DbPlugin } from '@btst/db';
+export { Route } from '@btst/yar';
+import 'better-call/client';
+
+/**
+ * Plugin utilities and types for building standalone plugins
+ *
+ * This module exports everything needed to create custom plugins
+ * for Better Stack outside of this package.
+ *
+ * Note: Backend and Client plugins are separate to prevent SSR issues
+ * and enable better code splitting. Import them separately:
+ * - Backend: import type { BackendPlugin } from "@btst/stack/plugins"
+ * - Client: import type { ClientPlugin } from "@btst/stack/plugins"
+ */
+
+/**
+ * Helper to define a client plugin with full type inference
+ *
+ * Automatically infers route keys, hook names, and their types without needing casts.
+ *
+ * @example
+ * ```ts
+ * const messagesPlugin = defineClientPlugin({
+ *   name: "messages",
+ *   routes: () => ({
+ *     messagesList: createRoute("/messages", () => ({ ... }))
+ *   }),
+ *   hooks: () => ({
+ *     useMessages: () => { ... }
+ *   })
+ * });
+ * // No casts needed - route keys, hook names, and types are all preserved!
+ * ```
+ *
+ * @template TPlugin - The exact plugin definition (auto-inferred)
+ */
+declare function defineClientPlugin<TPlugin extends ClientPlugin<any, any>>(plugin: TPlugin): TPlugin;
+/**
+ * Helper to define a backend plugin with full type inference
+ *
+ * @example
+ * ```ts
+ * const messagesPlugin = defineBackendPlugin({
+ *   name: "messages",
+ *   dbPlugin: createDbPlugin("messages", messagesSchema),
+ *   routes: (adapter) => ({
+ *     list: endpoint("/messages", { method: "GET" }, async () => { ... }),
+ *     create: endpoint("/messages", { method: "POST" }, async () => { ... })
+ *   })
+ * });
+ * // Route keys "list" and "create" are preserved in types!
+ * ```
+ *
+ * @template TRoutes - The exact shape of routes (auto-inferred from routes function)
+ */
+declare function defineBackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>>(plugin: BackendPlugin<TRoutes>): BackendPlugin<TRoutes>;
+
+export { BackendPlugin, ClientPlugin, defineBackendPlugin, defineClientPlugin };

package/dist/plugins/index.mjs

@@ -0,0 +1,11 @@
+export { c as createApiClient, g as getServerBaseURL } from '../shared/stack.CwGEQ10b.mjs';
+import 'better-call/client';
+
+function defineClientPlugin(plugin) {
+  return plugin;
+}
+function defineBackendPlugin(plugin) {
+  return plugin;
+}
+
+export { defineBackendPlugin, defineClientPlugin };

package/dist/shared/stack.Br2KMECJ.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+const client = require('better-call/client');
+
+function createApiClient(options) {
+  const { baseURL = "", basePath = "/api" } = options ?? {};
+  const normalizedBaseURL = baseURL ? baseURL.replace(/\/$/, "") : "";
+  const normalizedBasePath = basePath.startsWith("/") ? basePath : `/${basePath}`;
+  const finalBasePath = normalizedBasePath.replace(/\/$/, "");
+  const apiPath = normalizedBaseURL + finalBasePath;
+  return client.createClient({
+    baseURL: apiPath
+  });
+}
+function getServerBaseURL() {
+  if (typeof window === "undefined") {
+    return process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000";
+  }
+  return void 0;
+}
+
+exports.createApiClient = createApiClient;
+exports.getServerBaseURL = getServerBaseURL;

package/dist/shared/stack.CwGEQ10b.mjs

@@ -0,0 +1,20 @@
+import { createClient } from 'better-call/client';
+
+function createApiClient(options) {
+  const { baseURL = "", basePath = "/api" } = options ?? {};
+  const normalizedBaseURL = baseURL ? baseURL.replace(/\/$/, "") : "";
+  const normalizedBasePath = basePath.startsWith("/") ? basePath : `/${basePath}`;
+  const finalBasePath = normalizedBasePath.replace(/\/$/, "");
+  const apiPath = normalizedBaseURL + finalBasePath;
+  return createClient({
+    baseURL: apiPath
+  });
+}
+function getServerBaseURL() {
+  if (typeof window === "undefined") {
+    return process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000";
+  }
+  return void 0;
+}
+
+export { createApiClient as c, getServerBaseURL as g };

package/dist/shared/stack.DvFqFlOV.d.cts

@@ -0,0 +1,22 @@
+import { createClient } from 'better-call/client';
+import { Router, Endpoint } from 'better-call';
+
+interface CreateApiClientOptions {
+    baseURL?: string;
+    basePath?: string;
+}
+/**
+ * Creates a Better Call API client with proper URL handling for both server and client side
+ * @param options - Configuration options
+ * @param options.baseURL - The base URL (e.g., 'http://localhost:3000'). If not provided, uses relative URLs (same domain)
+ * @param options.basePath - The API base path (defaults to '/api')
+ * @template TRouter - The router type (Router or Record<string, Endpoint>)
+ */
+declare function createApiClient<TRouter extends Router | Record<string, Endpoint> = Record<string, Endpoint>>(options?: CreateApiClientOptions): ReturnType<typeof createClient<TRouter>>;
+/**
+ * Helper to get the server-side baseURL
+ * On the server, we need an absolute URL. On the client, we can use relative URLs.
+ */
+declare function getServerBaseURL(): string | undefined;
+
+export { createApiClient as c, getServerBaseURL as g };

package/dist/shared/stack.DvFqFlOV.d.mts

@@ -0,0 +1,22 @@
+import { createClient } from 'better-call/client';
+import { Router, Endpoint } from 'better-call';
+
+interface CreateApiClientOptions {
+    baseURL?: string;
+    basePath?: string;
+}
+/**
+ * Creates a Better Call API client with proper URL handling for both server and client side
+ * @param options - Configuration options
+ * @param options.baseURL - The base URL (e.g., 'http://localhost:3000'). If not provided, uses relative URLs (same domain)
+ * @param options.basePath - The API base path (defaults to '/api')
+ * @template TRouter - The router type (Router or Record<string, Endpoint>)
+ */
+declare function createApiClient<TRouter extends Router | Record<string, Endpoint> = Record<string, Endpoint>>(options?: CreateApiClientOptions): ReturnType<typeof createClient<TRouter>>;
+/**
+ * Helper to get the server-side baseURL
+ * On the server, we need an absolute URL. On the client, we can use relative URLs.
+ */
+declare function getServerBaseURL(): string | undefined;
+
+export { createApiClient as c, getServerBaseURL as g };

package/dist/shared/stack.DvFqFlOV.d.ts

@@ -0,0 +1,22 @@
+import { createClient } from 'better-call/client';
+import { Router, Endpoint } from 'better-call';
+
+interface CreateApiClientOptions {
+    baseURL?: string;
+    basePath?: string;
+}
+/**
+ * Creates a Better Call API client with proper URL handling for both server and client side
+ * @param options - Configuration options
+ * @param options.baseURL - The base URL (e.g., 'http://localhost:3000'). If not provided, uses relative URLs (same domain)
+ * @param options.basePath - The API base path (defaults to '/api')
+ * @template TRouter - The router type (Router or Record<string, Endpoint>)
+ */
+declare function createApiClient<TRouter extends Router | Record<string, Endpoint> = Record<string, Endpoint>>(options?: CreateApiClientOptions): ReturnType<typeof createClient<TRouter>>;
+/**
+ * Helper to get the server-side baseURL
+ * On the server, we need an absolute URL. On the client, we can use relative URLs.
+ */
+declare function getServerBaseURL(): string | undefined;
+
+export { createApiClient as c, getServerBaseURL as g };

package/dist/shared/stack.Dva9muUy.d.cts

@@ -0,0 +1,138 @@
+import { Route, createRouter } from '@btst/yar';
+import { Adapter, DbPlugin, DatabaseDefinition } from '@btst/db';
+import { Endpoint, Router } from 'better-call';
+
+/**
+ * Backend plugin definition
+ * Defines API routes and data access for a feature
+ *
+ * Note: Each plugin defines its own schema using createDbPlugin().
+ * Better Stack composes all plugin schemas together at runtime using Better DB's .use() method.
+ * You can optionally provide a base schema via the dbSchema config option.
+ *
+ * @template TRoutes - The exact shape of routes this plugin provides (preserves keys and endpoint types)
+ */
+interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>> {
+    name: string;
+    /**
+     * Create API endpoints for this plugin
+     * Returns an object with named endpoints that will be composed into the router
+     *
+     * @param adapter - Better DB adapter instance with methods:
+     *   create, update, updateMany, delete, deleteMany, findOne, findMany, count
+     */
+    routes: (adapter: Adapter) => TRoutes;
+    dbPlugin: DbPlugin;
+}
+/**
+ * Hook function type
+ * Generic function type for React hooks returned by plugins
+ */
+type HookFunction = (...args: unknown[]) => unknown;
+/**
+ * Frontend plugin definition
+ * Defines pages, components, loaders, and React Query hooks for a feature
+ *
+ * @template TOverrides - The shape of overridable components/functions this plugin requires
+ * Example: { Link: ComponentType<{href: string}>, navigate: (path: string) => void }
+ * @template TRoutes - The exact shape of routes this plugin provides (preserves keys and route types)
+ */
+interface ClientPlugin<TOverrides = Record<string, never>, TRoutes extends Record<string, Route> = Record<string, Route>> {
+    name: string;
+    /**
+     * Define routes (pages) for this plugin
+     * Returns yar routes that will be composed into the router
+     */
+    routes: () => TRoutes;
+    /**
+     * Optional: Create React Query hooks for this plugin
+     * These can be used directly in components without the loader
+     */
+    hooks?: () => Record<string, HookFunction>;
+    /**
+     * Optional: Default implementations for overridable components/functions
+     * These will be used if no override is provided in BetterStackContext
+     */
+    defaultOverrides?: Partial<TOverrides>;
+}
+/**
+ * Configuration for creating the backend library
+ */
+interface BackendLibConfig<TPlugins extends Record<string, BackendPlugin<any>> = Record<string, BackendPlugin<any>>> {
+    dbSchema?: DatabaseDefinition;
+    plugins: TPlugins;
+    adapter: (db: DatabaseDefinition) => Adapter;
+}
+/**
+ * Configuration for creating the client library
+ */
+interface ClientLibConfig<TPlugins extends Record<string, ClientPlugin<any, any>> = Record<string, ClientPlugin<any, any>>> {
+    plugins: TPlugins;
+    baseURL?: string;
+    basePath?: string;
+}
+/**
+ * Utility type to extract override types from plugins
+ * Maps plugin names to their override types
+ */
+type InferPluginOverrides<TPlugins extends Record<string, ClientPlugin<any, any>>> = {
+    [K in keyof TPlugins]: TPlugins[K] extends ClientPlugin<infer TOverrides, any> ? TOverrides : never;
+};
+/**
+ * Type for the pluginOverrides prop in BetterStackContext
+ * Allows partial overrides per plugin
+ */
+type PluginOverrides<TPlugins extends Record<string, ClientPlugin<any, any>>> = {
+    [K in keyof TPlugins]?: Partial<InferPluginOverrides<TPlugins>[K]>;
+};
+/**
+ * Extract all routes from all client plugins, merging them into a single record
+ */
+type PluginRoutes<TPlugins extends Record<string, ClientPlugin<any, any>>> = MergeAllPluginRoutes<TPlugins>;
+/**
+ * Extract all hooks from all client plugins, organized by plugin name
+ * For plugins without hooks, the type will be an empty object
+ */
+type PluginHooks<TPlugins extends Record<string, ClientPlugin<any, any>>> = {
+    [K in keyof TPlugins]: TPlugins[K]["hooks"] extends () => infer H ? H : {};
+};
+/**
+ * Prefix all backend plugin route keys with the plugin name
+ * Example: { messages: { list: Endpoint } } => { messages_list: Endpoint }
+ */
+type PrefixedPluginRoutes<TPlugins extends Record<string, BackendPlugin<any>>> = UnionToIntersection<{
+    [PluginKey in keyof TPlugins]: TPlugins[PluginKey] extends BackendPlugin<infer TRoutes> ? {
+        [RouteKey in keyof TRoutes as `${PluginKey & string}_${RouteKey & string}`]: TRoutes[RouteKey];
+    } : never;
+}[keyof TPlugins]> extends infer U ? U extends Record<string, Endpoint> ? U : Record<string, Endpoint> : Record<string, Endpoint>;
+/**
+ * Result of creating the backend library
+ */
+interface BackendLib<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>> {
+    handler: (request: Request) => Promise<Response>;
+    router: Router;
+    dbSchema: DatabaseDefinition;
+}
+/**
+ * Helper type to extract routes from a client plugin
+ */
+type ExtractPluginRoutes<T> = T extends ClientPlugin<any, infer TRoutes> ? TRoutes : never;
+/**
+ * Helper type to merge all routes from all plugins into a single record
+ */
+type MergeAllPluginRoutes<TPlugins extends Record<string, ClientPlugin<any, any>>> = UnionToIntersection<{
+    [K in keyof TPlugins]: ExtractPluginRoutes<TPlugins[K]>;
+}[keyof TPlugins]> extends infer U ? U extends Record<string, Route> ? U : Record<string, Route> : Record<string, Route>;
+/**
+ * Utility type to convert union to intersection
+ */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Result of creating the client library
+ */
+interface ClientLib<TRoutes extends Record<string, Route> = Record<string, Route>, THooks extends Record<string, any> = Record<string, any>> {
+    router: ReturnType<typeof createRouter<TRoutes, {}>>;
+    hooks: THooks;
+}
+
+export type { BackendPlugin as B, ClientPlugin as C, InferPluginOverrides as I, PluginRoutes as P, PluginHooks as a, ClientLibConfig as b, ClientLib as c, PluginOverrides as d, PrefixedPluginRoutes as e, BackendLibConfig as f, BackendLib as g };