@synap-core/sdk 1.1.0 → 1.2.0

package/src/public/form-model.ts

@@ -0,0 +1,210 @@
+/**
+ * Lead form — pure model. A form component only renders what these
+ * functions decide, so the decisions are testable without a DOM.
+ *
+ * Privacy rule: the pod answers every accepted submission with the same 202,
+ * so the site can only ever say "received". Never add copy that implies
+ * whether an email address is already known.
+ */
+import type {
+  PublicForm,
+  PublicFormField,
+  PublicReadError,
+  SubmitResult,
+} from "./client";
+
+export type FieldControl = "input" | "textarea" | "select" | "checkbox";
+
+export interface FieldModel {
+  key: string;
+  label: string;
+  help?: string;
+  required: boolean;
+  control: FieldControl;
+  /** HTML input type for `control: "input"`. */
+  inputType: "text" | "email" | "tel" | "url" | "number" | "date";
+  options: string[];
+  maxLength?: number;
+  min?: number;
+  max?: number;
+}
+
+export type FieldValue = string | boolean;
+export type FormValues = Record<string, FieldValue>;
+
+const INPUT_TYPE: Record<PublicFormField["type"], FieldModel["inputType"]> = {
+  text: "text",
+  richtext: "text",
+  email: "email",
+  phone: "tel",
+  url: "url",
+  number: "number",
+  boolean: "text",
+  date: "date",
+  enum: "text",
+};
+
+function controlFor(type: PublicFormField["type"]): FieldControl {
+  if (type === "richtext") return "textarea";
+  if (type === "enum") return "select";
+  if (type === "boolean") return "checkbox";
+  return "input";
+}
+
+export function toFieldModels(form: PublicForm): FieldModel[] {
+  return form.fields.map((f) => ({
+    key: f.key,
+    label: f.label,
+    help: f.help,
+    required: f.required === true,
+    control: controlFor(f.type),
+    inputType: INPUT_TYPE[f.type],
+    options: f.constraints?.enum ?? [],
+    maxLength: f.constraints?.maxLength,
+    min: f.constraints?.min,
+    max: f.constraints?.max,
+  }));
+}
+
+export function initialValues(fields: FieldModel[]): FormValues {
+  return Object.fromEntries(fields.map((f) => [f.key, f.control === "checkbox" ? false : ""]));
+}
+
+/** Client-side checks only; the pod re-validates everything. */
+export function validate(fields: FieldModel[], values: FormValues): Record<string, string> {
+  const errors: Record<string, string> = {};
+  for (const f of fields) {
+    const v = values[f.key];
+    if (f.control === "checkbox") {
+      if (f.required && v !== true) errors[f.key] = "Required";
+      continue;
+    }
+    const s = typeof v === "string" ? v.trim() : "";
+    if (s === "") {
+      if (f.required) errors[f.key] = "Required";
+      continue;
+    }
+    if (f.maxLength !== undefined && s.length > f.maxLength) {
+      errors[f.key] = `At most ${f.maxLength} characters`;
+    } else if (f.control === "select" && f.options.length > 0 && !f.options.includes(s)) {
+      errors[f.key] = "Pick one of the options";
+    } else if (f.inputType === "email" && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s)) {
+      errors[f.key] = "Enter a valid email";
+    } else if (f.inputType === "number") {
+      const n = Number(s);
+      if (!Number.isFinite(n)) errors[f.key] = "Enter a number";
+      else if (f.min !== undefined && n < f.min) errors[f.key] = `At least ${f.min}`;
+      else if (f.max !== undefined && n > f.max) errors[f.key] = `At most ${f.max}`;
+    }
+  }
+  return errors;
+}
+
+/** The `fields` payload for `submitForm`: trimmed, empties dropped, numbers typed. */
+export function toSubmission(fields: FieldModel[], values: FormValues): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const f of fields) {
+    const v = values[f.key];
+    if (f.control === "checkbox") {
+      out[f.key] = v === true;
+      continue;
+    }
+    const s = typeof v === "string" ? v.trim() : "";
+    if (s === "") continue;
+    out[f.key] = f.inputType === "number" ? Number(s) : s;
+  }
+  return out;
+}
+
+/** Whether the submit button may fire (captcha passthrough). */
+export function captchaSatisfied(form: PublicForm, captchaToken: string | null): boolean {
+  return !form.captcha.required || (captchaToken !== null && captchaToken !== "");
+}
+
+export function loadErrorMessage(error: PublicReadError): string {
+  switch (error) {
+    case "not_found":
+      return "This form isn't available.";
+    case "rate_limited":
+      return "Too many requests. Try again in a minute.";
+    case "doors_disabled":
+      return "This form isn't accepting responses right now.";
+    case "network":
+      return "We couldn't reach the server. Check your connection.";
+    case "server":
+      return "Something went wrong loading this form.";
+  }
+}
+
+/** A failed submit, as the form renders it. */
+export interface SubmitFailure {
+  /** One plain sentence for the form; never server detail. */
+  message: string;
+  /** Sentences by field key, only for keys that are on this form. */
+  fieldErrors: Record<string, string>;
+  /** Offer "Try again": nothing was filed and resending is safe. */
+  retryable: boolean;
+  /** The ticket is stale: fetch the form again before the next send. */
+  refreshForm: boolean;
+}
+
+export type FailedSubmit = Extract<SubmitResult, { ok: false }>;
+
+/**
+ * What to show for a submit that was NOT received. Success is only ever
+ * `{ ok: true, received: true }`; every branch here says "not sent".
+ */
+export function submitFailure(res: FailedSubmit, fields: FieldModel[]): SubmitFailure {
+  const none = { fieldErrors: {}, retryable: false, refreshForm: false };
+  switch (res.error) {
+    case "invalid": {
+      const known = new Set(fields.map((f) => f.key));
+      const fieldErrors = Object.fromEntries(
+        res.fields.filter((k) => known.has(k)).map((k) => [k, "Check this answer."])
+      );
+      const n = Object.keys(fieldErrors).length;
+      return {
+        ...none,
+        fieldErrors,
+        message:
+          n > 0
+            ? "Some answers need another look. Your message was not sent."
+            : "We couldn't read that as a message. Reload the page and try again.",
+      };
+    }
+    case "retry":
+      return {
+        ...none,
+        retryable: true,
+        refreshForm: true,
+        message: "That was sent a little too fast. Your message was not sent; try again.",
+      };
+    case "unavailable":
+      return {
+        ...none,
+        retryable: true,
+        message: "We couldn't save your message just now. It was not sent; try again.",
+      };
+    case "rate_limited":
+      return { ...none, message: "Too many attempts. Try again in a minute." };
+    case "doors_disabled":
+      return {
+        ...none,
+        message: "This form isn't accepting responses right now. Your message was not sent.",
+      };
+    case "network":
+      return {
+        ...none,
+        retryable: true,
+        message: "We couldn't reach the server. Your message was not sent.",
+      };
+    case "server":
+      return { ...none, message: "Something went wrong. Your message was not sent." };
+  }
+}
+
+/** Milliseconds until the pod will accept a submit for a ticket minted at `loadedAt`. */
+export function submitWaitRemaining(minSubmitMs: number, loadedAt: number, now: number): number {
+  const wait = Number.isFinite(minSubmitMs) && minSubmitMs > 0 ? minSubmitMs : 0;
+  return Math.max(0, loadedAt + wait - now);
+}

