@guidelytech/nextjs 0.6.1 → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guidely
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -30,6 +30,54 @@ export function Providers({ children }: { children: React.ReactNode }) {
 |---|---|
 | `GuidelyNavigationListener` | Client component using `usePathname`/`useSearchParams` (wrapped in `Suspense`) to call `client.page()` on every route change. sdk-core also detects History API navigation; this is the explicit bridge. |
 | `guidelyEnv(env?)` | Reads `NEXT_PUBLIC_GUIDELY_PROJECT_ID`, `NEXT_PUBLIC_GUIDELY_ENV`, `NEXT_PUBLIC_GUIDELY_API_URL`, `NEXT_PUBLIC_GUIDELY_RELEASE` into provider props (`release` selects the source maps uploaded with `@guidelytech/sourcemaps`). Note: Next.js inlines `process.env.NEXT_PUBLIC_*` only when referenced literally, so pass them explicitly in your own code as shown above. |
-| everything from `@guidelytech/react` | `GuidelyProvider`, `useGuidely`, `useGuidelyReady`, `useGuidelyIdentify`, `useGuidelyEvent`, `useChecklistProgress`, `useGuideState`. |
+| everything from `@guidelytech/react` | `GuidelyProvider`, `useGuidely`, `useGuidelyReady`, `useGuidelyIdentify`, `useGuidelyEvent`, `useChecklistProgress`, `useGuideState`, the flag hooks (`useFlag`, `useFeatureValue`, `useFlagDetails`, `useFlags`, `useFlagsReady`, `useFlagsClient`), `<Feature>`, `<FeatureValue>`, `<FlagsProvider>`. |
 
 The built output carries a `"use client"` banner; import it only from client components.
+
+## Feature flags on the server — `@guidelytech/nextjs/server`
+
+No React and no `"use client"`: works in Server Components, route handlers, server actions and
+middleware. The same public key as the browser works with no extra configuration.
+
+```tsx
+// app/layout.tsx (Server Component)
+import { getFlagsBootstrap } from "@guidelytech/nextjs/server";
+
+export default async function RootLayout({ children }) {
+  const flagsPayload = await getFlagsBootstrap(); // the browser starts from this: no flicker
+  return <html><body><Providers flagsPayload={flagsPayload}>{children}</Providers></body></html>;
+}
+// app/providers.tsx ("use client"): <GuidelyProvider … flagsPayload={flagsPayload} user={user}>
+```
+
+```ts
+// app/checkout/page.tsx, a route handler or a server action
+import { getFlags } from "@guidelytech/nextjs/server";
+
+const flags = await getFlags({ id: user.id, plan: user.plan });
+if (flags.isEnabled("new-checkout")) …
+const color = flags.getString("checkout-button-color", "blue");
+```
+
+| Export | Description |
+|---|---|
+| `createServerFlags(options?)` | The process-wide flags client, created once and kept on `globalThis` (survives dev hot reloads). Options default to `GUIDELY_SDK_KEY` (a `pk_…` or server-only `gly_sk_…` key) or `NEXT_PUBLIC_GUIDELY_PROJECT_ID`, `GUIDELY_API_URL` / `NEXT_PUBLIC_GUIDELY_API_URL`, `GUIDELY_ENV` / `NEXT_PUBLIC_GUIDELY_ENV`. Polls every 60 s; fetches bypass the Next.js data cache. |
+| `getFlags(attributes, { client?, timeoutMs? })` | Getters bound to one user (`isEnabled`, `getValue`, `getString`, `getDetails`, `getAll`…). Waits up to `timeoutMs` (1500) for the first download, then serves fallbacks. |
+| `getFlagsBootstrap({ client?, timeoutMs? })` | The payload for `<GuidelyProvider flagsPayload>` / `<FlagsProvider payload>`. `null` for a `gly_sk_` client (its payload contains server-only flags) — bootstrap from a public-key client. |
+
+Evaluate with the attributes the browser will have — the provider's `user` (`id`, traits,
+`account`) plus `flagAttributes` — so server-rendered values and hydration agree. Anonymous
+visitors have no id on the server, so percentage rollouts and experiments keyed on `id` resolve in
+the browser (with the visitor's anonymous id) after hydration.
+
+**Middleware and edge functions** are short-lived: refresh on read instead of polling.
+
+```ts
+// middleware.ts
+import { createServerFlags, getFlags } from "@guidelytech/nextjs/server";
+const client = createServerFlags({ pollingMode: "lazy", cacheTtlSeconds: 30 });
+export async function middleware(req) {
+  const flags = await getFlags({ id: req.cookies.get("uid")?.value }, { client });
+  if (flags.isEnabled("maintenance-mode")) return Response.redirect(new URL("/maintenance", req.url));
+}
+```

package/dist/server.cjs

@@ -0,0 +1,87 @@
+"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/server.ts
+var server_exports = {};
+__export(server_exports, {
+  createServerFlags: () => createServerFlags,
+  getFlags: () => getFlags,
+  getFlagsBootstrap: () => getFlagsBootstrap
+});
+module.exports = __toCommonJS(server_exports);
+var import_flags = require("@guidelytech/flags");
+function registry() {
+  const g = globalThis;
+  return g.__guidelyServerFlags ?? (g.__guidelyServerFlags = { clients: /* @__PURE__ */ new Map(), current: null, warned: /* @__PURE__ */ new Set() });
+}
+function env(name) {
+  try {
+    return globalThis.process?.env?.[name] || void 0;
+  } catch {
+    return void 0;
+  }
+}
+var noStoreFetch = (input, init) => {
+  const original = globalThis.fetch._nextOriginalFetch;
+  return original ? original(input, init) : fetch(input, { ...init, cache: "no-store" });
+};
+function createServerFlags(options = {}) {
+  const sdkKey = options.sdkKey ?? options.projectId ?? env("GUIDELY_SDK_KEY") ?? env("NEXT_PUBLIC_GUIDELY_PROJECT_ID");
+  if (!sdkKey) throw new Error("[Guidely] createServerFlags: pass `sdkKey` or set GUIDELY_SDK_KEY / NEXT_PUBLIC_GUIDELY_PROJECT_ID.");
+  const apiUrl = options.apiUrl ?? env("GUIDELY_API_URL") ?? env("NEXT_PUBLIC_GUIDELY_API_URL");
+  const environment = options.environment ?? env("GUIDELY_ENV") ?? env("NEXT_PUBLIC_GUIDELY_ENV");
+  const id = `${sdkKey}|${apiUrl ?? ""}|${environment ?? ""}|${options.pollingMode ?? "auto"}`;
+  const reg = registry();
+  let client = reg.clients.get(id);
+  if (!client) {
+    client = (0, import_flags.createFlagsClient)({ storage: false, ...options, sdkKey, apiUrl, environment, fetch: options.fetch ?? noStoreFetch });
+    reg.clients.set(id, client);
+  }
+  reg.current = client;
+  return client;
+}
+function settle(client, timeoutMs) {
+  if (client.isReady()) return Promise.resolve();
+  return Promise.race([client.ready(), new Promise((r) => setTimeout(r, timeoutMs))]);
+}
+async function getFlags(attributes = {}, options = {}) {
+  const client = options.client ?? registry().current ?? createServerFlags();
+  await settle(client, options.timeoutMs ?? 1500);
+  return client.forUser(attributes);
+}
+async function getFlagsBootstrap(options = {}) {
+  const client = options.client ?? registry().current ?? createServerFlags();
+  if (client.sdkKey.startsWith("gly_sk_")) {
+    const reg = registry();
+    if (!reg.warned.has(client.sdkKey)) {
+      reg.warned.add(client.sdkKey);
+      console.warn("[Guidely] getFlagsBootstrap() needs a public-key client (pk_\u2026): a gly_sk_ payload includes server-only flags. Pass { client: createServerFlags({ sdkKey: process.env.NEXT_PUBLIC_GUIDELY_PROJECT_ID }) }.");
+    }
+    return null;
+  }
+  await settle(client, options.timeoutMs ?? 1500);
+  return client.getPayload();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createServerFlags,
+  getFlags,
+  getFlagsBootstrap
+});
+//# sourceMappingURL=server.cjs.map

