@tdacorp/hyle-sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TDACorp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# @tdacorp/hyle-sdk
 
-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.
+Mount hyle content in a site with one route. The SDK calls hyle's resolve endpoint (`GET /cp1/read/resolve`, ADR 0012), renders the page, follows redirects, answers 404, emits metadata and revalidates when hyle publishes.
+
+```bash
+pnpm add @tdacorp/hyle-sdk
+```
+
+MIT licensed. Node 22.12 or later. Semver from 0.1.0 (see `CHANGELOG.md`); until 1.0 a minor bump may change the API.
+
+## Quickstart (Next.js 16, React 19)
+
+Environment (server-side only, never `NEXT_PUBLIC_`):
+
+```
+HYLE_TARGET_BASE_URL=https://hyle.tdacorp.in
+HYLE_TARGET_TOKEN=hyle_tr_...        # this workspace's target credential
+HYLE_WORKSPACE_ID=<workspace uuid>
+HYLE_WEBHOOK_SECRET=<signing secret>
+```
+
+`app/layout.tsx`: `import "@tdacorp/hyle-sdk/styles.css";`
+
+`app/learn/[[...hyle]]/page.tsx`:
+
+```tsx
+import { hylePage, hyleMetadata, type HyleNextOptions } from "@tdacorp/hyle-sdk/next";
+
+const options: HyleNextOptions = {
+  baseUrl: process.env.HYLE_TARGET_BASE_URL!,
+  token: process.env.HYLE_TARGET_TOKEN!,
+  workspaceId: process.env.HYLE_WORKSPACE_ID!,
+  basePath: "/learn", // must equal the workspace's site path prefix in hyle
+};
+export default hylePage(options);
+export const generateMetadata = hyleMetadata(options);
+```
+
+`app/api/hyle/revalidate/route.ts`:
+
+```ts
+import { createRevalidateRoute } from "@tdacorp/hyle-sdk/next";
+export const { POST } = createRevalidateRoute({ workspaceId: process.env.HYLE_WORKSPACE_ID, secrets: [process.env.HYLE_WEBHOOK_SECRET] });
+```
+
+Register that URL as the workspace's webhook endpoint in hyle. Set `metadataBase` in your root layout so canonical and hreflang URLs are absolute.
+
+## Entry points
+
+| Import | Contents | Needs |
+|---|---|---|
+| `@tdacorp/hyle-sdk` | `createHyleClient` (typed `resolve`), `listPublicationPaths`, `Cp1ClientError`, `verifyHyleSignature`, `parseSignatureHeader`, `isValidCacheTag`, `DeliveryDedupe`, `createRevalidationCallbackRoute`, the result types | nothing (no framework) |
+| `@tdacorp/hyle-sdk/react` | `ArticlePage`, `ListPage`, `DocsPage`, `NotFound`, `Redirecting`, `Unavailable`, `HastContent`, `TrustedServerHtml`, `sanitizeHast` | react >= 19 |
+| `@tdacorp/hyle-sdk/next` | `hylePage`, `hyleMetadata`, `hyleSitemap`, `createRevalidateRoute`, `fetchResolver`, `workspaceTags` | next >= 16 |
+| `@tdacorp/hyle-sdk/next/use-cache` | `cachedResolver` | next >= 16 with `cacheComponents: true` |
+| `@tdacorp/hyle-sdk/styles.css` | the stylesheet | |
+
+The only runtime dependency is `hast-util-to-jsx-runtime` (MIT, unified collective, the library behind react-markdown): it maps hast nodes and properties to React elements correctly, which is more than a short hand-rolled function would get right. Everything else is hand-written.
+
+## Locale
+
+hyle serves the workspace's default locale unless you pass one. A multilingual site must pass `locale`:
+
+```tsx
+// app/[locale]/learn/[[...hyle]]/page.tsx
+const options = { ..., locale: (params) => String(params.locale), localePrefix: (l) => `/${l}` };
+```
+
+hyle's paths and redirect targets never contain your locale prefix. `localePrefix(locale)` returns the prefix your router uses (`"/fr"`, or `""` for a default locale served unprefixed); the SDK puts it back on redirect targets, canonical URLs, hreflang alternates and in-page links. When the requested locale has a published translation at another path, hyle answers a 307 and the SDK issues a temporary `redirect()`; a 301 (retired slug, non-canonical spelling) becomes `permanentRedirect()`. When no translation exists the page is shown in the default locale with a "not translated yet" notice (the response's `fallback` field).
+
+## Redirect safety
+
+A redirect target is followed only if it is a same-origin path: one leading `/`, no `//`, no backslash, no control character or whitespace. It is checked on hyle's `to` and again on the final target after `localePrefix`; anything else raises a `Cp1ClientError` (`INVALID_RESPONSE`) instead of redirecting. A `locale` that is not a plain language tag (`en`, `pt-BR`) is treated as unset. A target equal to the current URL is treated as not found, so it cannot loop.
+
+## Caching (read this before shipping)
+
+hyle tags every response with `cache.tags` and, on publish, calls your revalidate route with the tags to purge. Next's fetch cache needs the tags when the request is made, but the response (which carries the tags) does not exist yet. The SDK offers two strategies. Both were run against a real `next build` and `next start` (Next 16.3.4) with a mock hyle: a second request is served from cache, a signed webhook purges, the next request refetches.
+
+1. **Fetch cache (default, no host configuration).** The fetch is tagged with what is known beforehand, a fixed and small set whatever URLs visitors request: the workspace tag, the default section `posts` and the sections you list (`hyle:1:sec:{workspaceId}:{section}`). Publish, unpublish, rename and edit all purge the section tag (cp1-spec section 5.8), so the page refreshes without knowing its own publication tag. Pass `sections: ["docs"]` for every other section the mount shows. Limits: a page in a section you did not list, and a page that renders a wikilink to a document in another section, refreshes only when `revalidate` (default 300 s) elapses; the per-publication tags in the response are not used. Redirects and 404s return real HTTP 308, 307 and 404.
+2. **`'use cache'` (exact tags, opt in).** `cachedResolver` fetches inside a `'use cache'` function and tags the entry with the response's own `cache.tags`. The host must set `cacheComponents: true` in `next.config`, and must wrap the page in `<Suspense>` (Next requires it for route params under Cache Components). Because the page then streams, a redirect reaches the browser as a meta refresh and a not found as a noindex page, both with HTTP 200 (observed). Import it only when opting in: Next compiles the directive inside this package, and with `cacheComponents` off even importing the module fails the build ("To use "use cache", please enable the feature flag cacheComponents", observed), which is why it is a separate entry point.
+
+```tsx
+import { hylePage } from "@tdacorp/hyle-sdk/next";
+import { cachedResolver } from "@tdacorp/hyle-sdk/next/use-cache";
+const Page = hylePage({ basePath: "/learn", resolver: cachedResolver({ baseUrl, workspaceId, token, revalidate: 300 }) });
+export default function Wrapper(props) { return <Suspense fallback={null}><Page {...props} /></Suspense>; }
+```
+
+The credential is never part of a cache key: entries are keyed by `baseUrl` plus `workspaceId` (pass both to `cachedResolver`), and the token stays in a module-level map. A switched-off read surface (`kind: "disabled"`) is cached for at most 30 s, so turning it back on is not delayed by the full window.
+
+The revalidate route expires tags immediately (`revalidateTag(tag, { expire: 0 })`), so no stale page is served after a purge. `HYLE_CONTENT_ENABLED=0` (or `false`) answers 404 from the route, the site-side rollback switch; nothing configured is also 404; partly configured is 503.
+
+### List pages
+
+`list: { title, description }` sets the list page's h1, `<title>`, description and Open Graph. Each wins over hyle's section title (which is the slug, "Posts") and falls back separately: no `list.title` keeps the section title, no `list.description` shows none. Articles are unaffected.
+
+List pages show the first page of results (`listLimit`, server default 20, maximum 100). `paginate: "searchParams"` turns on cursor pagination: `?cursor=` is read (it must be 1 to 256 characters of `A-Za-z0-9_-`, otherwise it is ignored; a well-formed cursor hyle rejects is a 404), sent to hyle, and "Older posts" links to `?cursor=<next_cursor>`. It is off by default because reading `searchParams` makes the route dynamic: it can no longer be statically generated or served from ISR (hyle's fetch cache and tags still apply per request). Leave it off when one page is enough. `generateMetadata` does not read the cursor, so page 2 shares page 1's title.
+
+## Errors
+
+How `hylePage` treats a hyle failure is chosen so a bad moment never replaces a good cached page:
+
+| Failure | Behaviour |
+|---|---|
+| A 4xx rejection of the request (`VALIDATION_ERROR`, `NOT_FOUND`, any 4xx except 401, 403 and 429), a path over 1024 characters, a non-NFC segment | `notFound()` (a real 404; the last two never reach hyle) |
+| Network error, timeout, 5xx, 401, 403, 429, a malformed response, a refused redirect target | **Rethrown.** Under ISR, Next keeps serving the last good page when a revalidation fails; a failure on a first render is an uncached 500 |
+| `notFound()` and redirects | Next control flow, always propagated (`unstable_rethrow`) |
+
+Why rethrow: a rendered "unavailable" page is a normal 200 render, so ISR would cache it and replace the last good article for everyone for the revalidate window. `onError: (error) => ReactElement` is the opt-in for a custom UI anyway; its element IS cached like any render, and the `error` it receives can contain `Cp1ClientError.message` and `requestId`, so never render it (only its name is logged, never the token or message). The `Unavailable` component (en, fr, es; `data-hyle-page="unavailable"`, `role="status"`, no error text) is exported from `./react` for `onError` or your own `error.tsx`. `hyleMetadata` follows the same split: a 4xx rejection gives `{}`, anything else is rethrown, so a transient outage never caches a noindex page.
+
+## Sitemap
+
+The contract has no "list every page" endpoint, so the helper pages the list result at each section index (100 per page, `next_cursor`, at most 20 pages per index by default). Spread it into your sitemap:
+
+```ts
+import { hyleSitemap } from "@tdacorp/hyle-sdk/next";
+export default async function sitemap() {
+  return [...staticEntries, ...(await hyleSitemap({ ...options, origin: "https://tdacorp.in", sections: ["docs"] }))];
+}
+```
+
+`origin` must be a bare https origin (anything else throws). URLs are percent-encoded and use `localePrefix`; the locale is `options.locale` when it is a string, and a function of the route params is never called (the sitemap is for the default locale). `lastModified` is `published_at` (omitted if it is not an ISO date): the list carries no `updated_at`. Only the default section and the `sections` you list are covered (a section's index resolves at `basePath/<slug>`), at most 2000 pages per index. `onIncomplete` decides what a hyle failure (or a listing cut off by the page limit) does: `"partial"` returns what was collected, `"throw"` throws so a build during an outage fails; the default throws only when nothing was collected. The core `listPublicationPaths({ client, basePath, sections?, locale?, maxPages? })` never throws and returns `{ paths: { path, publishedAt }[], complete }`, where `complete: false` means `paths` is partial.
+
+## Building blocks
+
+`fetchResolver(options)` is the default fetch-cache resolver, and `workspaceTags(workspaceId, sections?)` builds its tags (`hyle:1:ws:<id>`, `hyle:1:sec:<ws>:<section>`). Wrap `fetchResolver` to adjust a result (pass the wrapper as `resolver`) instead of copying it.
+
+## Host requirements
+
+No layout or page above the mount may export `dynamicParams = false`. hyle content (an article published after your last build) is by definition not known at build time, and Next inherits a parent's `false` for every child route: the route is compiled with `"fallback": false`, so each path not generated at build time is a hard 404 that falls through to any `[locale]/[...rest]` catch-all (observed: `x-matched-path: /[locale]/[...rest]`, content looks missing). Setting `dynamicParams = true` on the page does not override a parent's `false`.
+
+Verify after `next build`: `.next/prerender-manifest.json` must not show `"fallback": false` for the route that mounts `hylePage`, and a request for a published article that did not exist at build time must return 200.
+
+Locale-prefixed hosts: you may keep `generateStaticParams` for the locales, but validate the locale in the layout (call `notFound()` for an unknown one) and set `dynamicParams = true` there, so unknown locales are still rejected.
+
+## Styling
+
+Import `@tdacorp/hyle-sdk/styles.css`. It is the design kit's stylesheet: every value comes from a public `--hyle-*` custom property with a SIGNAL fallback (`--sig-*` from `@tdacorp/signal-tokens`, so dark and light acts flip with no extra code). Set variables on `:root`, `body` or any wrapper above the mount; the SDK never declares them:
+
+```css
+:root { --hyle-accent: #ff8a3d; --hyle-radius: 12px; --hyle-font-heading: "Fraunces", serif; }
+```
+
+The 52 variables are listed in the token block at the top of `styles.css`. Layout reacts to the width of the mount (container queries), not the window. Code uses highlight.js token classes (`hljs-*`, mapped to `--hyle-syn-*`). Math arrives as KaTeX HTML from the server: load `katex/dist/katex.min.css` in the host (it brings the fonts and resolves their URLs relative to itself). It is not bundled here because the fonts are about 1 MB of binary assets that would tie this package's version to KaTeX's and double-load in hosts that already use KaTeX.
+
+## Customization
+
+`components` replaces how a part is drawn, `slots` fills named places. Both are props of the pages and options of `hylePage`.
+
+- Component slots: `Link` (every internal link, breadcrumb and in-page link: pass your router's Link), `Image`, `CodeBlock` (receives `code`, `language`, and the default `children`; the stock block has no copy button because that needs client JavaScript), `Mermaid` (receives hyle's sandboxed `srcDoc`), `Callout` (GFM alerts such as `> [!NOTE]`). The raw element overrides `a`, `img`, `code`, `pre`, `table`, `blockquote` and `h1` to `h6` also work.
+- Visual slots: `article.before`, `article.meta`, `article.aside`, `article.after`, `list.header`, `list.item` (a component that receives the item), `list.empty`, `docs.sidebar-header`, `docs.version`, `docs.sidebar-footer`, `docs.after`, `notfound.body`, `notfound.actions`, `redirecting.body`. An unfilled slot renders nothing.
+- Layout: `layout: "docs"` renders articles as `DocsPage` (tree navigation from `ancestors`, `children` and `breadcrumbs`).
+
+Chrome strings exist for en, fr and es (fr and es are unreviewed drafts). The page title is the only `h1`: a body `h1` becomes `h2`, and a leading body `h1` that repeats the title is dropped.
+
+## Security model
+
+- The token is sent only as an `Authorization` header from the server. It is never placed in a URL, logged or put in an error message. Keep it out of client components. The client requires an https `baseUrl` (http only for localhost, or with `allowInsecureHttp`), refuses redirects, aborts after `timeoutMs` (default 10 s) and refuses responses over `maxResponseBytes` (default 5 MiB).
+- The path is sent as a query parameter (encoded once); catch-all segments are decoded and refused if they contain `/`, `\`, control characters, `.` or `..`.
+- The `hast` tree is rendered through an allowlist (`sanitizeHast`) even though hyle sanitizes server-side: only known tags and properties with accepted value shapes survive; no `on*` attributes, `style` only inside KaTeX output and only for the properties KaTeX emits with small values (no `position:absolute`, `z-index`, `left` or large sizes), ids and in-page fragments scoped with the server's `user-content-` prefix (so heading ids, footnote links and TOC links still resolve), `href` and `src` limited to site-relative paths and `http(s)` (and `mailto` for links), unknown tags are unwrapped, `script` and `style` are dropped, and an `iframe` is kept only with `sandbox="allow-scripts"` and a `srcdoc` that is exactly the document hyle's renderer builds for a Mermaid fence (pinned script URL, at most 64 KiB); the SDK adds `referrerpolicy="no-referrer"` and a `csp` that allows only that script (checked in headless Chromium: the diagram still renders). A tree over 20,000 nodes or 512 KiB of text fails closed with `HastLimitError` and a safe notice. `dangerouslySetInnerHTML` is used in exactly one place, `TrustedServerHtml`, the escape hatch for `content.format === "html"`: it renders HTML as is, so pass it only HTML that came straight from hyle's resolve endpoint, never user input.
+- Webhooks are verified with HMAC-SHA256 over the raw body (read with a running 64 KiB cap), a 300 s timestamp tolerance and constant-time comparison, with dual-secret rotation (empty secrets are never candidates), a payload shape check (400, not 500), tag validation, and delivery-id dedupe that records an id only after every purge succeeded, so a failed delivery can be retried.
+
+## Not included
+
+Docs versions, reading time, scroll-spy, "closest matches" on the 404 page and a copy-code button: hyle does not provide that data or the page would need client JavaScript. Image URLs in content such as `/assets/<id>` are passed through unchanged; map them with the `Image` slot if they live on hyle's origin.
+
+## Contract
+
+Types in `src/types.ts` mirror `packages/cp1-read/src/resolve.ts`. `src/__tests__/contract.test.ts` pins them against fixture JSON for every result kind, so a server-side shape change fails a test here.

package/dist/chunk-7VCMJUPC.js

@@ -0,0 +1,35 @@
+import {
+  createHyleClient,
+  isValidCacheTag
+} from "./chunk-HFUJRNFP.js";
+
+// src/next/resolve.ts
+var DEFAULT_REVALIDATE = 300;
+var MAX_TAGS = 64;
+function workspaceTags(workspaceId, sections = []) {
+  const workspaceTag = `hyle:1:ws:${workspaceId}`;
+  if (!isValidCacheTag(workspaceTag)) throw new TypeError("hyle: `workspaceId` is not a valid workspace id (a uuid)");
+  const slugs = /* @__PURE__ */ new Set(["posts", ...sections]);
+  const tags = [...slugs].map((slug) => `hyle:1:sec:${workspaceId}:${slug}`);
+  if (!tags.every(isValidCacheTag)) throw new TypeError("hyle: a configured `sections` slug cannot be used in a cache tag (printable ASCII, at most 200 characters)");
+  return [workspaceTag, ...tags].slice(0, MAX_TAGS);
+}
+function fetchResolver(options) {
+  if (!options.workspaceId) throw new TypeError("hylePage: `workspaceId` is required for the fetch cache (or pass a cachedResolver)");
+  const client = createHyleClient({ baseUrl: options.baseUrl, token: options.token });
+  const revalidate = options.revalidate ?? DEFAULT_REVALIDATE;
+  const tags = workspaceTags(options.workspaceId, options.sections);
+  return (path, locale, limit, cursor) => client.resolve({
+    path,
+    ...locale !== void 0 ? { locale } : {},
+    ...limit !== void 0 ? { limit } : {},
+    ...cursor !== void 0 ? { cursor } : {},
+    init: { next: { revalidate, tags } }
+  });
+}
+
+export {
+  DEFAULT_REVALIDATE,
+  workspaceTags,
+  fetchResolver
+};

package/dist/chunk-HFUJRNFP.js

@@ -0,0 +1,290 @@
+// src/errors.ts
+var Cp1ClientError = class extends Error {
+  code;
+  status;
+  requestId;
+  details;
+  constructor(code, message, status, requestId, details) {
+    super(message);
+    this.name = "Cp1ClientError";
+    this.code = code;
+    this.status = status;
+    this.requestId = requestId;
+    this.details = details;
+  }
+};
+
+// src/client.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+async function readCapped(res, max) {
+  const tooLarge = () => new Cp1ClientError("RESPONSE_TOO_LARGE", `hyle response exceeds ${max} bytes`, res.status, "");
+  if (Number(res.headers.get("content-length")) > max) throw tooLarge();
+  if (!res.body) return "";
+  const reader = res.body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > max) {
+      await reader.cancel();
+      throw tooLarge();
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+var KINDS = /* @__PURE__ */ new Set(["article", "list", "redirect", "notfound", "disabled"]);
+function createHyleClient(options) {
+  let origin;
+  try {
+    origin = new URL(options.baseUrl);
+  } catch {
+    throw new TypeError("baseUrl must be an https origin");
+  }
+  if (origin.protocol !== "https:" && !(origin.protocol === "http:" && (options.allowInsecureHttp || LOOPBACK.has(origin.hostname)))) {
+    throw new TypeError("baseUrl must be https (http is allowed only for localhost, or with allowInsecureHttp)");
+  }
+  if (!options.token) throw new TypeError("token is required");
+  const base = options.baseUrl.replace(/\/+$/, "");
+  const fetchImpl = options.fetch ?? fetch;
+  async function resolve(opts) {
+    const url = new URL(`${base}/cp1/read/resolve`);
+    url.searchParams.set("path", opts.path);
+    if (opts.locale !== void 0) url.searchParams.set("locale", opts.locale);
+    if (opts.format !== void 0) url.searchParams.set("format", opts.format);
+    if (opts.cursor !== void 0) url.searchParams.set("cursor", opts.cursor);
+    if (opts.limit !== void 0) url.searchParams.set("limit", String(opts.limit));
+    const headers = new Headers(opts.init?.headers);
+    headers.set("authorization", `Bearer ${options.token}`);
+    const timeout = AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const signal = opts.init?.signal ? AbortSignal.any([opts.init.signal, timeout]) : timeout;
+    const res = await fetchImpl(url.toString(), { ...opts.init, method: "GET", headers, redirect: "error", signal });
+    const text = await readCapped(res, options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES);
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = void 0;
+    }
+    const data = parsed?.data;
+    if (data && data.cp === 1 && typeof data.kind === "string" && KINDS.has(data.kind)) return data;
+    const err = parsed?.error;
+    throw new Cp1ClientError(
+      err?.code ?? "INVALID_RESPONSE",
+      err?.message ?? `Unexpected response from hyle (HTTP ${res.status})`,
+      res.status,
+      err?.request_id ?? "",
+      err?.details
+    );
+  }
+  return { resolve };
+}
+
+// src/delivery-dedupe.ts
+var DeliveryDedupe = class {
+  constructor(capacity = 1e3) {
+    this.capacity = capacity;
+  }
+  capacity;
+  seen = /* @__PURE__ */ new Map();
+  /** True if this id was already recorded (a duplicate delivery). */
+  has(deliveryId) {
+    return this.seen.has(deliveryId);
+  }
+  add(deliveryId) {
+    this.seen.delete(deliveryId);
+    this.seen.set(deliveryId, true);
+    if (this.seen.size > this.capacity) {
+      const oldest = this.seen.keys().next().value;
+      if (oldest !== void 0) this.seen.delete(oldest);
+    }
+  }
+};
+
+// src/signature.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var SIGNATURE_HEX = /^[0-9a-f]{64}$/;
+function parseSignatureHeader(header) {
+  let timestamp;
+  const signatures = [];
+  for (const part of header.split(",")) {
+    const [key, value] = part.split("=", 2);
+    if (key === "t" && value) {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed)) timestamp = parsed;
+    } else if (key === "v1" && value && SIGNATURE_HEX.test(value)) {
+      signatures.push(value);
+    }
+  }
+  if (timestamp === void 0 || signatures.length === 0) return void 0;
+  return { timestamp, signatures };
+}
+function computeSignature(secret, timestamp, rawBody) {
+  return createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
+}
+function signaturesEqual(a, b) {
+  const bufA = Buffer.from(a, "hex");
+  const bufB = Buffer.from(b, "hex");
+  if (bufA.length !== bufB.length) return false;
+  return timingSafeEqual(bufA, bufB);
+}
+function verifyHyleSignature(params) {
+  const secrets = params.secrets.filter((s) => s !== "");
+  if (!params.header || secrets.length === 0) return false;
+  const parsed = parseSignatureHeader(params.header);
+  if (!parsed) return false;
+  const tolerance = params.toleranceSeconds ?? 300;
+  const now = (params.now ?? Date.now)() / 1e3;
+  if (Math.abs(now - parsed.timestamp) > tolerance) return false;
+  for (const secret of secrets) {
+    const expected = computeSignature(secret, parsed.timestamp, params.rawBody);
+    for (const candidate of parsed.signatures) {
+      if (signaturesEqual(candidate, expected)) return true;
+    }
+  }
+  return false;
+}
+
+// src/tag-validation.ts
+var CACHE_TAG_PATTERN = /^hyle:1:(pub|doc|sec|link|ws):[0-9a-f-]{36}(:[\x21-\x7e]{1,200})?$/;
+function isValidCacheTag(tag) {
+  return CACHE_TAG_PATTERN.test(tag);
+}
+
+// src/revalidation-callback.ts
+var MAX_BODY_BYTES = 65536;
+var MAX_TAGS = 1e3;
+function createRevalidationCallbackRoute(options) {
+  const dedupe = new DeliveryDedupe(options.dedupeCapacity);
+  return {
+    async POST(req) {
+      const rawBody = await readCapped2(req);
+      if (rawBody === void 0) return new Response(null, { status: 413 });
+      const verified = verifyHyleSignature({
+        header: req.headers.get("hyle-signature"),
+        rawBody,
+        secrets: options.secrets,
+        ...options.toleranceSeconds !== void 0 ? { toleranceSeconds: options.toleranceSeconds } : {},
+        ...options.now !== void 0 ? { now: options.now } : {}
+      });
+      if (!verified) {
+        return new Response(null, { status: 401 });
+      }
+      let payload;
+      try {
+        payload = JSON.parse(rawBody);
+      } catch {
+        return new Response(null, { status: 400 });
+      }
+      if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return new Response(null, { status: 400 });
+      const body = payload;
+      if (body.cp !== 1) {
+        return okResponse(0);
+      }
+      const tags = body.tags ?? [];
+      if (typeof body.workspace_id !== "string" || !Array.isArray(tags) || tags.length > MAX_TAGS || !tags.every((t) => typeof t === "string")) {
+        return new Response(null, { status: 400 });
+      }
+      if (body.workspace_id !== options.workspaceId) {
+        return okResponse(0);
+      }
+      const deliveryId = req.headers.get("hyle-delivery-id");
+      if (deliveryId && dedupe.has(deliveryId)) {
+        return okResponse(0);
+      }
+      let purged = 0;
+      try {
+        for (const tag of tags) {
+          if (!isValidCacheTag(tag)) continue;
+          options.revalidateTag(tag);
+          purged += 1;
+        }
+      } catch {
+        return new Response(null, { status: 500 });
+      }
+      if (deliveryId) dedupe.add(deliveryId);
+      return okResponse(purged);
+    }
+  };
+}
+async function readCapped2(req) {
+  const declared = Number(req.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) return void 0;
+  if (!req.body) return "";
+  const reader = req.body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > MAX_BODY_BYTES) {
+      await reader.cancel();
+      return void 0;
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+function okResponse(purged) {
+  return new Response(JSON.stringify({ ok: true, purged }), {
+    status: 200,
+    headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" }
+  });
+}
+
+// src/sitemap.ts
+var PAGE_LIMIT = 100;
+var DEFAULT_MAX_PAGES = 20;
+var SECTION_SLUG = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+var UNSAFE_PATH = /[\\?#<>&"'\u0000- \u007f]/;
+async function listPublicationPaths(options) {
+  const maxPages = options.maxPages ?? DEFAULT_MAX_PAGES;
+  const prefix = `${options.basePath}/`;
+  const indexes = [options.basePath || "/"];
+  for (const slug of options.sections ?? []) if (slug !== "posts" && SECTION_SLUG.test(slug)) indexes.push(`${options.basePath}/${slug}`);
+  const found = /* @__PURE__ */ new Map();
+  let complete = true;
+  try {
+    for (const index of new Set(indexes)) {
+      let cursor;
+      for (let page = 0; page < maxPages; page++) {
+        const result = await options.client.resolve({
+          path: index,
+          limit: PAGE_LIMIT,
+          ...options.locale !== void 0 ? { locale: options.locale } : {},
+          ...cursor !== void 0 ? { cursor } : {}
+        });
+        if (result.kind !== "list") {
+          complete = false;
+          break;
+        }
+        for (const item of result.items) {
+          if (item.canonical_path.startsWith(prefix) && !UNSAFE_PATH.test(item.canonical_path)) found.set(item.canonical_path, item.published_at);
+        }
+        if (!result.next_cursor) break;
+        if (page === maxPages - 1) complete = false;
+        cursor = result.next_cursor;
+      }
+    }
+  } catch {
+    complete = false;
+  }
+  return { paths: [...found].map(([path, publishedAt]) => ({ path, publishedAt })), complete };
+}
+
+export {
+  Cp1ClientError,
+  createHyleClient,
+  DeliveryDedupe,
+  parseSignatureHeader,
+  verifyHyleSignature,
+  CACHE_TAG_PATTERN,
+  isValidCacheTag,
+  createRevalidationCallbackRoute,
+  listPublicationPaths
+};