@saypsst/next 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
+# @saypsst/next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Drop-in route modules that serve [PSST](https://saypsst.com) pages on your own domain, inside your Next.js App Router app (Next 15 or 16, any host). PSST publishes, updates and withdraws pages under a path prefix it owns (default `/resources`) without another deploy on your side.
+
+- Server components and route handlers only: no client component, no client JavaScript added.
+- Full text in the HTML for every visitor and crawler, with canonical, Open Graph, JSON-LD and a `psst-version` meta.
+- Time-based ISR (300 s). If PSST is down, your site keeps serving the last good render.
+- No secrets. The only value you configure is your public site id.
+- Runtime dependency: `zod` (pinned). `@psst/content`, the PSST content contract, is bundled into `dist/`. No install scripts.
+
+`npx saypsst init` writes all of this for you. This README is the reference for what it writes.
+
+## Files you add
+
+Paths assume `app/` at the project root and the default prefix `/resources`. With `src/app/`, put `psst.config.ts` in `src/` (the relative imports stay the same). With another prefix, replace `resources` in the folder names and add one `../` per extra segment.
+
+> Two Next.js rules shape these files. Route segment config (`revalidate`, `dynamicParams`) must be a literal in the route file, because Next reads it statically: it cannot be re-exported from a package. And a folder whose name starts with `_` is private in the App Router, so the URL segment `/_psst` needs the folder name `%5Fpsst`.
+
+### `psst.config.ts`
+
+```ts
+import { definePsst } from "@saypsst/next";
+
+export default definePsst({
+  site: "site_xxxxxxxxxxxxxxxx", // public site id from the PSST dashboard
+  domain: "example.com", // production host, no scheme
+  siteName: "Example",
+  prefix: "/resources",
+  rootPaths: [], // add "/about" and/or "/llms.txt" only when the dashboard claimed them
+});
+```
+
+Optional keys: `edge` (defaults to `https://edge.saypsst.com`; `http:` is accepted only on localhost) and `shell: { nav: [{ label, href }], footer }` for the built-in header/footer. `definePsst` validates everything and throws on a bad value, so a typo fails the build instead of serving broken pages.
+
+### `app/(psst)/resources/[...slug]/page.tsx`
+
+```tsx
+import { psstPage } from "@saypsst/next/page";
+import psst from "../../../../psst.config";
+
+const page = psstPage(psst);
+
+export const revalidate = 300;
+export const dynamicParams = true;
+export const generateStaticParams = page.generateStaticParams;
+export const generateMetadata = page.generateMetadata;
+export default page.default;
+```
+
+To get your site's header and footer (needed when your root layout renders none), pass a `Shell`. It receives the PSST `<main>` element as `children`; do not wrap it in another `<main>`:
+
+```tsx
+import type { PsstShellProps } from "@saypsst/next/page";
+import { SiteHeader, SiteFooter } from "@/components/site";
+
+function Shell({ children }: PsstShellProps) {
+  return (
+    <>
+      <SiteHeader />
+      {children}
+      <SiteFooter />
+    </>
+  );
+}
+
+const page = psstPage(psst, { Shell });
+```
+
+### `app/(psst)/resources/sitemap.xml/route.ts`
+
+```ts
+import { psstSitemap } from "@saypsst/next/sitemap";
+import psst from "../../../../psst.config";
+
+export const revalidate = 300;
+export const GET = psstSitemap(psst);
+```
+
+### `app/(psst)/resources/%5Fpsst/style.css/route.ts`
+
+```ts
+import { psstStyle } from "@saypsst/next/style";
+import psst from "../../../../../psst.config";
+
+export const revalidate = 300;
+export const GET = psstStyle(psst);
+```
+
+### `app/(psst)/resources/%5Fpsst/verify/route.ts`
+
+```ts
+import { psstVerify } from "@saypsst/next/verify";
+import psst from "../../../../../psst.config";
+
+export const revalidate = 300;
+export const GET = psstVerify(psst);
+```
+
+### `proxy.ts` (Next 16; `middleware.ts` on Next 15)
+
+New file:
+
+```ts
+import { withPsst } from "@saypsst/next/proxy";
+import psst from "./psst.config";
+
+export const proxy = withPsst(psst);
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+```
+
+If you already have a proxy, wrap it and keep your own matcher (make sure it also matches the PSST prefix):
+
+```ts
+export const proxy = withPsst(psst, yourProxy);
+```
+
+Then reference the PSST sitemap from `robots.txt` (`Sitemap: https://example.com/resources/sitemap.xml`) or from `app/robots.ts`.
+
+### Only when the dashboard claimed a root path
+
+`app/about/page.tsx` (add `"/about"` to `rootPaths`):
+
+```tsx
+import { psstPage } from "@saypsst/next/page";
+import psst from "../../psst.config";
+
+const page = psstPage(psst, { path: "/about" });
+
+export const revalidate = 300;
+export const generateMetadata = page.generateMetadata;
+export default page.default;
+```
+
+`app/llms.txt/route.ts` (add `"/llms.txt"` to `rootPaths`):
+
+```ts
+import { psstLlms } from "@saypsst/next/llms";
+import psst from "../../psst.config";
+
+export const revalidate = 300;
+export const GET = psstLlms(psst);
+```
+
+Do not edit these files by hand beyond the `Shell`; PSST content is never added locally.
+
+## Exports
+
+| Import | Export | What it is |
+| --- | --- | --- |
+| `@saypsst/next` | `definePsst(input)` | Validates and freezes the config. Throws `PsstConfigError`. |
+| | `PsstConfig`, `PsstConfigInput`, `PsstConfigError`, `PSST_REVALIDATE` (300), `DEFAULT_EDGE`, `PSST_NEXT_VERSION` | Types and constants. |
+| `@saypsst/next/page` | `psstPage(config, { Shell?, path? })` | Returns `{ default, generateMetadata, generateStaticParams }` for the page file. |
+| | `PsstShellProps`, `PsstPageOptions`, `PsstPageProps`, `PsstPageModule`, `PsstIntegrityError`, `PSST_REVALIDATE` | |
+| `@saypsst/next/sitemap` | `psstSitemap(config)` | `GET` handler: XML sitemap of the published PSST pages. |
+| `@saypsst/next/style` | `psstStyle(config)` | `GET` handler: the PSST stylesheet, same-origin, `text/css`. |
+| `@saypsst/next/verify` | `psstVerify(config)` | `GET` handler: the domain-proof text PSST checks. |
+| `@saypsst/next/llms` | `psstLlms(config)` | `GET` handler: `/llms.txt`. Throws unless `/llms.txt` is in `rootPaths`. |
+| `@saypsst/next/proxy` | `withPsst(config, proxy?)`, `PsstProxy` | Wraps your proxy: AI-crawler / AI-referral hits, 410 for withdrawn paths. |
+
+## What each module does
+
+**Page.** `generateMetadata` and the page fetch `GET {edge}/v1/sites/{site}/pages?path=…` (one request per render; 8 s timeout), validate the response and the document against the content contract (images only from your domain or `edge.saypsst.com`), and check the document's sha256 against the version hash PSST approved. The body has the same structure as PSST's static renderer: header, `main > article.psst-article` (h1, lede, updated date, blocks, sources), footer, plus one JSON-LD script (escaped; the only script). Metadata replaces your layout's defaults: absolute title, description, canonical `https://{domain}{path}`, Open Graph, Twitter, `robots: index, follow`, and `<meta name="psst-version" content="{12-char hash}">`. `generateStaticParams` prerenders the published pages from the manifest at build, and returns `[]` if PSST is unreachable.
+
+**Sitemap** renders the manifest's published HTML pages (withdrawn paths are already out). **Style, verify, llms** copy the files PSST's edge renders (`GET {edge}/s/{site}{path}`), check the media type and size, and serve them same-origin with `nosniff`.
+
+**Proxy.** On every matched request it classifies the `User-Agent` (a claim, not proof) and the `Referer` host. Known AI crawlers and visitors arriving from ChatGPT, Perplexity, Gemini, Copilot or Claude produce one `POST {edge}/v1/hits` with the path and the classes only: no IP, no cookie, no query string, no UA string. The post is not awaited (`event.waitUntil`, 300 ms abort) and errors are swallowed. Requests with `X-Psst-Doctor: 1`, prefetches, RSC navigations, `/_next/*` and static assets are skipped. Then your proxy runs unchanged and its result is returned as is.
+
+## Caching and failure behaviour (Next 16 mechanisms)
+
+Verified against the Next 16.4 docs (`incremental-static-regeneration`, `caching-without-cache-components`, `route-segment-config`, `route`, `unstable_rethrow`, `proxy`) and source (`build/templates/app-page-runtime.js`, `app-route.js`, `server/lib/patch-fetch.js`).
+
+| Requirement | Mechanism used |
+| --- | --- |
+| Time-based ISR, 300 s | Route segment config `export const revalidate = 300` written as a literal in every route file (page and the four route handlers), plus `dynamicParams = true` on the catch-all. Edge fetches set no `cache` option, so they never enter the Data Cache (only status-200 responses would) and the ISR entry is the one cache layer; using no Request-time API keeps the routes static. Pages missing from `generateStaticParams` render on first request and are then cached the same way. |
+| Keep the last good render on fetch failure | The page and handlers **throw** (`PsstUnavailableError`, `PsstIntegrityError`) on a network error, timeout, non-200/404/410 answer, invalid JSON, contract failure or hash mismatch. Next's response cache keeps serving the previous entry when a background regeneration throws, and retries on the next request. Nothing is caught that Next needs: `notFound()` is called outside any `try`, so `unstable_rethrow` is not needed. |
+| Never-rendered page while PSST is down | **A page cannot set a 503 in the App Router** (only `notFound()` 404, redirects, and the experimental 401/403). The closest correct mechanism: the thrown error makes Next answer **500 with `Cache-Control: private, no-cache, no-store`** and a `noindex` robots meta, and the failure is never persisted as ISR output, so no cached 404 and no cached error; the next request retries. There is no `Retry-After` on this response. |
+| PSST down during `next build` | Your build never fails because of PSST. `generateStaticParams` returns `[]` (the pages render on first request). A fixed-path page (`/about`) that cannot fetch at build calls `connection()` (`next/server`), so Next renders it at request time for that deployment. Route handlers (`process.env.NEXT_PHASE === "phase-production-build"`) return **503, `Retry-After: 300`, `Cache-Control: no-store`**; Next never stores a build-time route response with status ≥ 400 other than 404 (it sets `revalidate: 0`), so those routes are also rendered at request time for that deployment. In that degraded mode every request asks the edge: it answers normally once PSST is back (successful handler responses carry `Cache-Control: public, max-age=0, s-maxage=300, stale-while-revalidate=86400`, so a CDN still caches them), and answers 500 uncached while PSST is down. The next deploy restores full ISR. At runtime the handlers never return an error response: they throw, as above, so a good response is never replaced. |
+| Not found / withdrawn | Edge 404 or 410 → `notFound()` (404, cached for one ISR period). A page cannot answer 410, so `withPsst()` answers **410** for paths in the manifest's `withdrawn` list. It keeps that list in memory per instance and refreshes it in the background every 300 s, so no request waits on PSST; until the first refresh completes, a withdrawn path answers 404. The sitemap drops withdrawn paths. |
+
+Cache Components (`cacheComponents: true`) removes the `revalidate` and `dynamicParams` segment configs, so these route files do not build there. Such an app sets `serveFromEdge: true` in `psst.config.ts` and adds only `proxy.ts`: `withPsst()` rewrites PSST paths to the edge, which renders them with its own header and footer (not your layout), answers 410 for withdrawn paths and counts crawler hits itself. `npx saypsst init` does this when it detects the flag.
+
+Self-hosted with several instances (for example behind CloudFront): the default ISR cache is per instance. PSST content then refreshes per instance within 300 s, which is correct but uneven; a shared cache handler fixes that.
+
+## Security notes
+
+- Every text field is escaped by React; links are `https:` or same-site paths; images only from your domain or `edge.saypsst.com`; the document is re-validated before rendering, and its hash must match the approved version.
+- JSON-LD is serialized with `<`, `>`, `&`, U+2028 and U+2029 escaped. It is the only script, and it is a data block, so it fits strict CSPs.
+- Edge requests use `redirect: "error"`, size caps (2 MB JSON, 256 KB CSS, 1 KB proof, 512 KB llms.txt), and a `psst-next/<version>` user agent.