package/dist/server.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * `@guidelytech/nextjs/server` — feature flags on the server: React Server Components, route\n * handlers, server actions, middleware and edge functions. No React and no `\"use client\"` here.\n *\n * ```ts\n * import { getFlags, getFlagsBootstrap } from \"@guidelytech/nextjs/server\";\n * const flags = await getFlags({ id: user.id, plan: user.plan });\n * if (flags.isEnabled(\"new-dashboard-banner\")) …\n * ```\n */\nimport { createFlagsClient, type Attributes, type FlagsBootstrap, type FlagsClient, type FlagsClientOptions, type FlagsEvaluator } from \"@guidelytech/flags\";\n\nexport type { Attributes, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsEvaluator, FlagDetails, JsonValue } from \"@guidelytech/flags\";\n\ninterface Registry {\n  clients: Map<string, FlagsClient>;\n  current: FlagsClient | null;\n  warned: Set<string>;\n}\n\n/** Kept on `globalThis` so dev-server hot reloads reuse the client (and its timers) instead of leaking new ones. */\nfunction registry(): Registry {\n  const g = globalThis as { __guidelyServerFlags?: Registry };\n  return (g.__guidelyServerFlags ??= { clients: new Map(), current: null, warned: new Set() });\n}\n\nfunction env(name: string): string | undefined {\n  try {\n    return (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.[name] || undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Flag downloads must always reach Guidely and outlive the request that started them: use the\n * fetch Next.js wrapped (no data cache, no request scope), else ask for `no-store`.\n */\nconst noStoreFetch: typeof fetch = (input, init) => {\n  const original = (globalThis.fetch as typeof fetch & { _nextOriginalFetch?: typeof fetch })._nextOriginalFetch;\n  return original ? original(input, init) : fetch(input, { ...init, cache: \"no-store\" });\n};\n\n/**\n * The process-wide flags client (created once, then reused across requests and hot reloads).\n * Options default to `GUIDELY_SDK_KEY` (a public `pk_…` or secret `gly_sk_…` key), falling back to\n * `NEXT_PUBLIC_GUIDELY_PROJECT_ID`, plus `GUIDELY_API_URL` / `NEXT_PUBLIC_GUIDELY_API_URL` and\n * `GUIDELY_ENV` / `NEXT_PUBLIC_GUIDELY_ENV`. Polls every 60 s by default; in middleware and\n * edge functions use `{ pollingMode: \"lazy\" }` (refreshes on read once the cache is stale).\n */\nexport function createServerFlags(options: Partial<FlagsClientOptions> = {}): FlagsClient {\n  const sdkKey = options.sdkKey ?? options.projectId ?? env(\"GUIDELY_SDK_KEY\") ?? env(\"NEXT_PUBLIC_GUIDELY_PROJECT_ID\");\n  if (!sdkKey) throw new Error(\"[Guidely] createServerFlags: pass `sdkKey` or set GUIDELY_SDK_KEY / NEXT_PUBLIC_GUIDELY_PROJECT_ID.\");\n  const apiUrl = options.apiUrl ?? env(\"GUIDELY_API_URL\") ?? env(\"NEXT_PUBLIC_GUIDELY_API_URL\");\n  const environment = options.environment ?? env(\"GUIDELY_ENV\") ?? env(\"NEXT_PUBLIC_GUIDELY_ENV\");\n  const id = `${sdkKey}|${apiUrl ?? \"\"}|${environment ?? \"\"}|${options.pollingMode ?? \"auto\"}`;\n  const reg = registry();\n  let client = reg.clients.get(id);\n  if (!client) {\n    client = createFlagsClient({ storage: false, ...options, sdkKey, apiUrl, environment, fetch: options.fetch ?? noStoreFetch });\n    reg.clients.set(id, client);\n  }\n  reg.current = client;\n  return client;\n}\n\nfunction settle(client: FlagsClient, timeoutMs: number): Promise<void> {\n  if (client.isReady()) return Promise.resolve();\n  return Promise.race([client.ready(), new Promise<void>((r) => setTimeout(r, timeoutMs))]);\n}\n\nexport interface GetFlagsOptions {\n  /** A client from `createServerFlags(...)` (default: the last one created, or one from environment variables). */\n  client?: FlagsClient;\n  /** How long to wait for the first download before serving fallbacks (default 1500 ms). */\n  timeoutMs?: number;\n}\n\n/**\n * Flag getters for one user, for this request. Waits (briefly, the first time only) for the\n * flags to load. Pass the same attributes you give the browser (`flagAttributes` / `user`) so\n * server and client agree.\n */\nexport async function getFlags(attributes: Attributes = {}, options: GetFlagsOptions = {}): Promise<FlagsEvaluator> {\n  const client = options.client ?? registry().current ?? createServerFlags();\n  await settle(client, options.timeoutMs ?? 1500);\n  return client.forUser(attributes);\n}\n\n/**\n * The payload to pass to `<GuidelyProvider flagsPayload={…}>` / `<FlagsProvider payload={…}>` so\n * the first render matches the server. Returns `null` for a `gly_sk_` client: its payload holds\n * server-only flags that must not reach browsers — bootstrap from a public-key client instead.\n */\nexport async function getFlagsBootstrap(options: GetFlagsOptions = {}): Promise<FlagsBootstrap | null> {\n  const client = options.client ?? registry().current ?? createServerFlags();\n  if (client.sdkKey.startsWith(\"gly_sk_\")) {\n    const reg = registry();\n    if (!reg.warned.has(client.sdkKey)) {\n      reg.warned.add(client.sdkKey);\n      console.warn(\"[Guidely] getFlagsBootstrap() needs a public-key client (pk_…): a gly_sk_ payload includes server-only flags. Pass { client: createServerFlags({ sdkKey: process.env.NEXT_PUBLIC_GUIDELY_PROJECT_ID }) }.\");\n    }\n    return null;\n  }\n  await settle(client, options.timeoutMs ?? 1500);\n  return client.getPayload();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,mBAAwI;AAWxI,SAAS,WAAqB;AAC5B,QAAM,IAAI;AACV,SAAQ,EAAE,yBAAF,EAAE,uBAAyB,EAAE,SAAS,oBAAI,IAAI,GAAG,SAAS,MAAM,QAAQ,oBAAI,IAAI,EAAE;AAC5F;AAEA,SAAS,IAAI,MAAkC;AAC7C,MAAI;AACF,WAAQ,WAA0E,SAAS,MAAM,IAAI,KAAK;AAAA,EAC5G,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAMA,IAAM,eAA6B,CAAC,OAAO,SAAS;AAClD,QAAM,WAAY,WAAW,MAA+D;AAC5F,SAAO,WAAW,SAAS,OAAO,IAAI,IAAI,MAAM,OAAO,EAAE,GAAG,MAAM,OAAO,WAAW,CAAC;AACvF;AASO,SAAS,kBAAkB,UAAuC,CAAC,GAAgB;AACxF,QAAM,SAAS,QAAQ,UAAU,QAAQ,aAAa,IAAI,iBAAiB,KAAK,IAAI,gCAAgC;AACpH,MAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,qGAAqG;AAClI,QAAM,SAAS,QAAQ,UAAU,IAAI,iBAAiB,KAAK,IAAI,6BAA6B;AAC5F,QAAM,cAAc,QAAQ,eAAe,IAAI,aAAa,KAAK,IAAI,yBAAyB;AAC9F,QAAM,KAAK,GAAG,MAAM,IAAI,UAAU,EAAE,IAAI,eAAe,EAAE,IAAI,QAAQ,eAAe,MAAM;AAC1F,QAAM,MAAM,SAAS;AACrB,MAAI,SAAS,IAAI,QAAQ,IAAI,EAAE;AAC/B,MAAI,CAAC,QAAQ;AACX,iBAAS,gCAAkB,EAAE,SAAS,OAAO,GAAG,SAAS,QAAQ,QAAQ,aAAa,OAAO,QAAQ,SAAS,aAAa,CAAC;AAC5H,QAAI,QAAQ,IAAI,IAAI,MAAM;AAAA,EAC5B;AACA,MAAI,UAAU;AACd,SAAO;AACT;AAEA,SAAS,OAAO,QAAqB,WAAkC;AACrE,MAAI,OAAO,QAAQ,EAAG,QAAO,QAAQ,QAAQ;AAC7C,SAAO,QAAQ,KAAK,CAAC,OAAO,MAAM,GAAG,IAAI,QAAc,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC,CAAC,CAAC;AAC1F;AAcA,eAAsB,SAAS,aAAyB,CAAC,GAAG,UAA2B,CAAC,GAA4B;AAClH,QAAM,SAAS,QAAQ,UAAU,SAAS,EAAE,WAAW,kBAAkB;AACzE,QAAM,OAAO,QAAQ,QAAQ,aAAa,IAAI;AAC9C,SAAO,OAAO,QAAQ,UAAU;AAClC;AAOA,eAAsB,kBAAkB,UAA2B,CAAC,GAAmC;AACrG,QAAM,SAAS,QAAQ,UAAU,SAAS,EAAE,WAAW,kBAAkB;AACzE,MAAI,OAAO,OAAO,WAAW,SAAS,GAAG;AACvC,UAAM,MAAM,SAAS;AACrB,QAAI,CAAC,IAAI,OAAO,IAAI,OAAO,MAAM,GAAG;AAClC,UAAI,OAAO,IAAI,OAAO,MAAM;AAC5B,cAAQ,KAAK,gNAA2M;AAAA,IAC1N;AACA,WAAO;AAAA,EACT;AACA,QAAM,OAAO,QAAQ,QAAQ,aAAa,IAAI;AAC9C,SAAO,OAAO,WAAW;AAC3B;","names":[]}

