@vard-app/sdk 0.1.4 → 0.1.6

package/dist/index.d.mts

@@ -1,5 +1,203 @@
-import { V as VardSchema, a as VardOptions, b as VardClient, c as VardStore } from './types-Dd-I7jwP.mjs';
-export { I as InferListItem, d as InferSchema, M as MergeSchema, e as VardListItemSchema, f as VardRole, g as VardSchemaFragment, h as VardVariableDefinition, i as VardVariableOptions, j as VardVariableType, v } from './types-Dd-I7jwP.mjs';
+interface VardFieldOptions<T = any> {
+    label?: string;
+    description?: string;
+    editableBy?: VardRole;
+    group?: string;
+    default?: T;
+}
+interface VardField<T = any> extends VardFieldOptions<T> {
+    type: VardVariableType;
+}
+interface VardCollection<S extends Record<string, VardField | any> = any> {
+    type: "collection";
+    schema: S;
+}
+type VardSchemaValue = VardField | VardCollection | boolean | {
+    [key: string]: VardSchemaValue;
+};
+type VardSchema = Record<string, VardSchemaValue>;
+/**
+ * A branded schema fragment created with `v.schema()`. Use with `vard.extend()`
+ * to compose schemas defined across multiple files.
+ */
+type VardSchemaFragment<S extends VardSchema> = S & {
+    readonly __fragment: true;
+};
+/**
+ * Merges two VardSchema types, with B's keys overriding A on collision.
+ */
+type MergeSchema<A extends VardSchema, B extends VardSchema> = Omit<A, keyof B> & B;
+declare const v: {
+    string: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
+    richtext: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
+    color: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
+    image: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
+    boolean: (defaultValue?: boolean, opts?: Omit<VardFieldOptions<boolean>, "default">) => VardField<boolean>;
+    collection: <S extends Record<string, VardField | any>>(schema: S) => VardCollection<S>;
+    /**
+     * Creates a reusable schema fragment that can be merged into a Vard client
+     * via `vard.extend(fragment)`. Co-locate this with your page/component.
+     *
+     * @example
+     * // app/therapists/schema.ts
+     * export const therapistSchema = v.schema({
+     *   therapists: v.collection({ name: v.string(), photo: v.image() }),
+     * });
+     *
+     * // app/therapists/page.tsx
+     * const { therapists } = await vard.extend(therapistSchema).get();
+     */
+    schema: <S extends VardSchema>(schema: S) => VardSchemaFragment<S>;
+};
+type InferSchema<T> = 0 extends 1 & T ? any : T extends VardField<infer U> ? U : T extends VardCollection<infer S> ? InferSchema<S>[] : T extends VardSchemaFragment<infer S> ? InferSchema<S> : T extends Record<string, any> ? {
+    [K in keyof T as K extends "__fragment" ? never : K]: InferSchema<T[K]>;
+} : T;
+
+type VardVariableType = "string" | "richtext" | "color" | "image" | "boolean" | "list";
+type VardListItemSchema = Record<string, "string" | "richtext" | "color" | "image" | "boolean">;
+type InferListItem<S extends VardListItemSchema> = {
+    [K in keyof S]: S[K] extends "string" ? string : S[K] extends "richtext" ? string : S[K] extends "color" ? string : S[K] extends "image" ? string : S[K] extends "boolean" ? boolean : never;
+};
+type VardRole = "owner" | "developer" | "member" | "viewer";
+interface VardVariableDefinition<T = unknown> {
+    /** Dot-notation key, e.g. "hero.title" */
+    key: string;
+    /** Human-readable label shown in the client portal */
+    label: string;
+    type: VardVariableType;
+    /** The default value baked into the codebase */
+    defaultValue: T;
+    /** Minimum role required to edit this variable. Defaults to "member". */
+    editableBy: VardRole;
+    /** Optional description shown as a hint in the client portal */
+    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 */
+    get(key: string): unknown;
+    /** Returns the full structured content object */
+    getStructured?(): any;
+    /** Ensures all values are loaded from the backend */
+    prefetch?(): Promise<void>;
+}
+interface VardOptions<S extends VardSchema = any> {
+    /**
+     * 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;
+    /**
+     * Optional content schema for type-safe data access and auto-syncing.
+     */
+    schema?: S;
+    /**
+     * VARD_API_KEY is unset (local dev without Vard).
+     */
+    store?: VardStore;
+    /**
+     * Enable verbose logging for requests and responses.
+     * Useful for debugging connection issues and verifying data flow.
+     */
+    debug?: boolean;
+}
+interface VardClient<S extends VardSchema = any> {
+    /**
+     * Define your content structure for type-safe data access and auto-syncing.
+     *
+     * @example
+     * const content = vard.define({
+     *   hero: { title: v.string("Welcome") }
+     * });
+     */
+    define<NS extends VardSchema>(schema: NS): InferSchema<NS>;
+    /**
+     * Returns a type-safe object containing all variable values matching the schema.
+     */
+    get(): Promise<InferSchema<S>>;
+    /**
+     * Returns a new scoped client with the given schema fragment merged in.
+     * Shares the same underlying store and registry as the parent client.
+     * Use this to co-locate page-specific schema definitions with their pages.
+     *
+     * @example
+     * // app/therapists/schema.ts
+     * export const therapistSchema = v.schema({
+     *   therapists: v.collection({ name: v.string() }),
+     * });
+     *
+     * // app/therapists/page.tsx
+     * const { therapists, global } = await vard.extend(therapistSchema).get();
+     */
+    extend<E extends VardSchema>(fragment: VardSchemaFragment<E>): VardClient<MergeSchema<S, E>>;
+    /**
+     * 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.
+     *
+     * @param key       Dot-notation identifier, unique within the workspace
+     * @param fallback  Default value when no client value is stored
+     * @param options   Optional label, description, permission
+     */
+    string(key: string, fallback: string, options?: VardVariableOptions): string;
+    /**
+     * A rich text (markdown) variable. Rendered as HTML at build time.
+     */
+    richtext(key: string, fallback: string, options?: VardVariableOptions): string;
+    /**
+     * A CSS color string (hex, hsl, rgb).
+     */
+    color(key: string, fallback: string, options?: VardVariableOptions): string;
+    /**
+     * A URL pointing to an uploaded asset (image, video).
+     */
+    image(key: string, fallback: string, options?: VardVariableOptions): string;
+    /**
+     * A boolean feature flag. e.g. show/hide a section.
+     */
+    boolean(key: string, fallback: boolean, options?: Omit<VardVariableOptions, "type">): boolean;
+    /**
+     * An ordered list of typed objects. e.g. team members, testimonials.
+     *
+     * @param schema  Defines the shape of each list item
+     */
+    list<S extends VardListItemSchema>(key: string, schema: S, fallback: InferListItem<S>[], options?: Omit<VardVariableOptions, "type">): InferListItem<S>[];
+    /**
+     * Returns all registered variable definitions. Used by the CLI scanner
+     * 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;
+}
 
 /**
  * Creates a Vard client instance. Call this once at the top of your site
@@ -20,6 +218,10 @@ interface VardFetchStoreOptions {
      * Custom fetch options (headers, etc.)
      */
     fetchOptions?: RequestInit;
+    /**
+     * Enable verbose logging for requests and responses.
+     */
+    debug?: boolean;
 }
 /**
  * Creates a universal VardStore that fetches variable values from the Vard API.
@@ -29,4 +231,4 @@ declare function createVardFetchStore(options?: VardFetchStoreOptions): VardStor
     prefetch(): Promise<void>;
 };
 
-export { VardClient, VardOptions, VardSchema, VardStore, createVard, createVardFetchStore };
+export { type InferListItem, type InferSchema, type MergeSchema, type VardClient, type VardListItemSchema, type VardOptions, type VardRole, type VardSchema, type VardSchemaFragment, type VardStore, type VardVariableDefinition, type VardVariableOptions, type VardVariableType, createVard, createVardFetchStore, v };

package/dist/index.d.ts

@@ -1,5 +1,203 @@
-import { V as VardSchema, a as VardOptions, b as VardClient, c as VardStore } from './types-Dd-I7jwP.js';
-export { I as InferListItem, d as InferSchema, M as MergeSchema, e as VardListItemSchema, f as VardRole, g as VardSchemaFragment, h as VardVariableDefinition, i as VardVariableOptions, j as VardVariableType, v } from './types-Dd-I7jwP.js';
+interface VardFieldOptions<T = any> {
+    label?: string;
+    description?: string;
+    editableBy?: VardRole;
+    group?: string;
+    default?: T;
+}
+interface VardField<T = any> extends VardFieldOptions<T> {
+    type: VardVariableType;
+}
+interface VardCollection<S extends Record<string, VardField | any> = any> {
+    type: "collection";
+    schema: S;
+}
+type VardSchemaValue = VardField | VardCollection | boolean | {
+    [key: string]: VardSchemaValue;
+};
+type VardSchema = Record<string, VardSchemaValue>;
+/**
+ * A branded schema fragment created with `v.schema()`. Use with `vard.extend()`
+ * to compose schemas defined across multiple files.
+ */
+type VardSchemaFragment<S extends VardSchema> = S & {
+    readonly __fragment: true;
+};
+/**
+ * Merges two VardSchema types, with B's keys overriding A on collision.
+ */
+type MergeSchema<A extends VardSchema, B extends VardSchema> = Omit<A, keyof B> & B;
+declare const v: {
+    string: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
+    richtext: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
+    color: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
+    image: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
+    boolean: (defaultValue?: boolean, opts?: Omit<VardFieldOptions<boolean>, "default">) => VardField<boolean>;
+    collection: <S extends Record<string, VardField | any>>(schema: S) => VardCollection<S>;
+    /**
+     * Creates a reusable schema fragment that can be merged into a Vard client
+     * via `vard.extend(fragment)`. Co-locate this with your page/component.
+     *
+     * @example
+     * // app/therapists/schema.ts
+     * export const therapistSchema = v.schema({
+     *   therapists: v.collection({ name: v.string(), photo: v.image() }),
+     * });
+     *
+     * // app/therapists/page.tsx
+     * const { therapists } = await vard.extend(therapistSchema).get();
+     */
+    schema: <S extends VardSchema>(schema: S) => VardSchemaFragment<S>;
+};
+type InferSchema<T> = 0 extends 1 & T ? any : T extends VardField<infer U> ? U : T extends VardCollection<infer S> ? InferSchema<S>[] : T extends VardSchemaFragment<infer S> ? InferSchema<S> : T extends Record<string, any> ? {
+    [K in keyof T as K extends "__fragment" ? never : K]: InferSchema<T[K]>;
+} : T;
+
+type VardVariableType = "string" | "richtext" | "color" | "image" | "boolean" | "list";
+type VardListItemSchema = Record<string, "string" | "richtext" | "color" | "image" | "boolean">;
+type InferListItem<S extends VardListItemSchema> = {
+    [K in keyof S]: S[K] extends "string" ? string : S[K] extends "richtext" ? string : S[K] extends "color" ? string : S[K] extends "image" ? string : S[K] extends "boolean" ? boolean : never;
+};
+type VardRole = "owner" | "developer" | "member" | "viewer";
+interface VardVariableDefinition<T = unknown> {
+    /** Dot-notation key, e.g. "hero.title" */
+    key: string;
+    /** Human-readable label shown in the client portal */
+    label: string;
+    type: VardVariableType;
+    /** The default value baked into the codebase */
+    defaultValue: T;
+    /** Minimum role required to edit this variable. Defaults to "member". */
+    editableBy: VardRole;
+    /** Optional description shown as a hint in the client portal */
+    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 */
+    get(key: string): unknown;
+    /** Returns the full structured content object */
+    getStructured?(): any;
+    /** Ensures all values are loaded from the backend */
+    prefetch?(): Promise<void>;
+}
+interface VardOptions<S extends VardSchema = any> {
+    /**
+     * 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;
+    /**
+     * Optional content schema for type-safe data access and auto-syncing.
+     */
+    schema?: S;
+    /**
+     * VARD_API_KEY is unset (local dev without Vard).
+     */
+    store?: VardStore;
+    /**
+     * Enable verbose logging for requests and responses.
+     * Useful for debugging connection issues and verifying data flow.
+     */
+    debug?: boolean;
+}
+interface VardClient<S extends VardSchema = any> {
+    /**
+     * Define your content structure for type-safe data access and auto-syncing.
+     *
+     * @example
+     * const content = vard.define({
+     *   hero: { title: v.string("Welcome") }
+     * });
+     */
+    define<NS extends VardSchema>(schema: NS): InferSchema<NS>;
+    /**
+     * Returns a type-safe object containing all variable values matching the schema.
+     */
+    get(): Promise<InferSchema<S>>;
+    /**
+     * Returns a new scoped client with the given schema fragment merged in.
+     * Shares the same underlying store and registry as the parent client.
+     * Use this to co-locate page-specific schema definitions with their pages.
+     *
+     * @example
+     * // app/therapists/schema.ts
+     * export const therapistSchema = v.schema({
+     *   therapists: v.collection({ name: v.string() }),
+     * });
+     *
+     * // app/therapists/page.tsx
+     * const { therapists, global } = await vard.extend(therapistSchema).get();
+     */
+    extend<E extends VardSchema>(fragment: VardSchemaFragment<E>): VardClient<MergeSchema<S, E>>;
+    /**
+     * 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.
+     *
+     * @param key       Dot-notation identifier, unique within the workspace
+     * @param fallback  Default value when no client value is stored
+     * @param options   Optional label, description, permission
+     */
+    string(key: string, fallback: string, options?: VardVariableOptions): string;
+    /**
+     * A rich text (markdown) variable. Rendered as HTML at build time.
+     */
+    richtext(key: string, fallback: string, options?: VardVariableOptions): string;
+    /**
+     * A CSS color string (hex, hsl, rgb).
+     */
+    color(key: string, fallback: string, options?: VardVariableOptions): string;
+    /**
+     * A URL pointing to an uploaded asset (image, video).
+     */
+    image(key: string, fallback: string, options?: VardVariableOptions): string;
+    /**
+     * A boolean feature flag. e.g. show/hide a section.
+     */
+    boolean(key: string, fallback: boolean, options?: Omit<VardVariableOptions, "type">): boolean;
+    /**
+     * An ordered list of typed objects. e.g. team members, testimonials.
+     *
+     * @param schema  Defines the shape of each list item
+     */
+    list<S extends VardListItemSchema>(key: string, schema: S, fallback: InferListItem<S>[], options?: Omit<VardVariableOptions, "type">): InferListItem<S>[];
+    /**
+     * Returns all registered variable definitions. Used by the CLI scanner
+     * 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;
+}
 
 /**
  * Creates a Vard client instance. Call this once at the top of your site
@@ -20,6 +218,10 @@ interface VardFetchStoreOptions {
      * Custom fetch options (headers, etc.)
      */
     fetchOptions?: RequestInit;
+    /**
+     * Enable verbose logging for requests and responses.
+     */
+    debug?: boolean;
 }
 /**
  * Creates a universal VardStore that fetches variable values from the Vard API.
@@ -29,4 +231,4 @@ declare function createVardFetchStore(options?: VardFetchStoreOptions): VardStor
     prefetch(): Promise<void>;
 };
 
-export { VardClient, VardOptions, VardSchema, VardStore, createVard, createVardFetchStore };
+export { type InferListItem, type InferSchema, type MergeSchema, type VardClient, type VardListItemSchema, type VardOptions, type VardRole, type VardSchema, type VardSchemaFragment, type VardStore, type VardVariableDefinition, type VardVariableOptions, type VardVariableType, createVard, createVardFetchStore, v };

package/dist/index.js

@@ -18,20 +18,21 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var src_exports = {};
-__export(src_exports, {
+var index_exports = {};
+__export(index_exports, {
   createVard: () => createVard,
   createVardFetchStore: () => createVardFetchStore,
   v: () => v
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 
 // src/fetch-store.ts
 function createVardFetchStore(options = {}) {
   const {
-    apiBase = options.apiBase ?? process.env.VARD_API_BASE ?? process.env.NEXT_PUBLIC_VARD_API_BASE ?? "https://dash.vard.app",
+    apiBase = options.apiBase ?? process.env.VARD_API_HOST ?? "https://dash.vard.app",
     apiKey = options.apiKey ?? process.env.VARD_API_KEY,
-    fetchOptions = {}
+    fetchOptions = {},
+    debug = options.debug ?? false
   } = options;
   let resolvedValues = null;
   let structuredContent = null;
@@ -50,7 +51,14 @@ function createVardFetchStore(options = {}) {
       }
       return { variables: /* @__PURE__ */ new Map(), structured: {} };
     }
