@preprio/toolkit 0.5.0-rc.1 → 0.5.0-rc.3

package/dist/nextjs/index.d.cts

@@ -4,6 +4,8 @@ type Dictionary = Record<string, unknown>;
 declare const dictionaries: {
     en: Dictionary;
     nl: Dictionary;
+    fr: Dictionary;
+    de: Dictionary;
 };
 type Locale = keyof typeof dictionaries;
 
@@ -60,10 +62,23 @@ interface PreprPreviewOptions extends PreprToolbarOptions {
      */
     ui?: boolean;
     /**
-     * Replace the `*.prepr.io` editor-origin wildcard with an exact list.
-     * Intended for self-hosted editors; when set, the wildcard no longer applies.
+     * Replace the `*.prepr.io` editor-origin wildcard with an exact list, e.g.
+     * `['http://acme.localhost:8000']`. Intended for self-hosted or locally run
+     * editors; when set, the wildcard no longer applies. Entries are compared to
+     * the editor's origin exactly: scheme, host and port.
+     *
+     * `['*']` accepts any editor origin. Use it for development only: any page
+     * that frames the preview can then switch on preview and edit mode and
+     * receives the field-edit events, which carry content item ids.
      */
     allowedEditorOrigins?: string[];
+    /**
+     * Set when your preview token uses GraphQL strict mode, where required
+     * fields are never null. The editor then holds back new entries until
+     * their required fields are filled, and never sends a cleared required
+     * field as null.
+     */
+    strictMode?: boolean;
     /**
      * Strip the invisible stega characters out of visible text at runtime.
      * Default `true`.
@@ -148,6 +163,17 @@ interface PreprMiddlewareOptions {
 declare function createPreprMiddleware(request: NextRequest, options?: PreprMiddlewareOptions): NextResponse;
 declare function createPreprMiddleware(request: NextRequest, response: NextResponse, options?: PreprMiddlewareOptions): NextResponse;
 
+/**
+ * What `normalizeQuery` accepts as the query: GraphQL source text, a parsed
+ * `DocumentNode` (from `graphql-tag`, Apollo or GraphQL Code Generator), or a
+ * string-like object such as codegen's `TypedDocumentString`.
+ */
+type QueryInput = string | {
+    kind: 'Document';
+} | {
+    toString(): string;
+};
+
 /** Prepr Customer ID for the current request. Server-only. */
 declare function getPreprUUID(): Promise<string | null>;
 /** Active segment for the current request. Server-only. */
@@ -168,6 +194,28 @@ declare function getPreprHeaders(): Promise<PreprHeaders>;
  * bad or missing token can't crash the host app.
  */
 declare function getToolbarProps(token: string, features?: PreprFeatures): Promise<PreprToolbarProps>;
+interface NextNormalizeQueryOptions {
+    /**
+     * Pass the same preview flag as the middleware; never `true` on a
+     * production deployment. When false (the default) the request is not read,
+     * so static and ISR pages stay static.
+     */
+    enabled?: boolean;
+    /** Which operation to use when the document holds more than one. */
+    operationName?: string;
+}
+/**
+ * Show the Prepr editor's unsaved changes in server components: pass the
+ * query and its result, and render what comes back.
+ *
+ * ```ts
+ * const page = await normalizeQuery(GetPageDocument, data, { enabled: isPreview });
+ * ```
+ *
+ * Needs `PreprRefresh` mounted, and `_id` selected on every item and
+ * component that should update. Server-only; Next.js 16+.
+ */
+declare function normalizeQuery<T>(query: QueryInput, result: T, options?: NextNormalizeQueryOptions): Promise<T>;
 
 /** Error thrown by the token helpers and the segments fetch. */
 declare class PreprError extends Error {
@@ -242,4 +290,34 @@ declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): n
  */
 declare function PreprToolbar({ options, ...props }: PreprToolbarComponentProps): null;
 
-export { PreprError, type PreprMiddlewareOptions, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, createPreprMiddleware, extractAccessToken, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, validatePreprToken };
+/** Executes a registered query. `query` is opaque — string or DocumentNode. */
+interface LiveFetcher {
+    (query: unknown, variables?: Record<string, unknown>): Promise<unknown>;
+}
+
+interface LivePreviewConfig {
+    /**
+     * Pass your preview flag; never `true` on a production deployment.
+     * Defaults to false: nothing starts and `useLive` is a passthrough.
+     */
+    enabled?: boolean;
+    /** Runs registered queries against Prepr GraphQL in preview mode. */
+    fetcher?: LiveFetcher;
+    /** Exact editor origins, replacing the `*.prepr.io` default. */
+    allowedEditorOrigins?: string[];
+    /** Your preview token uses GraphQL strict mode; see the toolbar option. */
+    strictMode?: boolean;
+}
+interface PreprRefreshProps {
+    /** Pass your preview flag; never `true` on a production deployment. */
+    enabled?: boolean;
+    /** Your preview token uses GraphQL strict mode; see the toolbar option. */
+    strictMode?: boolean;
+}
+interface UseLiveOptions {
+    /** Query (string or DocumentNode) passed as-is to the fetcher. */
+    query?: unknown;
+    variables?: Record<string, unknown>;
+}
+
+export { type LiveFetcher, type LivePreviewConfig, type NextNormalizeQueryOptions, PreprError, type PreprMiddlewareOptions, type PreprRefreshProps, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, type UseLiveOptions, createPreprMiddleware, extractAccessToken, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, normalizeQuery, validatePreprToken };

package/dist/nextjs/index.d.ts

@@ -4,6 +4,8 @@ type Dictionary = Record<string, unknown>;
 declare const dictionaries: {
     en: Dictionary;
     nl: Dictionary;
+    fr: Dictionary;
+    de: Dictionary;
 };
 type Locale = keyof typeof dictionaries;
 
@@ -60,10 +62,23 @@ interface PreprPreviewOptions extends PreprToolbarOptions {
      */
     ui?: boolean;
     /**
-     * Replace the `*.prepr.io` editor-origin wildcard with an exact list.
-     * Intended for self-hosted editors; when set, the wildcard no longer applies.
+     * Replace the `*.prepr.io` editor-origin wildcard with an exact list, e.g.
+     * `['http://acme.localhost:8000']`. Intended for self-hosted or locally run
+     * editors; when set, the wildcard no longer applies. Entries are compared to
+     * the editor's origin exactly: scheme, host and port.
+     *
+     * `['*']` accepts any editor origin. Use it for development only: any page
+     * that frames the preview can then switch on preview and edit mode and
+     * receives the field-edit events, which carry content item ids.
      */
     allowedEditorOrigins?: string[];
+    /**
+     * Set when your preview token uses GraphQL strict mode, where required
+     * fields are never null. The editor then holds back new entries until
+     * their required fields are filled, and never sends a cleared required
+     * field as null.
+     */
+    strictMode?: boolean;
     /**
      * Strip the invisible stega characters out of visible text at runtime.
      * Default `true`.
@@ -148,6 +163,17 @@ interface PreprMiddlewareOptions {
 declare function createPreprMiddleware(request: NextRequest, options?: PreprMiddlewareOptions): NextResponse;
 declare function createPreprMiddleware(request: NextRequest, response: NextResponse, options?: PreprMiddlewareOptions): NextResponse;
 
+/**
+ * What `normalizeQuery` accepts as the query: GraphQL source text, a parsed
+ * `DocumentNode` (from `graphql-tag`, Apollo or GraphQL Code Generator), or a
+ * string-like object such as codegen's `TypedDocumentString`.
+ */
+type QueryInput = string | {
+    kind: 'Document';
+} | {
+    toString(): string;
+};
+
 /** Prepr Customer ID for the current request. Server-only. */
 declare function getPreprUUID(): Promise<string | null>;
 /** Active segment for the current request. Server-only. */
@@ -168,6 +194,28 @@ declare function getPreprHeaders(): Promise<PreprHeaders>;
  * bad or missing token can't crash the host app.
  */
 declare function getToolbarProps(token: string, features?: PreprFeatures): Promise<PreprToolbarProps>;
+interface NextNormalizeQueryOptions {
+    /**
+     * Pass the same preview flag as the middleware; never `true` on a
+     * production deployment. When false (the default) the request is not read,
+     * so static and ISR pages stay static.
+     */
+    enabled?: boolean;
+    /** Which operation to use when the document holds more than one. */
+    operationName?: string;
+}
+/**
+ * Show the Prepr editor's unsaved changes in server components: pass the
+ * query and its result, and render what comes back.
+ *
+ * ```ts
+ * const page = await normalizeQuery(GetPageDocument, data, { enabled: isPreview });
+ * ```
+ *
+ * Needs `PreprRefresh` mounted, and `_id` selected on every item and
+ * component that should update. Server-only; Next.js 16+.
+ */
+declare function normalizeQuery<T>(query: QueryInput, result: T, options?: NextNormalizeQueryOptions): Promise<T>;
 
 /** Error thrown by the token helpers and the segments fetch. */
 declare class PreprError extends Error {
@@ -242,4 +290,34 @@ declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): n
  */
 declare function PreprToolbar({ options, ...props }: PreprToolbarComponentProps): null;
 
-export { PreprError, type PreprMiddlewareOptions, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, createPreprMiddleware, extractAccessToken, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, validatePreprToken };
+/** Executes a registered query. `query` is opaque — string or DocumentNode. */
+interface LiveFetcher {
+    (query: unknown, variables?: Record<string, unknown>): Promise<unknown>;
+}
+
+interface LivePreviewConfig {
+    /**
+     * Pass your preview flag; never `true` on a production deployment.
+     * Defaults to false: nothing starts and `useLive` is a passthrough.
+     */
+    enabled?: boolean;
+    /** Runs registered queries against Prepr GraphQL in preview mode. */
+    fetcher?: LiveFetcher;
+    /** Exact editor origins, replacing the `*.prepr.io` default. */
+    allowedEditorOrigins?: string[];
+    /** Your preview token uses GraphQL strict mode; see the toolbar option. */
+    strictMode?: boolean;
+}
+interface PreprRefreshProps {
+    /** Pass your preview flag; never `true` on a production deployment. */
+    enabled?: boolean;
+    /** Your preview token uses GraphQL strict mode; see the toolbar option. */
+    strictMode?: boolean;
+}
+interface UseLiveOptions {
+    /** Query (string or DocumentNode) passed as-is to the fetcher. */
+    query?: unknown;
+    variables?: Record<string, unknown>;
+}
+
+export { type LiveFetcher, type LivePreviewConfig, type NextNormalizeQueryOptions, PreprError, type PreprMiddlewareOptions, type PreprRefreshProps, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, type UseLiveOptions, createPreprMiddleware, extractAccessToken, getActiveSegment, getActiveVariant, getPreprHeaders, getPreprUUID, getToolbarProps, normalizeQuery, validatePreprToken };