package/dist/server.d.cts

@@ -0,0 +1,42 @@
+import { FlagsClient, FlagsClientOptions, Attributes, FlagsEvaluator, FlagsBootstrap } from '@guidelytech/flags';
+export { Attributes, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsEvaluator, JsonValue } from '@guidelytech/flags';
+
+/**
+ * `@guidelytech/nextjs/server` — feature flags on the server: React Server Components, route
+ * handlers, server actions, middleware and edge functions. No React and no `"use client"` here.
+ *
+ * ```ts
+ * import { getFlags, getFlagsBootstrap } from "@guidelytech/nextjs/server";
+ * const flags = await getFlags({ id: user.id, plan: user.plan });
+ * if (flags.isEnabled("new-dashboard-banner")) …
+ * ```
+ */
+
+/**
+ * The process-wide flags client (created once, then reused across requests and hot reloads).
+ * Options default to `GUIDELY_SDK_KEY` (a public `pk_…` or secret `gly_sk_…` key), falling back to
+ * `NEXT_PUBLIC_GUIDELY_PROJECT_ID`, plus `GUIDELY_API_URL` / `NEXT_PUBLIC_GUIDELY_API_URL` and
+ * `GUIDELY_ENV` / `NEXT_PUBLIC_GUIDELY_ENV`. Polls every 60 s by default; in middleware and
+ * edge functions use `{ pollingMode: "lazy" }` (refreshes on read once the cache is stale).
+ */
+declare function createServerFlags(options?: Partial<FlagsClientOptions>): FlagsClient;
+interface GetFlagsOptions {
+    /** A client from `createServerFlags(...)` (default: the last one created, or one from environment variables). */
+    client?: FlagsClient;
+    /** How long to wait for the first download before serving fallbacks (default 1500 ms). */
+    timeoutMs?: number;
+}
+/**
+ * Flag getters for one user, for this request. Waits (briefly, the first time only) for the
+ * flags to load. Pass the same attributes you give the browser (`flagAttributes` / `user`) so
+ * server and client agree.
+ */
+declare function getFlags(attributes?: Attributes, options?: GetFlagsOptions): Promise<FlagsEvaluator>;
+/**
+ * The payload to pass to `<GuidelyProvider flagsPayload={…}>` / `<FlagsProvider payload={…}>` so
+ * the first render matches the server. Returns `null` for a `gly_sk_` client: its payload holds
+ * server-only flags that must not reach browsers — bootstrap from a public-key client instead.
+ */
+declare function getFlagsBootstrap(options?: GetFlagsOptions): Promise<FlagsBootstrap | null>;
+
+export { type GetFlagsOptions, createServerFlags, getFlags, getFlagsBootstrap };

