@crombolo/next-integration 0.0.0-stage → 0.38.1

package/dist/index.js

@@ -0,0 +1,205 @@
+/**
+ * A Next.js App Router front end for a crombolo site (story 208).
+ *
+ * `createCrombolo()` wraps the typed Delivery API client for server
+ * components: answers kept in Next's cache and tagged by the content they hold,
+ * drafts in Draft Mode, a member's own reads, route lookup as a `Result`, and
+ * Next's `Metadata` from a page's search and sharing details.
+ * docs/delivery-api.md, "A Next.js front end".
+ */
+import { Outcome, ok } from '@crombolo/common';
+import { createDeliveryClient, DeliveryError, memoryConditionalStore, } from '@crombolo/delivery-client';
+import { cookies, draftMode } from 'next/headers';
+import { forbidden, notFound, permanentRedirect, redirect, unauthorized } from 'next/navigation';
+import { PREVIEW_COOKIE, SESSION_COOKIE, sessionSecret, unseal, } from './session.js';
+export { assertSafeLocation, isOk, isOutcome, Ok, Outcome, ok, Result, } from '@crombolo/common';
+export { SITE_TAG, tagOf, tagsFor } from './cache.js';
+/** An address for this path that never answers a page, to ask the site for its not-found page. */
+const NOT_FOUND_PROBE = '/.crombolo/not-found';
+const etagCopies = memoryConditionalStore();
+export function createCrombolo(options) {
+    const base = {
+        baseUrl: options.url,
+        apiPath: options.apiPath,
+        apiKey: options.apiKey,
+        culture: options.culture,
+        startItem: options.startItem,
+    };
+    const uncached = (url, init) => fetch(url, { ...init, cache: 'no-store' });
+    const kept = createDeliveryClient({
+        ...base,
+        fetch: options.cache
+            ? async (url, init) => {
+                const answer = await options.cache.answer(url, Object.fromEntries(new Headers(init.headers)));
+                return new Response(answer.body || null, {
+                    status: answer.status,
+                    headers: answer.headers,
+                });
+            }
+            : uncached,
+        conditional: options.cache ? undefined : etagCopies,
+    });
+    const revalidated = createDeliveryClient({
+        ...base,
+        fetch: uncached,
+        conditional: etagCopies,
+    });
+    /** In Draft Mode, the editor's drafts and never a kept copy. */
+    const draftClient = async () => {
+        if (!(await draftMode()).isEnabled)
+            return undefined;
+        const token = (await cookies()).get(PREVIEW_COOKIE)?.value;
+        return createDeliveryClient({
+            ...base,
+            fetch: uncached,
+            preview: () => (token ? { token } : true),
+        });
+    };
+    const reads = (pick, fixed) => {
+        const call = (name) => async (...args) => {
+            const client = await pick();
+            return client[name](...args);
+        };
+        const page = async (path, request = {}) => {
+            const client = await pick();
+            try {
+                const answer = await client.route(path, {
+                    host: request.host ?? options.host,
+                    expand: request.expand,
+                    seo: true,
+                });
+                if (answer.kind === 'page')
+                    return ok(answer.item);
+                if (answer.kind === 'notFound')
+                    return Outcome.notFound();
+                switch (answer.statusCode) {
+                    case 301:
+                        return Outcome.movedPermanentlyTo(answer.location);
+                    case 303:
+                        return Outcome.seeOther(answer.location);
+                    case 307:
+                        return Outcome.redirect(answer.location);
+                    case 308:
+                        return Outcome.permanentRedirect(answer.location);
+                    default:
+                        return Outcome.foundAt(answer.location);
+                }
+            }
+            catch (error) {
+                if (error instanceof DeliveryError && error.status === 401)
+                    return Outcome.unauthorized();
+                if (error instanceof DeliveryError && error.status === 403)
+                    return Outcome.forbidden();
+                throw error;
+            }
+        };
+        return {
+            get client() {
+                return fixed ?? kept;
+            },
+            page,
+            async resolvePage(path, request) {
+                const result = await page(path, request);
+                if (result.ok)
+                    return result.value;
+                switch (result.status) {
+                    case 301:
+                    case 308:
+                        return permanentRedirect(result.location);
+                    case 302:
+                    case 303:
+                    case 307:
+                        return redirect(result.location);
+                    case 401:
+                        return unauthorized();
+                    case 403:
+                        return forbidden();
+                    default:
+                        return notFound();
+                }
+            },
+            async notFoundPage(request = {}) {
+                const answer = await (await pick()).route(NOT_FOUND_PROBE, {
+                    host: request.host ?? options.host,
+                    seo: true,
+                });
+                return answer.kind === 'notFound' ? (answer.item ?? undefined) : undefined;
+            },
+            item: call('item'),
+            items: call('items'),
+            content: call('content'),
+            mediaItem: call('mediaItem'),
+            media: call('media'),
+            menu: call('menu'),
+            search: call('search'),
+            form: call('form'),
+            sitemap: call('sitemap'),
+        };
+    };
+    const tagged = options.revalidate === 'etag' ? revalidated : kept;
+    const crombolo = reads(async () => (await draftClient()) ?? tagged);
+    return {
+        ...crombolo,
+        options,
+        fresh: reads(async () => (await draftClient()) ?? revalidated, revalidated),
+        async member() {
+            const secret = sessionSecret(options.secret ?? process.env.CROMBOLO_NEXT_SECRET);
+            const session = await unseal((await cookies()).get(SESSION_COOKIE)?.value, secret);
+            // An expired token is refreshed by the middleware, which may set cookies; a page may not.
+            if (!session || session.expiresAt <= Date.now())
+                return undefined;
+            const preview = (await draftMode()).isEnabled
+                ? (await cookies()).get(PREVIEW_COOKIE)?.value
+                : undefined;
+            const client = createDeliveryClient({
+                ...base,
+                fetch: uncached,
+                memberToken: () => session.accessToken,
+                ...(preview ? { preview: () => ({ token: preview }) } : {}),
+            });
+            return { ...reads(async () => client, client), session };
+        },
+        metadata: (item, extra) => metadataOf(item, extra),
+        revalidate(keys) {
+            options.cache?.revalidate(keys);
+        },
+    };
+}
+/** Next's `Metadata` from a page's `seo` details; `extra` wins field by field. Pure. */
+export function metadataOf(item, extra = {}) {
+    const seo = item?.seo;
+    if (!seo)
+        return { ...(item ? { title: item.name } : {}), ...extra };
+    const languages = Object.fromEntries(seo.alternates.map((a) => [a.culture, a.url]));
+    if (seo.xDefault)
+        languages['x-default'] = seo.xDefault;
+    const image = seo.image
+        ? [
+            {
+                url: seo.image.url,
+                ...(seo.image.width ? { width: seo.image.width } : {}),
+                ...(seo.image.height ? { height: seo.image.height } : {}),
+            },
+        ]
+        : undefined;
+    return {
+        title: { absolute: seo.title },
+        ...(seo.description ? { description: seo.description } : {}),
+        alternates: {
+            ...(seo.canonical ? { canonical: seo.canonical } : {}),
+            ...(Object.keys(languages).length > 0 ? { languages } : {}),
+        },
+        ...(seo.robots?.includes('noindex') ? { robots: { index: false } } : {}),
+        openGraph: {
+            title: seo.title,
+            ...(seo.description ? { description: seo.description } : {}),
+            ...(seo.canonical ? { url: seo.canonical } : {}),
+            siteName: seo.siteName,
+            type: 'website',
+            ...(image ? { images: image } : {}),
+        },
+        twitter: { card: image ? 'summary_large_image' : 'summary' },
+        ...extra,
+    };
+}
+export { decodeEntities, isExpanded, walkRichText } from '@crombolo/delivery-client';

