@proveanything/smartlinks 1.9.20 → 1.9.21

package/dist/docs/ui-utils.md

@@ -0,0 +1,127 @@
+# SmartLinks UI Utils (`@proveanything/ui-utils`)
+
+> Companion module to the SmartLinks SDK. Provides React primitives, hooks, and admin shells for building consistent microapp UIs.
+>
+> Package: `@proveanything/ui-utils`  
+> Install: `npm install @proveanything/ui-utils`
+
+---
+
+## What is this module for?
+
+`@proveanything/ui-utils` sits on top of `@proveanything/smartlinks`. The core SDK handles data — authentication, records, configurations, interactions. This module handles **UI** — the shared React components, hooks, and shell primitives that translate SDK data into consistent admin and public interfaces.
+
+**When do you need it?**
+
+- You are building an admin UI for a records-based microapp (see [records-admin-pattern.md](records-admin-pattern.md))
+- You want the standard inheritance/override editor for scoped records
+- You need the `useResolvedRecord` hook on the public widget side
+- You are using `parseRef` / `buildRef` for the standard `ref` convention
+
+You do **not** need it for apps that only use `appConfiguration`, basic widgets without scoped data, or executor bundles.
+
+---
+
+## Key exports
+
+### Records admin shell
+
+```tsx
+import { RecordsAdminShell } from '@proveanything/ui-utils';
+
+// Drop-in admin interface for any records-based app.
+// Reads the app's manifest `records` block to determine tabs and scopes.
+<RecordsAdminShell
+  collectionId={collectionId}
+  appId={appId}
+  recordType="nutrition"
+  renderForm={(record, parentRecord) => <NutritionForm record={record} parent={parentRecord} />}
+/>
+```
+
+`RecordsAdminShell` handles: left-rail product/scope browsing, variant/batch tab discovery, the "New record" button, inheritance markers, bulk operations, CSV import/export, and telemetry events. Your app only provides the domain form.
+
+### Record editor primitive
+
+```tsx
+import { RecordEditor } from '@proveanything/ui-utils';
+
+// Lower-level editor with inheritance diffing. Use when you need
+// custom layout but still want the inherited/override markers.
+<RecordEditor
+  record={variantRecord}
+  parentRecord={productRecord}
+  fields={nutritionFields}
+  onSave={(data) => app.records.update(collectionId, appId, record.id, { data }, true)}
+/>
+```
+
+### `useResolvedRecord` hook
+
+```ts
+import { useResolvedRecord } from '@proveanything/ui-utils/records';
+
+const { data, source, isLoading } = useResolvedRecord({
+  appId,
+  recordType: 'nutrition',
+  collectionId,
+  productId,
+  variantId,   // optional
+  batchId,     // optional
+  proofId,     // optional
+});
+// source: 'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'default' | null
+```
+
+Walks the resolution chain defined in [records-admin-pattern.md §4](records-admin-pattern.md#4-resolution-order-required) and returns the first matching record plus its source scope.
+
+### `resolveRecord` function
+
+```ts
+import { resolveRecord } from '@proveanything/ui-utils/records';
+
+// Async, non-hook version for executors and server-side logic.
+const resolved = await resolveRecord({
+  appId,
+  recordType: 'nutrition',
+  scope: { collectionId, productId, variantId, batchId, proofId },
+  supportedScopes: ['product', 'facet'], // optional — skip unsupported scopes
+});
+// → { record: AppRecord, source: string } | null
+```
+
+### `parseRef` / `buildRef` utilities
+
+```ts
+import { parseRef, buildRef } from '@proveanything/ui-utils/records';
+
+const parsed = parseRef('variant:prod_abc:var_500ml');
+// → { kind: 'variant', productId: 'prod_abc', variantId: 'var_500ml' }
+
+const ref = buildRef({ kind: 'facet', facetKey: 'bread_type', valueKey: 'sourdough' });
+// → 'facet:bread_type:sourdough'
+```
+
+See [records-admin-pattern.md Appendix A](records-admin-pattern.md#appendix-a--ref-parser-reference) for the full `ParsedRef` type and standalone implementation.
+
+---
+
+## Relationship to the core SDK
+
+```
+@proveanything/smartlinks       ← data layer (records, config, interactions, …)
+        ↑
+@proveanything/ui-utils         ← UI layer (components, hooks, admin shells)
+        ↑
+your microapp                   ← domain logic and custom forms
+```
+
+`ui-utils` imports from `@proveanything/smartlinks` internally. You should install both packages, but only import directly from each for their respective concerns — don't reach into `ui-utils` for SDK data primitives.
+
+---
+
+## Further reading
+
+- [records-admin-pattern.md](records-admin-pattern.md) — the data contract that `RecordsAdminShell` implements
+- [building-react-components.md](building-react-components.md) — dual-mode rendering rules that apply to all ui-utils components
+- [app-manifest.md](app-manifest.md) — the `records` manifest block that drives tab generation

package/dist/openapi.yaml

@@ -17134,6 +17134,10 @@ components:
           type: string
         allowAutoGenerateClaims:
           type: boolean
+        variants:
+          type: boolean
+        batches:
+          type: boolean
         defaultAuthKitId:
           type: string
       required:
@@ -17159,6 +17163,8 @@ components:
         - supported
         - roles
         - shortId
+        - variants
+        - batches
         - defaultAuthKitId
     AppConfig:
       type: object

package/dist/types/collection.d.ts

@@ -69,6 +69,8 @@ export interface Collection {
     portalUrl?: string;
     /** Allow users to claim products without providing a proof ID (auto-generates serial on-demand) */
     allowAutoGenerateClaims?: boolean;
+    variants: boolean;
+    batches: boolean;
     defaultAuthKitId: string;
 }
 export type CollectionResponse = Collection;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.20  |  Generated: 2026-04-17T10:13:30.466Z
+Version: 1.9.21  |  Generated: 2026-04-25T10:48:10.932Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2994,6 +2994,8 @@ interface Collection {
   secondaryColor?: string
   portalUrl?: string // URL for the collection's portal (if applicable)
   allowAutoGenerateClaims?: boolean
+  variants: boolean // does this collection support variants?
+  batches: boolean // does this collection support batches?
   defaultAuthKitId: string // default auth kit for this collection, used for auth
 }
 ```

package/docs/app-manifest.md

@@ -95,7 +95,20 @@ The manifest is loaded automatically by the platform for every collection page.
     { "title": "Home",     "path": "/" },
     { "title": "Gallery",  "path": "/gallery" },
     { "title": "Settings", "path": "/settings", "params": { "tab": "advanced" } }
-  ]
+  ],
+
+  "records": {
+    "nutrition": {
+      "scopes": ["product", "facet", "batch"],
+      "defaultScope": "facet",
+      "label": "Nutrition info"
+    },
+    "cooking_steps": {
+      "scopes": ["product", "facet"],
+      "defaultScope": "product",
+      "label": "Cooking steps"
+    }
+  }
 }
 ```
 
@@ -188,6 +201,30 @@ See the [Deep Link Discovery guide](deep-link-discovery.md) for the full dual-so
 | `path` | string | ❌ | Hash route within the app (defaults to `"/"` if omitted) |
 | `params` | object | ❌ | App-specific query params appended to the URL — do **not** include platform params (`collectionId`, `productId`, etc.) |
 
+#### `records`
+
+Declares which `app.records` record types the app stores, and which scopes each type supports. Required for any app that follows the [Records-Based Admin Pattern](records-admin-pattern.md). Omit if the app does not use scoped records.
+
+The platform and the `<RecordsAdminShell>` from `@proveanything/ui-utils` read this block to render only the relevant tabs and affordances.
+
+```json
+"records": {
+  "<recordType>": {
+    "scopes": ["product", "facet", "batch"],
+    "defaultScope": "facet",
+    "label": "Human-readable label"
+  }
+}
+```
+
+| Field          | Type     | Required | Description |
+|----------------|----------|----------|-------------|
+| `scopes`       | string[] | ✅ | Allowed scope kinds in resolution order. Valid values: `"product"`, `"variant"`, `"batch"`, `"facet"`, `"proof"`, `"default"`. |
+| `defaultScope` | string   | ✅ | The scope the "Create new" button targets in the admin shell. Must be one of the declared `scopes`. |
+| `label`        | string   | ✅ | Human-readable label for the record type, used in headings and tabs. |
+
+An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`).
+
 #### `executor`
 
 Declares the executor bundle — a standalone JS library for programmatic configuration, server-side SEO, and LLM content generation. Omit if the app has no executor.

package/docs/auth-kit.md

@@ -0,0 +1,162 @@
+# SmartLinks Auth Kit (`@proveanything/smartlinks` — `authKit` namespace)
+
+> End-user authentication flows for SmartLinks microapps. Covers email/password, magic links, phone OTP, Google OAuth, profile management, and password/email change flows.
+>
+> **This is part of the core SDK** — no separate install required. Import from `@proveanything/smartlinks`.
+
+---
+
+## What is Auth Kit for?
+
+Auth Kit is the **end-user identity layer** for microapps that need users to sign in. It is distinct from the admin/platform authentication (Bearer tokens) used to call admin endpoints.
+
+Use Auth Kit when:
+- Your app has a login/register screen for end users (not collection admins)
+- You need to gate features behind a verified user identity
+- You want to store user-specific data with the `userAppData` API (see [app-data-storage.md](app-data-storage.md))
+
+Do **not** use Auth Kit for:
+- Admin-side API calls (those use Bearer tokens set by the platform shell)
+- Claiming proofs (see proof claiming methods)
+
+---
+
+## Setup: creating an Auth Kit client
+
+Each app requires an Auth Kit configuration, created by a collection admin:
+
+```ts
+// Admin setup (one-time, done in admin console)
+import { authKit } from '@proveanything/smartlinks';
+
+// Returns an authKitId to store in your app config
+const config = await authKit.create(collectionId, {
+  name: 'My App Auth',
+  loginMethods: ['email', 'google', 'magic_link'],
+  redirectUrl: 'https://myapp.example.com/auth/callback',
+});
+```
+
+---
+
+## Key flows
+
+### Email / password
+
+```ts
+import { authKit } from '@proveanything/smartlinks';
+
+// Register
+const session = await authKit.register(clientId, {
+  email: 'user@example.com',
+  password: 'securePassword123',
+  displayName: 'Alice',
+});
+
+// Login
+const session = await authKit.login(clientId, 'user@example.com', 'securePassword123');
+
+// session.token — store this; pass to initializeApi for subsequent calls
+```
+
+### Magic link (passwordless email)
+
+```ts
+await authKit.sendMagicLink(clientId, {
+  email: 'user@example.com',
+  redirectUrl: 'https://myapp.example.com/auth/verify',
+});
+
+// On callback page, extract token from URL and verify
+const session = await authKit.verifyMagicLink(clientId, tokenFromUrl);
+```
+
+### Phone OTP
+
+```ts
+await authKit.sendPhoneCode(clientId, '+61400000000');
+const session = await authKit.verifyPhoneCode(clientId, '+61400000000', '123456');
+```
+
+### Google OAuth
+
+```ts
+// After Google sign-in, pass the id_token to Auth Kit
+const session = await authKit.googleLogin(clientId, googleIdToken);
+```
+
+---
+
+## Profile management
+
+```ts
+import { authKit } from '@proveanything/smartlinks';
+
+// Get current user's profile
+const profile = await authKit.getProfile(clientId);
+
+// Update profile
+await authKit.updateProfile(clientId, { displayName: 'Alice B.', avatarUrl: '...' });
+
+// Change password
+await authKit.changePassword(clientId, 'currentPass', 'newPass');
+
+// Change email (triggers verification)
+await authKit.changeEmail(clientId, 'newemail@example.com', 'password', redirectUrl);
+
+// Delete account
+await authKit.deleteAccount(clientId, 'password', 'DELETE');
+```
+
+---
+
+## Email verification
+
+Auth Kit can send and verify email addresses after registration:
+
+```ts
+await authKit.sendEmailVerification(clientId, {
+  userId,
+  email: 'user@example.com',
+  redirectUrl: 'https://myapp.example.com/auth/verified',
+});
+
+// On callback page
+await authKit.verifyEmail(clientId, tokenFromUrl);
+```
+
+---
+
+## Password reset
+
+```ts
+await authKit.requestPasswordReset(clientId, {
+  email: 'user@example.com',
+  redirectUrl: 'https://myapp.example.com/auth/reset',
+  clientName: 'My App',
+});
+
+// On reset page — verify token is still valid before showing the form
+await authKit.verifyResetToken(clientId, tokenFromUrl);
+
+// Complete reset
+await authKit.completePasswordReset(clientId, tokenFromUrl, 'newSecurePassword');
+```
+
+---
+
+## Relationship to other parts of the SDK
+
+| Concern | Where it lives |
+|---------|---------------|
+| End-user sign-in / register | `authKit` namespace (this doc) |
+| Admin Bearer token auth | Platform shell — not set by your app |
+| Per-user data storage | `userAppData` namespace — see [app-data-storage.md](app-data-storage.md) |
+| User identity in analytics | `userId` field on `analytics` and `interactions` calls |
+
+---
+
+## Further reading
+
+- [app-data-storage.md](app-data-storage.md) — storing user-specific data after login
+- [app-manifest.md](app-manifest.md) — `app.admin.json` setup questions for configuring `clientId`

package/docs/forms.md

@@ -0,0 +1,113 @@
+# SmartLinks Forms
+
+> Platform-managed form definitions and submissions. Covers the `form` data API (core SDK) and the `@proveanything/ui-forms` React package for schema-driven form UIs.
+
+---
+
+## Two layers
+
+| Layer | Package | What it does |
+|-------|---------|--------------|
+| **Forms data API** | `@proveanything/smartlinks` (`form` namespace) | CRUD for form definitions; stores submission schema |
+| **Forms UI** | `@proveanything/ui-forms` | React components that render a form definition, validate input, and submit |
+
+You can use the data API without the UI package (e.g. in an executor), but the UI package requires both.
+
+---
+
+## Forms data API (`form` namespace)
+
+The `form` namespace in the core SDK manages **form definitions** — the schema that describes fields, validation rules, and submission behaviour. This is an admin-side API.
+
+```ts
+import { form } from '@proveanything/smartlinks';
+
+// List all forms in a collection
+const forms = await form.list(collectionId, /* admin= */ true);
+
+// Get a specific form
+const myForm = await form.get(collectionId, formId);
+
+// Create a form (admin)
+const created = await form.create(collectionId, {
+  name: 'Warranty Registration',
+  fields: [
+    { id: 'name',    type: 'text',  label: 'Full name',       required: true },
+    { id: 'email',   type: 'email', label: 'Email address',   required: true },
+    { id: 'serial',  type: 'text',  label: 'Serial number',   required: true },
+    { id: 'receipt', type: 'file',  label: 'Proof of purchase' },
+  ],
+});
+
+// Update a form (admin)
+await form.update(collectionId, formId, { name: 'Warranty Registration v2' });
+
+// Delete a form (admin)
+await form.remove(collectionId, formId);
+```
+
+Form definitions are stored per-collection and referenced by `formId`.
+
+---
+
+## Forms UI (`@proveanything/ui-forms`)
+
+`@proveanything/ui-forms` provides React components that consume a form definition from the API and render a complete, accessible, validated form.
+
+Install: `npm install @proveanything/ui-forms`
+
+### Rendering a form
+
+```tsx
+import { SmartForm } from '@proveanything/ui-forms';
+
+// Fetches the form definition and renders it
+<SmartForm
+  collectionId={collectionId}
+  formId={formId}
+  onSubmit={async (values) => {
+    // handle submission — e.g. create an app.records entry or send via comms
+  }}
+/>
+```
+
+### Headless usage
+
+```tsx
+import { useFormDefinition, FormRenderer } from '@proveanything/ui-forms';
+
+const { fields, isLoading } = useFormDefinition(collectionId, formId);
+
+// Render fields yourself using the definition
+```
+
+---
+
+## Common patterns
+
+### Warranty / registration forms
+
+Define the form in `app.admin.json` setup or via the admin API. On the public widget, render with `<SmartForm>` and on submit create an `app.records` entry:
+
+```ts
+onSubmit={async (values) => {
+  await app.records.create(collectionId, appId, {
+    recordType: 'warranty_registration',
+    ref: `proof:${proofId}`,
+    data: values,
+  });
+}}
+```
+
+### Competition / feedback forms
+
+Same pattern — use `<SmartForm>` for capture and write to `app.records` or trigger an `interactions.appendEvent` on submit.
+
+---
+
+## Further reading
+
+- [app-objects.md](app-objects.md) — `app.records` for storing submissions
+- [app-data-storage.md](app-data-storage.md) — choosing the right storage model
+- [interactions.md](interactions.md) — firing events on form submission
+- [comms.md](comms.md) — sending confirmation emails after submission

package/docs/overview.md

@@ -64,6 +64,10 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Liquid Templates** | `docs/liquid-templates.md` | Dynamic content rendering with LiquidJS |
 | **Iframe Responder** | `docs/iframe-responder.md` | Iframe communication and proxy mode internals |
 | **AI Guide Template** | `docs/ai-guide-template.md` | Template for creating `public/ai-guide.md` — customise per app |
+| **Forms** | `docs/forms.md` | Form definitions, schema-driven rendering, submission patterns |
+| **Auth Kit** | `docs/auth-kit.md` | End-user sign-in: email/password, magic links, phone OTP, Google OAuth |
+| **Records Admin Pattern** | `docs/records-admin-pattern.md` | Standard pattern for per-product/facet/variant/batch admin UIs |
+| **UI Utils** | `docs/ui-utils.md` | `@proveanything/ui-utils` — React shells, hooks, and primitives for records-based apps |
 
 ---