@dreamtree-org/landing-kit 0.7.2 → 0.9.0

package/platform.d.ts

@@ -0,0 +1,342 @@
+// @dreamtree-org/landing-kit/platform: client for the Platform console HTTP contract.
+// The contract itself (paths, bodies, step-up rules) is documented in PLATFORM-API.md.
+
+export const PLATFORM_API_BASE: '/api/platform';
+export const PLATFORM_LOGIN_PATH: '/platform/login';
+export const STEP_UP_REQUIRED: 'STEP_UP_REQUIRED';
+
+export type PlatformFeature = 'overview' | 'companies' | 'jobs' | 'plans' | 'audit' | 'support' | 'settings' | 'admins';
+/** Every console feature, in nav order. */
+export const PLATFORM_FEATURES: readonly PlatformFeature[];
+/** Features a server without `GET /me` serves. */
+export const SHIPPED_FEATURES: readonly PlatformFeature[];
+
+export class PlatformApiError extends Error {
+  constructor(message: string, status: number, code?: string, body?: unknown);
+  /** HTTP status; 0 when the admin cancelled a step-up. */
+  status: number;
+  /** `STEP_UP_REQUIRED`, `FORBIDDEN`, `CANCELLED`, … */
+  code?: string | undefined;
+  body?: unknown;
+}
+
+export function isStepUpRequired(err: unknown): err is PlatformApiError;
+/** The named cookie, or the first `<prefix>_platform_csrf` when no name is given. */
+export function readPlatformCsrf(cookieString: string | null | undefined, name?: string): string | null;
+
+export type Query = Record<string, string | number | boolean | null | undefined>;
+
+export interface PlatformRequestInit extends Omit<RequestInit, 'body' | 'method'> {
+  method?: string;
+  json?: unknown;
+  query?: Query;
+  body?: BodyInit | null;
+  /** Throw on 401 without calling onUnauthorized (used by step-up confirm). */
+  skipAuthRedirect?: boolean;
+}
+
+export interface PlatformClientOptions {
+  /** Where the contract is mounted. Default `/api/platform`. */
+  basePath?: string;
+  /** Where a 401 sends the browser. Default `/platform/login`. */
+  loginPath?: string;
+  /** Exact CSRF cookie name, e.g. `pp_platform_csrf`. Default: any `*_platform_csrf` cookie. */
+  csrfCookie?: string;
+  fetch?: typeof fetch;
+  /** Cookie source; default `document.cookie`. */
+  cookies?: () => string;
+  /** Default: `window.location.assign(loginPath)`. */
+  onUnauthorized?: (err: PlatformApiError) => void;
+}
+
+export interface PlatformClient {
+  readonly basePath: string;
+  readonly loginPath: string;
+  url(path: string, query?: Query): string;
+  /** Raw Response with the CSRF header added (CSV export, downloads). */
+  raw(path: string, init?: PlatformRequestInit): Promise<Response>;
+  request<T = unknown>(path: string, init?: PlatformRequestInit): Promise<T>;
+  get<T = unknown>(path: string, query?: Query, init?: PlatformRequestInit): Promise<T>;
+  post<T = unknown>(path: string, json?: unknown, init?: PlatformRequestInit): Promise<T>;
+  patch<T = unknown>(path: string, json?: unknown, init?: PlatformRequestInit): Promise<T>;
+  put<T = unknown>(path: string, json?: unknown, init?: PlatformRequestInit): Promise<T>;
+  del<T = unknown>(path: string, init?: PlatformRequestInit): Promise<T>;
+}
+
+export function createPlatformClient(opts?: PlatformClientOptions): PlatformClient;
+
+export type StepUpSecret = { password: string } | { code: string };
+/**
+ * Wraps sensitive actions: on STEP_UP_REQUIRED calls `ask` (with the 403, or the 401 of a wrong
+ * secret), POSTs `auth/confirm`, retries once. `ask` resolving null cancels (code `CANCELLED`).
+ */
+export function createStepUp(
+  client: PlatformClient,
+  ask: (reason: PlatformApiError) => Promise<StepUpSecret | null>
+): <T>(action: () => Promise<T>) => Promise<T>;
+
+/** Features to show: those `me.features` advertises, else `SHIPPED_FEATURES`. Overview, companies, admins are always on. */
+export function enabledFeatures(requested?: readonly PlatformFeature[], me?: Pick<PlatformMe, 'features'> | null): PlatformFeature[];
+
+export function formatDate(value: string | Date | null | undefined): string;
+export function timeAgo(value: string | Date | null | undefined, now?: number): string;
+
+// ── Contract shapes (PLATFORM-API.md) ────────────────────────────────────────
+
+export type Iso = string;
+export type CompanyStatus = 'draft' | 'provisioning' | 'provisioning_failed' | 'active' | 'maintenance' | 'suspended' | 'archived';
+
+export interface PlatformMe {
+  admin: { id: string; email: string; roles: string[]; totpEnrolled: boolean };
+  permissions: string[];
+  /** `console` false = enrollment-only session (enroll an authenticator first). */
+  access?: { console: boolean; stepUpFresh: boolean };
+  features: Partial<Record<PlatformFeature | 'domains', boolean>>;
+  app: { key: string; name: string; companyLoginPath?: string };
+}
+
+export interface LoginResponse {
+  ok: true;
+  mfa?: 'none' | 'required' | 'enroll';
+  ticket?: string;
+  needsFactorEnrollment: boolean;
+}
+
+export interface PlatformAdmin {
+  id: string;
+  email: string;
+  status: 'active' | 'disabled';
+  roles?: string[];
+  totpEnrolled?: boolean;
+  lastLoginAt: Iso | null;
+  createdAt: Iso;
+}
+
+export interface CompanyRow {
+  id: string;
+  slug: string;
+  displayName: string;
+  status: CompanyStatus;
+  createdAt: Iso;
+  branchCount: number;
+  dbMode: 'managed' | 'external' | null;
+  dbStatus: string | null;
+  schemaVersion: string | number | null;
+  lastCheckAt: Iso | null;
+  lastCheckOk: 0 | 1 | null;
+}
+
+export interface CompanyDetail {
+  id: string;
+  slug: string;
+  displayName: string;
+  status: CompanyStatus;
+  defaultBranchId: string | null;
+  configVersion: number;
+  createdAt: Iso;
+  updatedAt: Iso;
+  branches?: Array<{ id: string; code: string; name: string; status: string }>;
+  [key: string]: unknown;
+}
+
+export interface CompanyUser {
+  id: string;
+  fullName: string;
+  email: string;
+  phone?: string | null;
+  status: 'active' | 'disabled' | string;
+  lastLoginAt?: Iso | null;
+}
+
+export interface AuditEvent {
+  id: string;
+  at: Iso;
+  actorEmail: string | null;
+  action: string;
+  companyId: string | null;
+  companyName?: string | null;
+  target: string | null;
+  diff?: unknown;
+}
+
+export interface ProvisioningJob {
+  id: string;
+  companyId: string;
+  status: 'queued' | 'running' | 'succeeded' | 'failed' | string;
+  step?: string | null;
+  error?: string | null;
+  createdAt: Iso;
+  updatedAt?: Iso;
+}
+
+export interface OverviewResponse {
+  counts: { total: number; active: number; setup: number; suspended: number; archived: number; failedJobs: number; dbFailures: number };
+  attention: CompanyRow[];
+  recent: AuditEvent[];
+  provisioner: { ok: boolean; configured: boolean; principal?: string; error?: string };
+}
+
+export interface Plan {
+  id: string;
+  code: string;
+  name: string;
+  status: 'active' | 'archived';
+  priceMinor: number;
+  currency: string;
+  interval: 'month' | 'year' | 'one-time';
+  seats?: number | null;
+  limits?: Record<string, number | null>;
+  features?: string[];
+}
+
+export interface Subscription {
+  id: string;
+  companyId: string;
+  planId: string;
+  status: 'trial' | 'active' | 'past_due' | 'cancelled' | 'expired';
+  startsAt: Iso;
+  endsAt: Iso | null;
+  seats?: number | null;
+  notes?: string | null;
+}
+
+export interface SettingsField {
+  key: string;
+  label: string;
+  type: 'text' | 'number' | 'boolean' | 'select' | 'secret' | 'email' | 'url';
+  options?: string[];
+  /** Secret values come back masked (`set: true`), never in clear. */
+  value?: unknown;
+  set?: boolean;
+  help?: string;
+}
+export interface SettingsFamily {
+  family: string;
+  label: string;
+  scope: 'platform' | 'company';
+  fields: SettingsField[];
+}
+
+export interface SupportGrant {
+  id: string;
+  companyId: string;
+  companyName?: string;
+  requestedBy: string;
+  approvedBy?: string | null;
+  reason: string;
+  status: 'requested' | 'active' | 'expired' | 'revoked';
+  expiresAt: Iso | null;
+  createdAt: Iso;
+}
+
+export interface CompanyDomain {
+  id: string;
+  host: string;
+  primary: boolean;
+  verifiedAt: Iso | null;
+  verification?: { type: 'TXT'; name: string; value: string };
+}
+
+// ── React console (needs @dreamtree-org/twreact-ui ^2 and Tailwind scanning dist/platform.*) ──
+
+import type { ComponentType, ElementType, ReactNode } from 'react';
+import type { Brand, LegalLink } from './index.js';
+
+export interface PlatformPage {
+  /** Below the console base path, e.g. "jobs". Sub-paths are passed to `render` as `path`. */
+  path: string;
+  label: string;
+  icon?: ReactNode;
+  /** Nav group heading. */
+  group?: string;
+  /** Hide unless GET /me advertises this feature (e.g. "jobs"). */
+  feature?: PlatformFeature;
+  /** Hide unless the admin holds this permission. */
+  permission?: string;
+  render(ctx: { client: PlatformClient; path: string; navigate(href: string): void; href(rel?: string): string; me: PlatformMe | null | undefined }): ReactNode;
+}
+
+export interface PlatformCompanyTab {
+  id: string;
+  label: string;
+  render(ctx: { company: CompanyDetail; reload(): Promise<void>; client: PlatformClient; sensitive: <T>(action: () => Promise<T>) => Promise<T> }): ReactNode;
+}
+
+export interface PlatformConsoleProps {
+  /** From toLandingBrand(dreamtree.brand.json). */
+  brand: Brand;
+  appName?: string;
+  /** Where the console pages live. Default `/platform`. */
+  basePath?: string;
+  /** Where the API lives. Default `/api/platform`. */
+  apiBasePath?: string;
+  client?: PlatformClient;
+  /** Router integration (Next: usePathname() / router.push / next/link). Without them: window.location + history. */
+  pathname?: string;
+  navigate?: (href: string) => void;
+  linkAs?: ElementType;
+  /** Features to offer; each also needs the server to advertise it (GET /me). */
+  features?: readonly PlatformFeature[];
+  /** Product pages, e.g. the background-jobs console. */
+  pages?: PlatformPage[];
+  /** Extra tabs on the company page. */
+  companyTabs?: PlatformCompanyTab[];
+  /** "/c/:slug/login" or (slug) => path. Default: GET /me app.companyLoginPath, else "/c/:slug/login". */
+  companyLoginPath?: string | ((slug: string) => string);
+  adminEmail?: string;
+  /** Session resolved on the server (e.g. a Next layout) so the shell renders without a flash. */
+  initialMe?: PlatformMe | null;
+  /** Default `${basePath}/login`. */
+  loginPath?: string;
+  onSignOut?: () => void;
+}
+export const PlatformConsole: ComponentType<PlatformConsoleProps>;
+export function matchConsoleRoute(rel: string, pages?: PlatformPage[]): { view: string; id?: string; page?: PlatformPage; rest?: string };
+
+export interface PlatformLoginProps {
+  brand: Brand;
+  basePath?: string;
+  client?: PlatformClient;
+  /** Default: window.location.assign(redirectTo). */
+  onSignedIn?: (res: LoginResponse) => void;
+  redirectTo?: string;
+  title?: string;
+  subtitle?: string;
+  linkComponent?: ElementType;
+  legalLinks?: LegalLink[];
+}
+export const PlatformLogin: ComponentType<PlatformLoginProps>;
+
+export const PlatformShell: ComponentType<{
+  brand?: Brand;
+  appName?: string;
+  nav: Array<{ id: string; label: string; href?: string; icon?: ReactNode; active?: boolean; group?: string }>;
+  adminEmail?: string;
+  onSignOut?: () => void;
+  linkAs?: ElementType;
+  pageTitle?: string;
+  children?: ReactNode;
+}>;
+export const StepUpProvider: ComponentType<{ client: PlatformClient; totpEnrolled?: boolean; children?: ReactNode }>;
+export function useSensitive(): <T>(action: () => Promise<T>) => Promise<T>;
+export function usePlatform(): {
+  client: PlatformClient;
+  me: PlatformMe | null | undefined;
+  reloadMe(): Promise<void>;
+  Link: ElementType;
+  href(rel?: string): string;
+  navigate(href: string): void;
+  can(permission: string): boolean;
+  companyLoginPath(slug: string): string;
+  companyLoginUrl(slug: string): string;
+};
+export function useLoad<T = any>(path: string | null, query?: Query): { data: T | null; error: PlatformApiError | null; loading: boolean; reload(): Promise<void>; setData(data: T): void };
+export const StatusPill: ComponentType<{ status?: string | null }>;
+export const ModePill: ComponentType<{ mode?: string | null }>;
+export const HealthDot: ComponentType<{ ok?: boolean | null }>;
+export const Card: ComponentType<{ title: ReactNode; actions?: ReactNode; children?: ReactNode }>;
+export const Facts: ComponentType<{ rows: Array<[string, ReactNode]> }>;
+export const CopyButton: ComponentType<{ value: string; label?: string }>;
+export const OneTimeSecret: ComponentType<{ title?: string; loginUrl?: string; email: string; password: string; onDone?: () => void }>;
+export const InspectResult: ComponentType<{ report: Record<string, any> }>;
+export function describeAction(action: string): string;