package/dist/chunk-2NMIB353.js

@@ -0,0 +1,65 @@
+import { domainSchema, publicIdSchema, isSafeHref, prefixSchema } from './chunk-X3GT7AOS.js';
+import { z } from 'zod';
+
+var PSST_REVALIDATE = 300;
+var DEFAULT_EDGE = "https://edge.saypsst.com";
+var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function isEdgeOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") return false;
+  if (url.pathname !== "/" && url.pathname !== "") return false;
+  if (url.protocol === "https:") return true;
+  return url.protocol === "http:" && LOCAL_HOSTS.has(url.hostname);
+}
+var configSchema = z.strictObject({
+  /** Public site id from the psst dashboard (`site_` + 16 characters). Not a secret. */
+  site: publicIdSchema,
+  /** Bare production host, e.g. `example.com`. Used for canonical URLs and the image allowlist. */
+  domain: domainSchema,
+  /** Brand name shown in JSON-LD and Open Graph. */
+  siteName: z.string().min(1).max(120),
+  /** Path prefix psst owns on the site. */
+  prefix: prefixSchema.default("/resources"),
+  /** Root paths psst serves outside the prefix (only what the dashboard claimed). */
+  rootPaths: z.array(z.enum(["/about", "/llms.txt"])).max(2).default([]),
+  /** psst edge origin. Override only for local development. */
+  edge: z.string().refine(isEdgeOrigin, "edge must be an https origin (http only on localhost)").default(DEFAULT_EDGE),
+  /**
+   * Serve psst paths from the edge through `withPsst()` instead of route files, for apps with Cache Components, where
+   * the route files do not build. Pages use the edge's own header and footer, not the app's layout.
+   */
+  serveFromEdge: z.boolean().default(false),
+  /** Header/footer used when the page module gets no `Shell` component. Same shape as the static renderer's shell. */
+  shell: z.strictObject({
+    nav: z.array(
+      z.strictObject({
+        label: z.string().min(1).max(60),
+        href: z.string().refine(isSafeHref, "nav href must be https: or a same-site path")
+      })
+    ).max(12).optional(),
+    footer: z.string().min(1).max(300).optional()
+  }).optional()
+});
+var PsstConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PsstConfigError";
+  }
+};
+function definePsst(input) {
+  const parsed = configSchema.safeParse(input);
+  if (!parsed.success) {
+    throw new PsstConfigError(
+      `invalid PSST config: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`
+    );
+  }
+  const c = parsed.data;
+  return Object.freeze({ ...c, edge: c.edge.replace(/\/+$/, "") });
+}
+
+export { DEFAULT_EDGE, PSST_REVALIDATE, PsstConfigError, definePsst };

