@vard-app/sdk 0.1.0 → 0.1.2

package/dist/next.mjs

@@ -1,32 +1,38 @@
-// src/next.ts
-function createVardNextAdapter(options = {}) {
+// src/fetch-store.ts
+function createVardFetchStore(options = {}) {
   const {
     apiBase = "https://api.vard.app",
-    workspaceId = process.env.VARD_WORKSPACE_ID,
-    apiKey = process.env.VARD_API_KEY,
-    cache = "force-cache",
-    revalidate = 60
+    workspaceId = options.workspaceId ?? process.env.VARD_WORKSPACE_ID,
+    apiKey = options.apiKey ?? process.env.VARD_API_KEY,
+    fetchOptions = {}
   } = options;
   let resolvedValues = null;
   let fetchPromise = null;
   async function fetchValues() {
+    const isDevelopment = process.env.NODE_ENV === "development";
     if (!apiKey && !workspaceId) {
+      if (!isDevelopment) {
+        console.error(
+          "\x1B[31m[vard] Missing configuration! VARD_API_KEY is not set.\x1B[0m\nPlease set this environment variable in your production environment."
+        );
+      } else {
+        console.warn(
+          "[vard] No API Key found. Running in local fallback mode (using default values)."
+        );
+      }
       return /* @__PURE__ */ new Map();
     }
     const url = apiKey ? `${apiBase}/api/content/variables` : `${apiBase}/v1/workspaces/${workspaceId}/variables`;
     try {
       const res = await fetch(url, {
-        cache,
+        ...fetchOptions,
         headers: {
+          ...fetchOptions.headers,
           ...apiKey ? { "X-Vard-API-Key": apiKey } : {}
-        },
-        // Next.js specific: revalidation hint
-        ...revalidate !== void 0 && cache === "force-cache" ? { next: { revalidate } } : {}
+        }
       });
       if (!res.ok) {
-        console.warn(
-          `[vard] Failed to fetch variables: ${res.status}`
-        );
+        console.warn(`[vard] Failed to fetch variables: ${res.status}`);
         return /* @__PURE__ */ new Map();
       }
       const data = await res.json();
@@ -40,8 +46,6 @@ function createVardNextAdapter(options = {}) {
     get(key) {
       return resolvedValues?.get(key);
     },
-    // Extended method — not on base VardStore interface, but available
-    // for Next.js users who import from @vard/sdk/next
     async prefetch() {
       if (resolvedValues) return;
       if (!fetchPromise) {
@@ -51,10 +55,172 @@ function createVardNextAdapter(options = {}) {
     }
   };
 }
-async function prefetchVardValues(adapter) {
-  await adapter.prefetch();
+
+// src/client.ts
+var hasLoggedNoop = false;
+var noopStore = {
+  get: () => {
+    if (!hasLoggedNoop && process.env.NODE_ENV !== "test") {
+      console.warn(
+        "[vard] Using default values for all variables because no Store was provided to createVard()."
+      );
+      hasLoggedNoop = true;
+    }
+    return void 0;
+  }
+};
+function createVard(options = {}) {
+  const store = options.store ?? (options.apiKey || options.workspaceId ? createVardFetchStore(options) : noopStore);
+  const registry = [];
+  function register(def) {
+    if (!registry.find((d) => d.key === def.key)) {
+      registry.push(def);
+    }
+    const stored = store.get(def.key);
+    if (stored !== void 0 && stored !== null) {
+      return stored;
+    }
+    return def.defaultValue;
+  }
+  const client = {
+    string(key, fallback, opts = {}) {
+      return register({
+        key,
+        label: opts.label ?? labelFromKey(key),
+        description: opts.description,
+        type: "string",
+        defaultValue: fallback,
+        editableBy: opts.editableBy ?? "member",
+        group: opts.group
+      });
+    },
+    richtext(key, fallback, opts = {}) {
+      return register({
+        key,
+        label: opts.label ?? labelFromKey(key),
+        description: opts.description,
+        type: "richtext",
+        defaultValue: fallback,
+        editableBy: opts.editableBy ?? "member",
+        group: opts.group
+      });
+    },
+    color(key, fallback, opts = {}) {
+      return register({
+        key,
+        label: opts.label ?? labelFromKey(key),
+        description: opts.description,
+        type: "color",
+        defaultValue: fallback,
+        editableBy: opts.editableBy ?? "member",
+        group: opts.group
+      });
+    },
+    image(key, fallback, opts = {}) {
+      return register({
+        key,
+        label: opts.label ?? labelFromKey(key),
+        description: opts.description,
+        type: "image",
+        defaultValue: fallback,
+        editableBy: opts.editableBy ?? "member",
+        group: opts.group
+      });
+    },
+    boolean(key, fallback, opts = {}) {
+      return register({
+        key,
+        label: opts.label ?? labelFromKey(key),
+        description: opts.description,
+        type: "boolean",
+        defaultValue: fallback,
+        editableBy: opts.editableBy ?? "member",
+        group: opts.group
+      });
+    },
+    list(key, schema, fallback, opts = {}) {
+      return register({
+        key,
+        label: opts.label ?? labelFromKey(key),
+        description: opts.description,
+        type: "list",
+        defaultValue: fallback,
+        editableBy: opts.editableBy ?? "member",
+        listItemSchema: schema,
+        group: opts.group
+      });
+    },
+    collection(key, schema, fallback, opts = {}) {
+      return register({
+        key,
+        label: opts.label ?? labelFromKey(key),
+        description: opts.description,
+        type: "list",
+        defaultValue: fallback,
+        editableBy: opts.editableBy ?? "member",
+        listItemSchema: schema,
+        group: opts.group,
+        isCollection: true
+      });
+    },
+    global: {
+      string(key, fallback, opts = {}) {
+        return client.string(key, fallback, { ...opts, group: "Global" });
+      },
+      richtext(key, fallback, opts = {}) {
+        return client.richtext(key, fallback, { ...opts, group: "Global" });
+      },
+      color(key, fallback, opts = {}) {
+        return client.color(key, fallback, { ...opts, group: "Global" });
+      },
+      image(key, fallback, opts = {}) {
+        return client.image(key, fallback, { ...opts, group: "Global" });
+      },
+      boolean(key, fallback, opts = {}) {
+        return client.boolean(key, fallback, { ...opts, group: "Global" });
+      },
+      list(key, schema, fallback, opts = {}) {
+        return client.list(key, schema, fallback, { ...opts, group: "Global" });
+      }
+    },
+    getDefinitions() {
+      return [...registry];
+    },
+    store
+  };
+  return client;
+}
+function labelFromKey(key) {
+  const lastSegment = key.split(".").pop() ?? key;
+  return lastSegment.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase()).trim();
+}
+
+// src/next.ts
+function createVardNextAdapter(options = {}) {
+  const { cache = "force-cache", revalidate = 60, ...rest } = options;
+  return createVardFetchStore({
+    ...rest,
+    fetchOptions: {
+      cache,
+      ...revalidate !== void 0 && cache === "force-cache" ? { next: { revalidate } } : {}
+    }
+  });
+}
+function createVardNext(options = {}) {
+  const adapter = createVardNextAdapter(options);
+  return createVard({
+    ...options,
+    store: adapter
+  });
+}
+async function prefetchVardValues(target) {
+  const adapter = target.prefetch ? target : target.store;
+  if (adapter && typeof adapter.prefetch === "function") {
+    await adapter.prefetch();
+  }
 }
 export {
+  createVardNext,
   createVardNextAdapter,
   prefetchVardValues
 };

package/dist/next.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/next.ts"],"sourcesContent":["/**\n * @vard/sdk — Next.js adapter\n *\n * This module provides a VardStore implementation that reads variable values\n * from the Vard API at request time (App Router) or build time (static export).\n *\n * Usage in your Next.js site:\n *\n *   // lib/vard.ts\n *   import { createVardNextAdapter } from \"@vard/sdk/next\"\n *   import { createVard } from \"@vard/sdk\"\n *\n *   export const vard = createVard({\n *     workspaceId: process.env.VARD_WORKSPACE_ID,\n *     store: createVardNextAdapter(),\n *   })\n *\n * The adapter fetches variable values from the Vard API:\n *   GET https://api.vard.app/v1/workspaces/{workspaceId}/variables\n *\n * In local development (no VARD_WORKSPACE_ID set) it silently falls back\n * to default values so your site works without any Vard account.\n */\n\nimport type { VardStore } from \"./types\";\n\nexport interface VardNextAdapterOptions {\n  /**\n   * Base URL of the Vard API. Defaults to https://api.vard.app\n   */\n  apiBase?: string;\n\n  /**\n   * Workspace ID. Falls back to process.env.VARD_WORKSPACE_ID.\n   */\n  workspaceId?: string;\n\n  /**\n   * API Key for authentication. Falls back to process.env.VARD_API_KEY.\n   */\n  apiKey?: string;\n\n  /**\n   * Next.js fetch cache strategy. Defaults to \"force-cache\" (SSG-friendly).\n   * Use \"no-store\" for fully dynamic pages.\n   */\n  cache?: RequestCache;\n\n  /**\n   * Next.js ISR revalidation interval in seconds.\n   * Only applies when cache is \"force-cache\".\n   */\n  revalidate?: number;\n}\n\n/**\n * Creates a VardStore that fetches live variable values from the Vard API.\n * Designed for use inside Next.js App Router (server components, server actions).\n *\n * Values are fetched once per request and cached in a simple Map.\n * In local dev with no workspaceId, returns undefined for every key (defaults take over).\n */\nexport function createVardNextAdapter(\n  options: VardNextAdapterOptions = {}\n): VardStore {\n  const {\n    apiBase = \"https://api.vard.app\",\n    workspaceId = process.env.VARD_WORKSPACE_ID,\n    apiKey = process.env.VARD_API_KEY,\n    cache = \"force-cache\",\n    revalidate = 60,\n  } = options;\n\n  // In-memory cache per module instance (one Node.js process = one workspace)\n  let resolvedValues: Map<string, unknown> | null = null;\n  let fetchPromise: Promise<Map<string, unknown>> | null = null;\n\n  async function fetchValues(): Promise<Map<string, unknown>> {\n    if (!apiKey && !workspaceId) {\n      return new Map();\n    }\n\n    // New format uses API Key and points to a generic content endpoint\n    // Old format uses workspaceId and points to a workspace-specific endpoint\n    const url = apiKey \n      ? `${apiBase}/api/content/variables`\n      : `${apiBase}/v1/workspaces/${workspaceId}/variables`;\n\n    try {\n      const res = await fetch(url, {\n        cache,\n        headers: {\n          ...(apiKey ? { \"X-Vard-API-Key\": apiKey } : {}),\n        },\n        // Next.js specific: revalidation hint\n        ...(revalidate !== undefined && cache === \"force-cache\"\n          ? { next: { revalidate } }\n          : {}),\n      });\n\n      if (!res.ok) {\n        console.warn(\n          `[vard] Failed to fetch variables: ${res.status}`\n        );\n        return new Map();\n      }\n\n      const data = (await res.json()) as { key: string; value: unknown }[];\n      return new Map(data.map((v) => [v.key, v.value]));\n    } catch (err) {\n      console.warn(\"[vard] Error fetching variable values:\", err);\n      return new Map();\n    }\n  }\n\n  return {\n    get(key: string): unknown {\n      // Synchronous path — values must have been pre-fetched.\n      // In Next.js App Router, call vard.prefetch() in your layout/page\n      // before rendering, or use the async helper below.\n      return resolvedValues?.get(key);\n    },\n\n    // Extended method — not on base VardStore interface, but available\n    // for Next.js users who import from @vard/sdk/next\n    async prefetch(): Promise<void> {\n      if (resolvedValues) return;\n      if (!fetchPromise) {\n        fetchPromise = fetchValues();\n      }\n      resolvedValues = await fetchPromise;\n    },\n  } as VardStore & { prefetch(): Promise<void> };\n}\n\n/**\n * A convenience wrapper that creates a Vard client pre-loaded with live values.\n * Call this once in your Next.js layout before rendering any server component\n * that uses vard variables.\n *\n * @example\n * // app/layout.tsx\n * import { prefetchVardValues } from \"@vard/sdk/next\"\n * import { vard } from \"@/lib/vard\"\n *\n * export default async function RootLayout({ children }) {\n *   await prefetchVardValues(vard)\n *   return <html>...</html>\n * }\n */\nexport async function prefetchVardValues(\n  adapter: { prefetch(): Promise<void> }\n): Promise<void> {\n  await adapter.prefetch();\n}\n"],"mappings":";AA8DO,SAAS,sBACd,UAAkC,CAAC,GACxB;AACX,QAAM;AAAA,IACJ,UAAU;AAAA,IACV,cAAc,QAAQ,IAAI;AAAA,IAC1B,SAAS,QAAQ,IAAI;AAAA,IACrB,QAAQ;AAAA,IACR,aAAa;AAAA,EACf,IAAI;AAGJ,MAAI,iBAA8C;AAClD,MAAI,eAAqD;AAEzD,iBAAe,cAA6C;AAC1D,QAAI,CAAC,UAAU,CAAC,aAAa;AAC3B,aAAO,oBAAI,IAAI;AAAA,IACjB;AAIA,UAAM,MAAM,SACR,GAAG,OAAO,2BACV,GAAG,OAAO,kBAAkB,WAAW;AAE3C,QAAI;AACF,YAAM,MAAM,MAAM,MAAM,KAAK;AAAA,QAC3B;AAAA,QACA,SAAS;AAAA,UACP,GAAI,SAAS,EAAE,kBAAkB,OAAO,IAAI,CAAC;AAAA,QAC/C;AAAA;AAAA,QAEA,GAAI,eAAe,UAAa,UAAU,gBACtC,EAAE,MAAM,EAAE,WAAW,EAAE,IACvB,CAAC;AAAA,MACP,CAAC;AAED,UAAI,CAAC,IAAI,IAAI;AACX,gBAAQ;AAAA,UACN,qCAAqC,IAAI,MAAM;AAAA,QACjD;AACA,eAAO,oBAAI,IAAI;AAAA,MACjB;AAEA,YAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,aAAO,IAAI,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAAA,IAClD,SAAS,KAAK;AACZ,cAAQ,KAAK,0CAA0C,GAAG;AAC1D,aAAO,oBAAI,IAAI;AAAA,IACjB;AAAA,EACF;AAEA,SAAO;AAAA,IACL,IAAI,KAAsB;AAIxB,aAAO,gBAAgB,IAAI,GAAG;AAAA,IAChC;AAAA;AAAA;AAAA,IAIA,MAAM,WAA0B;AAC9B,UAAI,eAAgB;AACpB,UAAI,CAAC,cAAc;AACjB,uBAAe,YAAY;AAAA,MAC7B;AACA,uBAAiB,MAAM;AAAA,IACzB;AAAA,EACF;AACF;AAiBA,eAAsB,mBACpB,SACe;AACf,QAAM,QAAQ,SAAS;AACzB;","names":[]}
+{"version":3,"sources":["../src/fetch-store.ts","../src/client.ts","../src/next.ts"],"sourcesContent":["import type { VardStore } from \"./types\";\n\nexport interface VardFetchStoreOptions {\n  /**\n   * Base URL of the Vard API. Defaults to https://api.vard.app\n   */\n  apiBase?: string;\n\n  /**\n   * Workspace ID (Legacy). Defaults to process.env.VARD_WORKSPACE_ID.\n   */\n  workspaceId?: string;\n\n  /**\n   * API Key for authentication. Defaults to process.env.VARD_API_KEY.\n   */\n  apiKey?: string;\n\n  /**\n   * Custom fetch options (headers, etc.)\n   */\n  fetchOptions?: RequestInit;\n}\n\n/**\n * Creates a universal VardStore that fetches variable values from the Vard API.\n * Works in any environment with a global `fetch` (Browsers, Node 18+, Bun, Deno).\n */\nexport function createVardFetchStore(\n  options: VardFetchStoreOptions = {}\n): VardStore & { prefetch(): Promise<void> } {\n  const {\n    apiBase = \"https://api.vard.app\",\n    workspaceId = options.workspaceId ?? process.env.VARD_WORKSPACE_ID,\n    apiKey = options.apiKey ?? process.env.VARD_API_KEY,\n    fetchOptions = {},\n  } = options;\n\n  let resolvedValues: Map<string, unknown> | null = null;\n  let fetchPromise: Promise<Map<string, unknown>> | null = null;\n\n  async function fetchValues(): Promise<Map<string, unknown>> {\n    const isDevelopment = process.env.NODE_ENV === \"development\";\n\n    if (!apiKey && !workspaceId) {\n      if (!isDevelopment) {\n        console.error(\n          \"\\x1b[31m[vard] Missing configuration! VARD_API_KEY is not set.\\x1b[0m\\n\" +\n            \"Please set this environment variable in your production environment.\"\n        );\n      } else {\n        console.warn(\n          \"[vard] No API Key found. Running in local fallback mode (using default values).\"\n        );\n      }\n      return new Map();\n    }\n\n    const url = apiKey\n      ? `${apiBase}/api/content/variables`\n      : `${apiBase}/v1/workspaces/${workspaceId}/variables`;\n\n    try {\n      const res = await fetch(url, {\n        ...fetchOptions,\n        headers: {\n          ...fetchOptions.headers,\n          ...(apiKey ? { \"X-Vard-API-Key\": apiKey } : {}),\n        },\n      });\n\n      if (!res.ok) {\n        console.warn(`[vard] Failed to fetch variables: ${res.status}`);\n        return new Map();\n      }\n\n      const data = (await res.json()) as { key: string; value: unknown }[];\n      return new Map(data.map((v) => [v.key, v.value]));\n    } catch (err) {\n      console.warn(\"[vard] Error fetching variable values:\", err);\n      return new Map();\n    }\n  }\n\n  return {\n    get(key: string): unknown {\n      return resolvedValues?.get(key);\n    },\n\n    async prefetch(): Promise<void> {\n      if (resolvedValues) return;\n      if (!fetchPromise) {\n        fetchPromise = fetchValues();\n      }\n      resolvedValues = await fetchPromise;\n    },\n  };\n}\n","import type {\n  VardClient,\n  VardOptions,\n  VardStore,\n  VardVariableDefinition,\n  VardVariableOptions,\n  VardListItemSchema,\n  InferListItem,\n  VardRole,\n} from \"./types\";\n\n// ─────────────────────────────────────────────\n// No-op store (used in local dev when no workspaceId is set)\n// ─────────────────────────────────────────────\n\nlet hasLoggedNoop = false;\nconst noopStore: VardStore = {\n  get: () => {\n    if (!hasLoggedNoop && process.env.NODE_ENV !== \"test\") {\n      console.warn(\n        \"[vard] Using default values for all variables because no Store was provided to createVard().\"\n      );\n      hasLoggedNoop = true;\n    }\n    return undefined;\n  },\n};\n\n// ─────────────────────────────────────────────\n// createVard — the main SDK factory\n// ─────────────────────────────────────────────\n\nimport { createVardFetchStore } from \"./fetch-store\";\n\n/**\n * Creates a Vard client instance. Call this once at the top of your site\n * (e.g. in `lib/vard.ts`) and export the result.\n *\n * @example\n * // lib/vard.ts\n * import { createVard } from \"@vard/sdk\"\n * export const vard = createVard({ apiKey: \"...\" })\n *\n * // app/page.tsx\n * import { vard } from \"@/lib/vard\"\n * const title = vard.string(\"hero.title\", \"Hello, world\")\n */\nexport function createVard(options: VardOptions = {}): VardClient {\n  const store: VardStore =\n    options.store ??\n    (options.apiKey || options.workspaceId ? createVardFetchStore(options) : noopStore);\n\n  // Registry of all declared variables — used by CLI + build pipeline\n  const registry: VardVariableDefinition[] = [];\n\n  function register<T>(def: VardVariableDefinition<T>): T {\n    // Avoid double-registering the same key (e.g. in hot-reload scenarios)\n    if (!registry.find((d) => d.key === def.key)) {\n      registry.push(def as VardVariableDefinition);\n    }\n\n    // Resolve value: stored client value takes precedence over the default\n    const stored = store.get(def.key);\n    if (stored !== undefined && stored !== null) {\n      return stored as T;\n    }\n\n    return def.defaultValue;\n  }\n\n  const client: VardClient = {\n    string(key, fallback, opts: VardVariableOptions = {}) {\n      return register<string>({\n        key,\n        label: opts.label ?? labelFromKey(key),\n        description: opts.description,\n        type: \"string\",\n        defaultValue: fallback,\n        editableBy: opts.editableBy ?? \"member\",\n        group: opts.group,\n      });\n    },\n\n    richtext(key, fallback, opts: VardVariableOptions = {}) {\n      return register<string>({\n        key,\n        label: opts.label ?? labelFromKey(key),\n        description: opts.description,\n        type: \"richtext\",\n        defaultValue: fallback,\n        editableBy: opts.editableBy ?? \"member\",\n        group: opts.group,\n      });\n    },\n\n    color(key, fallback, opts: VardVariableOptions = {}) {\n      return register<string>({\n        key,\n        label: opts.label ?? labelFromKey(key),\n        description: opts.description,\n        type: \"color\",\n        defaultValue: fallback,\n        editableBy: opts.editableBy ?? \"member\",\n        group: opts.group,\n      });\n    },\n\n    image(key, fallback, opts: VardVariableOptions = {}) {\n      return register<string>({\n        key,\n        label: opts.label ?? labelFromKey(key),\n        description: opts.description,\n        type: \"image\",\n        defaultValue: fallback,\n        editableBy: opts.editableBy ?? \"member\",\n        group: opts.group,\n      });\n    },\n\n    boolean(key, fallback, opts: VardVariableOptions = {}) {\n      return register<boolean>({\n        key,\n        label: opts.label ?? labelFromKey(key),\n        description: opts.description,\n        type: \"boolean\",\n        defaultValue: fallback,\n        editableBy: (opts.editableBy as VardRole) ?? \"member\",\n        group: opts.group,\n      });\n    },\n\n    list<S extends VardListItemSchema>(\n      key: string,\n      schema: S,\n      fallback: InferListItem<S>[],\n      opts: VardVariableOptions = {}\n    ): InferListItem<S>[] {\n      return register<InferListItem<S>[]>({\n        key,\n        label: opts.label ?? labelFromKey(key),\n        description: opts.description,\n        type: \"list\",\n        defaultValue: fallback,\n        editableBy: (opts.editableBy as VardRole) ?? \"member\",\n        listItemSchema: schema,\n        group: opts.group,\n      });\n    },\n\n    collection<S extends VardListItemSchema>(\n      key: string,\n      schema: S,\n      fallback: InferListItem<S>[],\n      opts: Omit<VardVariableOptions, \"type\"> = {}\n    ): InferListItem<S>[] {\n      return register<InferListItem<S>[]>({\n        key,\n        label: opts.label ?? labelFromKey(key),\n        description: opts.description,\n        type: \"list\",\n        defaultValue: fallback,\n        editableBy: (opts.editableBy as VardRole) ?? \"member\",\n        listItemSchema: schema,\n        group: opts.group,\n        isCollection: true,\n      });\n    },\n\n    global: {\n      string(key, fallback, opts = {}) {\n        return client.string(key, fallback, { ...opts, group: \"Global\" } as VardVariableOptions);\n      },\n      richtext(key, fallback, opts = {}) {\n        return client.richtext(key, fallback, { ...opts, group: \"Global\" } as VardVariableOptions);\n      },\n      color(key, fallback, opts = {}) {\n        return client.color(key, fallback, { ...opts, group: \"Global\" } as VardVariableOptions);\n      },\n      image(key, fallback, opts = {}) {\n        return client.image(key, fallback, { ...opts, group: \"Global\" } as VardVariableOptions);\n      },\n      boolean(key, fallback, opts = {}) {\n        return client.boolean(key, fallback, { ...opts, group: \"Global\" } as Omit<\n          VardVariableOptions,\n          \"type\"\n        >);\n      },\n      list(key, schema, fallback, opts = {}) {\n        return client.list(key, schema, fallback, { ...opts, group: \"Global\" } as Omit<\n          VardVariableOptions,\n          \"type\"\n        >);\n      },\n    },\n\n    getDefinitions() {\n      return [...registry];\n    },\n    store,\n  };\n\n  return client;\n}\n\n// ─────────────────────────────────────────────\n// Helpers\n// ─────────────────────────────────────────────\n\n/**\n * Converts a dot-notation key to a human-readable label.\n * e.g. \"hero.primaryTitle\" → \"Hero Primary Title\"\n */\nfunction labelFromKey(key: string): string {\n  const lastSegment = key.split(\".\").pop() ?? key;\n  // Split on camelCase boundaries and capitalise\n  return lastSegment\n    .replace(/([A-Z])/g, \" $1\")\n    .replace(/^./, (c) => c.toUpperCase())\n    .trim();\n}\n","/**\n * @vard/sdk — Next.js adapter\n *\n * This module provides a VardStore implementation that reads variable values\n * from the Vard API at request time (App Router) or build time (static export).\n *\n * Usage in your Next.js site:\n *\n *   // lib/vard.ts\n *   import { createVardNextAdapter } from \"@vard/sdk/next\"\n *   import { createVard } from \"@vard/sdk\"\n *\n *   export const vard = createVard({\n *     workspaceId: process.env.VARD_WORKSPACE_ID,\n *     store: createVardNextAdapter(),\n *   })\n *\n * The adapter fetches variable values from the Vard API:\n *   GET https://api.vard.app/v1/workspaces/{workspaceId}/variables\n *\n * In local development (no VARD_WORKSPACE_ID set) it silently falls back\n * to default values so your site works without any Vard account.\n */\n\nimport type { VardStore } from \"./types\";\n\nexport interface VardNextAdapterOptions {\n  /**\n   * Base URL of the Vard API. Defaults to https://api.vard.app\n   */\n  apiBase?: string;\n\n  /**\n   * Workspace ID. Falls back to process.env.VARD_WORKSPACE_ID.\n   */\n  workspaceId?: string;\n\n  /**\n   * API Key for authentication. Falls back to process.env.VARD_API_KEY.\n   */\n  apiKey?: string;\n\n  /**\n   * Next.js fetch cache strategy. Defaults to \"force-cache\" (SSG-friendly).\n   * Use \"no-store\" for fully dynamic pages.\n   */\n  cache?: RequestCache;\n\n  /**\n   * Next.js ISR revalidation interval in seconds.\n   * Only applies when cache is \"force-cache\".\n   */\n  revalidate?: number;\n}\n\nimport { createVardFetchStore, VardFetchStoreOptions } from \"./fetch-store\";\n\n/**\n * Creates a VardStore that fetches live variable values from the Vard API.\n * Designed for use inside Next.js App Router (server components, server actions).\n */\nexport function createVardNextAdapter(\n  options: VardNextAdapterOptions = {}\n): VardStore & { prefetch(): Promise<void> } {\n  const { cache = \"force-cache\", revalidate = 60, ...rest } = options;\n\n  return createVardFetchStore({\n    ...rest,\n    fetchOptions: {\n      cache,\n      ...(revalidate !== undefined && cache === \"force-cache\"\n        ? ({ next: { revalidate } } as any)\n        : {}),\n    },\n  });\n}\n\n/**\n * A convenience wrapper that creates a Vard client pre-loaded with live values.\n * Call this once in your Next.js layout before rendering any server component\n * that uses vard variables.\n *\n * @example\n * // app/layout.tsx\n * import { prefetchVardValues } from \"@vard/sdk/next\"\n * import { vard } from \"@/lib/vard\"\n *\n * export default async function RootLayout({ children }) {\n *   await prefetchVardValues(vard)\n *   return <html>...</html>\n * }\n */\nimport { createVard } from \"./client\";\nimport type { VardClient, VardOptions } from \"./types\";\n\n/**\n * A convenience wrapper for createVard that automatically uses the Next.js adapter.\n *\n * @example\n * // lib/vard.ts\n * import { createVardNext } from \"@vard/sdk/next\"\n * export const vard = createVardNext({ revalidate: 60 })\n */\nexport function createVardNext(options: VardNextAdapterOptions & VardOptions = {}): VardClient {\n  const adapter = createVardNextAdapter(options);\n  return createVard({\n    ...options,\n    store: adapter,\n  });\n}\n\nexport async function prefetchVardValues(\n  target: { prefetch(): Promise<void> } | VardClient\n): Promise<void> {\n  const adapter = (target as any).prefetch ? target : (target as VardClient).store;\n  if (adapter && typeof (adapter as any).prefetch === \"function\") {\n    await (adapter as any).prefetch();\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{types-DLM7i_Qr.d.mts → types-eJuYa65b.d.mts}

@@ -18,6 +18,10 @@ interface VardVariableDefinition<T = unknown> {
     description?: string;
     /** For list variables — the schema of each item */
     listItemSchema?: VardListItemSchema;
+    /** Optional grouping for the dashboard UI */
+    group?: string;
+    /** Indicates this is a reusable content pool/collection */
+    isCollection?: boolean;
 }
 interface VardStore {
     /** Returns a stored value for the given key, or undefined if not set */
@@ -25,7 +29,12 @@ interface VardStore {
 }
 interface VardOptions {
     /**
-     * Workspace ID. Required in production so the SDK can look up values.
+     * API Key for authentication. Read from VARD_API_KEY env var if not provided.
+     * This is the preferred way to configure the SDK as it's tied to your workspace.
+     */
+    apiKey?: string;
+    /**
+     * Workspace ID (Legacy). Required only if not using an API Key.
      * Read from VARD_WORKSPACE_ID env var if not provided.
      */
     workspaceId?: string;
@@ -37,6 +46,15 @@ interface VardOptions {
     store?: VardStore;
 }
 interface VardClient {
+    /**
+     * Access to global (project-wide) variables.
+     * e.g., vard.global.string("contact.email", "...")
+     */
+    global: VardGlobalClient;
+    /**
+     * Define a reusable content pool/collection.
+     */
+    collection<S extends VardListItemSchema>(key: string, schema: S, fallback: InferListItem<S>[], options?: Omit<VardVariableOptions, "type">): InferListItem<S>[];
     /**
      * A plain string variable. e.g. a hero headline, a CTA label.
      *
@@ -72,11 +90,24 @@ interface VardClient {
      * and the build pipeline to sync definitions to the Vard API.
      */
     getDefinitions(): VardVariableDefinition[];
+    /**
+     * Access to the underlying store.
+     */
+    readonly store: VardStore;
+}
+interface VardGlobalClient {
+    string(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
+    richtext(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
+    color(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
+    image(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
+    boolean(key: string, fallback: boolean, options?: Omit<VardVariableOptions, "type" | "group">): boolean;
+    list<S extends VardListItemSchema>(key: string, schema: S, fallback: InferListItem<S>[], options?: Omit<VardVariableOptions, "type" | "group">): InferListItem<S>[];
 }
 interface VardVariableOptions {
     label?: string;
     description?: string;
     editableBy?: VardRole;
+    group?: string;
 }
 
-export type { InferListItem as I, VardOptions as V, VardClient as a, VardListItemSchema as b, VardRole as c, VardStore as d, VardVariableDefinition as e, VardVariableOptions as f, VardVariableType as g };
+export type { InferListItem as I, VardOptions as V, VardClient as a, VardStore as b, VardListItemSchema as c, VardRole as d, VardVariableDefinition as e, VardVariableOptions as f, VardVariableType as g };

package/dist/{types-DLM7i_Qr.d.ts → types-eJuYa65b.d.ts}

@@ -18,6 +18,10 @@ interface VardVariableDefinition<T = unknown> {
     description?: string;
     /** For list variables — the schema of each item */
     listItemSchema?: VardListItemSchema;
+    /** Optional grouping for the dashboard UI */
+    group?: string;
+    /** Indicates this is a reusable content pool/collection */
+    isCollection?: boolean;
 }
 interface VardStore {
     /** Returns a stored value for the given key, or undefined if not set */
@@ -25,7 +29,12 @@ interface VardStore {
 }
 interface VardOptions {
     /**
-     * Workspace ID. Required in production so the SDK can look up values.
+     * API Key for authentication. Read from VARD_API_KEY env var if not provided.
+     * This is the preferred way to configure the SDK as it's tied to your workspace.
+     */
+    apiKey?: string;
+    /**
+     * Workspace ID (Legacy). Required only if not using an API Key.
      * Read from VARD_WORKSPACE_ID env var if not provided.
      */
     workspaceId?: string;
@@ -37,6 +46,15 @@ interface VardOptions {
     store?: VardStore;
 }
 interface VardClient {
+    /**
+     * Access to global (project-wide) variables.
+     * e.g., vard.global.string("contact.email", "...")
+     */
+    global: VardGlobalClient;
+    /**
+     * Define a reusable content pool/collection.
+     */
+    collection<S extends VardListItemSchema>(key: string, schema: S, fallback: InferListItem<S>[], options?: Omit<VardVariableOptions, "type">): InferListItem<S>[];
     /**
      * A plain string variable. e.g. a hero headline, a CTA label.
      *
@@ -72,11 +90,24 @@ interface VardClient {
      * and the build pipeline to sync definitions to the Vard API.
      */
     getDefinitions(): VardVariableDefinition[];
+    /**
+     * Access to the underlying store.
+     */
+    readonly store: VardStore;
+}
+interface VardGlobalClient {
+    string(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
+    richtext(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
+    color(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
+    image(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
+    boolean(key: string, fallback: boolean, options?: Omit<VardVariableOptions, "type" | "group">): boolean;
+    list<S extends VardListItemSchema>(key: string, schema: S, fallback: InferListItem<S>[], options?: Omit<VardVariableOptions, "type" | "group">): InferListItem<S>[];
 }
 interface VardVariableOptions {
     label?: string;
     description?: string;
     editableBy?: VardRole;
+    group?: string;
 }
 
-export type { InferListItem as I, VardOptions as V, VardClient as a, VardListItemSchema as b, VardRole as c, VardStore as d, VardVariableDefinition as e, VardVariableOptions as f, VardVariableType as g };
+export type { InferListItem as I, VardOptions as V, VardClient as a, VardStore as b, VardListItemSchema as c, VardRole as d, VardVariableDefinition as e, VardVariableOptions as f, VardVariableType as g };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vard-app/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Vard SDK — annotate variables in your Next.js site for client-editable content",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",