package/schema.d.ts

@@ -94,3 +94,53 @@ export function hexToOklch(hex: string): { l: number; c: number; h: number };
 export function oklchToHex(c: { l: number; c: number; h: number }): string;
 export function isHex(v: unknown): boolean;
 export const PALETTE_STEPS: number[];
+
+// ---------------------------------------------------------------------------
+// Store documents (version 2): the landing page plus listing and product
+// template pages, the header/footer and the product card.
+
+export type StorePageKey = 'listing' | 'product';
+export type ListingSlot = 'collection_header' | 'toolbar' | 'filters' | 'results';
+export type ProductSlot = 'gallery' | 'buy_box' | 'highlights' | 'delivery' | 'seller' | 'inspection' | 'battery' | 'included' | 'specs' | 'policies' | 'similar';
+export type ContentBlock = 'promo_banner' | 'usp_strip' | 'trust_badges' | 'cta_cards' | 'faq' | 'rich_text' | 'testimonials' | 'brand_strip' | 'gallery';
+export interface SlotDef { label: string; description: string; required?: boolean; fields: FieldDef[] }
+export interface TemplateDef { label: string; description: string; /** Setting values that differ from the page's defaults. */ settings: Record<string, unknown>; /** Default block order. */ blocks: string[] }
+export interface StorePageDef { label: string; slots: Record<string, SlotDef>; settings: FieldDef[]; templates: Record<string, TemplateDef>; default: string }
+export interface TemplateBlock { id: string; type: string; enabled: boolean; props: Record<string, unknown> }
+export interface TemplatePage { template: string; settings: Record<string, unknown>; blocks: TemplateBlock[] }
+export interface GroupDef { key: string; kind: 'group'; label: string; fields: FieldDef[] }
+export interface StoreLink { label: string; href: string }
+export interface StoreChrome {
+  announcement: { enabled: boolean; text: string; href: string; tone: 'brand' | 'accent' | 'dark' };
+  header: { utility_text: string; show_search: boolean; category_nav: boolean; nav_links: StoreLink[]; sticky: boolean };
+  footer: { about: string; columns: { title: string; links: StoreLink[] }[]; socials: { network: string; href: string }[]; note: string };
+}
+export interface StoreCard { image_ratio: '4:3' | '1:1' | '3:4'; badges: boolean; spec_line: boolean; compare: boolean; quick_add: boolean; mrp: boolean; hover: 'none' | 'zoom' | 'second_image' }
+export interface StoreDoc { version: 2; pages: { home: PageDoc; listing: TemplatePage; product: TemplatePage }; chrome: StoreChrome; card: StoreCard }
+
+export const STORE_VERSION: 2;
+export const MAX_BLOCKS: number;
+export const STORE_PAGES: Record<StorePageKey, StorePageDef>;
+export const STORE_PAGE_KEYS: StorePageKey[];
+export const LISTING_SLOTS: Record<ListingSlot, SlotDef>;
+export const PRODUCT_SLOTS: Record<ProductSlot, SlotDef>;
+export const CONTENT_BLOCKS: ContentBlock[];
+export const CHROME_FIELDS: GroupDef[];
+export const CARD_FIELDS: FieldDef[];
+/** Normalise a store document (a version-1 landing page is migrated first) and report every problem by path. Required slots cannot be hidden or removed. */
+export function validateStore(doc: unknown): { ok: boolean; errors: ValidationError[]; doc: StoreDoc };
+/** A version-1 landing page (or nothing) wrapped into a store document with defaults. */
+export function migrateStore(page: unknown): StoreDoc;
+export function isLegacyPage(doc: unknown): boolean;
+export function defaultStore(store?: { name?: string; tagline?: string }): StoreDoc;
+/** A template page with that template's settings and default blocks (unknown template → the page default). */
+export function templatePage(page: StorePageKey, template?: string): TemplatePage;
+export function newBlock(page: StorePageKey, type: string): TemplateBlock;
+/** A slot or content section's definition on a page (slot: true for app-rendered blocks), or null. */
+export function blockDef(page: StorePageKey, type: string): ((SlotDef | SectionTypeDef) & { slot: boolean }) | null;
+export function defaultChrome(): StoreChrome;
+export function defaultCard(): StoreCard;
+/** Every uploaded-image reference in a document. */
+export function storeMediaRefs(doc: unknown): MediaRef[];
+/** Validate an object against a field list with the section rules; problems are pushed onto `errors`. */
+export function validateFields(defs: FieldDef[], obj: unknown, path: string, errors: ValidationError[]): Record<string, unknown>;