package/dist/chunk-ELYUDQHH.js

@@ -0,0 +1,42 @@
+import { PsstUnavailableError } from './chunk-ZELUPPQB.js';
+
+// src/route.ts
+var RETRY_AFTER_SECONDS = 300;
+function isBuildPhase() {
+  return process.env["NEXT_PHASE"] === "phase-production-build";
+}
+function psstRoute(handler) {
+  return async () => {
+    try {
+      return await handler();
+    } catch (err) {
+      if (err instanceof PsstUnavailableError && isBuildPhase()) {
+        console.warn(`${err.message}; serving 503 until the next regeneration`);
+        return unavailable();
+      }
+      throw err;
+    }
+  };
+}
+function unavailable() {
+  return new Response("PSST is temporarily unavailable\n", {
+    status: 503,
+    headers: {
+      "content-type": "text/plain; charset=utf-8",
+      "retry-after": String(RETRY_AFTER_SECONDS),
+      "cache-control": "no-store"
+    }
+  });
+}
+function notFoundResponse() {
+  return new Response("Not found\n", { status: 404, headers: { "content-type": "text/plain; charset=utf-8" } });
+}
+var SUCCESS_CACHE_CONTROL = "public, max-age=0, s-maxage=300, stale-while-revalidate=86400";
+function textResponse(body, contentType) {
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": contentType, "x-content-type-options": "nosniff", "cache-control": SUCCESS_CACHE_CONTROL }
+  });
+}
+
+export { isBuildPhase, notFoundResponse, psstRoute, textResponse };

package/dist/chunk-QE3BBW25.js

@@ -0,0 +1,18 @@
+import { psstRoute, notFoundResponse, textResponse } from './chunk-ELYUDQHH.js';
+import { fetchEdgeFile, PsstUnavailableError, readCapped } from './chunk-ZELUPPQB.js';
+
+// src/edge-file.ts
+function edgeFileRoute(config, spec) {
+  return psstRoute(async () => {
+    const res = await fetchEdgeFile(config, spec.path, spec.type);
+    if (res.status === 404 || res.status === 410) return notFoundResponse();
+    if (res.status !== 200) throw new PsstUnavailableError(`edge answered ${res.status} for ${spec.path}`);
+    const type = (res.headers.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase();
+    if (type !== spec.type) throw new PsstUnavailableError(`edge answered ${type || "no type"} for ${spec.path}`);
+    const body = await readCapped(res, spec.maxBytes);
+    if (spec.accept && !spec.accept(body)) throw new PsstUnavailableError(`edge body for ${spec.path} failed its check`);
+    return textResponse(body, `${spec.type}; charset=utf-8`);
+  });
+}
+
+export { edgeFileRoute };