@vard-app/sdk 0.1.3 → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +57 -71
- package/dist/index.d.mts +199 -17
- package/dist/index.d.ts +199 -17
- package/dist/index.js +164 -15
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +159 -11
- package/dist/index.mjs.map +1 -1
- package/dist/next.d.mts +177 -13
- package/dist/next.d.ts +177 -13
- package/dist/next.js +110 -10
- package/dist/next.js.map +1 -1
- package/dist/next.mjs +110 -10
- package/dist/next.mjs.map +1 -1
- package/package.json +7 -3
- package/dist/types-eJuYa65b.d.mts +0 -113
- package/dist/types-eJuYa65b.d.ts +0 -113
package/README.md
CHANGED
|
@@ -1,70 +1,50 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Vard SDK
|
|
2
2
|
|
|
3
|
-
The
|
|
3
|
+
The modern, schema-first content layer for Next.js.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Installation
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
|
|
8
|
+
npm install @vard/sdk
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
## Quick
|
|
11
|
+
## Quick Start
|
|
12
12
|
|
|
13
|
-
### 1.
|
|
13
|
+
### 1. Define your client
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
import {
|
|
15
|
+
Setup a shared client instance in your project (e.g. `lib/vard.ts`).
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
import { createVard, v } from "@vard/sdk";
|
|
19
|
+
import { createVardNextAdapter } from "@vard/sdk/next";
|
|
19
20
|
|
|
20
21
|
export const vard = createVard({
|
|
21
|
-
|
|
22
|
+
apiKey: process.env.VARD_API_KEY,
|
|
22
23
|
store: createVardNextAdapter(),
|
|
24
|
+
schema: {
|
|
25
|
+
hero: {
|
|
26
|
+
title: v.string("Welcome to Vard"),
|
|
27
|
+
image: v.image("/hero.jpg"),
|
|
28
|
+
},
|
|
29
|
+
features: v.collection({
|
|
30
|
+
title: v.string(),
|
|
31
|
+
icon: v.image(),
|
|
32
|
+
}),
|
|
33
|
+
},
|
|
23
34
|
});
|
|
24
35
|
```
|
|
25
36
|
|
|
26
|
-
### 2.
|
|
27
|
-
|
|
28
|
-
```tsx
|
|
29
|
-
// app/page.tsx
|
|
30
|
-
import { vard } from "@/lib/vard";
|
|
31
|
-
|
|
32
|
-
export default function HomePage() {
|
|
33
|
-
const heroTitle = vard.string("hero.title", "Welcome to our site");
|
|
34
|
-
const heroCopy = vard.richtext("hero.copy", "We build great things.");
|
|
35
|
-
const primaryColor = vard.color("theme.primary", "#2563eb");
|
|
36
|
-
const heroImage = vard.image("hero.image", "/default-hero.jpg");
|
|
37
|
-
const showBanner = vard.boolean("banner.show", false);
|
|
38
|
-
|
|
39
|
-
const team = vard.list(
|
|
40
|
-
"team.members",
|
|
41
|
-
{ name: "string", role: "string", photo: "image" },
|
|
42
|
-
[{ name: "Jane Doe", role: "Founder", photo: "/jane.jpg" }],
|
|
43
|
-
{ label: "Team Members" }
|
|
44
|
-
);
|
|
45
|
-
|
|
46
|
-
return (
|
|
47
|
-
<main style={{ "--primary": primaryColor } as React.CSSProperties}>
|
|
48
|
-
{showBanner && <Banner />}
|
|
49
|
-
<h1>{heroTitle}</h1>
|
|
50
|
-
<p dangerouslySetInnerHTML={{ __html: heroCopy }} />
|
|
51
|
-
{team.map((member) => (
|
|
52
|
-
<TeamCard key={member.name} {...member} />
|
|
53
|
-
))}
|
|
54
|
-
</main>
|
|
55
|
-
);
|
|
56
|
-
}
|
|
57
|
-
```
|
|
37
|
+
### 2. Prefetch in Layout (App Router)
|
|
58
38
|
|
|
59
|
-
|
|
39
|
+
To ensure zero-layout shift, prefetch values in your root layout.
|
|
60
40
|
|
|
61
41
|
```tsx
|
|
62
42
|
// app/layout.tsx
|
|
63
|
-
import {
|
|
43
|
+
import { prefetchVardValues } from "@vard/sdk/next";
|
|
64
44
|
import { vard } from "@/lib/vard";
|
|
65
45
|
|
|
66
|
-
export default async function RootLayout({ children }
|
|
67
|
-
await prefetchVardValues(vard
|
|
46
|
+
export default async function RootLayout({ children }) {
|
|
47
|
+
await prefetchVardValues(vard);
|
|
68
48
|
return (
|
|
69
49
|
<html>
|
|
70
50
|
<body>{children}</body>
|
|
@@ -73,36 +53,42 @@ export default async function RootLayout({ children }: { children: React.ReactNo
|
|
|
73
53
|
}
|
|
74
54
|
```
|
|
75
55
|
|
|
76
|
-
|
|
56
|
+
### 3. Use in Server Components
|
|
77
57
|
|
|
78
|
-
|
|
79
|
-
| ----------------- | ---------------------- | ---------------- |
|
|
80
|
-
| `vard.string()` | Plain text | Text input |
|
|
81
|
-
| `vard.richtext()` | Markdown | Rich text editor |
|
|
82
|
-
| `vard.color()` | CSS color string | Color picker |
|
|
83
|
-
| `vard.image()` | Asset URL | Image uploader |
|
|
84
|
-
| `vard.boolean()` | `true` / `false` | Toggle switch |
|
|
85
|
-
| `vard.list()` | Array of typed objects | Repeater |
|
|
58
|
+
Retrieve your entire content structure with a single, type-safe call.
|
|
86
59
|
|
|
87
|
-
|
|
60
|
+
```tsx
|
|
61
|
+
// app/page.tsx
|
|
62
|
+
import { vard } from "@/lib/vard";
|
|
88
63
|
|
|
89
|
-
|
|
64
|
+
export default async function Page() {
|
|
65
|
+
const { hero, features } = await vard.get();
|
|
90
66
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
67
|
+
return (
|
|
68
|
+
<main>
|
|
69
|
+
<h1>{hero.title}</h1>
|
|
70
|
+
<img src={hero.image} />
|
|
71
|
+
|
|
72
|
+
<ul>
|
|
73
|
+
{features.map((f) => (
|
|
74
|
+
<li key={f.title}>{f.title}</li>
|
|
75
|
+
))}
|
|
76
|
+
</ul>
|
|
77
|
+
</main>
|
|
78
|
+
);
|
|
79
|
+
}
|
|
96
80
|
```
|
|
97
81
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
## Local development
|
|
82
|
+
## Schema-First Features
|
|
101
83
|
|
|
102
|
-
|
|
84
|
+
- **Type Safety**: Full TypeScript inference out of the box. No manual interfaces required.
|
|
85
|
+
- **Auto-Sync**: In `development` mode, the SDK automatically syncs your schema to the Vard dashboard.
|
|
86
|
+
- **Hierarchical Data**: Define nested objects and collections to match your UI perfectly.
|
|
87
|
+
- **Backward Compatibility**: Standard `vard.string(key, fallback)` methods still work for simple use cases.
|
|
103
88
|
|
|
104
|
-
## Environment
|
|
89
|
+
## Environment Variables
|
|
105
90
|
|
|
106
|
-
| Variable
|
|
107
|
-
|
|
|
108
|
-
| `
|
|
91
|
+
| Variable | Description |
|
|
92
|
+
| --------------- | ---------------------------------------------------- |
|
|
93
|
+
| `VARD_API_KEY` | Your workspace API Key (Required for production) |
|
|
94
|
+
| `VARD_API_BASE` | Optional custom API base (Defaults to dash.vard.app) |
|
package/dist/index.d.mts
CHANGED
|
@@ -1,30 +1,212 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
interface VardFieldOptions<T = any> {
|
|
2
|
+
label?: string;
|
|
3
|
+
description?: string;
|
|
4
|
+
editableBy?: VardRole;
|
|
5
|
+
group?: string;
|
|
6
|
+
default?: T;
|
|
7
|
+
}
|
|
8
|
+
interface VardField<T = any> extends VardFieldOptions<T> {
|
|
9
|
+
type: VardVariableType;
|
|
10
|
+
}
|
|
11
|
+
interface VardCollection<S extends Record<string, VardField | any> = any> {
|
|
12
|
+
type: "collection";
|
|
13
|
+
schema: S;
|
|
14
|
+
}
|
|
15
|
+
type VardSchemaValue = VardField | VardCollection | boolean | {
|
|
16
|
+
[key: string]: VardSchemaValue;
|
|
17
|
+
};
|
|
18
|
+
type VardSchema = Record<string, VardSchemaValue>;
|
|
19
|
+
/**
|
|
20
|
+
* A branded schema fragment created with `v.schema()`. Use with `vard.extend()`
|
|
21
|
+
* to compose schemas defined across multiple files.
|
|
22
|
+
*/
|
|
23
|
+
type VardSchemaFragment<S extends VardSchema> = S & {
|
|
24
|
+
readonly __fragment: true;
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* Merges two VardSchema types, with B's keys overriding A on collision.
|
|
28
|
+
*/
|
|
29
|
+
type MergeSchema<A extends VardSchema, B extends VardSchema> = Omit<A, keyof B> & B;
|
|
30
|
+
declare const v: {
|
|
31
|
+
string: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
|
|
32
|
+
richtext: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
|
|
33
|
+
color: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
|
|
34
|
+
image: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
|
|
35
|
+
boolean: (defaultValue?: boolean, opts?: Omit<VardFieldOptions<boolean>, "default">) => VardField<boolean>;
|
|
36
|
+
collection: <S extends Record<string, VardField | any>>(schema: S) => VardCollection<S>;
|
|
37
|
+
/**
|
|
38
|
+
* Creates a reusable schema fragment that can be merged into a Vard client
|
|
39
|
+
* via `vard.extend(fragment)`. Co-locate this with your page/component.
|
|
40
|
+
*
|
|
41
|
+
* @example
|
|
42
|
+
* // app/therapists/schema.ts
|
|
43
|
+
* export const therapistSchema = v.schema({
|
|
44
|
+
* therapists: v.collection({ name: v.string(), photo: v.image() }),
|
|
45
|
+
* });
|
|
46
|
+
*
|
|
47
|
+
* // app/therapists/page.tsx
|
|
48
|
+
* const { therapists } = await vard.extend(therapistSchema).get();
|
|
49
|
+
*/
|
|
50
|
+
schema: <S extends VardSchema>(schema: S) => VardSchemaFragment<S>;
|
|
51
|
+
};
|
|
52
|
+
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> ? {
|
|
53
|
+
[K in keyof T as K extends "__fragment" ? never : K]: InferSchema<T[K]>;
|
|
54
|
+
} : T;
|
|
55
|
+
|
|
56
|
+
type VardVariableType = "string" | "richtext" | "color" | "image" | "boolean" | "list";
|
|
57
|
+
type VardListItemSchema = Record<string, "string" | "richtext" | "color" | "image" | "boolean">;
|
|
58
|
+
type InferListItem<S extends VardListItemSchema> = {
|
|
59
|
+
[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;
|
|
60
|
+
};
|
|
61
|
+
type VardRole = "owner" | "developer" | "member" | "viewer";
|
|
62
|
+
interface VardVariableDefinition<T = unknown> {
|
|
63
|
+
/** Dot-notation key, e.g. "hero.title" */
|
|
64
|
+
key: string;
|
|
65
|
+
/** Human-readable label shown in the client portal */
|
|
66
|
+
label: string;
|
|
67
|
+
type: VardVariableType;
|
|
68
|
+
/** The default value baked into the codebase */
|
|
69
|
+
defaultValue: T;
|
|
70
|
+
/** Minimum role required to edit this variable. Defaults to "member". */
|
|
71
|
+
editableBy: VardRole;
|
|
72
|
+
/** Optional description shown as a hint in the client portal */
|
|
73
|
+
description?: string;
|
|
74
|
+
/** For list variables — the schema of each item */
|
|
75
|
+
listItemSchema?: VardListItemSchema;
|
|
76
|
+
/** Optional grouping for the dashboard UI */
|
|
77
|
+
group?: string;
|
|
78
|
+
/** Indicates this is a reusable content pool/collection */
|
|
79
|
+
isCollection?: boolean;
|
|
80
|
+
}
|
|
81
|
+
interface VardStore {
|
|
82
|
+
/** Returns a stored value for the given key, or undefined if not set */
|
|
83
|
+
get(key: string): unknown;
|
|
84
|
+
/** Returns the full structured content object */
|
|
85
|
+
getStructured?(): any;
|
|
86
|
+
/** Ensures all values are loaded from the backend */
|
|
87
|
+
prefetch?(): Promise<void>;
|
|
88
|
+
}
|
|
89
|
+
interface VardOptions<S extends VardSchema = any> {
|
|
90
|
+
/**
|
|
91
|
+
* API Key for authentication. Read from VARD_API_KEY env var if not provided.
|
|
92
|
+
* This is the preferred way to configure the SDK as it's tied to your workspace.
|
|
93
|
+
*/
|
|
94
|
+
apiKey?: string;
|
|
95
|
+
/**
|
|
96
|
+
* Optional content schema for type-safe data access and auto-syncing.
|
|
97
|
+
*/
|
|
98
|
+
schema?: S;
|
|
99
|
+
/**
|
|
100
|
+
* Provide a custom store implementation. Used internally by the Next.js
|
|
101
|
+
* adapter and for testing. Defaults to a no-op in environments where
|
|
102
|
+
* VARD_API_KEY is unset (local dev without Vard).
|
|
103
|
+
*/
|
|
104
|
+
store?: VardStore;
|
|
105
|
+
}
|
|
106
|
+
interface VardClient<S extends VardSchema = any> {
|
|
107
|
+
/**
|
|
108
|
+
* Define your content structure for type-safe data access and auto-syncing.
|
|
109
|
+
*
|
|
110
|
+
* @example
|
|
111
|
+
* const content = vard.define({
|
|
112
|
+
* hero: { title: v.string("Welcome") }
|
|
113
|
+
* });
|
|
114
|
+
*/
|
|
115
|
+
define<NS extends VardSchema>(schema: NS): InferSchema<NS>;
|
|
116
|
+
/**
|
|
117
|
+
* Returns a type-safe object containing all variable values matching the schema.
|
|
118
|
+
*/
|
|
119
|
+
get(): Promise<InferSchema<S>>;
|
|
120
|
+
/**
|
|
121
|
+
* Returns a new scoped client with the given schema fragment merged in.
|
|
122
|
+
* Shares the same underlying store and registry as the parent client.
|
|
123
|
+
* Use this to co-locate page-specific schema definitions with their pages.
|
|
124
|
+
*
|
|
125
|
+
* @example
|
|
126
|
+
* // app/therapists/schema.ts
|
|
127
|
+
* export const therapistSchema = v.schema({
|
|
128
|
+
* therapists: v.collection({ name: v.string() }),
|
|
129
|
+
* });
|
|
130
|
+
*
|
|
131
|
+
* // app/therapists/page.tsx
|
|
132
|
+
* const { therapists, global } = await vard.extend(therapistSchema).get();
|
|
133
|
+
*/
|
|
134
|
+
extend<E extends VardSchema>(fragment: VardSchemaFragment<E>): VardClient<MergeSchema<S, E>>;
|
|
135
|
+
/**
|
|
136
|
+
* Access to global (project-wide) variables.
|
|
137
|
+
* e.g., vard.global.string("contact.email", "...")
|
|
138
|
+
*/
|
|
139
|
+
global: VardGlobalClient;
|
|
140
|
+
/**
|
|
141
|
+
* Define a reusable content pool/collection.
|
|
142
|
+
*/
|
|
143
|
+
collection<S extends VardListItemSchema>(key: string, schema: S, fallback: InferListItem<S>[], options?: Omit<VardVariableOptions, "type">): InferListItem<S>[];
|
|
144
|
+
/**
|
|
145
|
+
* A plain string variable. e.g. a hero headline, a CTA label.
|
|
146
|
+
*
|
|
147
|
+
* @param key Dot-notation identifier, unique within the workspace
|
|
148
|
+
* @param fallback Default value when no client value is stored
|
|
149
|
+
* @param options Optional label, description, permission
|
|
150
|
+
*/
|
|
151
|
+
string(key: string, fallback: string, options?: VardVariableOptions): string;
|
|
152
|
+
/**
|
|
153
|
+
* A rich text (markdown) variable. Rendered as HTML at build time.
|
|
154
|
+
*/
|
|
155
|
+
richtext(key: string, fallback: string, options?: VardVariableOptions): string;
|
|
156
|
+
/**
|
|
157
|
+
* A CSS color string (hex, hsl, rgb).
|
|
158
|
+
*/
|
|
159
|
+
color(key: string, fallback: string, options?: VardVariableOptions): string;
|
|
160
|
+
/**
|
|
161
|
+
* A URL pointing to an uploaded asset (image, video).
|
|
162
|
+
*/
|
|
163
|
+
image(key: string, fallback: string, options?: VardVariableOptions): string;
|
|
164
|
+
/**
|
|
165
|
+
* A boolean feature flag. e.g. show/hide a section.
|
|
166
|
+
*/
|
|
167
|
+
boolean(key: string, fallback: boolean, options?: Omit<VardVariableOptions, "type">): boolean;
|
|
168
|
+
/**
|
|
169
|
+
* An ordered list of typed objects. e.g. team members, testimonials.
|
|
170
|
+
*
|
|
171
|
+
* @param schema Defines the shape of each list item
|
|
172
|
+
*/
|
|
173
|
+
list<S extends VardListItemSchema>(key: string, schema: S, fallback: InferListItem<S>[], options?: Omit<VardVariableOptions, "type">): InferListItem<S>[];
|
|
174
|
+
/**
|
|
175
|
+
* Returns all registered variable definitions. Used by the CLI scanner
|
|
176
|
+
* and the build pipeline to sync definitions to the Vard API.
|
|
177
|
+
*/
|
|
178
|
+
getDefinitions(): VardVariableDefinition[];
|
|
179
|
+
/**
|
|
180
|
+
* Access to the underlying store.
|
|
181
|
+
*/
|
|
182
|
+
readonly store: VardStore;
|
|
183
|
+
}
|
|
184
|
+
interface VardGlobalClient {
|
|
185
|
+
string(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
|
|
186
|
+
richtext(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
|
|
187
|
+
color(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
|
|
188
|
+
image(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
|
|
189
|
+
boolean(key: string, fallback: boolean, options?: Omit<VardVariableOptions, "type" | "group">): boolean;
|
|
190
|
+
list<S extends VardListItemSchema>(key: string, schema: S, fallback: InferListItem<S>[], options?: Omit<VardVariableOptions, "type" | "group">): InferListItem<S>[];
|
|
191
|
+
}
|
|
192
|
+
interface VardVariableOptions {
|
|
193
|
+
label?: string;
|
|
194
|
+
description?: string;
|
|
195
|
+
editableBy?: VardRole;
|
|
196
|
+
group?: string;
|
|
197
|
+
}
|
|
3
198
|
|
|
4
199
|
/**
|
|
5
200
|
* Creates a Vard client instance. Call this once at the top of your site
|
|
6
201
|
* (e.g. in `lib/vard.ts`) and export the result.
|
|
7
|
-
*
|
|
8
|
-
* @example
|
|
9
|
-
* // lib/vard.ts
|
|
10
|
-
* import { createVard } from "@vard/sdk"
|
|
11
|
-
* export const vard = createVard({ apiKey: "..." })
|
|
12
|
-
*
|
|
13
|
-
* // app/page.tsx
|
|
14
|
-
* import { vard } from "@/lib/vard"
|
|
15
|
-
* const title = vard.string("hero.title", "Hello, world")
|
|
16
202
|
*/
|
|
17
|
-
declare function createVard(options?: VardOptions): VardClient
|
|
203
|
+
declare function createVard<S extends VardSchema = any>(options?: VardOptions<S>): VardClient<S>;
|
|
18
204
|
|
|
19
205
|
interface VardFetchStoreOptions {
|
|
20
206
|
/**
|
|
21
207
|
* Base URL of the Vard API. Defaults to https://api.vard.app
|
|
22
208
|
*/
|
|
23
209
|
apiBase?: string;
|
|
24
|
-
/**
|
|
25
|
-
* Workspace ID (Legacy). Defaults to process.env.VARD_WORKSPACE_ID.
|
|
26
|
-
*/
|
|
27
|
-
workspaceId?: string;
|
|
28
210
|
/**
|
|
29
211
|
* API Key for authentication. Defaults to process.env.VARD_API_KEY.
|
|
30
212
|
*/
|
|
@@ -42,4 +224,4 @@ declare function createVardFetchStore(options?: VardFetchStoreOptions): VardStor
|
|
|
42
224
|
prefetch(): Promise<void>;
|
|
43
225
|
};
|
|
44
226
|
|
|
45
|
-
export { VardClient, VardOptions, VardStore, createVard, createVardFetchStore };
|
|
227
|
+
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
CHANGED
|
@@ -1,30 +1,212 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
interface VardFieldOptions<T = any> {
|
|
2
|
+
label?: string;
|
|
3
|
+
description?: string;
|
|
4
|
+
editableBy?: VardRole;
|
|
5
|
+
group?: string;
|
|
6
|
+
default?: T;
|
|
7
|
+
}
|
|
8
|
+
interface VardField<T = any> extends VardFieldOptions<T> {
|
|
9
|
+
type: VardVariableType;
|
|
10
|
+
}
|
|
11
|
+
interface VardCollection<S extends Record<string, VardField | any> = any> {
|
|
12
|
+
type: "collection";
|
|
13
|
+
schema: S;
|
|
14
|
+
}
|
|
15
|
+
type VardSchemaValue = VardField | VardCollection | boolean | {
|
|
16
|
+
[key: string]: VardSchemaValue;
|
|
17
|
+
};
|
|
18
|
+
type VardSchema = Record<string, VardSchemaValue>;
|
|
19
|
+
/**
|
|
20
|
+
* A branded schema fragment created with `v.schema()`. Use with `vard.extend()`
|
|
21
|
+
* to compose schemas defined across multiple files.
|
|
22
|
+
*/
|
|
23
|
+
type VardSchemaFragment<S extends VardSchema> = S & {
|
|
24
|
+
readonly __fragment: true;
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* Merges two VardSchema types, with B's keys overriding A on collision.
|
|
28
|
+
*/
|
|
29
|
+
type MergeSchema<A extends VardSchema, B extends VardSchema> = Omit<A, keyof B> & B;
|
|
30
|
+
declare const v: {
|
|
31
|
+
string: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
|
|
32
|
+
richtext: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
|
|
33
|
+
color: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
|
|
34
|
+
image: (defaultValue?: string, opts?: Omit<VardFieldOptions<string>, "default">) => VardField<string>;
|
|
35
|
+
boolean: (defaultValue?: boolean, opts?: Omit<VardFieldOptions<boolean>, "default">) => VardField<boolean>;
|
|
36
|
+
collection: <S extends Record<string, VardField | any>>(schema: S) => VardCollection<S>;
|
|
37
|
+
/**
|
|
38
|
+
* Creates a reusable schema fragment that can be merged into a Vard client
|
|
39
|
+
* via `vard.extend(fragment)`. Co-locate this with your page/component.
|
|
40
|
+
*
|
|
41
|
+
* @example
|
|
42
|
+
* // app/therapists/schema.ts
|
|
43
|
+
* export const therapistSchema = v.schema({
|
|
44
|
+
* therapists: v.collection({ name: v.string(), photo: v.image() }),
|
|
45
|
+
* });
|
|
46
|
+
*
|
|
47
|
+
* // app/therapists/page.tsx
|
|
48
|
+
* const { therapists } = await vard.extend(therapistSchema).get();
|
|
49
|
+
*/
|
|
50
|
+
schema: <S extends VardSchema>(schema: S) => VardSchemaFragment<S>;
|
|
51
|
+
};
|
|
52
|
+
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> ? {
|
|
53
|
+
[K in keyof T as K extends "__fragment" ? never : K]: InferSchema<T[K]>;
|
|
54
|
+
} : T;
|
|
55
|
+
|
|
56
|
+
type VardVariableType = "string" | "richtext" | "color" | "image" | "boolean" | "list";
|
|
57
|
+
type VardListItemSchema = Record<string, "string" | "richtext" | "color" | "image" | "boolean">;
|
|
58
|
+
type InferListItem<S extends VardListItemSchema> = {
|
|
59
|
+
[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;
|
|
60
|
+
};
|
|
61
|
+
type VardRole = "owner" | "developer" | "member" | "viewer";
|
|
62
|
+
interface VardVariableDefinition<T = unknown> {
|
|
63
|
+
/** Dot-notation key, e.g. "hero.title" */
|
|
64
|
+
key: string;
|
|
65
|
+
/** Human-readable label shown in the client portal */
|
|
66
|
+
label: string;
|
|
67
|
+
type: VardVariableType;
|
|
68
|
+
/** The default value baked into the codebase */
|
|
69
|
+
defaultValue: T;
|
|
70
|
+
/** Minimum role required to edit this variable. Defaults to "member". */
|
|
71
|
+
editableBy: VardRole;
|
|
72
|
+
/** Optional description shown as a hint in the client portal */
|
|
73
|
+
description?: string;
|
|
74
|
+
/** For list variables — the schema of each item */
|
|
75
|
+
listItemSchema?: VardListItemSchema;
|
|
76
|
+
/** Optional grouping for the dashboard UI */
|
|
77
|
+
group?: string;
|
|
78
|
+
/** Indicates this is a reusable content pool/collection */
|
|
79
|
+
isCollection?: boolean;
|
|
80
|
+
}
|
|
81
|
+
interface VardStore {
|
|
82
|
+
/** Returns a stored value for the given key, or undefined if not set */
|
|
83
|
+
get(key: string): unknown;
|
|
84
|
+
/** Returns the full structured content object */
|
|
85
|
+
getStructured?(): any;
|
|
86
|
+
/** Ensures all values are loaded from the backend */
|
|
87
|
+
prefetch?(): Promise<void>;
|
|
88
|
+
}
|
|
89
|
+
interface VardOptions<S extends VardSchema = any> {
|
|
90
|
+
/**
|
|
91
|
+
* API Key for authentication. Read from VARD_API_KEY env var if not provided.
|
|
92
|
+
* This is the preferred way to configure the SDK as it's tied to your workspace.
|
|
93
|
+
*/
|
|
94
|
+
apiKey?: string;
|
|
95
|
+
/**
|
|
96
|
+
* Optional content schema for type-safe data access and auto-syncing.
|
|
97
|
+
*/
|
|
98
|
+
schema?: S;
|
|
99
|
+
/**
|
|
100
|
+
* Provide a custom store implementation. Used internally by the Next.js
|
|
101
|
+
* adapter and for testing. Defaults to a no-op in environments where
|
|
102
|
+
* VARD_API_KEY is unset (local dev without Vard).
|
|
103
|
+
*/
|
|
104
|
+
store?: VardStore;
|
|
105
|
+
}
|
|
106
|
+
interface VardClient<S extends VardSchema = any> {
|
|
107
|
+
/**
|
|
108
|
+
* Define your content structure for type-safe data access and auto-syncing.
|
|
109
|
+
*
|
|
110
|
+
* @example
|
|
111
|
+
* const content = vard.define({
|
|
112
|
+
* hero: { title: v.string("Welcome") }
|
|
113
|
+
* });
|
|
114
|
+
*/
|
|
115
|
+
define<NS extends VardSchema>(schema: NS): InferSchema<NS>;
|
|
116
|
+
/**
|
|
117
|
+
* Returns a type-safe object containing all variable values matching the schema.
|
|
118
|
+
*/
|
|
119
|
+
get(): Promise<InferSchema<S>>;
|
|
120
|
+
/**
|
|
121
|
+
* Returns a new scoped client with the given schema fragment merged in.
|
|
122
|
+
* Shares the same underlying store and registry as the parent client.
|
|
123
|
+
* Use this to co-locate page-specific schema definitions with their pages.
|
|
124
|
+
*
|
|
125
|
+
* @example
|
|
126
|
+
* // app/therapists/schema.ts
|
|
127
|
+
* export const therapistSchema = v.schema({
|
|
128
|
+
* therapists: v.collection({ name: v.string() }),
|
|
129
|
+
* });
|
|
130
|
+
*
|
|
131
|
+
* // app/therapists/page.tsx
|
|
132
|
+
* const { therapists, global } = await vard.extend(therapistSchema).get();
|
|
133
|
+
*/
|
|
134
|
+
extend<E extends VardSchema>(fragment: VardSchemaFragment<E>): VardClient<MergeSchema<S, E>>;
|
|
135
|
+
/**
|
|
136
|
+
* Access to global (project-wide) variables.
|
|
137
|
+
* e.g., vard.global.string("contact.email", "...")
|
|
138
|
+
*/
|
|
139
|
+
global: VardGlobalClient;
|
|
140
|
+
/**
|
|
141
|
+
* Define a reusable content pool/collection.
|
|
142
|
+
*/
|
|
143
|
+
collection<S extends VardListItemSchema>(key: string, schema: S, fallback: InferListItem<S>[], options?: Omit<VardVariableOptions, "type">): InferListItem<S>[];
|
|
144
|
+
/**
|
|
145
|
+
* A plain string variable. e.g. a hero headline, a CTA label.
|
|
146
|
+
*
|
|
147
|
+
* @param key Dot-notation identifier, unique within the workspace
|
|
148
|
+
* @param fallback Default value when no client value is stored
|
|
149
|
+
* @param options Optional label, description, permission
|
|
150
|
+
*/
|
|
151
|
+
string(key: string, fallback: string, options?: VardVariableOptions): string;
|
|
152
|
+
/**
|
|
153
|
+
* A rich text (markdown) variable. Rendered as HTML at build time.
|
|
154
|
+
*/
|
|
155
|
+
richtext(key: string, fallback: string, options?: VardVariableOptions): string;
|
|
156
|
+
/**
|
|
157
|
+
* A CSS color string (hex, hsl, rgb).
|
|
158
|
+
*/
|
|
159
|
+
color(key: string, fallback: string, options?: VardVariableOptions): string;
|
|
160
|
+
/**
|
|
161
|
+
* A URL pointing to an uploaded asset (image, video).
|
|
162
|
+
*/
|
|
163
|
+
image(key: string, fallback: string, options?: VardVariableOptions): string;
|
|
164
|
+
/**
|
|
165
|
+
* A boolean feature flag. e.g. show/hide a section.
|
|
166
|
+
*/
|
|
167
|
+
boolean(key: string, fallback: boolean, options?: Omit<VardVariableOptions, "type">): boolean;
|
|
168
|
+
/**
|
|
169
|
+
* An ordered list of typed objects. e.g. team members, testimonials.
|
|
170
|
+
*
|
|
171
|
+
* @param schema Defines the shape of each list item
|
|
172
|
+
*/
|
|
173
|
+
list<S extends VardListItemSchema>(key: string, schema: S, fallback: InferListItem<S>[], options?: Omit<VardVariableOptions, "type">): InferListItem<S>[];
|
|
174
|
+
/**
|
|
175
|
+
* Returns all registered variable definitions. Used by the CLI scanner
|
|
176
|
+
* and the build pipeline to sync definitions to the Vard API.
|
|
177
|
+
*/
|
|
178
|
+
getDefinitions(): VardVariableDefinition[];
|
|
179
|
+
/**
|
|
180
|
+
* Access to the underlying store.
|
|
181
|
+
*/
|
|
182
|
+
readonly store: VardStore;
|
|
183
|
+
}
|
|
184
|
+
interface VardGlobalClient {
|
|
185
|
+
string(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
|
|
186
|
+
richtext(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
|
|
187
|
+
color(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
|
|
188
|
+
image(key: string, fallback: string, options?: Omit<VardVariableOptions, "group">): string;
|
|
189
|
+
boolean(key: string, fallback: boolean, options?: Omit<VardVariableOptions, "type" | "group">): boolean;
|
|
190
|
+
list<S extends VardListItemSchema>(key: string, schema: S, fallback: InferListItem<S>[], options?: Omit<VardVariableOptions, "type" | "group">): InferListItem<S>[];
|
|
191
|
+
}
|
|
192
|
+
interface VardVariableOptions {
|
|
193
|
+
label?: string;
|
|
194
|
+
description?: string;
|
|
195
|
+
editableBy?: VardRole;
|
|
196
|
+
group?: string;
|
|
197
|
+
}
|
|
3
198
|
|
|
4
199
|
/**
|
|
5
200
|
* Creates a Vard client instance. Call this once at the top of your site
|
|
6
201
|
* (e.g. in `lib/vard.ts`) and export the result.
|
|
7
|
-
*
|
|
8
|
-
* @example
|
|
9
|
-
* // lib/vard.ts
|
|
10
|
-
* import { createVard } from "@vard/sdk"
|
|
11
|
-
* export const vard = createVard({ apiKey: "..." })
|
|
12
|
-
*
|
|
13
|
-
* // app/page.tsx
|
|
14
|
-
* import { vard } from "@/lib/vard"
|
|
15
|
-
* const title = vard.string("hero.title", "Hello, world")
|
|
16
202
|
*/
|
|
17
|
-
declare function createVard(options?: VardOptions): VardClient
|
|
203
|
+
declare function createVard<S extends VardSchema = any>(options?: VardOptions<S>): VardClient<S>;
|
|
18
204
|
|
|
19
205
|
interface VardFetchStoreOptions {
|
|
20
206
|
/**
|
|
21
207
|
* Base URL of the Vard API. Defaults to https://api.vard.app
|
|
22
208
|
*/
|
|
23
209
|
apiBase?: string;
|
|
24
|
-
/**
|
|
25
|
-
* Workspace ID (Legacy). Defaults to process.env.VARD_WORKSPACE_ID.
|
|
26
|
-
*/
|
|
27
|
-
workspaceId?: string;
|
|
28
210
|
/**
|
|
29
211
|
* API Key for authentication. Defaults to process.env.VARD_API_KEY.
|
|
30
212
|
*/
|
|
@@ -42,4 +224,4 @@ declare function createVardFetchStore(options?: VardFetchStoreOptions): VardStor
|
|
|
42
224
|
prefetch(): Promise<void>;
|
|
43
225
|
};
|
|
44
226
|
|
|
45
|
-
export { VardClient, VardOptions, VardStore, createVard, createVardFetchStore };
|
|
227
|
+
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 };
|