@flamingo-stack/openframe-frontend-core 0.0.739 → 0.0.740

package/src/components/shared/legal-document/use-legal-documents.ts

@@ -0,0 +1,113 @@
+'use client';
+
+/**
+ * useLegalDocuments — the list of legal documents a hub publishes (privacy
+ * policy, terms of service, payment terms, license, security policy, and
+ * whatever it adds later), each with its page and the version it states.
+ *
+ * A host that lists legal pages reads this list, shows one entry per published
+ * document, each leading to that document's own page, and names no document
+ * itself: a document the hub adds appears with no change here.
+ *
+ * Endpoint: default `/api/legal`; an embedder passes its proxied path.
+ */
+
+import { useEffect, useState } from 'react';
+import { contentFetch } from '../../../utils/embed-content-fetch';
+
+export interface LegalDocumentSummary {
+  /** The identifier `useLegalDocs` and `<LegalDocumentPage>` take. */
+  docType: string;
+  title: string;
+  /** One line saying what the document is, for a card that lists it. */
+  summary: string;
+  /** The document's page on the hub's own site (a path). */
+  route: string;
+  sourceFile: string;
+  /** The topic the document's FAQs are written for, when the hub has one. */
+  faqTopic: string | null;
+  version: string | null;
+  effectiveDate: string | null;
+  /** False while the hub has no content for it yet. */
+  published: boolean;
+}
+
+export interface UseLegalDocumentsOptions {
+  /** Full GET endpoint URL. Default `/api/legal`. */
+  apiEndpoint?: string;
+  /** False: read nothing and answer an empty list. Default true. */
+  enabled?: boolean;
+}
+
+export interface UseLegalDocumentsReturn {
+  documents: LegalDocumentSummary[];
+  isLoading: boolean;
+  error: string | null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function text(source: Record<string, unknown>, key: string): string | null {
+  const value = source[key];
+  return typeof value === 'string' && value ? value : null;
+}
+
+/** Decode the endpoint's answer; a row without a type and a title is left out. */
+export function toLegalDocumentSummaries(payload: unknown): LegalDocumentSummary[] {
+  const rows: unknown = isRecord(payload) ? payload.documents : null;
+  if (!Array.isArray(rows)) return [];
+  const documents: LegalDocumentSummary[] = [];
+  for (const row of rows as readonly unknown[]) {
+    if (!isRecord(row)) continue;
+    const docType = text(row, 'docType');
+    const title = text(row, 'title');
+    if (!docType || !title) continue;
+    documents.push({
+      docType,
+      title,
+      summary: text(row, 'summary') ?? '',
+      route: text(row, 'route') ?? '',
+      sourceFile: text(row, 'sourceFile') ?? '',
+      faqTopic: text(row, 'faqTopic'),
+      version: text(row, 'version'),
+      effectiveDate: text(row, 'effectiveDate'),
+      published: row.published === true,
+    });
+  }
+  return documents;
+}
+
+export function useLegalDocuments(options: UseLegalDocumentsOptions = {}): UseLegalDocumentsReturn {
+  const endpoint = options.apiEndpoint ?? '/api/legal';
+  const enabled = options.enabled ?? true;
+  const [state, setState] = useState<UseLegalDocumentsReturn>({ documents: [], isLoading: enabled, error: null });
+
+  useEffect(() => {
+    let current = enabled;
+    const load = async () => {
+      try {
+        const response = await contentFetch(endpoint);
+        if (!response.ok) throw new Error(`Failed to fetch legal documents: ${response.status} ${response.statusText}`);
+        const payload: unknown = await response.json();
+        if (current) setState({ documents: toLegalDocumentSummaries(payload), isLoading: false, error: null });
+      } catch (err) {
+        console.error('Error fetching legal documents:', err);
+        if (current) {
+          setState({
+            documents: [],
+            isLoading: false,
+            error: err instanceof Error ? err.message : 'Unknown error occurred',
+          });
+        }
+      }
+    };
+    if (enabled) void load();
+    return () => {
+      current = false;
+    };
+  }, [endpoint, enabled]);
+
+  return state;
+}

package/src/utils/index.ts

@@ -415,6 +415,7 @@ export * from './humanity-signals';
 // so the host's draft endpoint re-applies the same filter the browser hook runs.
 // Also exported via the granular subpath `./utils/form-rescue`.
 export * from './form-rescue';
+export * from './legal-documents';
 
 // Doc-source viewer utilities (path parsing, tree building, section extraction,
 // embed-URL conversion) — single home for all doc-viewer pure helpers across

package/src/utils/legal-documents.ts

@@ -0,0 +1,21 @@
+/**
+ * The types of legal document a hub can publish, each with a page of its own
+ * (`/api/legal/<type>`, `<LegalDocumentPage docType>`).
+ *
+ * WHICH of them are published, and each one's title, version and effective
+ * date, is the hub's answer at run time (`GET /api/legal`, `useLegalDocuments`).
+ * This list exists for a host that must know every possible page before it
+ * runs: a statically exported app prerenders one legal page per type here and
+ * links only the ones the hub's list says are published.
+ *
+ * Pure and server-safe. The hub's own list of legal documents carries exactly
+ * these types.
+ */
+export const LEGAL_DOCUMENT_TYPES = ['privacy', 'terms', 'payment', 'license', 'security'] as const;
+
+export type LegalDocumentType = (typeof LEGAL_DOCUMENT_TYPES)[number];
+
+/** True for a type a host has a page for (one of {@link LEGAL_DOCUMENT_TYPES}). */
+export function isLegalDocumentType(value: string): value is LegalDocumentType {
+  return (LEGAL_DOCUMENT_TYPES as readonly string[]).includes(value);
+}