package/dist/server.d.ts

@@ -0,0 +1,42 @@
+import { FlagsClient, FlagsClientOptions, Attributes, FlagsEvaluator, FlagsBootstrap } from '@guidelytech/flags';
+export { Attributes, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsEvaluator, JsonValue } from '@guidelytech/flags';
+
+/**
+ * `@guidelytech/nextjs/server` — feature flags on the server: React Server Components, route
+ * handlers, server actions, middleware and edge functions. No React and no `"use client"` here.
+ *
+ * ```ts
+ * import { getFlags, getFlagsBootstrap } from "@guidelytech/nextjs/server";
+ * const flags = await getFlags({ id: user.id, plan: user.plan });
+ * if (flags.isEnabled("new-dashboard-banner")) …
+ * ```
+ */
+
+/**
+ * The process-wide flags client (created once, then reused across requests and hot reloads).
+ * Options default to `GUIDELY_SDK_KEY` (a public `pk_…` or secret `gly_sk_…` key), falling back to
+ * `NEXT_PUBLIC_GUIDELY_PROJECT_ID`, plus `GUIDELY_API_URL` / `NEXT_PUBLIC_GUIDELY_API_URL` and
+ * `GUIDELY_ENV` / `NEXT_PUBLIC_GUIDELY_ENV`. Polls every 60 s by default; in middleware and
+ * edge functions use `{ pollingMode: "lazy" }` (refreshes on read once the cache is stale).
+ */
+declare function createServerFlags(options?: Partial<FlagsClientOptions>): FlagsClient;
+interface GetFlagsOptions {
+    /** A client from `createServerFlags(...)` (default: the last one created, or one from environment variables). */
+    client?: FlagsClient;
+    /** How long to wait for the first download before serving fallbacks (default 1500 ms). */
+    timeoutMs?: number;
+}
+/**
+ * Flag getters for one user, for this request. Waits (briefly, the first time only) for the
+ * flags to load. Pass the same attributes you give the browser (`flagAttributes` / `user`) so
+ * server and client agree.
+ */
+declare function getFlags(attributes?: Attributes, options?: GetFlagsOptions): Promise<FlagsEvaluator>;
+/**
+ * The payload to pass to `<GuidelyProvider flagsPayload={…}>` / `<FlagsProvider payload={…}>` so
+ * the first render matches the server. Returns `null` for a `gly_sk_` client: its payload holds
+ * server-only flags that must not reach browsers — bootstrap from a public-key client instead.
+ */
+declare function getFlagsBootstrap(options?: GetFlagsOptions): Promise<FlagsBootstrap | null>;
+
+export { type GetFlagsOptions, createServerFlags, getFlags, getFlagsBootstrap };

