@tdacorp/hyle-sdk 0.1.1 → 0.2.1

package/README.md

@@ -49,9 +49,9 @@ Register that URL as the workspace's webhook endpoint in hyle. Set `metadataBase
 
 | Import | Contents | Needs |
 |---|---|---|
-| `@tdacorp/hyle-sdk` | `createHyleClient` (typed `resolve`), `Cp1ClientError`, `verifyHyleSignature`, `parseSignatureHeader`, `isValidCacheTag`, `DeliveryDedupe`, `createRevalidationCallbackRoute`, the result types | nothing (no framework) |
-| `@tdacorp/hyle-sdk/react` | `ArticlePage`, `ListPage`, `DocsPage`, `NotFound`, `Redirecting`, `HastContent`, `TrustedServerHtml`, `sanitizeHast` | react >= 19 |
-| `@tdacorp/hyle-sdk/next` | `hylePage`, `hyleMetadata`, `createRevalidateRoute` | next >= 16 |
+| `@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 | |
 
@@ -90,10 +90,45 @@ The credential is never part of a cache key: entries are keyed by `baseUrl` plus
 
 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 show the first page of results (`listLimit`, server default 20, maximum 100). Cursor pagination through the URL is not wired into `hylePage` in 0.1.0, because reading `searchParams` would make every page dynamic. `ListPage` accepts an `olderHref` if you build your own route.
+### 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
 
+Bundler only: `@tdacorp/hyle-sdk/next` and `/next/use-cache` import `next/navigation` and `next/cache` the way a Next app does, so plain Node ESM cannot import them. Real `next build` runs of the packed package passed with Next 16.2.7, 16.3.4 and 16.4.2 (Turbopack, the default).
+
 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.
@@ -127,9 +162,9 @@ Chrome strings exist for en, fr and es (fr and es are unreviewed drafts). The pa
 - 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 in 0.1.0
+## Not included
 
-A sitemap helper (the contract has no listing endpoint that covers every page), 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.
+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
 

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-RI3BP4MI.js → chunk-HFUJRNFP.js}

@@ -237,6 +237,46 @@ function okResponse(purged) {
   });
 }
 
+// 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,
@@ -245,5 +285,6 @@ export {
   verifyHyleSignature,
   CACHE_TAG_PATTERN,
   isValidCacheTag,
-  createRevalidationCallbackRoute
+  createRevalidationCallbackRoute,
+  listPublicationPaths
 };

package/dist/{chunk-XODMIT6N.js → chunk-MHVWHSKC.js}

@@ -243,7 +243,10 @@ var en = {
   rdBody: "You are being taken to its new address.",
   from: "From",
   to: "To",
-  rdFallback: "If nothing happens, go to the new address."
+  rdFallback: "If nothing happens, go to the new address.",
+  unKind: "Unavailable",
+  unTitle: "This page is temporarily unavailable",
+  unBody: "The content could not be loaded. Please try again in a moment."
 };
 var fr = {
   toc: "Sur cette page",
@@ -279,7 +282,10 @@ var fr = {
   rdBody: "Vous \xEAtes redirig\xE9 vers sa nouvelle adresse.",
   from: "De",
   to: "Vers",
-  rdFallback: "Si rien ne se passe, allez \xE0 la nouvelle adresse."
+  rdFallback: "Si rien ne se passe, allez \xE0 la nouvelle adresse.",
+  unKind: "Indisponible",
+  unTitle: "Cette page est momentan\xE9ment indisponible",
+  unBody: "Le contenu n'a pas pu \xEAtre charg\xE9. R\xE9essayez dans un instant."
 };
 var es = {
   toc: "En esta p\xE1gina",
@@ -315,7 +321,10 @@ var es = {
   rdBody: "Te estamos llevando a su nueva direcci\xF3n.",
   from: "Desde",
   to: "A",
-  rdFallback: "Si no pasa nada, ve a la nueva direcci\xF3n."
+  rdFallback: "Si no pasa nada, ve a la nueva direcci\xF3n.",
+  unKind: "No disponible",
+  unTitle: "Esta p\xE1gina no est\xE1 disponible por el momento",
+  unBody: "No se pudo cargar el contenido. Int\xE9ntalo de nuevo en un momento."
 };
 var TABLE = { en, fr, es };
 function stringsFor(locale) {
@@ -679,6 +688,14 @@ function NotFound({ path, homeHref = "/", ...base }) {
     ] })
   ] }) });
 }
+function Unavailable(base) {
+  const c = ctx(base, "en");
+  return /* @__PURE__ */ jsx4(Shell, { children: /* @__PURE__ */ jsxs4("section", { className: "hyle-state", "data-hyle-page": "unavailable", lang: c.locale, role: "status", children: [
+    /* @__PURE__ */ jsx4("span", { className: "kind", children: c.s.unKind }),
+    /* @__PURE__ */ jsx4("h1", { children: c.s.unTitle }),
+    /* @__PURE__ */ jsx4("p", { children: c.s.unBody })
+  ] }) });
+}
 function Redirecting({ from, to, ...base }) {
   const c = ctx(base, "en");
   const { Link, s } = c;
@@ -714,5 +731,6 @@ export {
   ListPage,
   DocsPage,
   NotFound,
+  Unavailable,
   Redirecting
 };

package/dist/index.cjs

@@ -26,6 +26,7 @@ __export(src_exports, {
   createHyleClient: () => createHyleClient,
   createRevalidationCallbackRoute: () => createRevalidationCallbackRoute,
   isValidCacheTag: () => isValidCacheTag,
+  listPublicationPaths: () => listPublicationPaths,
   parseSignatureHeader: () => parseSignatureHeader,
   verifyHyleSignature: () => verifyHyleSignature
 });
@@ -269,6 +270,46 @@ function okResponse(purged) {
     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 };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CACHE_TAG_PATTERN,
@@ -277,6 +318,7 @@ function okResponse(purged) {
   createHyleClient,
   createRevalidationCallbackRoute,
   isValidCacheTag,
+  listPublicationPaths,
   parseSignatureHeader,
   verifyHyleSignature
 });

package/dist/index.d.cts

@@ -99,4 +99,33 @@ declare class DeliveryDedupe {
     add(deliveryId: string): void;
 }
 
-export { CACHE_TAG_PATTERN, Cp1ClientError, DeliveryDedupe, type HyleClient, type HyleClientOptions, type HyleRequestInit, type ParsedSignatureHeader, type ResolveOptions, Resolved, type VerifySignatureParams, createHyleClient, isValidCacheTag, parseSignatureHeader, verifyHyleSignature };
+interface PublicationPath {
+    /** The publication's canonical site path, for example "/learn/hello". */
+    readonly path: string;
+    /** ISO 8601 `published_at` (the list endpoint carries no `updated_at`). */
+    readonly publishedAt: string;
+}
+interface PublicationPaths {
+    readonly paths: PublicationPath[];
+    /** False when any index failed, answered something other than a list, or was cut off by `maxPages`: `paths` is then partial. */
+    readonly complete: boolean;
+}
+interface ListPublicationPathsOptions {
+    /** Anything with `resolve`: a `createHyleClient(...)`, or a wrapper around a host's own resolver. */
+    readonly client: Pick<HyleClient, "resolve">;
+    /** The mount prefix, "" or "/learn": the same value as `basePath` of `hylePage`. */
+    readonly basePath: string;
+    /** Section slugs to list besides the default section, whose index is `basePath` itself. A section's index is `basePath/<slug>`. */
+    readonly sections?: readonly string[];
+    readonly locale?: string;
+    /** Pages fetched per index (default 20, of 100 items each), so a workspace larger than 2000 per section is truncated. */
+    readonly maxPages?: number;
+}
+/**
+ * Every published page under a mount, for a sitemap. The contract has no "list everything" endpoint, so this pages the list
+ * result at each section index (`limit` 100, following `next_cursor`) up to `maxPages` per index. Only the default section and
+ * the listed `sections` are covered. Never throws: on any error it returns what it collected with `complete: false`, so the caller decides whether a partial listing is acceptable.
+ */
+declare function listPublicationPaths(options: ListPublicationPathsOptions): Promise<PublicationPaths>;
+
+export { CACHE_TAG_PATTERN, Cp1ClientError, DeliveryDedupe, type HyleClient, type HyleClientOptions, type HyleRequestInit, type ListPublicationPathsOptions, type ParsedSignatureHeader, type PublicationPath, type PublicationPaths, type ResolveOptions, Resolved, type VerifySignatureParams, createHyleClient, isValidCacheTag, listPublicationPaths, parseSignatureHeader, verifyHyleSignature };

package/dist/index.d.ts

@@ -99,4 +99,33 @@ declare class DeliveryDedupe {
     add(deliveryId: string): void;
 }
 
-export { CACHE_TAG_PATTERN, Cp1ClientError, DeliveryDedupe, type HyleClient, type HyleClientOptions, type HyleRequestInit, type ParsedSignatureHeader, type ResolveOptions, Resolved, type VerifySignatureParams, createHyleClient, isValidCacheTag, parseSignatureHeader, verifyHyleSignature };
+interface PublicationPath {
+    /** The publication's canonical site path, for example "/learn/hello". */
+    readonly path: string;
+    /** ISO 8601 `published_at` (the list endpoint carries no `updated_at`). */
+    readonly publishedAt: string;
+}
+interface PublicationPaths {
+    readonly paths: PublicationPath[];
+    /** False when any index failed, answered something other than a list, or was cut off by `maxPages`: `paths` is then partial. */
+    readonly complete: boolean;
+}
+interface ListPublicationPathsOptions {
+    /** Anything with `resolve`: a `createHyleClient(...)`, or a wrapper around a host's own resolver. */
+    readonly client: Pick<HyleClient, "resolve">;
+    /** The mount prefix, "" or "/learn": the same value as `basePath` of `hylePage`. */
+    readonly basePath: string;
+    /** Section slugs to list besides the default section, whose index is `basePath` itself. A section's index is `basePath/<slug>`. */
+    readonly sections?: readonly string[];
+    readonly locale?: string;
+    /** Pages fetched per index (default 20, of 100 items each), so a workspace larger than 2000 per section is truncated. */
+    readonly maxPages?: number;
+}
+/**
+ * Every published page under a mount, for a sitemap. The contract has no "list everything" endpoint, so this pages the list
+ * result at each section index (`limit` 100, following `next_cursor`) up to `maxPages` per index. Only the default section and
+ * the listed `sections` are covered. Never throws: on any error it returns what it collected with `complete: false`, so the caller decides whether a partial listing is acceptable.
+ */
+declare function listPublicationPaths(options: ListPublicationPathsOptions): Promise<PublicationPaths>;
+
+export { CACHE_TAG_PATTERN, Cp1ClientError, DeliveryDedupe, type HyleClient, type HyleClientOptions, type HyleRequestInit, type ListPublicationPathsOptions, type ParsedSignatureHeader, type PublicationPath, type PublicationPaths, type ResolveOptions, Resolved, type VerifySignatureParams, createHyleClient, isValidCacheTag, listPublicationPaths, parseSignatureHeader, verifyHyleSignature };

package/dist/index.js

@@ -5,9 +5,10 @@ import {
   createHyleClient,
   createRevalidationCallbackRoute,
   isValidCacheTag,
+  listPublicationPaths,
   parseSignatureHeader,
   verifyHyleSignature
-} from "./chunk-RI3BP4MI.js";
+} from "./chunk-HFUJRNFP.js";
 export {
   CACHE_TAG_PATTERN,
   Cp1ClientError,
@@ -15,6 +16,7 @@ export {
   createHyleClient,
   createRevalidationCallbackRoute,
   isValidCacheTag,
+  listPublicationPaths,
   parseSignatureHeader,
   verifyHyleSignature
 };