package/dist/middleware.d.ts

@@ -0,0 +1,27 @@
+import type { Crombolo } from './index.ts';
+/** A fresh session's cookie for this request, or undefined when nothing needs doing. */
+export declare function refreshedSession(crombolo: Crombolo, request: Request): Promise<{
+    value: string;
+    setCookie: string;
+} | {
+    value: '';
+    setCookie: string;
+} | undefined>;
+export interface MiddlewareOptions {
+    /**
+     * Look each page address up before it renders, so a redirect keeps its
+     * status, a miss is a real 404 and a members-only page sends a visitor to
+     * sign in. Default true.
+     */
+    routes?: boolean;
+    /** A route of the app's that calls `notFound()`, rewritten to for a miss. */
+    notFoundPath?: string;
+    /** Where a visitor is sent to sign in, with `returnTo`. */
+    signInPath?: string;
+}
+/**
+ * The app's middleware (`proxy.ts` in Next.js 16): refreshes the member's
+ * session, then answers redirects, misses and members-only pages before a page
+ * renders.
+ */
+export declare function cromboloMiddleware(crombolo: Crombolo, options?: MiddlewareOptions): (request: Request) => Promise<Response>;

package/dist/middleware.js

@@ -0,0 +1,138 @@
+/**
+ * What runs before a page renders (story 208). A page cannot set cookies, so a
+ * member's session is refreshed here: an expired access token is swapped for a
+ * new one with the refresh token, and the page sees the new session at once.
+ * And a page cannot change its status once Partial Prerendering has sent it, so
+ * the CMS's redirects, misses and members-only refusals are answered here too.
+ *
+ * ```ts
+ * // web/middleware.ts (proxy.ts in Next.js 16)
+ * export default cromboloMiddleware(crombolo)
+ * ```
+ */
+import { createDeliveryClient, DeliveryError, memoryConditionalStore, } from '@crombolo/delivery-client';
+import { NextResponse } from 'next/server';
+import { requestTokens } from './route-handlers.js';
+import { cookie, PREVIEW_COOKIE, readCookie, SESSION_COOKIE, seal, sessionSecret, unseal, } from './session.js';
+/** Refresh this long before the access token runs out, so a render never meets an expired one. */
+const EARLY_MS = 30_000;
+/** A fresh session's cookie for this request, or undefined when nothing needs doing. */
+export async function refreshedSession(crombolo, request) {
+    const secret = sessionSecret(crombolo.options.secret ?? process.env.CROMBOLO_NEXT_SECRET);
+    const sealed = readCookie(request.headers.get('cookie'), SESSION_COOKIE);
+    if (!sealed)
+        return undefined;
+    const session = await unseal(sealed, secret);
+    const secure = new URL(request.url).protocol === 'https:';
+    const forget = {
+        value: '',
+        setCookie: cookie(SESSION_COOKIE, '', { secure, maxAge: 0 }),
+    };
+    if (!session)
+        return forget;
+    if (session.expiresAt - EARLY_MS > Date.now())
+        return undefined;
+    if (!session.refreshToken)
+        return forget;
+    const next = await requestTokens(crombolo, {
+        grant_type: 'refresh_token',
+        refresh_token: session.refreshToken,
+    });
+    if (!next)
+        return forget;
+    const value = await seal(next, secret);
+    return { value, setCookie: cookie(SESSION_COOKIE, value, { secure, maxAge: 60 * 60 * 24 * 30 }) };
+}
+/** Copies kept for the route lookups, revalidated with `If-None-Match` on every request. */
+const routeCopies = memoryConditionalStore();
+/** Whether a request is a page navigation the CMS answers, rather than an asset or an API call. */
+function isPage(request, path) {
+    if (request.method !== 'GET' && request.method !== 'HEAD')
+        return false;
+    if (path.startsWith('/api/') || path.startsWith('/_next/') || path.startsWith('/media/'))
+        return false;
+    return !/\.[a-z0-9]+$/i.test(path);
+}
+/**
+ * What the CMS answers at this address, before the page renders. With Partial
+ * Prerendering a page's status is sent before its content streams, so a page
+ * cannot turn itself into a redirect or a 404 any more; this can.
+ */
+async function routeAnswer(crombolo, request, options, token) {
+    const url = new URL(request.url);
+    if (!isPage(request, url.pathname) || readCookie(request.headers.get('cookie'), PREVIEW_COOKIE))
+        return undefined;
+    const client = createDeliveryClient({
+        baseUrl: crombolo.options.url,
+        apiPath: crombolo.options.apiPath,
+        apiKey: crombolo.options.apiKey,
+        culture: crombolo.options.culture,
+        startItem: crombolo.options.startItem,
+        conditional: routeCopies,
+        ...(token ? { memberToken: () => token } : {}),
+        fetch: (input, init) => fetch(input, { ...init, cache: 'no-store' }),
+    });
+    try {
+        const answer = await client.route(url.pathname, { host: crombolo.options.host });
+        if (answer.kind === 'page')
+            return undefined;
+        if (answer.kind === 'redirect') {
+            const target = new URL(answer.location, url);
+            if (!target.search)
+                target.search = url.search;
+            return NextResponse.redirect(target, answer.statusCode);
+        }
+        return NextResponse.rewrite(new URL(options.notFoundPath ?? '/crombolo/not-found', url), {
+            status: 404,
+        });
+    }
+    catch (error) {
+        if (error instanceof DeliveryError && error.status === 401) {
+            const signIn = new URL(options.signInPath ?? '/api/crombolo/sign-in', url);
+            signIn.searchParams.set('returnTo', `${url.pathname}${url.search}`);
+            return NextResponse.redirect(signIn, 307);
+        }
+        // A refusal for this member, or the CMS unreachable: the page has its say.
+        return undefined;
+    }
+}
+/**
+ * The app's middleware (`proxy.ts` in Next.js 16): refreshes the member's
+ * session, then answers redirects, misses and members-only pages before a page
+ * renders.
+ */
+export function cromboloMiddleware(crombolo, options = {}) {
+    return async (request) => {
+        const refreshed = await refreshedSession(crombolo, request).catch(() => undefined);
+        let token;
+        if (options.routes !== false) {
+            const secret = crombolo.options.secret ?? process.env.CROMBOLO_NEXT_SECRET;
+            const sealed = refreshed
+                ? refreshed.value
+                : readCookie(request.headers.get('cookie'), SESSION_COOKIE);
+            const session = secret && secret.length >= 32 && sealed
+                ? await unseal(sealed, secret)
+                : undefined;
+            token = session && session.expiresAt > Date.now() ? session.accessToken : undefined;
+            const answered = await routeAnswer(crombolo, request, options, token);
+            if (answered) {
+                if (refreshed)
+                    answered.headers.append('set-cookie', refreshed.setCookie);
+                return answered;
+            }
+        }
+        if (!refreshed)
+            return NextResponse.next();
+        const headers = new Headers(request.headers);
+        const others = (request.headers.get('cookie') ?? '')
+            .split(';')
+            .map((part) => part.trim())
+            .filter((part) => part && !part.startsWith(`${SESSION_COOKIE}=`));
+        if (refreshed.value)
+            others.push(`${SESSION_COOKIE}=${encodeURIComponent(refreshed.value)}`);
+        headers.set('cookie', others.join('; '));
+        const response = NextResponse.next({ request: { headers } });
+        response.headers.append('set-cookie', refreshed.setCookie);
+        return response;
+    };
+}

