fontdue-js 3.0.6 → 3.2.0

package/dist/relay/serverConfig.js

@@ -26,6 +26,9 @@
 
 import * as React from 'react';
 
+// Recovers a visitor's per-collection node-access headers when a server fetch
+// comes back `password_protected` — see registerNodeAccessRecovery below.
+
 // This module owns two pieces of cross-cutting state — the render-scoped slot
 // and the ambient resolver — and both must be shared by every server-side
 // fetch in a render. The catch: a Next.js server build can bundle this same
@@ -58,7 +61,8 @@ function store() {
       })) : () => ({
         current: undefined
       }),
-      ambientResolver: undefined
+      ambientResolver: undefined,
+      nodeAccessRecovery: undefined
     };
     g[STORE_KEY] = s;
   }
@@ -84,6 +88,23 @@ export function registerAmbientConfigResolver(resolver) {
   store().ambientResolver = resolver;
 }
 
+// Node-access recovery — the seam that lets the browser-safe transport recover
+// from a `password_protected` error without importing a framework's request
+// APIs. The Next adapter registers a recovery that reads the visitor's
+// node-access cookie (via next/headers); createFontdueFetch calls it when a
+// fetch comes back locked, folds the returned headers into the per-render config
+// so the page fetch AND the embedded server components' own preloads resolve,
+// then retries once (see ../server/index.ts). Returns {} when the visitor hasn't
+// unlocked the collection. Unregistered (non-Next, or frameworks that forward
+// the token ambiently up-front via runWithNodeAccess) → no recovery, the error
+// propagates so the page can render the password form.
+export function registerNodeAccessRecovery(recovery) {
+  store().nodeAccessRecovery = recovery;
+}
+export function resolveNodeAccessRecovery() {
+  return store().nodeAccessRecovery;
+}
+
 // Merge an ambient config under the RSC slot: the slot wins for scalar fields;
 // headers merge with the slot overriding.
 function mergeServerConfig(ambient, slot) {

package/dist/server/index.d.ts

@@ -2,6 +2,14 @@ export declare class FontdueNotFoundError extends Error {
     readonly queryName: string;
     constructor(queryName: string);
 }
+export declare class FontdueGraphqlError extends Error {
+    readonly code: string | undefined;
+    readonly queryName: string;
+    constructor(message: string, code: string | undefined, queryName: string);
+}
+export declare class FontduePasswordProtectedError extends FontdueGraphqlError {
+    constructor(message: string, queryName: string);
+}
 export interface CreateFontdueFetchOptions {
     /**
      * GraphQL base URL (without the trailing /graphql), e.g.

package/dist/server/index.js

@@ -45,7 +45,7 @@
 // The Next fetch hints are inert in other runtimes: Node's fetch accepts and
 // ignores the cache mode, and `next` is just an unknown init property.
 
-import { resolveFontdueServerConfig } from '../relay/serverConfig.js';
+import { resolveFontdueServerConfig, setFontdueServerConfig, resolveNodeAccessRecovery } from '../relay/serverConfig.js';
 import { PREVIEW_HEADER } from '../preview/constants.js';
 function readEnv(name) {
   if (typeof process !== 'undefined' && process.env) {
@@ -87,6 +87,30 @@ export class FontdueNotFoundError extends Error {
     this.name = 'FontdueNotFoundError';
   }
 }
+
+// Thrown when a GraphQL response carries an `errors` entry. Subclasses Error so
+// existing `catch`/rethrow keeps working, but also exposes the machine-readable
+// `code` from the first error (e.g. "password_protected") so callers can branch
+// on a specific failure instead of string-matching the message.
+export class FontdueGraphqlError extends Error {
+  constructor(message, code, queryName) {
+    super(message);
+    this.code = code;
+    this.queryName = queryName;
+    this.name = 'FontdueGraphqlError';
+  }
+}
+
+// Thrown when the requested collection is password-protected and the visitor
+// hasn't unlocked it. Catch it to render a <NodePasswordForm> instead of a 404:
+// the collection exists, it's just gated. The matching server signal is the
+// GraphQL error code "password_protected" (see the Fontdue slug resolver).
+export class FontduePasswordProtectedError extends FontdueGraphqlError {
+  constructor(message, queryName) {
+    super(message, 'password_protected', queryName);
+    this.name = 'FontduePasswordProtectedError';
+  }
+}
 /**
  * Build a server-side GraphQL fetcher bound to a base URL and a set of headers.
  * The returned function takes the operation name, the query text (load it from
@@ -94,8 +118,10 @@ export class FontdueNotFoundError extends Error {
  */
 export function createFontdueFetch() {
   let options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
-  return async function fetchGraphql(queryName, query, variables) {
-    var _json$errors, _json$errors$;
+  async function runOnce(queryName, query, variables) {
+    let {
+      forceUncached = false
+    } = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
     // Per-render config (a runWithPreview AsyncLocalStorage store, the Next
     // render-scoped slot, or the Next single-tenant ambient resolver). Awaited
     // per call so a single module-level fetcher picks up the current request's
@@ -111,7 +137,9 @@ export function createFontdueFetch() {
     // Cache tags: explicit option wins, else the per-render config's. A
     // non-empty list opts the fetch into Next's data cache (inert elsewhere);
     // an empty/absent list leaves it uncached (preview + CDN-cached frameworks).
-    const cacheTags = options.cacheTags ?? (config === null || config === void 0 ? void 0 : config.cacheTags);
+    // A forced-uncached retry (an unlocked, per-visitor render) drops them
+    // entirely so nothing tags the response into the shared cache.
+    const cacheTags = forceUncached ? undefined : options.cacheTags ?? (config === null || config === void 0 ? void 0 : config.cacheTags);
 
     // Ambient headers (e.g. tenant + preview token), overridden by any explicit
     // per-fetcher headers.
@@ -151,10 +179,65 @@ export function createFontdueFetch() {
       throw new Error(`Fontdue request failed: ${response.status}`);
     }
     const json = await response.json();
-    const errorMessage = (_json$errors = json.errors) === null || _json$errors === void 0 ? void 0 : (_json$errors$ = _json$errors[0]) === null || _json$errors$ === void 0 ? void 0 : _json$errors$.message;
-    if (errorMessage) {
-      throw new Error(`Fontdue GraphQL error: ${errorMessage}`);
+    const errors = json.errors ?? [];
+    if (errors.length > 0) {
+      // Absinthe puts a resolver's error `code` on the error itself; some errors
+      // carry it under `extensions` instead — check both.
+      const codeOf = e => {
+        var _e$extensions;
+        return e.code ?? ((_e$extensions = e.extensions) === null || _e$extensions === void 0 ? void 0 : _e$extensions.code);
+      };
+      // Look across every error, not just the first: a query that touches a
+      // locked collection alongside another failing field can return
+      // `password_protected` in any position, and the recovery + the app's
+      // `instanceof FontduePasswordProtectedError` catch both depend on it being
+      // recognized regardless of order.
+      const locked = errors.find(e => codeOf(e) === 'password_protected');
+      if (locked) {
+        throw new FontduePasswordProtectedError(`Fontdue GraphQL error: ${locked.message}`, queryName);
+      }
+      const first = errors[0];
+      throw new FontdueGraphqlError(`Fontdue GraphQL error: ${first.message}`, codeOf(first), queryName);
     }
     return json.data;
+  }
+  return async function fetchGraphql(queryName, query, variables) {
+    try {
+      return await runOnce(queryName, query, variables);
+    } catch (error) {
+      // A password-protected collection comes back as a `password_protected`
+      // error. In a server render, recover transparently: a registered recovery
+      // (the Next adapter) reads the visitor's node-access cookie. If they've
+      // unlocked it, fold the token into the per-render config — so this fetch
+      // AND the page's embedded server components' own (Suspense) preloads
+      // resolve, not just this one call — and retry once. Reading the cookie is
+      // deferred to here (only when a fetch is actually gated) so non-protected
+      // pages stay static/cacheable; the retry runs `forceUncached` so the
+      // unlocked, per-visitor render is never written to the shared cache.
+      // Frameworks that forward the token ambiently up-front (runWithNodeAccess)
+      // never reach this path. With no recovery registered, or no token, the
+      // error propagates so the page can render the password form.
+      if (error instanceof FontduePasswordProtectedError) {
+        const recover = resolveNodeAccessRecovery();
+        if (recover) {
+          const nodeAccess = await recover();
+          if (Object.keys(nodeAccess).length > 0) {
+            const config = (await resolveFontdueServerConfig()) ?? {};
+            setFontdueServerConfig({
+              ...config,
+              headers: {
+                ...config.headers,
+                ...nodeAccess
+              },
+              cacheTags: undefined
+            });
+            return await runOnce(queryName, query, variables, {
+              forceUncached: true
+            });
+          }
+        }
+      }
+      throw error;
+    }
   };
 }

package/dist/server/middleware.d.ts

@@ -0,0 +1,37 @@
+/** Whether the current async context is an admin preview. */
+export declare function isPreviewing(): boolean;
+/**
+ * Request-scoped Fontdue headers for the current async context (admin preview
+ * and/or the visitor's node-access token), or {} when there are none. Spread
+ * into a hand-rolled fetch you make inside a runWith* middleware; the fontdue-js
+ * fetch/preload helpers pick these up automatically and don't need it.
+ */
+export declare function ambientHeaders(): Record<string, string>;
+/**
+ * Run `next` (your framework's render/loader chain) with the request's admin
+ * preview token in ambient scope, then return its Response. While active, every
+ * fontdue-js server fetch forwards the token (reveals unpublished fonts) with no
+ * per-call plumbing; when previewing, the response is forced out of any
+ * shared/CDN cache. Public requests (no preview cookie) pass through untouched
+ * and stay fully cacheable. For the visitor password-unlock token use
+ * runWithNodeAccess; for both, runWithFontdue.
+ */
+export declare function runWithPreview(request: Request, next: () => Response | Promise<Response>): Promise<Response>;
+/**
+ * Run `next` with the visitor's per-collection node-access token in ambient
+ * scope, then return its Response. The token is read from the first-party cookie
+ * the password form set; while active, every fontdue-js server fetch forwards it
+ * so a collection the visitor unlocked resolves for them. A request carrying an
+ * unlock is per-visitor, so its response is forced out of any shared/CDN cache —
+ * an unlocked render is never served to someone who hasn't unlocked. Requests
+ * with no node-access cookie pass through untouched and stay cacheable.
+ */
+export declare function runWithNodeAccess(request: Request, next: () => Response | Promise<Response>): Promise<Response>;
+/**
+ * The precomposed middleware most storefronts want: forwards the admin preview
+ * token AND the visitor's node-access token, each handled by its own
+ * single-responsibility middleware. Equivalent to nesting
+ * `runWithPreview(request, () => runWithNodeAccess(request, next))` — mount this
+ * in place of runWithPreview to get the password-unlock forwarding too.
+ */
+export declare function runWithFontdue(request: Request, next: () => Response | Promise<Response>): Promise<Response>;

package/dist/server/middleware.js

@@ -0,0 +1,144 @@
+// Request-scoped Fontdue context for non-RSC server frameworks (Astro, React
+// Router 7, TanStack Start). RSC apps (Next) don't use this — they drive the
+// per-render config through React.cache (see ../relay/serverConfig.ts).
+//
+// fontdue-js carries two kinds of request-scoped state to every server fetch:
+//
+//   - the admin *preview* token (reveals unpublished fonts), and
+//   - the visitor's per-collection *node-access* token (a collection they
+//     unlocked with a password).
+//
+// Both need the same plumbing: read a cookie, hold a header in ambient scope for
+// the whole render so every fontdue-js fetch/preload forwards it with no per-call
+// threading, and force the response out of any shared/CDN cache because it's now
+// per-visitor. This module provides that machinery once and exposes three
+// single-responsibility middlewares over it:
+//
+//   - runWithPreview     — forwards only the admin preview token.
+//   - runWithNodeAccess  — forwards only the visitor's node-access token.
+//   - runWithFontdue     — both, composed (runWithPreview ∘ runWithNodeAccess).
+//
+// Mount one of these in your framework's request middleware. A storefront that
+// wants both features mounts the precomposed runWithFontdue:
+//
+//   // Astro: src/middleware.ts
+//   export const onRequest = (ctx, next) => runWithFontdue(ctx.request, next);
+//
+//   // React Router 7 (root route, with future.v8_middleware):
+//   export const middleware = [({ request }, next) => runWithFontdue(request, next)];
+//
+// They compose because they share one ambient store and each merges its slice
+// onto whatever an outer middleware established — so nesting accumulates headers
+// rather than clobbering. Mount only the ones you need; the unused cookie is
+// simply never present.
+//
+// Requirement: AsyncLocalStorage must propagate from the install point into the
+// render. That holds for in-process middleware — Node (Netlify Functions, the
+// default SSR target), Deno (Netlify Edge), Bun. It does NOT hold when
+// middleware runs in a separate runtime from the render (e.g. Astro with
+// `edgeMiddleware: true`, where locals cross the boundary as a serialized
+// header); mount the middleware in-process on those setups.
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { readPreviewToken, previewAuthHeaders } from '../preview/index.js';
+import { nodeAccessHeadersFromCookie } from '../nodeAccess.js';
+import { registerAmbientConfigResolver } from '../relay/serverConfig.js';
+const ambientStore = new AsyncLocalStorage();
+
+// Feed the ambient headers into fontdue-js's server config resolution. Returns
+// undefined outside the context, so plain public requests are untouched.
+registerAmbientConfigResolver(() => {
+  const store = ambientStore.getStore();
+  return store ? {
+    headers: store.headers
+  } : undefined;
+});
+
+/** Whether the current async context is an admin preview. */
+export function isPreviewing() {
+  var _ambientStore$getStor;
+  return ((_ambientStore$getStor = ambientStore.getStore()) === null || _ambientStore$getStor === void 0 ? void 0 : _ambientStore$getStor.previewing) === true;
+}
+
+/**
+ * Request-scoped Fontdue headers for the current async context (admin preview
+ * and/or the visitor's node-access token), or {} when there are none. Spread
+ * into a hand-rolled fetch you make inside a runWith* middleware; the fontdue-js
+ * fetch/preload helpers pick these up automatically and don't need it.
+ */
+export function ambientHeaders() {
+  var _ambientStore$getStor2;
+  return ((_ambientStore$getStor2 = ambientStore.getStore()) === null || _ambientStore$getStor2 === void 0 ? void 0 : _ambientStore$getStor2.headers) ?? {};
+}
+const NO_STORE = 'private, no-store';
+
+// A per-visitor response (preview or an unlocked collection) must never be
+// stored in or served from a shared/CDN cache.
+function forceNoStore(response) {
+  response.headers.set('Cache-Control', NO_STORE);
+  response.headers.delete('Netlify-CDN-Cache-Control');
+  response.headers.delete('CDN-Cache-Control');
+  return response;
+}
+
+// Run `next` with `patch` merged onto any ambient context an outer middleware
+// already set, so runWithPreview ∘ runWithNodeAccess accumulate (headers union,
+// previewing OR'd) instead of the inner call clobbering the outer.
+function withAmbient(patch, next) {
+  const existing = ambientStore.getStore();
+  return Promise.resolve(ambientStore.run({
+    headers: {
+      ...(existing === null || existing === void 0 ? void 0 : existing.headers),
+      ...patch.headers
+    },
+    previewing: (existing === null || existing === void 0 ? void 0 : existing.previewing) === true || patch.previewing === true
+  }, next));
+}
+
+/**
+ * Run `next` (your framework's render/loader chain) with the request's admin
+ * preview token in ambient scope, then return its Response. While active, every
+ * fontdue-js server fetch forwards the token (reveals unpublished fonts) with no
+ * per-call plumbing; when previewing, the response is forced out of any
+ * shared/CDN cache. Public requests (no preview cookie) pass through untouched
+ * and stay fully cacheable. For the visitor password-unlock token use
+ * runWithNodeAccess; for both, runWithFontdue.
+ */
+export async function runWithPreview(request, next) {
+  const token = readPreviewToken(request.headers.get('cookie'));
+  if (!token) return next();
+  const response = await withAmbient({
+    headers: previewAuthHeaders(token),
+    previewing: true
+  }, next);
+  return forceNoStore(response);
+}
+
+/**
+ * Run `next` with the visitor's per-collection node-access token in ambient
+ * scope, then return its Response. The token is read from the first-party cookie
+ * the password form set; while active, every fontdue-js server fetch forwards it
+ * so a collection the visitor unlocked resolves for them. A request carrying an
+ * unlock is per-visitor, so its response is forced out of any shared/CDN cache —
+ * an unlocked render is never served to someone who hasn't unlocked. Requests
+ * with no node-access cookie pass through untouched and stay cacheable.
+ */
+export async function runWithNodeAccess(request, next) {
+  const headers = nodeAccessHeadersFromCookie(request.headers.get('cookie'));
+  if (Object.keys(headers).length === 0) return next();
+  const response = await withAmbient({
+    headers
+  }, next);
+  return forceNoStore(response);
+}
+
+/**
+ * The precomposed middleware most storefronts want: forwards the admin preview
+ * token AND the visitor's node-access token, each handled by its own
+ * single-responsibility middleware. Equivalent to nesting
+ * `runWithPreview(request, () => runWithNodeAccess(request, next))` — mount this
+ * in place of runWithPreview to get the password-unlock forwarding too.
+ */
+export async function runWithFontdue(request, next) {
+  return runWithPreview(request, () => runWithNodeAccess(request, next));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fontdue-js",
-  "version": "3.0.6",
+  "version": "3.2.0",
   "type": "module",
   "scripts": {
     "build": "npm run relay && run-p build-js build-css build-ts",
@@ -86,9 +86,11 @@
     "./preview": "./dist/preview/index.js",
     "./preview/server": "./dist/preview/server.js",
     "./server": "./dist/server/index.js",
+    "./server/middleware": "./dist/server/middleware.js",
     "./next": "./dist/next/index.js",
     "./next/config": "./dist/next/config.js",
     "./next/revalidate": "./dist/next/revalidate.js",
+    "./next/unlock": "./dist/next/unlock.js",
     "./next/image-loader": "./dist/next/image-loader.js",
     "./fontdue.css": "./dist/fontdue.css",
     "./BuyButton": {
@@ -101,6 +103,10 @@
       "default": "./dist/components/CharacterViewer/index.js"
     },
     "./CustomerLoginForm": "./dist/components/CustomerLoginForm/index.js",
+    "./FeatureTesters": {
+      "react-server": "./dist/components/FeatureTester/FeatureTesters.server.js",
+      "default": "./dist/components/FeatureTester/FeatureTesters.js"
+    },
     "./FontdueProvider": {
       "react-server": "./dist/components/FontdueProvider/index.server.js",
       "default": "./dist/components/FontdueProvider/index.js"
@@ -109,6 +115,7 @@
       "react-server": "./dist/components/NewsletterSignup/index.server.js",
       "default": "./dist/components/NewsletterSignup/index.js"
     },
+    "./NodePasswordForm": "./dist/components/NodePasswordForm/index.js",
     "./StoreModal": "./dist/components/StoreModal/index.js",
     "./TestFontsForm": {
       "react-server": "./dist/components/TestFontsForm/index.server.js",
@@ -128,4 +135,4 @@
     "./useFont": "./dist/components/useFont.js",
     "./useFontStyle": "./dist/components/useFont.js"
   }
-}
+}

package/types/next-headers.d.ts

@@ -2,7 +2,11 @@
 // installed (it's the host app's dependency; this package only ever runs the
 // import inside a Next.js server).
 declare module 'next/headers' {
-  export function draftMode(): Promise<{ isEnabled: boolean }>;
+  export function draftMode(): Promise<{
+    isEnabled: boolean;
+    enable(): void;
+    disable(): void;
+  }>;
   export function cookies(): Promise<{
     get(name: string): { value: string } | undefined;
   }>;