package/src/public/index.ts

@@ -0,0 +1,12 @@
+/**
+ * `@synap-core/sdk/public` — everything a public site needs, framework-free:
+ * the credentialless door client and the pure view-models a UI renders.
+ *
+ * Invariant (pinned by src/__tests__/public.guard.test.ts): every file of this
+ * entry imports only its siblings, and the client imports nothing at all.
+ */
+export * from "./client";
+export * from "./form-model";
+export * from "./share-model";
+export * from "./safe-markdown";
+export * from "./site-model";

package/src/public/safe-markdown.ts

@@ -0,0 +1,114 @@
+/**
+ * A deliberately tiny, SAFE markdown reader for published bodies (shares,
+ * site records).
+ *
+ * It produces plain data (blocks of text runs) that React renders as text
+ * nodes. It never produces HTML, so there is nothing to sanitize: raw HTML in
+ * the source (`<script>`, `<img onerror>`) is shown verbatim as text.
+ *
+ * Supported: `#`–`######` headings, paragraphs, `-`/`*`/`1.` list items,
+ * fenced code blocks, `**bold**`, and `[text](url)` links whose URL is
+ * http, https or mailto. Any other link renders as its text only.
+ * Everything else is plain text. Extend here — never by rendering HTML.
+ */
+
+export type Inline =
+  | { type: "text"; text: string }
+  | { type: "strong"; text: string }
+  | { type: "link"; text: string; href: string };
+
+export type Block =
+  | { type: "heading"; level: 1 | 2 | 3 | 4 | 5 | 6; inlines: Inline[] }
+  | { type: "paragraph"; inlines: Inline[] }
+  | { type: "list"; ordered: boolean; items: Inline[][] }
+  | { type: "code"; text: string };
+
+const SAFE_PROTOCOLS = new Set(["http:", "https:", "mailto:"]);
+
+/** The href if it is an absolute http/https/mailto URL, else null. */
+export function safeHref(raw: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    return null;
+  }
+  return SAFE_PROTOCOLS.has(url.protocol) ? url.href : null;
+}
+
+/** A link URL may hold one level of balanced parens (`/wiki/Foo_(bar)`). */
+const INLINE = /\*\*([^*]+)\*\*|\[([^\]]+)\]\(((?:[^()\s]|\([^()\s]*\))+)\)/g;
+
+export function parseInlines(text: string): Inline[] {
+  const out: Inline[] = [];
+  let last = 0;
+  for (const m of text.matchAll(INLINE)) {
+    const at = m.index ?? 0;
+    if (at > last) out.push({ type: "text", text: text.slice(last, at) });
+    if (m[1] !== undefined) {
+      out.push({ type: "strong", text: m[1] });
+    } else {
+      const href = safeHref(m[3]);
+      out.push(href ? { type: "link", text: m[2], href } : { type: "text", text: m[2] });
+    }
+    last = at + m[0].length;
+  }
+  if (last < text.length) out.push({ type: "text", text: text.slice(last) });
+  return out;
+}
+
+const HEADING = /^(#{1,6})\s+(.*)$/;
+const BULLET = /^\s*[-*]\s+(.*)$/;
+const ORDERED = /^\s*\d+[.)]\s+(.*)$/;
+const FENCE = /^\s*(```|~~~)/;
+
+export function parseSafeMarkdown(source: string): Block[] {
+  const lines = source.replace(/\r\n?/g, "\n").split("\n");
+  const blocks: Block[] = [];
+  let para: string[] = [];
+  let list: { ordered: boolean; items: Inline[][] } | null = null;
+
+  const flush = () => {
+    if (para.length) blocks.push({ type: "paragraph", inlines: parseInlines(para.join(" ")) });
+    para = [];
+    if (list) blocks.push({ type: "list", ...list });
+    list = null;
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fence = line.match(FENCE);
+    if (fence) {
+      flush();
+      const code: string[] = [];
+      i++;
+      while (i < lines.length && !lines[i].trimStart().startsWith(fence[1])) code.push(lines[i++]);
+      blocks.push({ type: "code", text: code.join("\n") });
+      continue;
+    }
+    if (line.trim() === "") {
+      flush();
+      continue;
+    }
+    const heading = line.match(HEADING);
+    if (heading) {
+      flush();
+      const level = heading[1].length as 1 | 2 | 3 | 4 | 5 | 6;
+      blocks.push({ type: "heading", level, inlines: parseInlines(heading[2]) });
+      continue;
+    }
+    const bullet = line.match(BULLET);
+    const ordered = bullet ? null : line.match(ORDERED);
+    if (bullet || ordered) {
+      const isOrdered = ordered !== null;
+      if (para.length || (list && list.ordered !== isOrdered)) flush();
+      if (!list) list = { ordered: isOrdered, items: [] };
+      list.items.push(parseInlines((bullet ?? ordered)![1]));
+      continue;
+    }
+    if (list) flush();
+    para.push(line.trim());
+  }
+  flush();
+  return blocks;
+}

package/src/public/share-model.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared-document page — pure model for a `/d/[token]` page.
+ *
+ * Every failure to read collapses into ONE "unavailable" state. `not_found`
+ * is already uniform at the pod (revoked, expired and unknown are
+ * indistinguishable by design); the page keeps that promise and does not add
+ * a distinction of its own. `retryable` only says whether "try again later"
+ * is honest (a network blip) — it never says anything about the token.
+ */
+import type { PublicReadError, PublicResult, PublicShare } from "./client";
+import { parseSafeMarkdown, type Block } from "./safe-markdown";
+import { formatPublicValue, type FormatOptions } from "./site-model";
+
+export const UNAVAILABLE_TITLE = "This link isn't available";
+
+export type SharePageModel =
+  | { kind: "unavailable"; retryable: boolean }
+  | {
+      kind: "share";
+      title: string | null;
+      /** Property rows exactly as the publisher allowlisted them. */
+      properties: Array<{ key: string; value: string }>;
+      blocks: Block[];
+      publishedOn: string;
+    };
+
+function isRetryable(error: PublicReadError): boolean {
+  return error === "network" || error === "rate_limited" || error === "server";
+}
+
+export function toSharePageModel(
+  result: PublicResult<PublicShare>,
+  opts: FormatOptions = {}
+): SharePageModel {
+  if (!result.ok) return { kind: "unavailable", retryable: isRetryable(result.error) };
+  const share = result.data;
+  return {
+    kind: "share",
+    title: share.title ?? null,
+    properties: Object.entries(share.properties ?? {}).map(([key, value]) => ({
+      key,
+      value: formatPublicValue(value, opts),
+    })),
+    blocks: share.body ? parseSafeMarkdown(share.body.content) : [],
+    publishedOn: share.publishedOn,
+  };
+}

package/src/public/site-model.ts

@@ -0,0 +1,217 @@
+/**
+ * Published site — pure models for collection and record pages: one value
+ * formatter, link-based pagination (`?page=n`, SEO-friendly) and the record
+ * view. A page component only renders what these decide.
+ *
+ * Formatting is deterministic: the locale and time zone default to `en` and
+ * `UTC`, never the runtime's, so a server render and a client render agree.
+ */
+import {
+  SITE_MAX_LIMIT,
+  SITE_MAX_OFFSET,
+  type PublicCollectionPage,
+  type PublicRecord,
+  type PublicRecordSummary,
+  type PublicValue,
+} from "./client";
+import { parseSafeMarkdown, type Block } from "./safe-markdown";
+
+export interface FormatOptions {
+  /** BCP 47 locale (default `en`). */
+  locale?: string;
+  /** IANA zone for date-times (default `UTC`). Plain dates are never shifted. */
+  timeZone?: string;
+  /** Words for booleans (default Yes / No). */
+  labels?: { yes: string; no: string };
+}
+
+/**
+ * Group digits only from 5 digits up, so a year stays `2026` and 12345 reads
+ * `12,345` (`useGrouping: "min2"`, ES2023 Intl; this package's lib is ES2022,
+ * hence the cast). An engine without it falls back to always grouping.
+ */
+const GROUPING = { useGrouping: "min2" } as unknown as Intl.NumberFormatOptions;
+
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})$/;
+
+/** A real calendar day (`2026-02-30` is not one). */
+function isCalendarDay(s: string): boolean {
+  const m = ISO_DATE.exec(s);
+  if (!m) return false;
+  const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])));
+  return d.toISOString().slice(0, 10) === s;
+}
+
+/**
+ * One published value as display text, the same on every site: booleans as
+ * words, numbers grouped for the locale, ISO dates and date-times as medium
+ * dates (date-times with a short time). Any other string is returned as is.
+ * Plain text only: render it as a text node.
+ */
+export function formatPublicValue(value: PublicValue, opts: FormatOptions = {}): string {
+  const locale = opts.locale ?? "en";
+  if (typeof value === "boolean") return value ? (opts.labels?.yes ?? "Yes") : (opts.labels?.no ?? "No");
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? new Intl.NumberFormat(locale, GROUPING).format(value) : String(value);
+  }
+  if (isCalendarDay(value)) {
+    return new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeZone: "UTC" }).format(
+      new Date(`${value}T00:00:00Z`)
+    );
+  }
+  if (ISO_DATE_TIME.test(value)) {
+    const at = new Date(value);
+    if (!Number.isNaN(at.getTime())) {
+      return new Intl.DateTimeFormat(locale, {
+        dateStyle: "medium",
+        timeStyle: "short",
+        timeZone: opts.timeZone ?? "UTC",
+      }).format(at);
+    }
+  }
+  return value;
+}
+
+// ── Pagination ──────────────────────────────────────────────────────────────
+
+/** Highest page number `parsePageParam` accepts. */
+const MAX_PAGE_PARAM = 1_000_000;
+
+/**
+ * A `?page=` value → a page number. Missing or empty → 1; a positive integer
+ * → itself; anything else → null (render the not-found state).
+ */
+export function parsePageParam(raw: string | string[] | null | undefined): number | null {
+  if (raw === undefined || raw === null || raw === "") return 1;
+  if (Array.isArray(raw)) return null;
+  if (!/^[1-9]\d*$/.test(raw)) return null;
+  const n = Number(raw);
+  return n <= MAX_PAGE_PARAM ? n : null;
+}
+
+/**
+ * The `listCollection` query for page `page` (1-based) of `pageSize` items.
+ * null when the page lies past the door's offset ceiling (10 000): render
+ * the not-found state, never a request that can only be refused.
+ */
+export function pageQuery(page: number, pageSize: number): { offset: number; limit: number } | null {
+  if (!Number.isInteger(page) || page < 1) return null;
+  const limit = Math.min(SITE_MAX_LIMIT, Math.max(1, Math.floor(pageSize) || 1));
+  const offset = (page - 1) * limit;
+  return offset <= SITE_MAX_OFFSET ? { offset, limit } : null;
+}
+
+export interface PageLink {
+  page: number;
+  /** `basePath` for page 1 (the canonical URL), else `basePath?page=n`. */
+  href: string;
+  current: boolean;
+}
+
+export type PageItem = ({ kind: "page" } & PageLink) | { kind: "gap"; key: string };
+
+export interface CollectionPageModel {
+  items: PublicRecordSummary[];
+  total: number;
+  /** Current page, 1-based. */
+  page: number;
+  /** Reachable pages (≥ 1); the door serves no offset past 10 000. */
+  pageCount: number;
+  pageSize: number;
+  /** 1-based positions of the first and last item shown; 0 and 0 when none. */
+  from: number;
+  to: number;
+  /** Nothing is published in this collection. */
+  empty: boolean;
+  /** Records exist but not on this page (a stale or hand-typed `?page=`). */
+  outOfRange: boolean;
+  prev: PageLink | null;
+  next: PageLink | null;
+  /** First, last, and `window` pages either side of the current one, with gaps. */
+  pages: PageItem[];
+}
+
+export interface PageModelOptions {
+  /** The collection page's path, e.g. `/papers` (may carry its own query). */
+  basePath: string;
+  /** Pages shown either side of the current one (default 1). */
+  window?: number;
+  /** Query parameter name (default `page`). */
+  param?: string;
+}
+
+export function toCollectionPageModel(
+  page: PublicCollectionPage,
+  opts: PageModelOptions
+): CollectionPageModel {
+  const pageSize = Math.max(1, page.limit);
+  const current = Math.floor(Math.max(0, page.offset) / pageSize) + 1;
+  const reachable = Math.floor(SITE_MAX_OFFSET / pageSize) + 1;
+  const pageCount = Math.max(1, Math.min(Math.ceil(page.total / pageSize), reachable));
+  const param = opts.param ?? "page";
+  const sep = opts.basePath.includes("?") ? "&" : "?";
+  const link = (n: number): PageLink => ({
+    page: n,
+    href: n === 1 ? opts.basePath : `${opts.basePath}${sep}${param}=${n}`,
+    current: n === current,
+  });
+
+  const window = Math.max(0, Math.floor(opts.window ?? 1));
+  const shown = new Set<number>([1, pageCount]);
+  for (let n = current - window; n <= current + window; n++) {
+    if (n >= 1 && n <= pageCount) shown.add(n);
+  }
+  const pages: PageItem[] = [];
+  let last = 0;
+  for (const n of [...shown].sort((a, b) => a - b)) {
+    if (n - last === 2) pages.push({ kind: "page", ...link(n - 1) });
+    else if (n - last > 2) pages.push({ kind: "gap", key: `gap-${last}` });
+    pages.push({ kind: "page", ...link(n) });
+    last = n;
+  }
+
+  const count = page.items.length;
+  const from = count > 0 ? page.offset + 1 : 0;
+  return {
+    items: page.items,
+    total: page.total,
+    page: current,
+    pageCount,
+    pageSize,
+    from,
+    to: count > 0 ? page.offset + count : 0,
+    empty: page.total === 0,
+    outOfRange: page.total > 0 && count === 0,
+    prev: current > 1 ? link(Math.min(current - 1, pageCount)) : null,
+    next: current < pageCount ? link(current + 1) : null,
+    pages,
+  };
+}
+
+// ── Record ──────────────────────────────────────────────────────────────────
+
+export interface RecordViewModel {
+  title: string | null;
+  publicId: string;
+  slug: string | null;
+  /** Rows exactly as the publisher allowlisted them, formatted. */
+  properties: Array<{ key: string; value: string }>;
+  /** The body as safe blocks (never HTML). */
+  blocks: Block[];
+  publishedOn: string;
+}
+
+export function toRecordViewModel(record: PublicRecord, opts: FormatOptions = {}): RecordViewModel {
+  return {
+    title: record.title ?? null,
+    publicId: record.publicId,
+    slug: record.slug,
+    properties: Object.entries(record.properties ?? {}).map(([key, value]) => ({
+      key,
+      value: formatPublicValue(value, opts),
+    })),
+    blocks: record.body ? parseSafeMarkdown(record.body.content) : [],
+    publishedOn: record.publishedOn,
+  };
+}