package/dist/route-handlers.d.ts

@@ -0,0 +1,52 @@
+import type { Crombolo } from './index.ts';
+import { type MemberSession } from './session.ts';
+/** Where member sign-in lives on the CMS. */
+export declare const MEMBER_SECURITY_PATH = "/crombolo/delivery/api/v1/security/member";
+/** A path on this app, or `/`: never another site, so a link cannot send anyone away. */
+export declare function localPath(value: string | null | undefined): string;
+/**
+ * `GET ?path=…&token=…`, what the Preview button opens: the token is checked
+ * against the CMS, Draft Mode is turned on, and the editor lands on the page.
+ */
+export declare function previewHandler(crombolo: Crombolo): (request: Request) => Promise<Response>;
+/** `GET ?path=…`: leaves Draft Mode and forgets the preview token. */
+export declare function exitPreviewHandler(): (request: Request) => Promise<Response>;
+/**
+ * `POST` from a CMS webhook with `payload = "crombolo"`: checks the shared
+ * secret header and clears what holds the item and each of its ancestors.
+ */
+export declare function revalidateHandler(crombolo: Crombolo, options?: {
+    secret?: string;
+    header?: string;
+}): (request: Request) => Promise<Response>;
+/** Asks the CMS's token endpoint, by authorization code or refresh token. */
+export declare function requestTokens(crombolo: Crombolo, form: Record<string, string>): Promise<MemberSession | undefined>;
+export interface MemberHandlerOptions {
+    /** This app's callback address, registered in the CMS's `deliveryApi.memberAuthorization`. */
+    redirectUri: string;
+    /** Where the CMS sends the member after signing out; registered there too. */
+    postLogoutRedirectUri: string;
+}
+/** Sign-in, its callback, and sign-out, for a member of the site. */
+export declare function memberHandlers(crombolo: Crombolo, options: MemberHandlerOptions): {
+    /** `GET ?returnTo=/path`: off to the CMS to sign in. */
+    signIn(request: Request): Promise<Response>;
+    /** `GET ?code=…&state=…`: the tokens, sealed into the session cookie. */
+    callback(request: Request): Promise<Response>;
+    /** `GET`: ends the member's tokens and their CMS session, then comes back. */
+    signOut(request: Request): Promise<Response>;
+};
+/**
+ * `GET /media/…`: the CMS's media file, sent with the member's token when one
+ * is signed in, so protected media reaches who may read it. Mount it at
+ * `web/app/media/[...path]/route.ts`.
+ */
+export declare function mediaHandler(crombolo: Crombolo): (request: Request) => Promise<Response>;
+/** Where the CMS streams its changes in development. */
+export declare const CMS_LIVE_EVENTS_PATH = "/crombolo/dev/events";
+/**
+ * `GET` for `<CromboloLiveReload />` in development: the CMS's change stream,
+ * and a `revalidated` event once this app has cleared what a webhook named, so
+ * a refresh after it shows the new content. 404 outside development.
+ */
+export declare function liveReloadHandler(crombolo: Crombolo): (request: Request) => Promise<Response>;