-    const url = `${apiBase}/api/content/variables?structured=true`;
+    const url = `${apiBase}/api/content/variables`;
+    if (debug) {
+      console.log(`[vard] Request: GET ${url}`);
+      console.log(`[vard] Headers:`, {
+        "X-Vard-API-Key": apiKey.substring(0, 10) + "...",
+        ...fetchOptions.headers
+      });
+    }
     try {
       const res = await fetch(url, {
         ...fetchOptions,
@@ -60,24 +68,39 @@ function createVardFetchStore(options = {}) {
         }
       });
       if (!res.ok) {
-        console.warn(`[vard] Failed to fetch variables: ${res.status}`);
+        const errorMsg = `[vard] Failed to fetch variables from ${url} (Status: ${res.status} ${res.statusText})`;
+        console.error(`\x1B[31m${errorMsg}\x1B[0m`);
         return { variables: /* @__PURE__ */ new Map(), structured: {} };
       }
       const data = await res.json();
-      if (Array.isArray(data)) {
-        return {
-          variables: new Map(data.map((v2) => [v2.key, v2.value])),
-          structured: {}
-        };
+      if (debug) {
+        console.log(`[vard] Response (${res.status}):`, data);
       }
+      const variablesMap = /* @__PURE__ */ new Map();
+      flattenObject(data, "", variablesMap);
       return {
-        variables: new Map(data.variables.map((v2) => [v2.key, v2.value])),
-        structured: data.structured || {}
+        variables: variablesMap,
+        structured: data
       };
     } catch (err) {
+      const errorMsg = `[vard] Network error fetching variables from ${url}`;
+      console.error(`\x1B[31m${errorMsg}\x1B[0m`, err);
       return { variables: /* @__PURE__ */ new Map(), structured: {} };
     }
   }
+  function flattenObject(obj, prefix, map) {
+    if (typeof obj !== "object" || obj === null) return;
+    for (const [key, value] of Object.entries(obj)) {
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+      if (Array.isArray(value)) {
+        map.set(fullKey, value);
+      } else if (typeof value === "object" && value !== null) {
+        flattenObject(value, fullKey, map);
+      } else {
+        map.set(fullKey, value);
+      }
+    }
+  }
   return {
     get(key) {
       return resolvedValues?.get(key);
@@ -173,7 +196,7 @@ function createVard(options = {}) {
   if (options.schema && process.env.NODE_ENV === "development" && options.apiKey) {
     flattenSchema(options.schema);
     const definitions = [...registry];
-    const apiBase = process.env.VARD_API_BASE ?? process.env.NEXT_PUBLIC_VARD_API_BASE ?? "https://dash.vard.app";
+    const apiBase = process.env.VARD_API_HOST ?? "https://dash.vard.app";
     fetch(`${apiBase}/api/content/variables/sync`, {
       method: "POST",
       headers: {