@proveanything/smartlinks 1.9.19 → 1.9.21

package/dist/utils/conditions.js

@@ -93,7 +93,7 @@ function summarizeConditionSet(condition) {
     return `${(_a = condition.type) !== null && _a !== void 0 ? _a : 'and'} (${(_c = (_b = condition.conditions) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0} conditions)`;
 }
 function summarizeCondition(condition) {
-    var _a, _b;
+    var _a, _b, _c, _d, _e;
     switch (condition.type) {
         case 'country':
             return `country regions=${((_a = condition.regions) === null || _a === void 0 ? void 0 : _a.join(',')) || 'none'} countries=${((_b = condition.countries) === null || _b === void 0 ? void 0 : _b.join(',')) || 'none'} contains=${condition.contains}`;
@@ -115,6 +115,11 @@ function summarizeCondition(condition) {
             return `geofence contains=${condition.contains}`;
         case 'value':
             return `value field=${condition.field} ${condition.validationType} ${String(condition.value)}`;
+        case 'facet': {
+            const mode = (_c = condition.matchMode) !== null && _c !== void 0 ? _c : 'any';
+            const vals = (_e = (_d = condition.values) === null || _d === void 0 ? void 0 : _d.join(', ')) !== null && _e !== void 0 ? _e : '—';
+            return `facet key=${condition.facetKey} mode=${mode} values=[${vals}]`;
+        }
         case 'itemStatus':
             return `itemStatus ${condition.statusType}`;
         default:
@@ -143,6 +148,8 @@ async function evaluateConditionEntry(condition, params) {
             return validateGeofence(condition, params);
         case 'value':
             return validateValue(condition, params);
+        case 'facet':
+            return validateFacet(condition, params);
         case 'itemStatus':
             return validateItemStatus(condition, params);
         default:
@@ -162,6 +169,7 @@ async function evaluateConditionEntry(condition, params) {
  * - **user** - User authentication status (logged in, owner, admin)
  * - **product** - Product-specific conditions
  * - **tag** - Product tag-based conditions
+ * - **facet** - Product facet-based conditions (any/all/none of specific facet values)
  * - **date** - Time-based conditions (before, after, between dates)
  * - **geofence** - Location-based restrictions
  * - **value** - Custom field comparisons
@@ -730,6 +738,82 @@ async function validateValue(condition, params) {
         },
     };
 }
+/**
+ * Validate facet-based condition
+ */
+async function validateFacet(condition, params) {
+    var _a, _b, _c;
+    const { facetKey, matchMode = 'any', values = [] } = condition;
+    const facets = (_a = params.product) === null || _a === void 0 ? void 0 : _a.facets;
+    // No product
+    if (!((_b = params.product) === null || _b === void 0 ? void 0 : _b.id)) {
+        return {
+            passed: false,
+            detail: 'Product ID was not available.',
+            context: { facetKey, matchMode },
+        };
+    }
+    const assigned = (_c = facets === null || facets === void 0 ? void 0 : facets[facetKey]) !== null && _c !== void 0 ? _c : [];
+    const assignedKeys = assigned.map(v => v.key);
+    // Presence-only modes — ignore `values`
+    if (matchMode === 'hasFacet') {
+        return {
+            passed: assignedKeys.length > 0,
+            detail: `Product ${assigned.length > 0 ? 'has' : 'does not have'} values on facet '${facetKey}'.`,
+            context: { facetKey, assignedKeys },
+        };
+    }
+    if (matchMode === 'notHasFacet') {
+        return {
+            passed: assignedKeys.length === 0,
+            detail: `Product ${assigned.length === 0 ? 'has no' : 'has'} values on facet '${facetKey}'.`,
+            context: { facetKey, assignedKeys },
+        };
+    }
+    // Value-matching modes require at least one value to test
+    if (values.length === 0) {
+        return {
+            passed: false,
+            detail: `Facet condition for '${facetKey}' with matchMode '${matchMode}' requires at least one value.`,
+            context: { facetKey, matchMode },
+        };
+    }
+    if (matchMode === 'any') {
+        const matched = values.filter(v => assignedKeys.includes(v));
+        return {
+            passed: matched.length > 0,
+            detail: matched.length > 0
+                ? `Product matched facet '${facetKey}' value(s): [${matched.join(', ')}].`
+                : `Product did not match any of [${values.join(', ')}] on facet '${facetKey}'.`,
+            context: { facetKey, matchMode, testedValues: values, matched, assignedKeys },
+        };
+    }
+    if (matchMode === 'all') {
+        const missing = values.filter(v => !assignedKeys.includes(v));
+        return {
+            passed: missing.length === 0,
+            detail: missing.length === 0
+                ? `Product has all required values on facet '${facetKey}'.`
+                : `Product is missing [${missing.join(', ')}] on facet '${facetKey}'.`,
+            context: { facetKey, matchMode, testedValues: values, missing, assignedKeys },
+        };
+    }
+    if (matchMode === 'none') {
+        const matched = values.filter(v => assignedKeys.includes(v));
+        return {
+            passed: matched.length === 0,
+            detail: matched.length === 0
+                ? `Product correctly has none of [${values.join(', ')}] on facet '${facetKey}'.`
+                : `Product has forbidden value(s) [${matched.join(', ')}] on facet '${facetKey}'.`,
+            context: { facetKey, matchMode, testedValues: values, matched, assignedKeys },
+        };
+    }
+    return {
+        passed: false,
+        detail: `Unsupported facet matchMode '${matchMode}'.`,
+        context: { facetKey, matchMode },
+    };
+}
 /**
  * Validate item status condition
  */

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.19  |  Generated: 2026-04-16T12:41:11.180Z
+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
 }
 ```
@@ -6847,6 +6849,18 @@ interface UserInfo {
 interface ProductInfo {
   id: string
   tags?: Record<string, any>
+  * Facet values assigned to this product.
+  * Shape mirrors `ProductFacetMap`: a map of facet key → array of value objects.
+  * Each value object must have at minimum a `key` string property.
+  *
+  * @example
+  * ```ts
+  * {
+  *   material: [{ key: 'cotton', name: 'Cotton' }],
+  *   certifications: [{ key: 'organic', name: 'Organic' }, { key: 'recycled', name: 'Recycled' }]
+  * }
+  * ```
+  facets?: Record<string, Array<{ key: string; [k: string]: unknown }>>
 }
 ```
 

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 |
 
 ---