@dreamtree-org/landing-kit 0.8.0 → 0.10.0

package/MIGRATION.md

@@ -159,3 +159,33 @@ Nothing changes for products that don't use it. The server half, `createPlatform
 - Credential-custodian "Reveal URL" with a reason, audited.
 
 **Not in the console yet:** plans and subscriptions, platform settings, support access and domains. Their server endpoints come first (tenancy). The nav shows them only when `GET /me` advertises them.
+
+## 0.9.0 — store documents (additive)
+
+A store's landing, listing and product pages, its header and footer, and its product card are now one
+version-2 document (`validateStore` from `/schema`). Nothing changes for apps that keep version-1 tenant pages.
+
+- To adopt it, run each stored v1 page through `migrateStore(page)`. It becomes `pages.home`, and the listing
+  and product pages get their default templates. `validateStore` migrates a v1 page itself, so an app can
+  switch over on its next save.
+- Listing and product pages are templates whose blocks are either app **slots** (`filters`, `results`,
+  `gallery`, `buy_box`…, rendered by the app through `TemplateRegion`'s `slots`) or ordinary content sections.
+  Required slots cannot be hidden or removed.
+- `safeHref` now rejects links containing a backslash, and registry lookups (`blockDef`, `templatePage`) ignore
+  inherited keys, so `__proto__` or `constructor` is an unknown type.
+
+## 0.10.0 — Platform console: plans, settings, support access, domains (additive)
+
+The console now shows the v1.1 features that `@dreamtree-org/tenancy` 0.5.0 serves. Nothing appears until the
+server advertises it in `GET /me`, so a product on tenancy 0.4.0 sees no change.
+
+- **New pages:** Plans (`/platform/plans`, `plans.read`) and Support access (`/platform/support-access`,
+  `support.request`).
+- **New company tabs**, between Admins and the product's `companyTabs`: Subscription, Domains, Settings and
+  Support. Each needs its feature and read permission.
+- `'domains'` joins `PLATFORM_FEATURES` and the `PlatformFeature` type. `usePlatform()` gains `features`.
+- New exports: `formatPrice`, `PlansView`, `SupportAccessView`, `SupportGrants`, `SubscriptionTab`,
+  `DomainsTab`, `SettingsTab`, `SupportTab`.
+- A product that already has its own settings or subscription tab in `companyTabs` should drop it once the
+  server serves the built-in one, or the company page shows both.
+

package/PLATFORM-API.md

@@ -5,7 +5,7 @@ server only through this contract. The server side is `createPlatformApi` in `@d
 mounted with `./next` (`app/api/platform/[...path]/route.ts`) or `./express` (`app.use('/api/platform', …)`).
 A product that implements these endpoints itself gets the same console.
 
-**Server status.** `@dreamtree-org/tenancy` 0.4.0 implements everything marked shipped, plus these v1.1 items: TOTP, throttle, rotation, `/me`, roles and audit. Plans, settings, support access and domains come next.
+**Server status.** `@dreamtree-org/tenancy` 0.5.0 implements the whole contract: everything marked shipped, and every v1.1 item (TOTP, throttle, rotation, `/me`, roles, audit, plans, settings, support access and domains). The console in landing-kit 0.10.0 shows all of them.
 
 The contract was taken from procurementpro's `app/api/platform/**`, the reference console. Paths are
 relative to the base path, `/api/platform` by default (`createPlatformClient({ basePath })`).
@@ -63,14 +63,16 @@ relative to the base path, `/api/platform` by default (`createPlatformClient({ b
 ```json
 {
   "admin": { "id": "…", "email": "…", "roles": ["superadmin"], "totpEnrolled": true },
-  "permissions": ["companies.read", "companies.write", "admins.write", "jobs.write", "db.reveal", "plans.write", "settings.write", "support.grant"],
+  "permissions": ["companies.read", "companies.write", "admins.write", "jobs.write", "db.reveal", "plans.write", "settings.write", "support.grant", "domains.write"],
   "access": { "console": true, "stepUpFresh": false },
   "features": { "jobs": true, "plans": true, "settings": true, "support": true, "domains": true, "audit": true },
   "app": { "key": "procurementpro", "name": "ProcurementPro", "companyLoginPath": "/c/:slug/login" }
 }
 ```
 
-**Roles.** `superadmin` holds every permission. `support` holds `companies.read`, `admins.read`, `jobs.read`, `audit.read`, `plans.read` and `support.request`.
+**Roles.** `superadmin` holds every permission. `support` holds `companies.read`, `admins.read`, `jobs.read`, `audit.read`, `plans.read`, `domains.read` and `support.request`.
+
+**Permissions per v1.1 feature:** plans and subscriptions use `plans.read` / `plans.write`; settings use `settings.read` / `settings.write`; support access uses `support.request` (list and request) and `support.grant` (approve and revoke); domains use `domains.read` / `domains.write`.
 
 Until `/me` exists, the console falls back to the shipped feature set (overview, companies, admins, and
 jobs when `GET /jobs` answers `enabled: true`).
@@ -157,14 +159,16 @@ advertised.
 | POST | `/plans` | `Plan` without `id` | **step-up** | v1.1 |
 | PATCH | `/plans/:id` | any `Plan` field | Archive with `{ status: "archived" }`; plans are never deleted. **step-up** | v1.1 |
 | GET | `/companies/:id/subscription` | — | `{ subscription: Subscription \| null, history: Subscription[] }` | v1.1 |
-| PUT | `/companies/:id/subscription` | `{ planId, status, startsAt?, endsAt?, seats?, notes? }` | **step-up** | v1.1 |
+| PUT | `/companies/:id/subscription` | `{ planId, status, startsAt?, endsAt?, seats?, notes? }` | `{ subscription, history }`. Appends a row; an archived plan is refused unless the company is already on it. **step-up** | v1.1 |
 
-### Platform settings
+### Company settings
 
 | Method | Path | Body | Response / notes | Status |
 |---|---|---|---|---|
-| GET | `/settings` | `?company=` (omit for platform defaults) | `{ families: SettingsFamily[] }`, with secret values masked | v1.1 |
-| PUT | `/settings/:family` | `{ companyId?, values }` | Secret fields are write-only. **step-up** | v1.1 |
+| GET | `/settings` | `?company=` (required) | `{ families: SettingsFamily[], version }`. Secret fields carry `set`, never a value | v1.1 |
+| PUT | `/settings/:family` | `{ companyId, values, version }` | `{ ok, changed, families, version }`. A blank secret keeps the stored one; a stale `version` answers 409 `CONFLICT`. The audit records the keys changed, never the values. **step-up** | v1.1 |
+
+Settings are per company. Platform-wide settings are not part of the contract yet.
 
 ### Support access
 
@@ -174,8 +178,8 @@ data (knowledge doc §5.8).
 | Method | Path | Body | Response / notes | Status |
 |---|---|---|---|---|
 | GET | `/support-access` | `?company&status` | `{ grants: SupportGrant[] }` | v1.1 |
-| POST | `/support-access` | `{ companyId, reason, minutes }` | Request a grant | v1.1 |
-| POST | `/support-access/:id` | `{ action: "approve" \| "revoke" }` | **step-up** | v1.1 |
+| POST | `/support-access` | `{ companyId, reason, minutes }` | `{ grant }`. Reason 8–255 characters; minutes 15–480. An unapproved request lapses after a day | v1.1 |
+| POST | `/support-access/:id` | `{ action: "approve" \| "revoke" }` | `{ grant }`. The requester cannot approve their own grant; the window starts at approval. **step-up** | v1.1 |
 
 ### Domains
 
@@ -183,7 +187,7 @@ data (knowledge doc §5.8).
 |---|---|---|---|---|
 | GET | `/companies/:id/domains` | — | `{ domains: CompanyDomain[] }` | v1.1 |
 | POST | `/companies/:id/domains` | `{ host }` | `{ domain, verification: { type: "TXT", name, value } }` | v1.1 |
-| POST | `/companies/:id/domains/:domainId` | `{ action: "verify" \| "make-primary" \| "remove" }` | `remove` needs **step-up** | v1.1 |
+| POST | `/companies/:id/domains/:domainId` | `{ action: "verify" \| "make-primary" \| "remove" }` | `verify` answers `{ ok, verified, domain }` (`verified: false` until the TXT record is published). The first verified domain becomes primary. `remove` needs **step-up** | v1.1 |
 
 ## Shapes
 
@@ -206,8 +210,8 @@ The server writes one `platform_audit_events` row per mutating call. Action name
 - `company.admin.create`, `branch.create`
 - `database.test`, `database.replace`, `database.credentials.reveal`
 - `job.run`, `job.retry`, `schedule.create`
-- `plan.update`, `subscription.update`, `settings.update`
-- `support.grant.request`, `support.grant.approve`
-- `domain.add`
+- `plan.create`, `plan.update`, `subscription.update`, `settings.update`
+- `support.grant.request`, `support.grant.approve`, `support.grant.revoke`
+- `domain.add`, `domain.verify`, `domain.primary`, `domain.remove`
 
 Products may add their own actions under their app key.

package/README.md

@@ -54,7 +54,7 @@ Every star ⭐, share, and contribution helps more than you know. Thank you for
   - `<LandingPage brand={brand} content={content} />` — a product's landing page is a content file.
   - `<AuthShell brand={brand} title="Welcome back">…</AuthShell>` (also available at `@dreamtree-org/landing-kit/auth` + `@dreamtree-org/landing-kit/auth.css`).
   - The built-in `brands` / `getBrand(id)` registry is **deprecated** (warns once, removed in 0.5.0).
-- **Platform admin console** (`@dreamtree-org/landing-kit/platform`, 0.8.0+): one HTTP contract ([PLATFORM-API.md](./PLATFORM-API.md)) that every product's super-administrator console speaks, and its browser client (`createPlatformClient`, `createStepUp`). The server half is `createPlatformApi` in `@dreamtree-org/tenancy`. The shared React shell and views (overview, companies, jobs, admins, audit, plans, settings, support access) build on this client.
+- **Platform admin console** (`@dreamtree-org/landing-kit/platform`, 0.8.0+): one HTTP contract ([PLATFORM-API.md](./PLATFORM-API.md)) that every product's super-administrator console speaks, and its browser client (`createPlatformClient`, `createStepUp`). The server half is `createPlatformApi` in `@dreamtree-org/tenancy`. The shared React shell and views (overview, companies, jobs, admins, audit; and from 0.10.0 plans, subscriptions, company settings, support access and domains) build on this client.
 - Plain CSS (`--dt-*` custom properties). It looks the same under Tailwind 3, Tailwind 4 (preflight or not) or no Tailwind. Dark mode via `[data-theme="dark"]` or `.dark`.
 - Built for prerendered, **un-hydrated** pages (fast and crawlable): `enhanceLanding()` wires the menu and the demo button in a few hundred bytes. It also works hydrated in an SPA or Next.js (`'use client'`, `onBookDemo`, `linkComponent`).
 - Responsive from 320px up. The nav folds into a menu below 1024px. Checked with Playwright at 320/375/768/1024/1440, light and dark.
@@ -202,6 +202,32 @@ import '@dreamtree-org/landing-kit/styles.css';
 - `newSection(type)` / `sectionDefaults(type)` start a section with valid defaults; `defaultPage({ name, tagline })`
   is a neutral starting page.
 
+### Store documents (0.9.0): landing, listing and product pages as one document
+
+A store's whole storefront design is one version-2 document, validated with `validateStore` from `/schema`:
+
+```js
+{ version: 2,
+  pages: { home: PageDoc /* the landing page above */,
+           listing: { template: 'classic' | 'topbar' | 'editorial', settings, blocks },
+           product: { template: 'classic' | 'immersive' | 'compact', settings, blocks } },
+  chrome: { announcement, header, footer },   // CHROME_FIELDS
+  card: { image_ratio, badges, spec_line, compare, quick_add, mrp, hover } }  // CARD_FIELDS
+```
+
+- `STORE_PAGES[page]` lists each page's `settings` (field defs, so a builder generates the form), `templates`
+  (setting values + default block order) and `slots`: the commerce blocks the app renders (results, filters,
+  gallery, buy box…). `required` slots can be moved, never removed or hidden, so a page always sells.
+- Between the slots a page may place content sections from `CONTENT_BLOCKS` (promo banner, FAQ, USP strip…),
+  validated with the same rules as landing-page sections. At most `MAX_BLOCKS` (12) blocks per page.
+- A version-1 landing page passed to `validateStore` is migrated (`migrateStore`): it becomes `pages.home`
+  and everything else takes its defaults. `isLegacyPage(doc)` tells them apart.
+- Render a template page with `<TemplateRegion blocks slots theme resolveMedia />`: `slots[type]` is the app's
+  component for a commerce block (`{ block, props }`; return null to place it yourself), content sections render
+  like `TenantPage`.
+- Helpers: `templatePage(page, template)`, `newBlock(page, type)`, `blockDef(page, type)`, `defaultStore`,
+  `defaultChrome`, `defaultCard`, `storeMediaRefs(doc)` (every `{ media_id }` to check before storing), `validateFields`.
+
 ### `<AuthShell>` & `@dreamtree-org/landing-kit/auth`
 
 The shared auth frame for login, signup, password reset, consent and platform-admin sign-in (`desktop [ brand panel 40% | form card ]`, `mobile [ logo · form card · footer · legal links ]`). Import from `@dreamtree-org/landing-kit` or the lightweight `@dreamtree-org/landing-kit/auth` subpath (with `@dreamtree-org/landing-kit/auth.css` or `styles.css`).

package/ai-skills/landing-kit.md

@@ -59,7 +59,7 @@ const { password } = await sensitive(() => api.post(`admins/${id}`, { action: 'r
 - **Cancelled step-up.** A step-up the admin cancels rejects with `code: 'CANCELLED'`. Treat it as a no-op, not an error toast.
 - **Enrollment gate.** A 403 `TOTP_ENROLLMENT_REQUIRED`, or `me.access.console === false`, means show the authenticator enrolment screen (`POST me/totp` with `begin`, then `verify`), not an error.
 - **One-time secrets.** New passwords and revealed DB URLs come back exactly once. Show them in a copy-once panel, and never log them or put them in state that persists.
-- **Feature gating.** Call `GET me` (v1.1 servers) and pass the result to `enabledFeatures(PLATFORM_FEATURES, me)`. That decides which nav items to show: jobs, plans, audit, support, settings. Older servers fall back to overview, companies, jobs and admins.
+- **Feature gating.** Call `GET me` (v1.1 servers) and pass the result to `enabledFeatures(PLATFORM_FEATURES, me)`. That decides which nav items and company tabs to show: jobs, plans, audit, support, settings, domains. Older servers fall back to overview, companies, jobs and admins.
 
 ## React console
 
@@ -76,13 +76,14 @@ const { password } = await sensitive(() => api.post(`admins/${id}`, { action: 'r
   - Companies: list, 4-step new-company wizard, detail with overview, branches, database (test, sync, replace, reveal), admins, jobs and activity
   - Background jobs: runs, schedules, workers and queues
   - Platform admins
-- **v1.1:**
+- **v1.1** (served by tenancy 0.5.0, shown by landing-kit 0.10.0):
   - TOTP sign-in and enrolment, login throttle, `GET /me` with a role-based permission list
   - Global audit viewer and CSV export
-  - Plans and per-company subscriptions
-  - Platform and company settings (secret fields are write-only)
-  - Support-access grants
-  - Company domains
+  - Plans page, and a Subscription tab on each company
+  - Settings tab on each company (secret fields are write-only; saves carry `version`)
+  - Support access page, and a Support tab on each company (a second admin approves)
+  - Domains tab on each company (TXT verification, primary, remove)
+- **Built in, not product tabs.** Subscription, Domains, Settings and Support are console built-ins that appear when `GET /me` advertises the feature. Don't re-implement them in `companyTabs`.
 
 ## Security invariants (do not weaken)