package/dist/server.js

@@ -0,0 +1,60 @@
+// src/server.ts
+import { createFlagsClient } from "@guidelytech/flags";
+function registry() {
+  const g = globalThis;
+  return g.__guidelyServerFlags ?? (g.__guidelyServerFlags = { clients: /* @__PURE__ */ new Map(), current: null, warned: /* @__PURE__ */ new Set() });
+}
+function env(name) {
+  try {
+    return globalThis.process?.env?.[name] || void 0;
+  } catch {
+    return void 0;
+  }
+}
+var noStoreFetch = (input, init) => {
+  const original = globalThis.fetch._nextOriginalFetch;
+  return original ? original(input, init) : fetch(input, { ...init, cache: "no-store" });
+};
+function createServerFlags(options = {}) {
+  const sdkKey = options.sdkKey ?? options.projectId ?? env("GUIDELY_SDK_KEY") ?? env("NEXT_PUBLIC_GUIDELY_PROJECT_ID");
+  if (!sdkKey) throw new Error("[Guidely] createServerFlags: pass `sdkKey` or set GUIDELY_SDK_KEY / NEXT_PUBLIC_GUIDELY_PROJECT_ID.");
+  const apiUrl = options.apiUrl ?? env("GUIDELY_API_URL") ?? env("NEXT_PUBLIC_GUIDELY_API_URL");
+  const environment = options.environment ?? env("GUIDELY_ENV") ?? env("NEXT_PUBLIC_GUIDELY_ENV");
+  const id = `${sdkKey}|${apiUrl ?? ""}|${environment ?? ""}|${options.pollingMode ?? "auto"}`;
+  const reg = registry();
+  let client = reg.clients.get(id);
+  if (!client) {
+    client = createFlagsClient({ storage: false, ...options, sdkKey, apiUrl, environment, fetch: options.fetch ?? noStoreFetch });
+    reg.clients.set(id, client);
+  }
+  reg.current = client;
+  return client;
+}
+function settle(client, timeoutMs) {
+  if (client.isReady()) return Promise.resolve();
+  return Promise.race([client.ready(), new Promise((r) => setTimeout(r, timeoutMs))]);
+}
+async function getFlags(attributes = {}, options = {}) {
+  const client = options.client ?? registry().current ?? createServerFlags();
+  await settle(client, options.timeoutMs ?? 1500);
+  return client.forUser(attributes);
+}
+async function getFlagsBootstrap(options = {}) {
+  const client = options.client ?? registry().current ?? createServerFlags();
+  if (client.sdkKey.startsWith("gly_sk_")) {
+    const reg = registry();
+    if (!reg.warned.has(client.sdkKey)) {
+      reg.warned.add(client.sdkKey);
+      console.warn("[Guidely] getFlagsBootstrap() needs a public-key client (pk_\u2026): a gly_sk_ payload includes server-only flags. Pass { client: createServerFlags({ sdkKey: process.env.NEXT_PUBLIC_GUIDELY_PROJECT_ID }) }.");
+    }
+    return null;
+  }
+  await settle(client, options.timeoutMs ?? 1500);
+  return client.getPayload();
+}
+export {
+  createServerFlags,
+  getFlags,
+  getFlagsBootstrap
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * `@guidelytech/nextjs/server` — feature flags on the server: React Server Components, route\n * handlers, server actions, middleware and edge functions. No React and no `\"use client\"` here.\n *\n * ```ts\n * import { getFlags, getFlagsBootstrap } from \"@guidelytech/nextjs/server\";\n * const flags = await getFlags({ id: user.id, plan: user.plan });\n * if (flags.isEnabled(\"new-dashboard-banner\")) …\n * ```\n */\nimport { createFlagsClient, type Attributes, type FlagsBootstrap, type FlagsClient, type FlagsClientOptions, type FlagsEvaluator } from \"@guidelytech/flags\";\n\nexport type { Attributes, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsEvaluator, FlagDetails, JsonValue } from \"@guidelytech/flags\";\n\ninterface Registry {\n  clients: Map<string, FlagsClient>;\n  current: FlagsClient | null;\n  warned: Set<string>;\n}\n\n/** Kept on `globalThis` so dev-server hot reloads reuse the client (and its timers) instead of leaking new ones. */\nfunction registry(): Registry {\n  const g = globalThis as { __guidelyServerFlags?: Registry };\n  return (g.__guidelyServerFlags ??= { clients: new Map(), current: null, warned: new Set() });\n}\n\nfunction env(name: string): string | undefined {\n  try {\n    return (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.[name] || undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Flag downloads must always reach Guidely and outlive the request that started them: use the\n * fetch Next.js wrapped (no data cache, no request scope), else ask for `no-store`.\n */\nconst noStoreFetch: typeof fetch = (input, init) => {\n  const original = (globalThis.fetch as typeof fetch & { _nextOriginalFetch?: typeof fetch })._nextOriginalFetch;\n  return original ? original(input, init) : fetch(input, { ...init, cache: \"no-store\" });\n};\n\n/**\n * The process-wide flags client (created once, then reused across requests and hot reloads).\n * Options default to `GUIDELY_SDK_KEY` (a public `pk_…` or secret `gly_sk_…` key), falling back to\n * `NEXT_PUBLIC_GUIDELY_PROJECT_ID`, plus `GUIDELY_API_URL` / `NEXT_PUBLIC_GUIDELY_API_URL` and\n * `GUIDELY_ENV` / `NEXT_PUBLIC_GUIDELY_ENV`. Polls every 60 s by default; in middleware and\n * edge functions use `{ pollingMode: \"lazy\" }` (refreshes on read once the cache is stale).\n */\nexport function createServerFlags(options: Partial<FlagsClientOptions> = {}): FlagsClient {\n  const sdkKey = options.sdkKey ?? options.projectId ?? env(\"GUIDELY_SDK_KEY\") ?? env(\"NEXT_PUBLIC_GUIDELY_PROJECT_ID\");\n  if (!sdkKey) throw new Error(\"[Guidely] createServerFlags: pass `sdkKey` or set GUIDELY_SDK_KEY / NEXT_PUBLIC_GUIDELY_PROJECT_ID.\");\n  const apiUrl = options.apiUrl ?? env(\"GUIDELY_API_URL\") ?? env(\"NEXT_PUBLIC_GUIDELY_API_URL\");\n  const environment = options.environment ?? env(\"GUIDELY_ENV\") ?? env(\"NEXT_PUBLIC_GUIDELY_ENV\");\n  const id = `${sdkKey}|${apiUrl ?? \"\"}|${environment ?? \"\"}|${options.pollingMode ?? \"auto\"}`;\n  const reg = registry();\n  let client = reg.clients.get(id);\n  if (!client) {\n    client = createFlagsClient({ storage: false, ...options, sdkKey, apiUrl, environment, fetch: options.fetch ?? noStoreFetch });\n    reg.clients.set(id, client);\n  }\n  reg.current = client;\n  return client;\n}\n\nfunction settle(client: FlagsClient, timeoutMs: number): Promise<void> {\n  if (client.isReady()) return Promise.resolve();\n  return Promise.race([client.ready(), new Promise<void>((r) => setTimeout(r, timeoutMs))]);\n}\n\nexport interface GetFlagsOptions {\n  /** A client from `createServerFlags(...)` (default: the last one created, or one from environment variables). */\n  client?: FlagsClient;\n  /** How long to wait for the first download before serving fallbacks (default 1500 ms). */\n  timeoutMs?: number;\n}\n\n/**\n * Flag getters for one user, for this request. Waits (briefly, the first time only) for the\n * flags to load. Pass the same attributes you give the browser (`flagAttributes` / `user`) so\n * server and client agree.\n */\nexport async function getFlags(attributes: Attributes = {}, options: GetFlagsOptions = {}): Promise<FlagsEvaluator> {\n  const client = options.client ?? registry().current ?? createServerFlags();\n  await settle(client, options.timeoutMs ?? 1500);\n  return client.forUser(attributes);\n}\n\n/**\n * The payload to pass to `<GuidelyProvider flagsPayload={…}>` / `<FlagsProvider payload={…}>` so\n * the first render matches the server. Returns `null` for a `gly_sk_` client: its payload holds\n * server-only flags that must not reach browsers — bootstrap from a public-key client instead.\n */\nexport async function getFlagsBootstrap(options: GetFlagsOptions = {}): Promise<FlagsBootstrap | null> {\n  const client = options.client ?? registry().current ?? createServerFlags();\n  if (client.sdkKey.startsWith(\"gly_sk_\")) {\n    const reg = registry();\n    if (!reg.warned.has(client.sdkKey)) {\n      reg.warned.add(client.sdkKey);\n      console.warn(\"[Guidely] getFlagsBootstrap() needs a public-key client (pk_…): a gly_sk_ payload includes server-only flags. Pass { client: createServerFlags({ sdkKey: process.env.NEXT_PUBLIC_GUIDELY_PROJECT_ID }) }.\");\n    }\n    return null;\n  }\n  await settle(client, options.timeoutMs ?? 1500);\n  return client.getPayload();\n}\n"],"mappings":";AAUA,SAAS,yBAA+H;AAWxI,SAAS,WAAqB;AAC5B,QAAM,IAAI;AACV,SAAQ,EAAE,yBAAF,EAAE,uBAAyB,EAAE,SAAS,oBAAI,IAAI,GAAG,SAAS,MAAM,QAAQ,oBAAI,IAAI,EAAE;AAC5F;AAEA,SAAS,IAAI,MAAkC;AAC7C,MAAI;AACF,WAAQ,WAA0E,SAAS,MAAM,IAAI,KAAK;AAAA,EAC5G,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAMA,IAAM,eAA6B,CAAC,OAAO,SAAS;AAClD,QAAM,WAAY,WAAW,MAA+D;AAC5F,SAAO,WAAW,SAAS,OAAO,IAAI,IAAI,MAAM,OAAO,EAAE,GAAG,MAAM,OAAO,WAAW,CAAC;AACvF;AASO,SAAS,kBAAkB,UAAuC,CAAC,GAAgB;AACxF,QAAM,SAAS,QAAQ,UAAU,QAAQ,aAAa,IAAI,iBAAiB,KAAK,IAAI,gCAAgC;AACpH,MAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,qGAAqG;AAClI,QAAM,SAAS,QAAQ,UAAU,IAAI,iBAAiB,KAAK,IAAI,6BAA6B;AAC5F,QAAM,cAAc,QAAQ,eAAe,IAAI,aAAa,KAAK,IAAI,yBAAyB;AAC9F,QAAM,KAAK,GAAG,MAAM,IAAI,UAAU,EAAE,IAAI,eAAe,EAAE,IAAI,QAAQ,eAAe,MAAM;AAC1F,QAAM,MAAM,SAAS;AACrB,MAAI,SAAS,IAAI,QAAQ,IAAI,EAAE;AAC/B,MAAI,CAAC,QAAQ;AACX,aAAS,kBAAkB,EAAE,SAAS,OAAO,GAAG,SAAS,QAAQ,QAAQ,aAAa,OAAO,QAAQ,SAAS,aAAa,CAAC;AAC5H,QAAI,QAAQ,IAAI,IAAI,MAAM;AAAA,EAC5B;AACA,MAAI,UAAU;AACd,SAAO;AACT;AAEA,SAAS,OAAO,QAAqB,WAAkC;AACrE,MAAI,OAAO,QAAQ,EAAG,QAAO,QAAQ,QAAQ;AAC7C,SAAO,QAAQ,KAAK,CAAC,OAAO,MAAM,GAAG,IAAI,QAAc,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC,CAAC,CAAC;AAC1F;AAcA,eAAsB,SAAS,aAAyB,CAAC,GAAG,UAA2B,CAAC,GAA4B;AAClH,QAAM,SAAS,QAAQ,UAAU,SAAS,EAAE,WAAW,kBAAkB;AACzE,QAAM,OAAO,QAAQ,QAAQ,aAAa,IAAI;AAC9C,SAAO,OAAO,QAAQ,UAAU;AAClC;AAOA,eAAsB,kBAAkB,UAA2B,CAAC,GAAmC;AACrG,QAAM,SAAS,QAAQ,UAAU,SAAS,EAAE,WAAW,kBAAkB;AACzE,MAAI,OAAO,OAAO,WAAW,SAAS,GAAG;AACvC,UAAM,MAAM,SAAS;AACrB,QAAI,CAAC,IAAI,OAAO,IAAI,OAAO,MAAM,GAAG;AAClC,UAAI,OAAO,IAAI,OAAO,MAAM;AAC5B,cAAQ,KAAK,gNAA2M;AAAA,IAC1N;AACA,WAAO;AAAA,EACT;AACA,QAAM,OAAO,QAAQ,QAAQ,aAAa,IAAI;AAC9C,SAAO,OAAO,WAAW;AAC3B;","names":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guidelytech/nextjs",
-  "version": "0.6.1",
-  "description": "Next.js App Router helpers for Guidely",
+  "version": "0.7.0",
+  "description": "Next.js App Router helpers for Guidely: provider, navigation bridge and server-side feature flags",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -13,6 +13,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
     }
   },
   "files": [
@@ -20,8 +25,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@guidelytech/react": "0.6.1",
-    "@guidelytech/sdk-core": "0.6.1"
+    "@guidelytech/sdk-core": "0.7.0",
+    "@guidelytech/flags": "0.7.0",
+    "@guidelytech/react": "0.7.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
@@ -61,7 +67,7 @@
     "nextjs"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "rm -rf dist && tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",