@smooai/config 2.0.3 → 2.1.0

package/dist/nextjs/getConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/nextjs/getConfig.ts","../../src/platform/client.ts"],"sourcesContent":["import { ConfigClient, type ConfigClientOptions } from '../platform/client';\n\nexport interface GetConfigOptions extends ConfigClientOptions {\n    /** Config keys to fetch. If omitted, fetches all values for the environment. */\n    keys?: string[];\n    /** Additional fetch options passed to the underlying HTTP call (e.g., Next.js `{ next: { revalidate: 60 } }`). */\n    fetchOptions?: RequestInit;\n}\n\n/**\n * Server-side helper for fetching config values in Next.js Server Components or `getServerSideProps`.\n *\n * ```tsx\n * // app/layout.tsx (Server Component)\n * import { getConfig } from '@smooai/config/nextjs';\n *\n * export default async function RootLayout({ children }) {\n *     const config = await getConfig({\n *         environment: 'production',\n *         fetchOptions: { next: { revalidate: 60 } },\n *     });\n *     return (\n *         <SmooConfigProvider initialValues={config}>\n *             {children}\n *         </SmooConfigProvider>\n *     );\n * }\n * ```\n */\nexport async function getConfig(options: GetConfigOptions = {}): Promise<Record<string, unknown>> {\n    const { keys, fetchOptions, ...clientOptions } = options;\n    const client = new ConfigClient(clientOptions);\n\n    if (keys && keys.length > 0) {\n        const result: Record<string, unknown> = {};\n        await Promise.all(\n            keys.map(async (key) => {\n                result[key] = await client.getValue(key, clientOptions.environment);\n            }),\n        );\n        return result;\n    }\n\n    return client.getAllValues(clientOptions.environment, fetchOptions);\n}\n","/**\n * Browser/universal HTTP client for fetching config values from the Smoo AI config server.\n *\n * Environment variables (optional — used as defaults when constructor args are omitted):\n *   SMOOAI_CONFIG_API_URL  — Base URL of the config API\n *   SMOOAI_CONFIG_API_KEY  — Bearer token for authentication\n *   SMOOAI_CONFIG_ORG_ID   — Organization ID\n *   SMOOAI_CONFIG_ENV      — Default environment name (e.g. \"production\")\n */\n\nexport interface ConfigClientOptions {\n    /** Base URL of the config API server. Falls back to SMOOAI_CONFIG_API_URL env var. */\n    baseUrl?: string;\n    /** API key (M2M / client credentials token). Falls back to SMOOAI_CONFIG_API_KEY env var. */\n    apiKey?: string;\n    /** Organization ID. Falls back to SMOOAI_CONFIG_ORG_ID env var. */\n    orgId?: string;\n    /** Default environment name. Falls back to SMOOAI_CONFIG_ENV env var, then \"development\". */\n    environment?: string;\n    /** Cache TTL in milliseconds. 0 or undefined means cache never expires (manual invalidation only). */\n    cacheTtlMs?: number;\n}\n\ninterface CacheEntry {\n    value: unknown;\n    expiresAt: number; // 0 = never expires\n}\n\nfunction getEnv(key: string): string | undefined {\n    if (typeof process !== 'undefined' && process.env) {\n        return process.env[key];\n    }\n    return undefined;\n}\n\nexport class ConfigClient {\n    private baseUrl: string;\n    private orgId: string;\n    private apiKey: string;\n    private defaultEnvironment: string;\n    private cacheTtlMs: number;\n    private cache: Map<string, CacheEntry> = new Map();\n\n    constructor(options: ConfigClientOptions = {}) {\n        const baseUrl = options.baseUrl ?? getEnv('SMOOAI_CONFIG_API_URL');\n        const apiKey = options.apiKey ?? getEnv('SMOOAI_CONFIG_API_KEY');\n        const orgId = options.orgId ?? getEnv('SMOOAI_CONFIG_ORG_ID');\n\n        if (!baseUrl) throw new Error('@smooai/config: baseUrl is required (or set SMOOAI_CONFIG_API_URL)');\n        if (!apiKey) throw new Error('@smooai/config: apiKey is required (or set SMOOAI_CONFIG_API_KEY)');\n        if (!orgId) throw new Error('@smooai/config: orgId is required (or set SMOOAI_CONFIG_ORG_ID)');\n\n        this.baseUrl = baseUrl.replace(/\\/+$/, '');\n        this.apiKey = apiKey;\n        this.orgId = orgId;\n        this.defaultEnvironment = options.environment ?? getEnv('SMOOAI_CONFIG_ENV') ?? 'development';\n        this.cacheTtlMs = options.cacheTtlMs ?? 0;\n    }\n\n    private computeExpiresAt(): number {\n        return this.cacheTtlMs > 0 ? Date.now() + this.cacheTtlMs : 0;\n    }\n\n    private getCached(cacheKey: string): unknown | undefined {\n        const entry = this.cache.get(cacheKey);\n        if (!entry) return undefined;\n        if (entry.expiresAt > 0 && Date.now() > entry.expiresAt) {\n            this.cache.delete(cacheKey);\n            return undefined;\n        }\n        return entry.value;\n    }\n\n    private async fetchJson<T>(path: string, fetchOptions?: RequestInit): Promise<T> {\n        const response = await fetch(`${this.baseUrl}${path}`, {\n            ...fetchOptions,\n            headers: { Authorization: `Bearer ${this.apiKey}`, ...fetchOptions?.headers },\n        });\n        if (!response.ok) {\n            throw new Error(`Config API error: HTTP ${response.status} ${response.statusText}`);\n        }\n        return response.json() as Promise<T>;\n    }\n\n    /**\n     * Get a single config value by key.\n     * Results are cached locally after the first fetch.\n     */\n    async getValue(key: string, environment?: string): Promise<unknown> {\n        const env = environment ?? this.defaultEnvironment;\n        const cacheKey = `${env}:${key}`;\n\n        const cached = this.getCached(cacheKey);\n        if (cached !== undefined) {\n            return cached;\n        }\n\n        const result = await this.fetchJson<{ value: unknown }>(\n            `/organizations/${this.orgId}/config/values/${encodeURIComponent(key)}?environment=${encodeURIComponent(env)}`,\n        );\n        this.cache.set(cacheKey, { value: result.value, expiresAt: this.computeExpiresAt() });\n        return result.value;\n    }\n\n    /**\n     * Get all config values for an environment.\n     * All returned values are cached locally.\n     * @param environment - Environment name (defaults to constructor option or SMOOAI_CONFIG_ENV)\n     * @param fetchOptions - Optional fetch options (e.g., Next.js `{ next: { revalidate: 60 } }`)\n     */\n    async getAllValues(environment?: string, fetchOptions?: RequestInit): Promise<Record<string, unknown>> {\n        const env = environment ?? this.defaultEnvironment;\n\n        const result = await this.fetchJson<{ values: Record<string, unknown> }>(\n            `/organizations/${this.orgId}/config/values?environment=${encodeURIComponent(env)}`,\n            fetchOptions,\n        );\n\n        const expiresAt = this.computeExpiresAt();\n        for (const [key, value] of Object.entries(result.values)) {\n            this.cache.set(`${env}:${key}`, { value, expiresAt });\n        }\n\n        return result.values;\n    }\n\n    /**\n     * Pre-populate a single cache entry (e.g., from SSR).\n     * Does not make a network request.\n     */\n    seedCache(key: string, value: unknown, environment?: string): void {\n        const env = environment ?? this.defaultEnvironment;\n        this.cache.set(`${env}:${key}`, { value, expiresAt: this.computeExpiresAt() });\n    }\n\n    /**\n     * Pre-populate multiple cache entries from a key-value map (e.g., from SSR).\n     * Does not make a network request.\n     */\n    seedCacheFromMap(values: Record<string, unknown>, environment?: string): void {\n        const env = environment ?? this.defaultEnvironment;\n        const expiresAt = this.computeExpiresAt();\n        for (const [key, value] of Object.entries(values)) {\n            this.cache.set(`${env}:${key}`, { value, expiresAt });\n        }\n    }\n\n    /**\n     * Synchronously read a value from the local cache without making a network request.\n     * Returns `undefined` if the key is not cached or has expired.\n     */\n    getCachedValue(key: string, environment?: string): unknown | undefined {\n        const env = environment ?? this.defaultEnvironment;\n        return this.getCached(`${env}:${key}`);\n    }\n\n    /** Clear the entire local cache. */\n    invalidateCache(): void {\n        this.cache.clear();\n    }\n\n    /** Clear cached values for a specific environment. */\n    invalidateCacheForEnvironment(environment: string): void {\n        const prefix = `${environment}:`;\n        for (const key of this.cache.keys()) {\n            if (key.startsWith(prefix)) {\n                this.cache.delete(key);\n            }\n        }\n    }\n}\n"],"mappings":"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","names":[]}

package/dist/nextjs/getConfig.mjs

@@ -0,0 +1,9 @@
+import {
+  getConfig
+} from "../chunk-FAF45VZA.mjs";
+import "../chunk-3B5SRHJ2.mjs";
+import "../chunk-J5LGTIGS.mjs";
+export {
+  getConfig
+};
+//# sourceMappingURL=getConfig.mjs.map

package/dist/nextjs/getConfig.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/nextjs/hooks.d.mts

@@ -0,0 +1,22 @@
+interface UseConfigResult<T = unknown> {
+    /** The resolved config value, or undefined while loading (synchronous when pre-seeded). */
+    value: T | undefined;
+    /** True while the initial fetch is in progress. False immediately if value was pre-seeded. */
+    isLoading: boolean;
+    /** The error if the fetch failed. */
+    error: Error | null;
+    /** Re-fetch the value (bypasses cache). */
+    refetch: () => void;
+}
+/**
+ * SSR-aware hook for fetching a public config value.
+ * Returns the value synchronously when pre-seeded via `SmooConfigProvider`.
+ */
+declare function usePublicConfig<T = unknown>(key: string, environment?: string): UseConfigResult<T>;
+/**
+ * SSR-aware hook for fetching a feature flag value.
+ * Returns the value synchronously when pre-seeded via `SmooConfigProvider`.
+ */
+declare function useFeatureFlag<T = unknown>(key: string, environment?: string): UseConfigResult<T>;
+
+export { useFeatureFlag, usePublicConfig };

package/dist/nextjs/hooks.d.ts

@@ -0,0 +1,22 @@
+interface UseConfigResult<T = unknown> {
+    /** The resolved config value, or undefined while loading (synchronous when pre-seeded). */
+    value: T | undefined;
+    /** True while the initial fetch is in progress. False immediately if value was pre-seeded. */
+    isLoading: boolean;
+    /** The error if the fetch failed. */
+    error: Error | null;
+    /** Re-fetch the value (bypasses cache). */
+    refetch: () => void;
+}
+/**
+ * SSR-aware hook for fetching a public config value.
+ * Returns the value synchronously when pre-seeded via `SmooConfigProvider`.
+ */
+declare function usePublicConfig<T = unknown>(key: string, environment?: string): UseConfigResult<T>;
+/**
+ * SSR-aware hook for fetching a feature flag value.
+ * Returns the value synchronously when pre-seeded via `SmooConfigProvider`.
+ */
+declare function useFeatureFlag<T = unknown>(key: string, environment?: string): UseConfigResult<T>;
+
+export { useFeatureFlag, usePublicConfig };

package/dist/nextjs/hooks.js

@@ -0,0 +1,89 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/nextjs/hooks.ts
+var hooks_exports = {};
+__export(hooks_exports, {
+  useFeatureFlag: () => useFeatureFlag,
+  usePublicConfig: () => usePublicConfig
+});
+module.exports = __toCommonJS(hooks_exports);
+var import_react2 = require("react");
+
+// src/react/ConfigProvider.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var ConfigContext = (0, import_react.createContext)(null);
+function useConfigClient() {
+  const client = (0, import_react.useContext)(ConfigContext);
+  if (!client) {
+    throw new Error("useConfigClient must be used within a <ConfigProvider>");
+  }
+  return client;
+}
+
+// src/nextjs/hooks.ts
+function useConfigValue(key, environment) {
+  const client = useConfigClient();
+  const [value, setValue] = (0, import_react2.useState)(() => client.getCachedValue(key, environment));
+  const [isLoading, setIsLoading] = (0, import_react2.useState)(value === void 0);
+  const [error, setError] = (0, import_react2.useState)(null);
+  const [fetchCount, setFetchCount] = (0, import_react2.useState)(0);
+  const refetch = (0, import_react2.useCallback)(() => {
+    client.invalidateCache();
+    setFetchCount((c) => c + 1);
+  }, [client]);
+  (0, import_react2.useEffect)(() => {
+    if (value !== void 0 && fetchCount === 0) {
+      setIsLoading(false);
+      return;
+    }
+    let cancelled = false;
+    setIsLoading(true);
+    setError(null);
+    client.getValue(key, environment).then((result) => {
+      if (!cancelled) {
+        setValue(result);
+        setIsLoading(false);
+      }
+    }).catch((err) => {
+      if (!cancelled) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setIsLoading(false);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [client, key, environment, fetchCount]);
+  return { value, isLoading, error, refetch };
+}
+function usePublicConfig(key, environment) {
+  return useConfigValue(key, environment);
+}
+function useFeatureFlag(key, environment) {
+  return useConfigValue(key, environment);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useFeatureFlag,
+  usePublicConfig
+});
+//# sourceMappingURL=hooks.js.map

package/dist/nextjs/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/nextjs/hooks.ts","../../src/react/ConfigProvider.tsx"],"sourcesContent":["'use client';\n\nimport { useCallback, useEffect, useState } from 'react';\nimport { useConfigClient } from '../react/ConfigProvider';\n\ninterface UseConfigResult<T = unknown> {\n    /** The resolved config value, or undefined while loading (synchronous when pre-seeded). */\n    value: T | undefined;\n    /** True while the initial fetch is in progress. False immediately if value was pre-seeded. */\n    isLoading: boolean;\n    /** The error if the fetch failed. */\n    error: Error | null;\n    /** Re-fetch the value (bypasses cache). */\n    refetch: () => void;\n}\n\nfunction useConfigValue(key: string, environment?: string): UseConfigResult {\n    const client = useConfigClient();\n\n    // Attempt synchronous read from pre-seeded cache (zero loading flash)\n    const [value, setValue] = useState<unknown>(() => client.getCachedValue(key, environment));\n    const [isLoading, setIsLoading] = useState(value === undefined);\n    const [error, setError] = useState<Error | null>(null);\n    const [fetchCount, setFetchCount] = useState(0);\n\n    const refetch = useCallback(() => {\n        client.invalidateCache();\n        setFetchCount((c) => c + 1);\n    }, [client]);\n\n    useEffect(() => {\n        // If we already have a cached value and this is the initial mount, skip fetch\n        if (value !== undefined && fetchCount === 0) {\n            setIsLoading(false);\n            return;\n        }\n\n        let cancelled = false;\n        setIsLoading(true);\n        setError(null);\n\n        client\n            .getValue(key, environment)\n            .then((result) => {\n                if (!cancelled) {\n                    setValue(result);\n                    setIsLoading(false);\n                }\n            })\n            .catch((err: unknown) => {\n                if (!cancelled) {\n                    setError(err instanceof Error ? err : new Error(String(err)));\n                    setIsLoading(false);\n                }\n            });\n\n        return () => {\n            cancelled = true;\n        };\n    }, [client, key, environment, fetchCount]);\n\n    return { value, isLoading, error, refetch };\n}\n\n/**\n * SSR-aware hook for fetching a public config value.\n * Returns the value synchronously when pre-seeded via `SmooConfigProvider`.\n */\nexport function usePublicConfig<T = unknown>(key: string, environment?: string): UseConfigResult<T> {\n    return useConfigValue(key, environment) as UseConfigResult<T>;\n}\n\n/**\n * SSR-aware hook for fetching a feature flag value.\n * Returns the value synchronously when pre-seeded via `SmooConfigProvider`.\n */\nexport function useFeatureFlag<T = unknown>(key: string, environment?: string): UseConfigResult<T> {\n    return useConfigValue(key, environment) as UseConfigResult<T>;\n}\n","'use client';\n\nimport { createContext, useContext, useMemo, type ReactNode } from 'react';\nimport { ConfigClient, type ConfigClientOptions } from '../platform/client';\n\nexport const ConfigContext = createContext<ConfigClient | null>(null);\n\nexport interface ConfigProviderProps extends ConfigClientOptions {\n    children: ReactNode;\n}\n\n/**\n * Provides a ConfigClient instance to all descendant components.\n *\n * ```tsx\n * <ConfigProvider baseUrl=\"https://api.smooai.dev\" apiKey=\"...\" orgId=\"...\" environment=\"production\">\n *   <App />\n * </ConfigProvider>\n * ```\n *\n * All props are optional if the corresponding environment variables are set:\n *   SMOOAI_CONFIG_API_URL, SMOOAI_CONFIG_API_KEY, SMOOAI_CONFIG_ORG_ID, SMOOAI_CONFIG_ENV\n */\nexport function ConfigProvider({ children, ...options }: ConfigProviderProps) {\n    const client = useMemo(() => new ConfigClient(options), [options.baseUrl, options.apiKey, options.orgId, options.environment]);\n\n    return <ConfigContext.Provider value={client}>{children}</ConfigContext.Provider>;\n}\n\n/**\n * Access the ConfigClient instance from the nearest ConfigProvider.\n * Throws if used outside a ConfigProvider.\n */\nexport function useConfigClient(): ConfigClient {\n    const client = useContext(ConfigContext);\n    if (!client) {\n        throw new Error('useConfigClient must be used within a <ConfigProvider>');\n    }\n    return client;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA,IAAAA,gBAAiD;;;ACAjD,mBAAmE;AAwBxD;AArBJ,IAAM,oBAAgB,4BAAmC,IAAI;AA4B7D,SAAS,kBAAgC;AAC5C,QAAM,aAAS,yBAAW,aAAa;AACvC,MAAI,CAAC,QAAQ;AACT,UAAM,IAAI,MAAM,wDAAwD;AAAA,EAC5E;AACA,SAAO;AACX;;;ADvBA,SAAS,eAAe,KAAa,aAAuC;AACxE,QAAM,SAAS,gBAAgB;AAG/B,QAAM,CAAC,OAAO,QAAQ,QAAI,wBAAkB,MAAM,OAAO,eAAe,KAAK,WAAW,CAAC;AACzF,QAAM,CAAC,WAAW,YAAY,QAAI,wBAAS,UAAU,MAAS;AAC9D,QAAM,CAAC,OAAO,QAAQ,QAAI,wBAAuB,IAAI;AACrD,QAAM,CAAC,YAAY,aAAa,QAAI,wBAAS,CAAC;AAE9C,QAAM,cAAU,2BAAY,MAAM;AAC9B,WAAO,gBAAgB;AACvB,kBAAc,CAAC,MAAM,IAAI,CAAC;AAAA,EAC9B,GAAG,CAAC,MAAM,CAAC;AAEX,+BAAU,MAAM;AAEZ,QAAI,UAAU,UAAa,eAAe,GAAG;AACzC,mBAAa,KAAK;AAClB;AAAA,IACJ;AAEA,QAAI,YAAY;AAChB,iBAAa,IAAI;AACjB,aAAS,IAAI;AAEb,WACK,SAAS,KAAK,WAAW,EACzB,KAAK,CAAC,WAAW;AACd,UAAI,CAAC,WAAW;AACZ,iBAAS,MAAM;AACf,qBAAa,KAAK;AAAA,MACtB;AAAA,IACJ,CAAC,EACA,MAAM,CAAC,QAAiB;AACrB,UAAI,CAAC,WAAW;AACZ,iBAAS,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;AAC5D,qBAAa,KAAK;AAAA,MACtB;AAAA,IACJ,CAAC;AAEL,WAAO,MAAM;AACT,kBAAY;AAAA,IAChB;AAAA,EACJ,GAAG,CAAC,QAAQ,KAAK,aAAa,UAAU,CAAC;AAEzC,SAAO,EAAE,OAAO,WAAW,OAAO,QAAQ;AAC9C;AAMO,SAAS,gBAA6B,KAAa,aAA0C;AAChG,SAAO,eAAe,KAAK,WAAW;AAC1C;AAMO,SAAS,eAA4B,KAAa,aAA0C;AAC/F,SAAO,eAAe,KAAK,WAAW;AAC1C;","names":["import_react"]}

package/dist/nextjs/hooks.mjs

@@ -0,0 +1,13 @@
+"use client";
+import {
+  useFeatureFlag,
+  usePublicConfig
+} from "../chunk-GP2JUWOD.mjs";
+import "../chunk-N6Z4AZZA.mjs";
+import "../chunk-3B5SRHJ2.mjs";
+import "../chunk-J5LGTIGS.mjs";
+export {
+  useFeatureFlag,
+  usePublicConfig
+};
+//# sourceMappingURL=hooks.mjs.map

package/dist/nextjs/hooks.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/nextjs/index.d.mts

@@ -0,0 +1,28 @@
+export { GetConfigOptions, getConfig } from './getConfig.mjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { ConfigClientOptions } from '../platform/client.mjs';
+export { useFeatureFlag, usePublicConfig } from './hooks.mjs';
+
+interface SmooConfigProviderProps extends ConfigClientOptions {
+    /** Initial config values fetched on the server (from `getConfig()`). Pre-seeds the client cache. */
+    initialValues?: Record<string, unknown>;
+    children: ReactNode;
+}
+/**
+ * Client Component that provides a pre-seeded ConfigClient, eliminating loading
+ * flashes on first render when used with server-fetched `initialValues`.
+ *
+ * ```tsx
+ * // layout.tsx (Server Component)
+ * const config = await getConfig({ environment: 'production' });
+ *
+ * // Client boundary
+ * <SmooConfigProvider initialValues={config} environment="production" {...clientOptions}>
+ *   <App />
+ * </SmooConfigProvider>
+ * ```
+ */
+declare function SmooConfigProvider({ initialValues, children, ...options }: SmooConfigProviderProps): react_jsx_runtime.JSX.Element;
+
+export { SmooConfigProvider, type SmooConfigProviderProps };

package/dist/nextjs/index.d.ts

@@ -0,0 +1,28 @@
+export { GetConfigOptions, getConfig } from './getConfig.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { ConfigClientOptions } from '../platform/client.js';
+export { useFeatureFlag, usePublicConfig } from './hooks.js';
+
+interface SmooConfigProviderProps extends ConfigClientOptions {
+    /** Initial config values fetched on the server (from `getConfig()`). Pre-seeds the client cache. */
+    initialValues?: Record<string, unknown>;
+    children: ReactNode;
+}
+/**
+ * Client Component that provides a pre-seeded ConfigClient, eliminating loading
+ * flashes on first render when used with server-fetched `initialValues`.
+ *
+ * ```tsx
+ * // layout.tsx (Server Component)
+ * const config = await getConfig({ environment: 'production' });
+ *
+ * // Client boundary
+ * <SmooConfigProvider initialValues={config} environment="production" {...clientOptions}>
+ *   <App />
+ * </SmooConfigProvider>
+ * ```
+ */
+declare function SmooConfigProvider({ initialValues, children, ...options }: SmooConfigProviderProps): react_jsx_runtime.JSX.Element;
+
+export { SmooConfigProvider, type SmooConfigProviderProps };

package/dist/nextjs/index.js

@@ -0,0 +1,255 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/nextjs/index.ts
+var nextjs_exports = {};
+__export(nextjs_exports, {
+  SmooConfigProvider: () => SmooConfigProvider,
+  getConfig: () => getConfig,
+  useFeatureFlag: () => useFeatureFlag,
+  usePublicConfig: () => usePublicConfig
+});
+module.exports = __toCommonJS(nextjs_exports);
+
+// src/platform/client.ts
+function getEnv(key) {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env[key];
+  }
+  return void 0;
+}
+var ConfigClient = class {
+  baseUrl;
+  orgId;
+  apiKey;
+  defaultEnvironment;
+  cacheTtlMs;
+  cache = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    const baseUrl = options.baseUrl ?? getEnv("SMOOAI_CONFIG_API_URL");
+    const apiKey = options.apiKey ?? getEnv("SMOOAI_CONFIG_API_KEY");
+    const orgId = options.orgId ?? getEnv("SMOOAI_CONFIG_ORG_ID");
+    if (!baseUrl) throw new Error("@smooai/config: baseUrl is required (or set SMOOAI_CONFIG_API_URL)");
+    if (!apiKey) throw new Error("@smooai/config: apiKey is required (or set SMOOAI_CONFIG_API_KEY)");
+    if (!orgId) throw new Error("@smooai/config: orgId is required (or set SMOOAI_CONFIG_ORG_ID)");
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+    this.orgId = orgId;
+    this.defaultEnvironment = options.environment ?? getEnv("SMOOAI_CONFIG_ENV") ?? "development";
+    this.cacheTtlMs = options.cacheTtlMs ?? 0;
+  }
+  computeExpiresAt() {
+    return this.cacheTtlMs > 0 ? Date.now() + this.cacheTtlMs : 0;
+  }
+  getCached(cacheKey) {
+    const entry = this.cache.get(cacheKey);
+    if (!entry) return void 0;
+    if (entry.expiresAt > 0 && Date.now() > entry.expiresAt) {
+      this.cache.delete(cacheKey);
+      return void 0;
+    }
+    return entry.value;
+  }
+  async fetchJson(path, fetchOptions) {
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      ...fetchOptions,
+      headers: { Authorization: `Bearer ${this.apiKey}`, ...fetchOptions?.headers }
+    });
+    if (!response.ok) {
+      throw new Error(`Config API error: HTTP ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+  }
+  /**
+   * Get a single config value by key.
+   * Results are cached locally after the first fetch.
+   */
+  async getValue(key, environment) {
+    const env = environment ?? this.defaultEnvironment;
+    const cacheKey = `${env}:${key}`;
+    const cached = this.getCached(cacheKey);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const result = await this.fetchJson(
+      `/organizations/${this.orgId}/config/values/${encodeURIComponent(key)}?environment=${encodeURIComponent(env)}`
+    );
+    this.cache.set(cacheKey, { value: result.value, expiresAt: this.computeExpiresAt() });
+    return result.value;
+  }
+  /**
+   * Get all config values for an environment.
+   * All returned values are cached locally.
+   * @param environment - Environment name (defaults to constructor option or SMOOAI_CONFIG_ENV)
+   * @param fetchOptions - Optional fetch options (e.g., Next.js `{ next: { revalidate: 60 } }`)
+   */
+  async getAllValues(environment, fetchOptions) {
+    const env = environment ?? this.defaultEnvironment;
+    const result = await this.fetchJson(
+      `/organizations/${this.orgId}/config/values?environment=${encodeURIComponent(env)}`,
+      fetchOptions
+    );
+    const expiresAt = this.computeExpiresAt();
+    for (const [key, value] of Object.entries(result.values)) {
+      this.cache.set(`${env}:${key}`, { value, expiresAt });
+    }
+    return result.values;
+  }
+  /**
+   * Pre-populate a single cache entry (e.g., from SSR).
+   * Does not make a network request.
+   */
+  seedCache(key, value, environment) {
+    const env = environment ?? this.defaultEnvironment;
+    this.cache.set(`${env}:${key}`, { value, expiresAt: this.computeExpiresAt() });
+  }
+  /**
+   * Pre-populate multiple cache entries from a key-value map (e.g., from SSR).
+   * Does not make a network request.
+   */
+  seedCacheFromMap(values, environment) {
+    const env = environment ?? this.defaultEnvironment;
+    const expiresAt = this.computeExpiresAt();
+    for (const [key, value] of Object.entries(values)) {
+      this.cache.set(`${env}:${key}`, { value, expiresAt });
+    }
+  }
+  /**
+   * Synchronously read a value from the local cache without making a network request.
+   * Returns `undefined` if the key is not cached or has expired.
+   */
+  getCachedValue(key, environment) {
+    const env = environment ?? this.defaultEnvironment;
+    return this.getCached(`${env}:${key}`);
+  }
+  /** Clear the entire local cache. */
+  invalidateCache() {
+    this.cache.clear();
+  }
+  /** Clear cached values for a specific environment. */
+  invalidateCacheForEnvironment(environment) {
+    const prefix = `${environment}:`;
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this.cache.delete(key);
+      }
+    }
+  }
+};
+
+// src/nextjs/getConfig.ts
+async function getConfig(options = {}) {
+  const { keys, fetchOptions, ...clientOptions } = options;
+  const client = new ConfigClient(clientOptions);
+  if (keys && keys.length > 0) {
+    const result = {};
+    await Promise.all(
+      keys.map(async (key) => {
+        result[key] = await client.getValue(key, clientOptions.environment);
+      })
+    );
+    return result;
+  }
+  return client.getAllValues(clientOptions.environment, fetchOptions);
+}
+
+// src/nextjs/SmooConfigProvider.tsx
+var import_react2 = require("react");
+
+// src/react/ConfigProvider.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var ConfigContext = (0, import_react.createContext)(null);
+function useConfigClient() {
+  const client = (0, import_react.useContext)(ConfigContext);
+  if (!client) {
+    throw new Error("useConfigClient must be used within a <ConfigProvider>");
+  }
+  return client;
+}
+
+// src/nextjs/SmooConfigProvider.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function SmooConfigProvider({ initialValues, children, ...options }) {
+  const client = (0, import_react2.useMemo)(() => {
+    const c = new ConfigClient(options);
+    if (initialValues) {
+      c.seedCacheFromMap(initialValues, options.environment);
+    }
+    return c;
+  }, [options.baseUrl, options.apiKey, options.orgId, options.environment]);
+  (0, import_react2.useEffect)(() => {
+    if (initialValues) {
+      client.seedCacheFromMap(initialValues, options.environment);
+    }
+  }, [initialValues, client, options.environment]);
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(ConfigContext.Provider, { value: client, children });
+}
+
+// src/nextjs/hooks.ts
+var import_react3 = require("react");
+function useConfigValue(key, environment) {
+  const client = useConfigClient();
+  const [value, setValue] = (0, import_react3.useState)(() => client.getCachedValue(key, environment));
+  const [isLoading, setIsLoading] = (0, import_react3.useState)(value === void 0);
+  const [error, setError] = (0, import_react3.useState)(null);
+  const [fetchCount, setFetchCount] = (0, import_react3.useState)(0);
+  const refetch = (0, import_react3.useCallback)(() => {
+    client.invalidateCache();
+    setFetchCount((c) => c + 1);
+  }, [client]);
+  (0, import_react3.useEffect)(() => {
+    if (value !== void 0 && fetchCount === 0) {
+      setIsLoading(false);
+      return;
+    }
+    let cancelled = false;
+    setIsLoading(true);
+    setError(null);
+    client.getValue(key, environment).then((result) => {
+      if (!cancelled) {
+        setValue(result);
+        setIsLoading(false);
+      }
+    }).catch((err) => {
+      if (!cancelled) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setIsLoading(false);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [client, key, environment, fetchCount]);
+  return { value, isLoading, error, refetch };
+}
+function usePublicConfig(key, environment) {
+  return useConfigValue(key, environment);
+}
+function useFeatureFlag(key, environment) {
+  return useConfigValue(key, environment);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SmooConfigProvider,
+  getConfig,
+  useFeatureFlag,
+  usePublicConfig
+});
+//# sourceMappingURL=index.js.map

package/dist/nextjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/nextjs/index.ts","../../src/platform/client.ts","../../src/nextjs/getConfig.ts","../../src/nextjs/SmooConfigProvider.tsx","../../src/react/ConfigProvider.tsx","../../src/nextjs/hooks.ts"],"sourcesContent":["export { getConfig } from './getConfig';\nexport type { GetConfigOptions } from './getConfig';\nexport { SmooConfigProvider } from './SmooConfigProvider';\nexport type { SmooConfigProviderProps } from './SmooConfigProvider';\nexport { usePublicConfig, useFeatureFlag } from './hooks';\n","/**\n * Browser/universal HTTP client for fetching config values from the Smoo AI config server.\n *\n * Environment variables (optional — used as defaults when constructor args are omitted):\n *   SMOOAI_CONFIG_API_URL  — Base URL of the config API\n *   SMOOAI_CONFIG_API_KEY  — Bearer token for authentication\n *   SMOOAI_CONFIG_ORG_ID   — Organization ID\n *   SMOOAI_CONFIG_ENV      — Default environment name (e.g. \"production\")\n */\n\nexport interface ConfigClientOptions {\n    /** Base URL of the config API server. Falls back to SMOOAI_CONFIG_API_URL env var. */\n    baseUrl?: string;\n    /** API key (M2M / client credentials token). Falls back to SMOOAI_CONFIG_API_KEY env var. */\n    apiKey?: string;\n    /** Organization ID. Falls back to SMOOAI_CONFIG_ORG_ID env var. */\n    orgId?: string;\n    /** Default environment name. Falls back to SMOOAI_CONFIG_ENV env var, then \"development\". */\n    environment?: string;\n    /** Cache TTL in milliseconds. 0 or undefined means cache never expires (manual invalidation only). */\n    cacheTtlMs?: number;\n}\n\ninterface CacheEntry {\n    value: unknown;\n    expiresAt: number; // 0 = never expires\n}\n\nfunction getEnv(key: string): string | undefined {\n    if (typeof process !== 'undefined' && process.env) {\n        return process.env[key];\n    }\n    return undefined;\n}\n\nexport class ConfigClient {\n    private baseUrl: string;\n    private orgId: string;\n    private apiKey: string;\n    private defaultEnvironment: string;\n    private cacheTtlMs: number;\n    private cache: Map<string, CacheEntry> = new Map();\n\n    constructor(options: ConfigClientOptions = {}) {\n        const baseUrl = options.baseUrl ?? getEnv('SMOOAI_CONFIG_API_URL');\n        const apiKey = options.apiKey ?? getEnv('SMOOAI_CONFIG_API_KEY');\n        const orgId = options.orgId ?? getEnv('SMOOAI_CONFIG_ORG_ID');\n\n        if (!baseUrl) throw new Error('@smooai/config: baseUrl is required (or set SMOOAI_CONFIG_API_URL)');\n        if (!apiKey) throw new Error('@smooai/config: apiKey is required (or set SMOOAI_CONFIG_API_KEY)');\n        if (!orgId) throw new Error('@smooai/config: orgId is required (or set SMOOAI_CONFIG_ORG_ID)');\n\n        this.baseUrl = baseUrl.replace(/\\/+$/, '');\n        this.apiKey = apiKey;\n        this.orgId = orgId;\n        this.defaultEnvironment = options.environment ?? getEnv('SMOOAI_CONFIG_ENV') ?? 'development';\n        this.cacheTtlMs = options.cacheTtlMs ?? 0;\n    }\n\n    private computeExpiresAt(): number {\n        return this.cacheTtlMs > 0 ? Date.now() + this.cacheTtlMs : 0;\n    }\n\n    private getCached(cacheKey: string): unknown | undefined {\n        const entry = this.cache.get(cacheKey);\n        if (!entry) return undefined;\n        if (entry.expiresAt > 0 && Date.now() > entry.expiresAt) {\n            this.cache.delete(cacheKey);\n            return undefined;\n        }\n        return entry.value;\n    }\n\n    private async fetchJson<T>(path: string, fetchOptions?: RequestInit): Promise<T> {\n        const response = await fetch(`${this.baseUrl}${path}`, {\n            ...fetchOptions,\n            headers: { Authorization: `Bearer ${this.apiKey}`, ...fetchOptions?.headers },\n        });\n        if (!response.ok) {\n            throw new Error(`Config API error: HTTP ${response.status} ${response.statusText}`);\n        }\n        return response.json() as Promise<T>;\n    }\n\n    /**\n     * Get a single config value by key.\n     * Results are cached locally after the first fetch.\n     */\n    async getValue(key: string, environment?: string): Promise<unknown> {\n        const env = environment ?? this.defaultEnvironment;\n        const cacheKey = `${env}:${key}`;\n\n        const cached = this.getCached(cacheKey);\n        if (cached !== undefined) {\n            return cached;\n        }\n\n        const result = await this.fetchJson<{ value: unknown }>(\n            `/organizations/${this.orgId}/config/values/${encodeURIComponent(key)}?environment=${encodeURIComponent(env)}`,\n        );\n        this.cache.set(cacheKey, { value: result.value, expiresAt: this.computeExpiresAt() });\n        return result.value;\n    }\n\n    /**\n     * Get all config values for an environment.\n     * All returned values are cached locally.\n     * @param environment - Environment name (defaults to constructor option or SMOOAI_CONFIG_ENV)\n     * @param fetchOptions - Optional fetch options (e.g., Next.js `{ next: { revalidate: 60 } }`)\n     */\n    async getAllValues(environment?: string, fetchOptions?: RequestInit): Promise<Record<string, unknown>> {\n        const env = environment ?? this.defaultEnvironment;\n\n        const result = await this.fetchJson<{ values: Record<string, unknown> }>(\n            `/organizations/${this.orgId}/config/values?environment=${encodeURIComponent(env)}`,\n            fetchOptions,\n        );\n\n        const expiresAt = this.computeExpiresAt();\n        for (const [key, value] of Object.entries(result.values)) {\n            this.cache.set(`${env}:${key}`, { value, expiresAt });\n        }\n\n        return result.values;\n    }\n\n    /**\n     * Pre-populate a single cache entry (e.g., from SSR).\n     * Does not make a network request.\n     */\n    seedCache(key: string, value: unknown, environment?: string): void {\n        const env = environment ?? this.defaultEnvironment;\n        this.cache.set(`${env}:${key}`, { value, expiresAt: this.computeExpiresAt() });\n    }\n\n    /**\n     * Pre-populate multiple cache entries from a key-value map (e.g., from SSR).\n     * Does not make a network request.\n     */\n    seedCacheFromMap(values: Record<string, unknown>, environment?: string): void {\n        const env = environment ?? this.defaultEnvironment;\n        const expiresAt = this.computeExpiresAt();\n        for (const [key, value] of Object.entries(values)) {\n            this.cache.set(`${env}:${key}`, { value, expiresAt });\n        }\n    }\n\n    /**\n     * Synchronously read a value from the local cache without making a network request.\n     * Returns `undefined` if the key is not cached or has expired.\n     */\n    getCachedValue(key: string, environment?: string): unknown | undefined {\n        const env = environment ?? this.defaultEnvironment;\n        return this.getCached(`${env}:${key}`);\n    }\n\n    /** Clear the entire local cache. */\n    invalidateCache(): void {\n        this.cache.clear();\n    }\n\n    /** Clear cached values for a specific environment. */\n    invalidateCacheForEnvironment(environment: string): void {\n        const prefix = `${environment}:`;\n        for (const key of this.cache.keys()) {\n            if (key.startsWith(prefix)) {\n                this.cache.delete(key);\n            }\n        }\n    }\n}\n","import { ConfigClient, type ConfigClientOptions } from '../platform/client';\n\nexport interface GetConfigOptions extends ConfigClientOptions {\n    /** Config keys to fetch. If omitted, fetches all values for the environment. */\n    keys?: string[];\n    /** Additional fetch options passed to the underlying HTTP call (e.g., Next.js `{ next: { revalidate: 60 } }`). */\n    fetchOptions?: RequestInit;\n}\n\n/**\n * Server-side helper for fetching config values in Next.js Server Components or `getServerSideProps`.\n *\n * ```tsx\n * // app/layout.tsx (Server Component)\n * import { getConfig } from '@smooai/config/nextjs';\n *\n * export default async function RootLayout({ children }) {\n *     const config = await getConfig({\n *         environment: 'production',\n *         fetchOptions: { next: { revalidate: 60 } },\n *     });\n *     return (\n *         <SmooConfigProvider initialValues={config}>\n *             {children}\n *         </SmooConfigProvider>\n *     );\n * }\n * ```\n */\nexport async function getConfig(options: GetConfigOptions = {}): Promise<Record<string, unknown>> {\n    const { keys, fetchOptions, ...clientOptions } = options;\n    const client = new ConfigClient(clientOptions);\n\n    if (keys && keys.length > 0) {\n        const result: Record<string, unknown> = {};\n        await Promise.all(\n            keys.map(async (key) => {\n                result[key] = await client.getValue(key, clientOptions.environment);\n            }),\n        );\n        return result;\n    }\n\n    return client.getAllValues(clientOptions.environment, fetchOptions);\n}\n","'use client';\n\nimport { useEffect, useMemo, type ReactNode } from 'react';\nimport { ConfigClient, type ConfigClientOptions } from '../platform/client';\nimport { ConfigContext } from '../react/ConfigProvider';\n\nexport interface SmooConfigProviderProps extends ConfigClientOptions {\n    /** Initial config values fetched on the server (from `getConfig()`). Pre-seeds the client cache. */\n    initialValues?: Record<string, unknown>;\n    children: ReactNode;\n}\n\n/**\n * Client Component that provides a pre-seeded ConfigClient, eliminating loading\n * flashes on first render when used with server-fetched `initialValues`.\n *\n * ```tsx\n * // layout.tsx (Server Component)\n * const config = await getConfig({ environment: 'production' });\n *\n * // Client boundary\n * <SmooConfigProvider initialValues={config} environment=\"production\" {...clientOptions}>\n *   <App />\n * </SmooConfigProvider>\n * ```\n */\nexport function SmooConfigProvider({ initialValues, children, ...options }: SmooConfigProviderProps) {\n    const client = useMemo(() => {\n        const c = new ConfigClient(options);\n        if (initialValues) {\n            c.seedCacheFromMap(initialValues, options.environment);\n        }\n        return c;\n    }, [options.baseUrl, options.apiKey, options.orgId, options.environment]);\n\n    // Re-seed if initialValues change (e.g., after revalidation)\n    useEffect(() => {\n        if (initialValues) {\n            client.seedCacheFromMap(initialValues, options.environment);\n        }\n    }, [initialValues, client, options.environment]);\n\n    return <ConfigContext.Provider value={client}>{children}</ConfigContext.Provider>;\n}\n","'use client';\n\nimport { createContext, useContext, useMemo, type ReactNode } from 'react';\nimport { ConfigClient, type ConfigClientOptions } from '../platform/client';\n\nexport const ConfigContext = createContext<ConfigClient | null>(null);\n\nexport interface ConfigProviderProps extends ConfigClientOptions {\n    children: ReactNode;\n}\n\n/**\n * Provides a ConfigClient instance to all descendant components.\n *\n * ```tsx\n * <ConfigProvider baseUrl=\"https://api.smooai.dev\" apiKey=\"...\" orgId=\"...\" environment=\"production\">\n *   <App />\n * </ConfigProvider>\n * ```\n *\n * All props are optional if the corresponding environment variables are set:\n *   SMOOAI_CONFIG_API_URL, SMOOAI_CONFIG_API_KEY, SMOOAI_CONFIG_ORG_ID, SMOOAI_CONFIG_ENV\n */\nexport function ConfigProvider({ children, ...options }: ConfigProviderProps) {\n    const client = useMemo(() => new ConfigClient(options), [options.baseUrl, options.apiKey, options.orgId, options.environment]);\n\n    return <ConfigContext.Provider value={client}>{children}</ConfigContext.Provider>;\n}\n\n/**\n * Access the ConfigClient instance from the nearest ConfigProvider.\n * Throws if used outside a ConfigProvider.\n */\nexport function useConfigClient(): ConfigClient {\n    const client = useContext(ConfigContext);\n    if (!client) {\n        throw new Error('useConfigClient must be used within a <ConfigProvider>');\n    }\n    return client;\n}\n","'use client';\n\nimport { useCallback, useEffect, useState } from 'react';\nimport { useConfigClient } from '../react/ConfigProvider';\n\ninterface UseConfigResult<T = unknown> {\n    /** The resolved config value, or undefined while loading (synchronous when pre-seeded). */\n    value: T | undefined;\n    /** True while the initial fetch is in progress. False immediately if value was pre-seeded. */\n    isLoading: boolean;\n    /** The error if the fetch failed. */\n    error: Error | null;\n    /** Re-fetch the value (bypasses cache). */\n    refetch: () => void;\n}\n\nfunction useConfigValue(key: string, environment?: string): UseConfigResult {\n    const client = useConfigClient();\n\n    // Attempt synchronous read from pre-seeded cache (zero loading flash)\n    const [value, setValue] = useState<unknown>(() => client.getCachedValue(key, environment));\n    const [isLoading, setIsLoading] = useState(value === undefined);\n    const [error, setError] = useState<Error | null>(null);\n    const [fetchCount, setFetchCount] = useState(0);\n\n    const refetch = useCallback(() => {\n        client.invalidateCache();\n        setFetchCount((c) => c + 1);\n    }, [client]);\n\n    useEffect(() => {\n        // If we already have a cached value and this is the initial mount, skip fetch\n        if (value !== undefined && fetchCount === 0) {\n            setIsLoading(false);\n            return;\n        }\n\n        let cancelled = false;\n        setIsLoading(true);\n        setError(null);\n\n        client\n            .getValue(key, environment)\n            .then((result) => {\n                if (!cancelled) {\n                    setValue(result);\n                    setIsLoading(false);\n                }\n            })\n            .catch((err: unknown) => {\n                if (!cancelled) {\n                    setError(err instanceof Error ? err : new Error(String(err)));\n                    setIsLoading(false);\n                }\n            });\n\n        return () => {\n            cancelled = true;\n        };\n    }, [client, key, environment, fetchCount]);\n\n    return { value, isLoading, error, refetch };\n}\n\n/**\n * SSR-aware hook for fetching a public config value.\n * Returns the value synchronously when pre-seeded via `SmooConfigProvider`.\n */\nexport function usePublicConfig<T = unknown>(key: string, environment?: string): UseConfigResult<T> {\n    return useConfigValue(key, environment) as UseConfigResult<T>;\n}\n\n/**\n * SSR-aware hook for fetching a feature flag value.\n * Returns the value synchronously when pre-seeded via `SmooConfigProvider`.\n */\nexport function useFeatureFlag<T = unknown>(key: string, environment?: string): UseConfigResult<T> {\n    return useConfigValue(key, environment) as UseConfigResult<T>;\n}\n"],"mappings":"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","names":["import_react","import_jsx_runtime","import_react"]}

package/dist/nextjs/index.mjs

@@ -0,0 +1,40 @@
+import {
+  getConfig
+} from "../chunk-FAF45VZA.mjs";
+import {
+  useFeatureFlag,
+  usePublicConfig
+} from "../chunk-GP2JUWOD.mjs";
+import {
+  ConfigContext
+} from "../chunk-N6Z4AZZA.mjs";
+import {
+  ConfigClient
+} from "../chunk-3B5SRHJ2.mjs";
+import "../chunk-J5LGTIGS.mjs";
+
+// src/nextjs/SmooConfigProvider.tsx
+import { useEffect, useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+function SmooConfigProvider({ initialValues, children, ...options }) {
+  const client = useMemo(() => {
+    const c = new ConfigClient(options);
+    if (initialValues) {
+      c.seedCacheFromMap(initialValues, options.environment);
+    }
+    return c;
+  }, [options.baseUrl, options.apiKey, options.orgId, options.environment]);
+  useEffect(() => {
+    if (initialValues) {
+      client.seedCacheFromMap(initialValues, options.environment);
+    }
+  }, [initialValues, client, options.environment]);
+  return /* @__PURE__ */ jsx(ConfigContext.Provider, { value: client, children });
+}
+export {
+  SmooConfigProvider,
+  getConfig,
+  useFeatureFlag,
+  usePublicConfig
+};
+//# sourceMappingURL=index.mjs.map

package/dist/nextjs/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/nextjs/SmooConfigProvider.tsx"],"sourcesContent":["'use client';\n\nimport { useEffect, useMemo, type ReactNode } from 'react';\nimport { ConfigClient, type ConfigClientOptions } from '../platform/client';\nimport { ConfigContext } from '../react/ConfigProvider';\n\nexport interface SmooConfigProviderProps extends ConfigClientOptions {\n    /** Initial config values fetched on the server (from `getConfig()`). Pre-seeds the client cache. */\n    initialValues?: Record<string, unknown>;\n    children: ReactNode;\n}\n\n/**\n * Client Component that provides a pre-seeded ConfigClient, eliminating loading\n * flashes on first render when used with server-fetched `initialValues`.\n *\n * ```tsx\n * // layout.tsx (Server Component)\n * const config = await getConfig({ environment: 'production' });\n *\n * // Client boundary\n * <SmooConfigProvider initialValues={config} environment=\"production\" {...clientOptions}>\n *   <App />\n * </SmooConfigProvider>\n * ```\n */\nexport function SmooConfigProvider({ initialValues, children, ...options }: SmooConfigProviderProps) {\n    const client = useMemo(() => {\n        const c = new ConfigClient(options);\n        if (initialValues) {\n            c.seedCacheFromMap(initialValues, options.environment);\n        }\n        return c;\n    }, [options.baseUrl, options.apiKey, options.orgId, options.environment]);\n\n    // Re-seed if initialValues change (e.g., after revalidation)\n    useEffect(() => {\n        if (initialValues) {\n            client.seedCacheFromMap(initialValues, options.environment);\n        }\n    }, [initialValues, client, options.environment]);\n\n    return <ConfigContext.Provider value={client}>{children}</ConfigContext.Provider>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAEA,SAAS,WAAW,eAA+B;AAwCxC;AAhBJ,SAAS,mBAAmB,EAAE,eAAe,UAAU,GAAG,QAAQ,GAA4B;AACjG,QAAM,SAAS,QAAQ,MAAM;AACzB,UAAM,IAAI,IAAI,aAAa,OAAO;AAClC,QAAI,eAAe;AACf,QAAE,iBAAiB,eAAe,QAAQ,WAAW;AAAA,IACzD;AACA,WAAO;AAAA,EACX,GAAG,CAAC,QAAQ,SAAS,QAAQ,QAAQ,QAAQ,OAAO,QAAQ,WAAW,CAAC;AAGxE,YAAU,MAAM;AACZ,QAAI,eAAe;AACf,aAAO,iBAAiB,eAAe,QAAQ,WAAW;AAAA,IAC9D;AAAA,EACJ,GAAG,CAAC,eAAe,QAAQ,QAAQ,WAAW,CAAC;AAE/C,SAAO,oBAAC,cAAc,UAAd,EAAuB,OAAO,QAAS,UAAS;AAC5D;","names":[]}

package/dist/platform/client.d.mts

@@ -38,8 +38,25 @@ declare class ConfigClient {
     /**
      * Get all config values for an environment.
      * All returned values are cached locally.
+     * @param environment - Environment name (defaults to constructor option or SMOOAI_CONFIG_ENV)
+     * @param fetchOptions - Optional fetch options (e.g., Next.js `{ next: { revalidate: 60 } }`)
      */
-    getAllValues(environment?: string): Promise<Record<string, unknown>>;
+    getAllValues(environment?: string, fetchOptions?: RequestInit): Promise<Record<string, unknown>>;
+    /**
+     * Pre-populate a single cache entry (e.g., from SSR).
+     * Does not make a network request.
+     */
+    seedCache(key: string, value: unknown, environment?: string): void;
+    /**
+     * Pre-populate multiple cache entries from a key-value map (e.g., from SSR).
+     * Does not make a network request.
+     */
+    seedCacheFromMap(values: Record<string, unknown>, environment?: string): void;
+    /**
+     * Synchronously read a value from the local cache without making a network request.
+     * Returns `undefined` if the key is not cached or has expired.
+     */
+    getCachedValue(key: string, environment?: string): unknown | undefined;
     /** Clear the entire local cache. */
     invalidateCache(): void;
     /** Clear cached values for a specific environment. */