@dyrected/sdk 2.5.60 → 2.5.62

package/dist/index.cjs

@@ -22,7 +22,9 @@ var index_exports = {};
 __export(index_exports, {
   DyrectedClient: () => DyrectedClient,
   DyrectedError: () => DyrectedError,
-  createClient: () => createClient
+  PREVIEW_TOKEN_PARAM: () => PREVIEW_TOKEN_PARAM,
+  createClient: () => createClient,
+  getPreviewToken: () => getPreviewToken
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -163,6 +165,13 @@ var DyrectedClient = class {
   getBaseUrl() {
     return this.baseUrl;
   }
+  /**
+   * Inject the client's configured `defaultDepth` when a read did not specify
+   * its own `depth`. A per-call `depth` (including `0`) always wins.
+   */
+  applyDefaultDepth(args) {
+    return args.depth === void 0 ? { ...args, depth: this.defaultDepth } : args;
+  }
   async getSchemas() {
     return this.request("/api/schemas");
   }
@@ -177,27 +186,48 @@ var DyrectedClient = class {
   }
   async getPreference(key, options) {
     const scopeParam = options?.scope ? `?scope=${options.scope}` : "";
-    return this.request(`/api/preferences/${encodeURIComponent(key)}${scopeParam}`);
+    return this.request(
+      `/api/preferences/${encodeURIComponent(key)}${scopeParam}`
+    );
   }
   async setPreference(key, value, options) {
     const scopeParam = options?.scope ? `?scope=${options.scope}` : "";
-    return this.request(`/api/preferences/${encodeURIComponent(key)}${scopeParam}`, {
-      method: "PUT",
-      body: JSON.stringify({ value })
-    });
+    return this.request(
+      `/api/preferences/${encodeURIComponent(key)}${scopeParam}`,
+      {
+        method: "PUT",
+        body: JSON.stringify({ value })
+      }
+    );
   }
   async deletePreference(key, options) {
     const scopeParam = options?.scope ? `?scope=${options.scope}` : "";
-    return this.request(`/api/preferences/${encodeURIComponent(key)}${scopeParam}`, {
-      method: "DELETE"
-    });
+    return this.request(
+      `/api/preferences/${encodeURIComponent(key)}${scopeParam}`,
+      {
+        method: "DELETE"
+      }
+    );
   }
   /**
    * Fetch draft data for a specific preview token.
    * Used in "token" preview mode.
    */
   async getPreviewData(token) {
-    return this.request(`/api/preview-data?token=${token}`);
+    return this.request(`/api/preview-data?token=${encodeURIComponent(token)}`);
+  }
+  /**
+   * Mint a short-lived preview token that carries the current (unsaved) draft
+   * data. Used by the Admin in `previewMode: "token"` to hand draft content to
+   * a server-rendered frontend that cannot receive it over `postMessage`.
+   *
+   * Requires an authenticated request (the Admin is logged in).
+   */
+  async createPreviewToken(input) {
+    return this.request(`/api/preview-token`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
   }
   async find(collection, args = {}) {
     const { initialData, ...queryArgs } = args;
@@ -205,13 +235,22 @@ var DyrectedClient = class {
     if (queryArgs.where && typeof queryArgs.where === "object") {
       normalizedArgs.where = JSON.stringify(queryArgs.where);
     }
-    const query = stringifyQuery(normalizedArgs, { addQueryPrefix: true });
-    const res = await this.request(`/api/collections/${collection}${query}`);
+    const query = stringifyQuery(this.applyDefaultDepth(normalizedArgs), {
+      addQueryPrefix: true
+    });
+    const res = await this.request(
+      `/api/collections/${collection}${query}`
+    );
     if (res.docs.length === 0 && initialData && initialData.length > 0) {
       this.request(`/api/collections/${collection}/seed`, {
         method: "POST",
         body: JSON.stringify({ data: initialData })
-      }).catch((err) => console.error(`[dyrected/sdk] Failed to auto-seed collection "${collection}":`, err));
+      }).catch(
+        (err) => console.error(
+          `[dyrected/sdk] Failed to auto-seed collection "${collection}":`,
+          err
+        )
+      );
       return {
         docs: initialData,
         total: initialData.length,
@@ -235,11 +274,12 @@ var DyrectedClient = class {
           (collectionName, queryArgs) => this.find(collectionName, queryArgs)
         );
         if (args) {
-          if (args.where && typeof args.where === "object") qb.where(args.where);
+          if (args.where && typeof args.where === "object")
+            qb.where(args.where);
           if (args.sort) qb.sort(args.sort);
           if (args.limit) qb.limit(args.limit);
           if (args.page) qb.page(args.page);
-          if (args.depth) qb.depth(args.depth);
+          if (args.depth !== void 0) qb.depth(args.depth);
           if (args.initialData) qb.seed(args.initialData);
         }
         return qb;
@@ -332,7 +372,12 @@ var DyrectedClient = class {
        *   comment: 'Please add more detail to section 2.',
        * })
        */
-      transition: (id, transitionName, opts) => this.transition(slug, id, transitionName, opts),
+      transition: (id, transitionName, opts) => this.transition(
+        slug,
+        id,
+        transitionName,
+        opts
+      ),
       /**
        * Fetch the workflow history for a single document — every transition that
        * has ever been performed, newest first.
@@ -362,7 +407,9 @@ var DyrectedClient = class {
   }
   async findOne(collection, id, args = {}) {
     const { initialData, ...queryArgs } = args;
-    const query = stringifyQuery(queryArgs, { addQueryPrefix: true });
+    const query = stringifyQuery(this.applyDefaultDepth(queryArgs), {
+      addQueryPrefix: true
+    });
     try {
       return await this.request(`/api/collections/${collection}/${id}${query}`);
     } catch (err) {
@@ -371,7 +418,10 @@ var DyrectedClient = class {
           method: "POST",
           body: JSON.stringify({ data: [{ id, ...initialData }] })
         }).catch(
-          (err2) => console.error(`[dyrected/sdk] Failed to auto-seed document "${id}" in collection "${collection}":`, err2)
+          (err2) => console.error(
+            `[dyrected/sdk] Failed to auto-seed document "${id}" in collection "${collection}":`,
+            err2
+          )
         );
         return initialData;
       }
@@ -410,10 +460,13 @@ var DyrectedClient = class {
    * const updated = await client.transition('posts', postId, 'publish')
    */
   async transition(collection, id, transitionName, opts = {}) {
-    return this.request(`/api/collections/${collection}/${id}/transitions/${encodeURIComponent(transitionName)}`, {
-      method: "POST",
-      body: JSON.stringify(opts)
-    });
+    return this.request(
+      `/api/collections/${collection}/${id}/transitions/${encodeURIComponent(transitionName)}`,
+      {
+        method: "POST",
+        body: JSON.stringify(opts)
+      }
+    );
   }
   /**
    * Fetch the workflow history for a document.
@@ -426,7 +479,9 @@ var DyrectedClient = class {
    */
   async workflowHistory(collection, id, args = {}) {
     const query = args.limit ? `?limit=${args.limit}` : "";
-    return this.request(`/api/collections/${collection}/${id}/workflow-history${query}`);
+    return this.request(
+      `/api/collections/${collection}/${id}/workflow-history${query}`
+    );
   }
   /**
    * Fetch audit entries across every audited collection the current caller can read.
@@ -434,7 +489,9 @@ var DyrectedClient = class {
    * Sends `GET /api/audit`.
    */
   async audit(args = {}) {
-    const query = stringifyQuery(normalizeQueryArgs(args), { addQueryPrefix: true });
+    const query = stringifyQuery(normalizeQueryArgs(args), {
+      addQueryPrefix: true
+    });
     return this.request(`/api/audit${query}`);
   }
   /**
@@ -443,7 +500,9 @@ var DyrectedClient = class {
    * Sends `GET /api/collections/:collection/__audit`.
    */
   async collectionAudit(collection, args = {}) {
-    const query = stringifyQuery(normalizeQueryArgs(args), { addQueryPrefix: true });
+    const query = stringifyQuery(normalizeQueryArgs(args), {
+      addQueryPrefix: true
+    });
     return this.request(`/api/collections/${collection}/__audit${query}`);
   }
   async deleteMany(collection, ids) {
@@ -454,7 +513,9 @@ var DyrectedClient = class {
   }
   async getGlobal(slug, args = {}) {
     const { initialData, ...queryArgs } = args;
-    const query = stringifyQuery(queryArgs, { addQueryPrefix: true });
+    const query = stringifyQuery(this.applyDefaultDepth(queryArgs), {
+      addQueryPrefix: true
+    });
     try {
       const res = await this.request(`/api/globals/${slug}${query}`);
       if ((!res || isFunctionallyEmpty(res)) && !isFunctionallyEmpty(initialData)) {
@@ -462,7 +523,12 @@ var DyrectedClient = class {
         this.request(`/api/globals/${slug}/seed`, {
           method: "POST",
           body: JSON.stringify({ data: initialData })
-        }).catch((err) => console.error(`[dyrected/sdk] Failed to auto-seed global "${slug}":`, err));
+        }).catch(
+          (err) => console.error(
+            `[dyrected/sdk] Failed to auto-seed global "${slug}":`,
+            err
+          )
+        );
         return initialData;
       }
       return res;
@@ -471,7 +537,12 @@ var DyrectedClient = class {
         this.request(`/api/globals/${slug}/seed`, {
           method: "POST",
           body: JSON.stringify({ data: initialData })
-        }).catch((err2) => console.error(`[dyrected/sdk] Failed to auto-seed global "${slug}":`, err2));
+        }).catch(
+          (err2) => console.error(
+            `[dyrected/sdk] Failed to auto-seed global "${slug}":`,
+            err2
+          )
+        );
         return initialData;
       }
       throw err;
@@ -484,8 +555,13 @@ var DyrectedClient = class {
     });
   }
   async listMedia(args = {}, collection = "media") {
-    const query = stringifyQuery(normalizeQueryArgs(args), { addQueryPrefix: true });
-    return this.request(`/api/collections/${collection}${query}`);
+    const query = stringifyQuery(
+      this.applyDefaultDepth(normalizeQueryArgs(args)),
+      { addQueryPrefix: true }
+    );
+    return this.request(
+      `/api/collections/${collection}${query}`
+    );
   }
   /** @deprecated Use client.collection('media').upload(file, data) instead */
   async uploadMedia(file, collection = "media") {
@@ -530,7 +606,9 @@ var DyrectedClient = class {
           reject(new DyrectedError("Upload aborted", 0));
           return;
         }
-        options.signal.addEventListener("abort", () => xhr.abort(), { once: true });
+        options.signal.addEventListener("abort", () => xhr.abort(), {
+          once: true
+        });
       }
       xhr.upload.onprogress = (event) => {
         if (event.lengthComputable) {
@@ -558,7 +636,13 @@ var DyrectedClient = class {
             })
           );
         }
-        reject(new DyrectedError(body.message || `Request failed with status ${xhr.status}`, xhr.status, body.code));
+        reject(
+          new DyrectedError(
+            body.message || `Request failed with status ${xhr.status}`,
+            xhr.status,
+            body.code
+          )
+        );
       };
       xhr.onerror = () => reject(new DyrectedError("Network error during upload", 0));
       xhr.onabort = () => reject(new DyrectedError("Upload aborted", 0));
@@ -577,7 +661,9 @@ var DyrectedClient = class {
     });
     if (res && typeof res.ok === "boolean") {
       if (!res.ok) {
-        const body = await res.json().catch(() => ({ message: "Unknown error" }));
+        const body = await res.json().catch(() => ({
+          message: "Unknown error"
+        }));
         if (res.status === 429 && typeof window !== "undefined") {
           window.dispatchEvent(
             new CustomEvent("dyrected:rate-limit", {
@@ -586,7 +672,11 @@ var DyrectedClient = class {
           );
         }
         console.log("[DyrectedError]", body, res.status);
-        throw new DyrectedError(body.message || `Request failed with status ${res.status}`, res.status, body.code);
+        throw new DyrectedError(
+          body.message || `Request failed with status ${res.status}`,
+          res.status,
+          body.code
+        );
       }
       return res.json();
     }
@@ -596,6 +686,22 @@ var DyrectedClient = class {
 function createClient(config) {
   return new DyrectedClient(config);
 }
+var PREVIEW_TOKEN_PARAM = "dyPreview";
+function getPreviewToken(search) {
+  if (!search) return null;
+  let value;
+  if (typeof search === "string") {
+    value = new URLSearchParams(
+      search.startsWith("?") ? search.slice(1) : search
+    ).get(PREVIEW_TOKEN_PARAM);
+  } else if (search instanceof URLSearchParams) {
+    value = search.get(PREVIEW_TOKEN_PARAM);
+  } else {
+    value = search[PREVIEW_TOKEN_PARAM];
+  }
+  if (Array.isArray(value)) value = value[0];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
 function isFunctionallyEmpty(obj) {
   if (obj === null || obj === void 0 || obj === "") return true;
   if (Array.isArray(obj)) {
@@ -605,7 +711,9 @@ function isFunctionallyEmpty(obj) {
   if (typeof obj === "object") {
     const keys = Object.keys(obj);
     if (keys.length === 0) return true;
-    return keys.every((key) => isFunctionallyEmpty(obj[key]));
+    return keys.every(
+      (key) => isFunctionallyEmpty(obj[key])
+    );
   }
   return false;
 }
@@ -639,5 +747,7 @@ function normalizeQueryArgs(args) {
 0 && (module.exports = {
   DyrectedClient,
   DyrectedError,
-  createClient
+  PREVIEW_TOKEN_PARAM,
+  createClient,
+  getPreviewToken
 });

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { PaginatedResult, CollectionConfig, GlobalConfig, AdminConfig, PublicAdminAuthConfig, FileData, WorkflowMetadata } from '@dyrected/core';
+import { PaginatedResult, Block, CollectionConfig, GlobalConfig, AdminConfig, PublicAdminAuthConfig, FileData, WorkflowMetadata } from '@dyrected/core';
 export { AdminIconName, Block, CollectionConfig, EmailField, Field, FieldType, GlobalConfig, IconField, LifecycleEvent, FileData as Media, NumberField, PaginatedResult, TextField, TextareaField, UrlField, WorkflowMetadata } from '@dyrected/core';
 
 type UnknownRecord$1 = Record<string, unknown>;
@@ -27,6 +27,7 @@ declare class QueryBuilder<T = UnknownRecord$1> {
 
 type UnknownRecord = Record<string, unknown>;
 type SchemaResponse = {
+    blocks?: Block[];
     collections: CollectionConfig[];
     globals: GlobalConfig[];
     admin?: AdminConfig;
@@ -129,13 +130,63 @@ interface DyrectedClientConfig {
     siteId?: string;
     headers?: Record<string, string>;
     fetch?: typeof fetch;
-    /** Default depth for relationship population. Applied to every request unless overridden per-call. */
+    /**
+     * Default relationship population depth applied to document reads
+     * (`find`, `findOne`, `global().get()`, and media listing) when a call
+     * does not pass its own `depth`. Defaults to `1`.
+     */
     defaultDepth?: number;
 }
 interface BaseSchema {
     collections: Record<string, UnknownRecord>;
     globals: Record<string, UnknownRecord>;
 }
+/**
+ * The structural bound used as the generic *constraint* for {@link DyrectedClient}
+ * and the framework hooks. Its map values are `object` rather than
+ * `Record<string, unknown>`.
+ *
+ * This matters because a generated `DyrectedSchema` is built from named
+ * `interface`s (one per collection/global), and TypeScript interfaces have **no
+ * implicit index signature** — so they are assignable to `object` but *not* to
+ * `Record<string, unknown>`. Constraining against {@link BaseSchema} would
+ * reject every real generated schema; constraining against `SchemaShape`
+ * accepts them while {@link BaseSchema} remains the rich fallback default.
+ */
+interface SchemaShape {
+    collections: Record<string, object>;
+    globals: Record<string, object>;
+}
+/**
+ * Global registration seam for your generated schema.
+ *
+ * `dyrected generate:types` emits a module augmentation that registers your
+ * `DyrectedSchema` here:
+ *
+ * ```ts
+ * declare module "@dyrected/sdk" {
+ *   interface Register { schema: DyrectedSchema }
+ * }
+ * ```
+ *
+ * Once that generated file is part of your compilation, every client and
+ * framework hook is typed against your schema automatically — no per-call
+ * generics. Until then, this stays empty and everything falls back to the
+ * loosely-typed {@link BaseSchema}.
+ */
+interface Register {
+}
+/**
+ * The schema the SDK and framework hooks type themselves against. Resolves to
+ * your registered {@link Register} schema when the generated types are present,
+ * otherwise to {@link BaseSchema}. This is the default type parameter for
+ * {@link DyrectedClient} and {@link createClient}, so `client.collection("...")`
+ * and the React/Vue hooks pick up your collections and document shapes with no
+ * explicit generic.
+ */
+type RegisteredSchema = Register extends {
+    schema: infer S;
+} ? S extends SchemaShape ? S : BaseSchema : BaseSchema;
 /**
  * Options for file uploads.
  * When `onProgress` is provided and the runtime supports XMLHttpRequest (browsers),
@@ -148,7 +199,7 @@ interface UploadOptions {
     /** Abort the in-flight upload. */
     signal?: AbortSignal;
 }
-declare class DyrectedClient<TSchema extends BaseSchema = BaseSchema> {
+declare class DyrectedClient<TSchema extends SchemaShape = RegisteredSchema> {
     private baseUrl;
     private headers;
     private fetch;
@@ -171,6 +222,11 @@ declare class DyrectedClient<TSchema extends BaseSchema = BaseSchema> {
      */
     getAuthHeaders(): Record<string, string>;
     getBaseUrl(): string;
+    /**
+     * Inject the client's configured `defaultDepth` when a read did not specify
+     * its own `depth`. A per-call `depth` (including `0`) always wins.
+     */
+    private applyDefaultDepth;
     getSchemas(): Promise<SchemaResponse>;
     getAdminAuthConfig(): Promise<PublicAdminAuthConfig>;
     exchangeAdminAuth(providerId: string, body: Record<string, unknown>): Promise<{
@@ -200,6 +256,21 @@ declare class DyrectedClient<TSchema extends BaseSchema = BaseSchema> {
      * Used in "token" preview mode.
      */
     getPreviewData<T = unknown>(token: string): Promise<T>;
+    /**
+     * Mint a short-lived preview token that carries the current (unsaved) draft
+     * data. Used by the Admin in `previewMode: "token"` to hand draft content to
+     * a server-rendered frontend that cannot receive it over `postMessage`.
+     *
+     * Requires an authenticated request (the Admin is logged in).
+     */
+    createPreviewToken(input: {
+        collectionSlug: string;
+        documentId?: string;
+        data: unknown;
+    }): Promise<{
+        token: string;
+        expiresAt: string;
+    }>;
     find<K extends keyof TSchema["collections"]>(collection: K & string, args?: QueryArgs<TSchema["collections"][K]>): Promise<PaginatedResult<TSchema["collections"][K]>>;
     /**
      * Returns a fluent query builder for a collection.
@@ -412,6 +483,24 @@ declare class DyrectedClient<TSchema extends BaseSchema = BaseSchema> {
     }>;
     private request;
 }
-declare function createClient<TSchema extends BaseSchema = BaseSchema>(config: DyrectedClientConfig): DyrectedClient<TSchema>;
+declare function createClient<TSchema extends SchemaShape = RegisteredSchema>(config: DyrectedClientConfig): DyrectedClient<TSchema>;
+/**
+ * The query-string parameter the Admin appends to a preview URL in
+ * `previewMode: "token"`. Read it on your frontend to decide whether to fetch
+ * draft data instead of published content.
+ */
+declare const PREVIEW_TOKEN_PARAM = "dyPreview";
+/**
+ * Extract the preview token from a request's query string. Accepts a raw query
+ * string, a `URLSearchParams`, or a plain params object (e.g. Nuxt's
+ * `route.query` or Next's `searchParams`). Returns `null` when absent.
+ *
+ * @example
+ *   const token = getPreviewToken(route.query);
+ *   const doc = token
+ *     ? (await client.getPreviewData(token)).data
+ *     : (await client.find("pages", { where })).docs[0];
+ */
+declare function getPreviewToken(search: string | URLSearchParams | Record<string, unknown> | undefined | null): string | null;
 
-export { type AuditEntry, type BaseSchema, DyrectedClient, type DyrectedClientConfig, DyrectedError, type InferSchema, type TransitionOptions, type UploadOptions, type WorkflowDocument, type WorkflowHistoryEntry, createClient };
+export { type AuditEntry, type BaseSchema, DyrectedClient, type DyrectedClientConfig, DyrectedError, type InferSchema, PREVIEW_TOKEN_PARAM, type Register, type RegisteredSchema, type SchemaShape, type TransitionOptions, type UploadOptions, type WorkflowDocument, type WorkflowHistoryEntry, createClient, getPreviewToken };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PaginatedResult, CollectionConfig, GlobalConfig, AdminConfig, PublicAdminAuthConfig, FileData, WorkflowMetadata } from '@dyrected/core';
+import { PaginatedResult, Block, CollectionConfig, GlobalConfig, AdminConfig, PublicAdminAuthConfig, FileData, WorkflowMetadata } from '@dyrected/core';
 export { AdminIconName, Block, CollectionConfig, EmailField, Field, FieldType, GlobalConfig, IconField, LifecycleEvent, FileData as Media, NumberField, PaginatedResult, TextField, TextareaField, UrlField, WorkflowMetadata } from '@dyrected/core';
 
 type UnknownRecord$1 = Record<string, unknown>;
@@ -27,6 +27,7 @@ declare class QueryBuilder<T = UnknownRecord$1> {
 
 type UnknownRecord = Record<string, unknown>;
 type SchemaResponse = {
+    blocks?: Block[];
     collections: CollectionConfig[];
     globals: GlobalConfig[];
     admin?: AdminConfig;
@@ -129,13 +130,63 @@ interface DyrectedClientConfig {
     siteId?: string;
     headers?: Record<string, string>;
     fetch?: typeof fetch;
-    /** Default depth for relationship population. Applied to every request unless overridden per-call. */
+    /**
+     * Default relationship population depth applied to document reads
+     * (`find`, `findOne`, `global().get()`, and media listing) when a call
+     * does not pass its own `depth`. Defaults to `1`.
+     */
     defaultDepth?: number;
 }
 interface BaseSchema {
     collections: Record<string, UnknownRecord>;
     globals: Record<string, UnknownRecord>;
 }
+/**
+ * The structural bound used as the generic *constraint* for {@link DyrectedClient}
+ * and the framework hooks. Its map values are `object` rather than
+ * `Record<string, unknown>`.
+ *
+ * This matters because a generated `DyrectedSchema` is built from named
+ * `interface`s (one per collection/global), and TypeScript interfaces have **no
+ * implicit index signature** — so they are assignable to `object` but *not* to
+ * `Record<string, unknown>`. Constraining against {@link BaseSchema} would
+ * reject every real generated schema; constraining against `SchemaShape`
+ * accepts them while {@link BaseSchema} remains the rich fallback default.
+ */
+interface SchemaShape {
+    collections: Record<string, object>;
+    globals: Record<string, object>;
+}
+/**
+ * Global registration seam for your generated schema.
+ *
+ * `dyrected generate:types` emits a module augmentation that registers your
+ * `DyrectedSchema` here:
+ *
+ * ```ts
+ * declare module "@dyrected/sdk" {
+ *   interface Register { schema: DyrectedSchema }
+ * }
+ * ```
+ *
+ * Once that generated file is part of your compilation, every client and
+ * framework hook is typed against your schema automatically — no per-call
+ * generics. Until then, this stays empty and everything falls back to the
+ * loosely-typed {@link BaseSchema}.
+ */
+interface Register {
+}
+/**
+ * The schema the SDK and framework hooks type themselves against. Resolves to
+ * your registered {@link Register} schema when the generated types are present,
+ * otherwise to {@link BaseSchema}. This is the default type parameter for
+ * {@link DyrectedClient} and {@link createClient}, so `client.collection("...")`
+ * and the React/Vue hooks pick up your collections and document shapes with no
+ * explicit generic.
+ */
+type RegisteredSchema = Register extends {
+    schema: infer S;
+} ? S extends SchemaShape ? S : BaseSchema : BaseSchema;
 /**
  * Options for file uploads.
  * When `onProgress` is provided and the runtime supports XMLHttpRequest (browsers),
@@ -148,7 +199,7 @@ interface UploadOptions {
     /** Abort the in-flight upload. */
     signal?: AbortSignal;
 }
-declare class DyrectedClient<TSchema extends BaseSchema = BaseSchema> {
+declare class DyrectedClient<TSchema extends SchemaShape = RegisteredSchema> {
     private baseUrl;
     private headers;
     private fetch;
@@ -171,6 +222,11 @@ declare class DyrectedClient<TSchema extends BaseSchema = BaseSchema> {
      */
     getAuthHeaders(): Record<string, string>;
     getBaseUrl(): string;
+    /**
+     * Inject the client's configured `defaultDepth` when a read did not specify
+     * its own `depth`. A per-call `depth` (including `0`) always wins.
+     */
+    private applyDefaultDepth;
     getSchemas(): Promise<SchemaResponse>;
     getAdminAuthConfig(): Promise<PublicAdminAuthConfig>;
     exchangeAdminAuth(providerId: string, body: Record<string, unknown>): Promise<{
@@ -200,6 +256,21 @@ declare class DyrectedClient<TSchema extends BaseSchema = BaseSchema> {
      * Used in "token" preview mode.
      */
     getPreviewData<T = unknown>(token: string): Promise<T>;
+    /**
+     * Mint a short-lived preview token that carries the current (unsaved) draft
+     * data. Used by the Admin in `previewMode: "token"` to hand draft content to
+     * a server-rendered frontend that cannot receive it over `postMessage`.
+     *
+     * Requires an authenticated request (the Admin is logged in).
+     */
+    createPreviewToken(input: {
+        collectionSlug: string;
+        documentId?: string;
+        data: unknown;
+    }): Promise<{
+        token: string;
+        expiresAt: string;
+    }>;
     find<K extends keyof TSchema["collections"]>(collection: K & string, args?: QueryArgs<TSchema["collections"][K]>): Promise<PaginatedResult<TSchema["collections"][K]>>;
     /**
      * Returns a fluent query builder for a collection.
@@ -412,6 +483,24 @@ declare class DyrectedClient<TSchema extends BaseSchema = BaseSchema> {
     }>;
     private request;
 }
-declare function createClient<TSchema extends BaseSchema = BaseSchema>(config: DyrectedClientConfig): DyrectedClient<TSchema>;
+declare function createClient<TSchema extends SchemaShape = RegisteredSchema>(config: DyrectedClientConfig): DyrectedClient<TSchema>;
+/**
+ * The query-string parameter the Admin appends to a preview URL in
+ * `previewMode: "token"`. Read it on your frontend to decide whether to fetch
+ * draft data instead of published content.
+ */
+declare const PREVIEW_TOKEN_PARAM = "dyPreview";
+/**
+ * Extract the preview token from a request's query string. Accepts a raw query
+ * string, a `URLSearchParams`, or a plain params object (e.g. Nuxt's
+ * `route.query` or Next's `searchParams`). Returns `null` when absent.
+ *
+ * @example
+ *   const token = getPreviewToken(route.query);
+ *   const doc = token
+ *     ? (await client.getPreviewData(token)).data
+ *     : (await client.find("pages", { where })).docs[0];
+ */
+declare function getPreviewToken(search: string | URLSearchParams | Record<string, unknown> | undefined | null): string | null;
 
-export { type AuditEntry, type BaseSchema, DyrectedClient, type DyrectedClientConfig, DyrectedError, type InferSchema, type TransitionOptions, type UploadOptions, type WorkflowDocument, type WorkflowHistoryEntry, createClient };
+export { type AuditEntry, type BaseSchema, DyrectedClient, type DyrectedClientConfig, DyrectedError, type InferSchema, PREVIEW_TOKEN_PARAM, type Register, type RegisteredSchema, type SchemaShape, type TransitionOptions, type UploadOptions, type WorkflowDocument, type WorkflowHistoryEntry, createClient, getPreviewToken };

package/dist/index.js

@@ -135,6 +135,13 @@ var DyrectedClient = class {
   getBaseUrl() {
     return this.baseUrl;
   }
+  /**
+   * Inject the client's configured `defaultDepth` when a read did not specify
+   * its own `depth`. A per-call `depth` (including `0`) always wins.
+   */
+  applyDefaultDepth(args) {
+    return args.depth === void 0 ? { ...args, depth: this.defaultDepth } : args;
+  }
   async getSchemas() {
     return this.request("/api/schemas");
   }
@@ -149,27 +156,48 @@ var DyrectedClient = class {
   }
   async getPreference(key, options) {
     const scopeParam = options?.scope ? `?scope=${options.scope}` : "";
-    return this.request(`/api/preferences/${encodeURIComponent(key)}${scopeParam}`);
+    return this.request(
+      `/api/preferences/${encodeURIComponent(key)}${scopeParam}`
+    );
   }
   async setPreference(key, value, options) {
     const scopeParam = options?.scope ? `?scope=${options.scope}` : "";
-    return this.request(`/api/preferences/${encodeURIComponent(key)}${scopeParam}`, {
-      method: "PUT",
-      body: JSON.stringify({ value })
-    });
+    return this.request(
+      `/api/preferences/${encodeURIComponent(key)}${scopeParam}`,
+      {
+        method: "PUT",
+        body: JSON.stringify({ value })
+      }
+    );
   }
   async deletePreference(key, options) {
     const scopeParam = options?.scope ? `?scope=${options.scope}` : "";
-    return this.request(`/api/preferences/${encodeURIComponent(key)}${scopeParam}`, {
-      method: "DELETE"
-    });
+    return this.request(
+      `/api/preferences/${encodeURIComponent(key)}${scopeParam}`,
+      {
+        method: "DELETE"
+      }
+    );
   }
   /**
    * Fetch draft data for a specific preview token.
    * Used in "token" preview mode.
    */
   async getPreviewData(token) {
-    return this.request(`/api/preview-data?token=${token}`);
+    return this.request(`/api/preview-data?token=${encodeURIComponent(token)}`);
+  }
+  /**
+   * Mint a short-lived preview token that carries the current (unsaved) draft
+   * data. Used by the Admin in `previewMode: "token"` to hand draft content to
+   * a server-rendered frontend that cannot receive it over `postMessage`.
+   *
+   * Requires an authenticated request (the Admin is logged in).
+   */
+  async createPreviewToken(input) {
+    return this.request(`/api/preview-token`, {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
   }
   async find(collection, args = {}) {
     const { initialData, ...queryArgs } = args;
@@ -177,13 +205,22 @@ var DyrectedClient = class {
     if (queryArgs.where && typeof queryArgs.where === "object") {
       normalizedArgs.where = JSON.stringify(queryArgs.where);
     }
-    const query = stringifyQuery(normalizedArgs, { addQueryPrefix: true });
-    const res = await this.request(`/api/collections/${collection}${query}`);
+    const query = stringifyQuery(this.applyDefaultDepth(normalizedArgs), {
+      addQueryPrefix: true
+    });
+    const res = await this.request(
+      `/api/collections/${collection}${query}`
+    );
     if (res.docs.length === 0 && initialData && initialData.length > 0) {
       this.request(`/api/collections/${collection}/seed`, {
         method: "POST",
         body: JSON.stringify({ data: initialData })
-      }).catch((err) => console.error(`[dyrected/sdk] Failed to auto-seed collection "${collection}":`, err));
+      }).catch(
+        (err) => console.error(
+          `[dyrected/sdk] Failed to auto-seed collection "${collection}":`,
+          err
+        )
+      );
       return {
         docs: initialData,
         total: initialData.length,
@@ -207,11 +244,12 @@ var DyrectedClient = class {
           (collectionName, queryArgs) => this.find(collectionName, queryArgs)
         );
         if (args) {
-          if (args.where && typeof args.where === "object") qb.where(args.where);
+          if (args.where && typeof args.where === "object")
+            qb.where(args.where);
           if (args.sort) qb.sort(args.sort);
           if (args.limit) qb.limit(args.limit);
           if (args.page) qb.page(args.page);
-          if (args.depth) qb.depth(args.depth);
+          if (args.depth !== void 0) qb.depth(args.depth);
           if (args.initialData) qb.seed(args.initialData);
         }
         return qb;
@@ -304,7 +342,12 @@ var DyrectedClient = class {
        *   comment: 'Please add more detail to section 2.',
        * })
        */
-      transition: (id, transitionName, opts) => this.transition(slug, id, transitionName, opts),
+      transition: (id, transitionName, opts) => this.transition(
+        slug,
+        id,
+        transitionName,
+        opts
+      ),
       /**
        * Fetch the workflow history for a single document — every transition that
        * has ever been performed, newest first.
@@ -334,7 +377,9 @@ var DyrectedClient = class {
   }
   async findOne(collection, id, args = {}) {
     const { initialData, ...queryArgs } = args;
-    const query = stringifyQuery(queryArgs, { addQueryPrefix: true });
+    const query = stringifyQuery(this.applyDefaultDepth(queryArgs), {
+      addQueryPrefix: true
+    });
     try {
       return await this.request(`/api/collections/${collection}/${id}${query}`);
     } catch (err) {
@@ -343,7 +388,10 @@ var DyrectedClient = class {
           method: "POST",
           body: JSON.stringify({ data: [{ id, ...initialData }] })
         }).catch(
-          (err2) => console.error(`[dyrected/sdk] Failed to auto-seed document "${id}" in collection "${collection}":`, err2)
+          (err2) => console.error(
+            `[dyrected/sdk] Failed to auto-seed document "${id}" in collection "${collection}":`,
+            err2
+          )
         );
         return initialData;
       }
@@ -382,10 +430,13 @@ var DyrectedClient = class {
    * const updated = await client.transition('posts', postId, 'publish')
    */
   async transition(collection, id, transitionName, opts = {}) {
-    return this.request(`/api/collections/${collection}/${id}/transitions/${encodeURIComponent(transitionName)}`, {
-      method: "POST",
-      body: JSON.stringify(opts)
-    });
+    return this.request(
+      `/api/collections/${collection}/${id}/transitions/${encodeURIComponent(transitionName)}`,
+      {
+        method: "POST",
+        body: JSON.stringify(opts)
+      }
+    );
   }
   /**
    * Fetch the workflow history for a document.
@@ -398,7 +449,9 @@ var DyrectedClient = class {
    */
   async workflowHistory(collection, id, args = {}) {
     const query = args.limit ? `?limit=${args.limit}` : "";
-    return this.request(`/api/collections/${collection}/${id}/workflow-history${query}`);
+    return this.request(
+      `/api/collections/${collection}/${id}/workflow-history${query}`
+    );
   }
   /**
    * Fetch audit entries across every audited collection the current caller can read.
@@ -406,7 +459,9 @@ var DyrectedClient = class {
    * Sends `GET /api/audit`.
    */
   async audit(args = {}) {
-    const query = stringifyQuery(normalizeQueryArgs(args), { addQueryPrefix: true });
+    const query = stringifyQuery(normalizeQueryArgs(args), {
+      addQueryPrefix: true
+    });
     return this.request(`/api/audit${query}`);
   }
   /**
@@ -415,7 +470,9 @@ var DyrectedClient = class {
    * Sends `GET /api/collections/:collection/__audit`.
    */
   async collectionAudit(collection, args = {}) {
-    const query = stringifyQuery(normalizeQueryArgs(args), { addQueryPrefix: true });
+    const query = stringifyQuery(normalizeQueryArgs(args), {
+      addQueryPrefix: true
+    });
     return this.request(`/api/collections/${collection}/__audit${query}`);
   }
   async deleteMany(collection, ids) {
@@ -426,7 +483,9 @@ var DyrectedClient = class {
   }
   async getGlobal(slug, args = {}) {
     const { initialData, ...queryArgs } = args;
-    const query = stringifyQuery(queryArgs, { addQueryPrefix: true });
+    const query = stringifyQuery(this.applyDefaultDepth(queryArgs), {
+      addQueryPrefix: true
+    });
     try {
       const res = await this.request(`/api/globals/${slug}${query}`);
       if ((!res || isFunctionallyEmpty(res)) && !isFunctionallyEmpty(initialData)) {
@@ -434,7 +493,12 @@ var DyrectedClient = class {
         this.request(`/api/globals/${slug}/seed`, {
           method: "POST",
           body: JSON.stringify({ data: initialData })
-        }).catch((err) => console.error(`[dyrected/sdk] Failed to auto-seed global "${slug}":`, err));
+        }).catch(
+          (err) => console.error(
+            `[dyrected/sdk] Failed to auto-seed global "${slug}":`,
+            err
+          )
+        );
         return initialData;
       }
       return res;
@@ -443,7 +507,12 @@ var DyrectedClient = class {
         this.request(`/api/globals/${slug}/seed`, {
           method: "POST",
           body: JSON.stringify({ data: initialData })
-        }).catch((err2) => console.error(`[dyrected/sdk] Failed to auto-seed global "${slug}":`, err2));
+        }).catch(
+          (err2) => console.error(
+            `[dyrected/sdk] Failed to auto-seed global "${slug}":`,
+            err2
+          )
+        );
         return initialData;
       }
       throw err;
@@ -456,8 +525,13 @@ var DyrectedClient = class {
     });
   }
   async listMedia(args = {}, collection = "media") {
-    const query = stringifyQuery(normalizeQueryArgs(args), { addQueryPrefix: true });
-    return this.request(`/api/collections/${collection}${query}`);
+    const query = stringifyQuery(
+      this.applyDefaultDepth(normalizeQueryArgs(args)),
+      { addQueryPrefix: true }
+    );
+    return this.request(
+      `/api/collections/${collection}${query}`
+    );
   }
   /** @deprecated Use client.collection('media').upload(file, data) instead */
   async uploadMedia(file, collection = "media") {
@@ -502,7 +576,9 @@ var DyrectedClient = class {
           reject(new DyrectedError("Upload aborted", 0));
           return;
         }
-        options.signal.addEventListener("abort", () => xhr.abort(), { once: true });
+        options.signal.addEventListener("abort", () => xhr.abort(), {
+          once: true
+        });
       }
       xhr.upload.onprogress = (event) => {
         if (event.lengthComputable) {
@@ -530,7 +606,13 @@ var DyrectedClient = class {
             })
           );
         }
-        reject(new DyrectedError(body.message || `Request failed with status ${xhr.status}`, xhr.status, body.code));
+        reject(
+          new DyrectedError(
+            body.message || `Request failed with status ${xhr.status}`,
+            xhr.status,
+            body.code
+          )
+        );
       };
       xhr.onerror = () => reject(new DyrectedError("Network error during upload", 0));
       xhr.onabort = () => reject(new DyrectedError("Upload aborted", 0));
@@ -549,7 +631,9 @@ var DyrectedClient = class {
     });
     if (res && typeof res.ok === "boolean") {
       if (!res.ok) {
-        const body = await res.json().catch(() => ({ message: "Unknown error" }));
+        const body = await res.json().catch(() => ({
+          message: "Unknown error"
+        }));
         if (res.status === 429 && typeof window !== "undefined") {
           window.dispatchEvent(
             new CustomEvent("dyrected:rate-limit", {
@@ -558,7 +642,11 @@ var DyrectedClient = class {
           );
         }
         console.log("[DyrectedError]", body, res.status);
-        throw new DyrectedError(body.message || `Request failed with status ${res.status}`, res.status, body.code);
+        throw new DyrectedError(
+          body.message || `Request failed with status ${res.status}`,
+          res.status,
+          body.code
+        );
       }
       return res.json();
     }
@@ -568,6 +656,22 @@ var DyrectedClient = class {
 function createClient(config) {
   return new DyrectedClient(config);
 }
+var PREVIEW_TOKEN_PARAM = "dyPreview";
+function getPreviewToken(search) {
+  if (!search) return null;
+  let value;
+  if (typeof search === "string") {
+    value = new URLSearchParams(
+      search.startsWith("?") ? search.slice(1) : search
+    ).get(PREVIEW_TOKEN_PARAM);
+  } else if (search instanceof URLSearchParams) {
+    value = search.get(PREVIEW_TOKEN_PARAM);
+  } else {
+    value = search[PREVIEW_TOKEN_PARAM];
+  }
+  if (Array.isArray(value)) value = value[0];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
 function isFunctionallyEmpty(obj) {
   if (obj === null || obj === void 0 || obj === "") return true;
   if (Array.isArray(obj)) {
@@ -577,7 +681,9 @@ function isFunctionallyEmpty(obj) {
   if (typeof obj === "object") {
     const keys = Object.keys(obj);
     if (keys.length === 0) return true;
-    return keys.every((key) => isFunctionallyEmpty(obj[key]));
+    return keys.every(
+      (key) => isFunctionallyEmpty(obj[key])
+    );
   }
   return false;
 }
@@ -610,5 +716,7 @@ function normalizeQueryArgs(args) {
 export {
   DyrectedClient,
   DyrectedError,
-  createClient
+  PREVIEW_TOKEN_PARAM,
+  createClient,
+  getPreviewToken
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dyrected/sdk",
-  "version": "2.5.60",
+  "version": "2.5.62",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -30,7 +30,7 @@
     "tsup": "^8.5.1",
     "typescript": "^5.4.5",
     "vitest": "^1.0.0",
-    "@dyrected/core": "2.5.60"
+    "@dyrected/core": "2.5.62"
   },
   "license": "BSL-1.1",
   "author": "Busola Okeowo <busolaokemoney@gmail.com>",