@proveanything/smartlinks 1.11.6 → 1.11.8

package/dist/api/interactions.d.ts

@@ -1,4 +1,4 @@
-import type { AdminInteractionsCountsByOutcomeRequest, AdminInteractionsQueryRequest, AdminInteractionsAggregateRequest, AdminInteractionsAggregateResponse, AppendInteractionBody, UpdateInteractionBody, OutcomeCount, InteractionEventRow, PublicInteractionsCountsByOutcomeRequest, PublicInteractionsByUserRequest, CreateInteractionTypeBody, UpdateInteractionTypeBody, ListInteractionTypesQuery, InteractionTypeRecord, InteractionTypeList } from "../types/interaction";
+import type { AdminInteractionsCountsByOutcomeRequest, AdminInteractionsQueryRequest, AdminInteractionsAggregateRequest, AdminInteractionsAggregateResponse, AppendInteractionBody, UpdateInteractionBody, OutcomeCount, InteractionEventRow, PublicInteractionsCountsByOutcomeRequest, PublicInteractionsByUserRequest, SubmitInteractionResponse, SubmitInteractionError, CreateInteractionTypeBody, UpdateInteractionTypeBody, ListInteractionTypesQuery, InteractionTypeRecord, InteractionTypeList } from "../types/interaction";
 export declare namespace interactions {
     /**
      * POST /admin/collection/:collectionId/interactions/query
@@ -30,11 +30,14 @@ export declare namespace interactions {
         success: true;
     }>;
     /**
-       * Appends one interaction event from a public source.
+       * POST /api/v1/public/collection/:collectionId/interactions/submit
+       *
+       * Submits an interaction event from a public/client-side context.
+       * When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor
+       * `contactId` is required. Pass `anonId` inside `metadata` to enable
+       * device-level deduplication via `uniquePerAnonId`.
        */
-    function submitPublicEvent(collectionId: string, body: AppendInteractionBody): Promise<{
-        success: true;
-    }>;
+    function submitPublicEvent(collectionId: string, body: AppendInteractionBody): Promise<SubmitInteractionResponse | SubmitInteractionError>;
     function create(collectionId: string, body: CreateInteractionTypeBody): Promise<InteractionTypeRecord>;
     function list(collectionId: string, query?: ListInteractionTypesQuery): Promise<InteractionTypeList>;
     function get(collectionId: string, id: string): Promise<InteractionTypeRecord>;

package/dist/api/interactions.js

@@ -73,12 +73,14 @@ export var interactions;
     }
     interactions.updateEvent = updateEvent;
     /**
-       * Appends one interaction event from a public source.
+       * POST /api/v1/public/collection/:collectionId/interactions/submit
+       *
+       * Submits an interaction event from a public/client-side context.
+       * When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor
+       * `contactId` is required. Pass `anonId` inside `metadata` to enable
+       * device-level deduplication via `uniquePerAnonId`.
        */
     async function submitPublicEvent(collectionId, body) {
-        if (!body.userId && !body.contactId) {
-            throw new Error("AppendInteractionBody must include one of userId or contactId");
-        }
         const path = `/public/collection/${encodeURIComponent(collectionId)}/interactions/submit`;
         return post(path, body);
     }

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.11.6  |  Generated: 2026-05-01T13:42:06.488Z
+Version: 1.11.8  |  Generated: 2026-05-03T08:12:27.170Z
 
 This is a concise summary of all available API functions and types.
 
@@ -5153,6 +5153,10 @@ interface InteractionPermissions {
   * Authenticated summary visibility (counts, aggregates) when user is signed in.
   allowAuthenticatedSummary?: boolean
   allowOwnRead?: boolean
+  uniquePerAnonId?: boolean
+  * Time window in seconds for `uniquePerAnonId` enforcement.
+  * `0` or omitted means all-time deduplication.
+  uniquePerAnonIdWindowSeconds?: number
 }
 ```
 
@@ -5220,6 +5224,30 @@ interface ListInteractionTypesQuery {
 }
 ```
 
+**SubmitInteractionResponse** (interface)
+```typescript
+interface SubmitInteractionResponse {
+  success: true
+  eventId: string
+}
+```
+
+**SubmitInteractionError** (interface)
+```typescript
+interface SubmitInteractionError {
+  error: 'FORBIDDEN'
+  reason:
+  | 'not_public'
+  | 'auth_required'
+  | 'duplicate'
+  | 'duplicate_anon'
+  | 'disabled'
+  | 'before_start'
+  | 'after_end'
+  | 'origin_forbidden'
+}
+```
+
 ### jobs
 
 **Job** (interface)
@@ -8333,47 +8361,47 @@ POST /admin/collection/:collectionId/interactions/append Appends one interaction
 POST /admin/collection/:collectionId/interactions/append Appends one interaction event.
 
 **submitPublicEvent**(collectionId: string,
-    body: AppendInteractionBody) → `Promise<`
-Appends one interaction event from a public source.
+    body: AppendInteractionBody) → `Promise<SubmitInteractionResponse | SubmitInteractionError>`
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **create**(collectionId: string,
     body: CreateInteractionTypeBody) → `Promise<InteractionTypeRecord>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **list**(collectionId: string,
     query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **get**(collectionId: string,
     id: string) → `Promise<InteractionTypeRecord>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **update**(collectionId: string,
     id: string,
     patchBody: UpdateInteractionTypeBody) → `Promise<InteractionTypeRecord>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **remove**(collectionId: string,
     id: string) → `Promise<void>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicCountsByOutcome**(collectionId: string,
     body: PublicInteractionsCountsByOutcomeRequest,
     authToken?: string) → `Promise<OutcomeCount[]>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicMyInteractions**(collectionId: string,
     body: PublicInteractionsByUserRequest,
     authToken?: string) → `Promise<InteractionEventRow[]>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicList**(collectionId: string,
     query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicGet**(collectionId: string,
     id: string) → `Promise<InteractionTypeRecord>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 ### jobs
 

package/dist/docs/app-manifest.md

@@ -270,7 +270,7 @@ See the [Deep Link Discovery guide](deep-link-discovery.md) for the full dual-so
 
 #### `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.
+Declares which `app.records` record types the app stores, and which scopes each type supports. Required for any app that follows the [App Records Pattern](app-records-pattern.md). Omit if the app does not use scoped records.
 
 The platform and the `<RecordsAdminShell>` from `@proveanything/smartlinks-utils-ui` read this block to render the right scope tabs, rule editor, and cardinality-appropriate right pane.
 
@@ -294,7 +294,7 @@ The platform and the `<RecordsAdminShell>` from `@proveanything/smartlinks-utils
 | `scopes`          | string[] | — | Allowed scope kinds in resolution order. Valid values: `"collection"`, `"product"`, `"variant"`, `"batch"`, `"facet"`, `"proof"`, `"rule"`. `'rule'` is a synthetic scope holding `facetRule`-targeted records. `'collection'` replaces the legacy empty-ref catch-all — **there is no `'global'` scope**. |
 | `defaultScope`    | string   | — | The scope the "Create new" button targets in the admin shell. Must be one of the declared `scopes`. |
 
-An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`). See [records-admin-pattern.md](records-admin-pattern.md) for the full admin + public pattern.
+An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`). See [app-records-pattern.md](app-records-pattern.md) for the full admin + public pattern.
 
 #### `executor`
 

package/dist/docs/app-objects.md

@@ -445,7 +445,7 @@ const productComments = await app.threads.list(collectionId, appId, {
 - **Usage logs** — record product usage metrics
 - **Audit trails** — immutable logs of actions
 - **Loyalty points** — track points earned/redeemed
-- **Per-product / per-facet configuration** — scoped data that varies by product axis (see [records-admin-pattern.md](records-admin-pattern.md))
+- **Per-product / per-facet configuration** — scoped data that varies by product axis (see [app-records-pattern.md](app-records-pattern.md))
 
 ### Key Features
 
@@ -526,7 +526,7 @@ proof  →  batch  →  variant  →  product  →  rule(*)  →  facet(*)  →
 - `facet(*)` — legacy single-facet anchors, walked alphabetically. Prefer `facetRule` for new work.
 - `collection` — the top of the chain and the catch-all for any record with no anchor fields. **There is no `'global'` tier above collection.**
 
-For a **singleton** record type (one answer wins), use `useResolvedRecord` — it performs this walk server-side and returns the first match plus a `matchedAt` tag. For a **collection** record type (every match is shown), use `useCollectedRecords`. See [records-admin-pattern.md §2](records-admin-pattern.md#2-resolution-order-one-canonical-chain) for the full guide.
+For a **singleton** record type (one answer wins), use `useResolvedRecord` — it performs this walk server-side and returns the first match plus a `matchedAt` tag. For a **collection** record type (every match is shown), use `useCollectedRecords`. See [app-records-pattern.md §2](app-records-pattern.md#2-resolution-order-one-canonical-chain) for the full guide.
 
 ### Singleton Cardinality
 

package/{docs/records-admin-pattern.md → dist/docs/app-records-pattern.md}

@@ -1,4 +1,4 @@
-# SmartLinks Records — Admin & Public Pattern
+# SmartLinks App Records Pattern
 
 > Canonical guide for microapps that store **per-product**, **per-facet**, **per-variant**, **per-batch**, or **rule-targeted** data.
 >
@@ -172,6 +172,26 @@ import { FacetRuleEditor } from '@proveanything/smartlinks-utils-ui/facet-rule-e
 
 ## 5. Public side — pick the right hook (this is where apps go wrong)
 
+> **Admin vs public — the rule is simple:**
+>
+> | Function | Public widget | Admin dashboard |
+> |---|---|---|
+> | `app.records.create(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.list(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.get(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.update(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.remove(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.aggregate(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.match(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.resolveAll(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.upsert()` | ❌ admin only — no public path | ✅ |
+> | `app.records.bulkUpsert()` | ❌ admin only — no public path | ✅ |
+> | `app.records.bulkDelete()` | ❌ admin only — no public path | ✅ |
+> | `app.records.restore()` | ❌ admin only — no public path | ✅ |
+> | `app.records.previewRule()` | ❌ admin only — no public path | ✅ |
+>
+> The `admin` parameter on `match()` and `resolveAll()` defaults to `false`, so public widgets that omit it are fine. **Never hardcode `true` in a public widget.** The hooks below always use the public path and are the recommended approach — prefer them over raw SDK calls in widget code.
+
 There is exactly **one decision** to make on the public side, and it follows from the manifest's `cardinality`:
 
 ### 5a. Singleton → `useResolvedRecord` (best match wins)
@@ -236,6 +256,10 @@ const { entries, isLoading } = useResolveAllRecords({
 | ❌ Anti-pattern                                            | ✅ Do this instead                                                |
 | ---------------------------------------------------------- | ----------------------------------------------------------------- |
 | Calling `SL.app.records.list()` and filtering client-side  | `useResolvedRecord` (singleton) or `useCollectedRecords` (collection). The server already knows the chain. |
+| Calling `SL.app.records.list(…, true)` from a public widget | Omit the `admin` flag (defaults to `false`). `list()` has a public path — just don't pass `true`. |
+| Calling `SL.app.records.match(…, true)` from a public widget | Omit the `admin` flag (defaults to `false`) or use `useResolvedRecord` / `useCollectedRecords`. |
+| Calling `SL.app.records.resolveAll(…, true)` from a public widget | Omit the `admin` flag (defaults to `false`) or use `useResolveAllRecords`. |
+| Calling `upsert`, `bulkUpsert`, `bulkDelete`, or `previewRule` from widget code | Those are admin-only. Widget code reads data — it never writes records directly. |
 | Walking the chain by hand with multiple `getConfig` calls  | One hook call. The resolver is tested, cached, and includes rules. |
 | Treating `facet:key:value` refs as the rule mechanism      | Use `facetRule` (`{ all: [{ facetKey, anyOf: [...] }] }`). Multi-condition, scored by specificity. |
 | Reading `matchedAt === 'global'`                           | There is no `'global'`. The top of the chain is `'collection'`.  |
@@ -302,4 +326,4 @@ interface EditorContext<TData> {
 
 ---
 
-_End of doc. If anything below the SDK contradicts this file, this file wins — open a PR against the SDK to bring the two back into sync._
+_End of doc. If anything below the SDK contradicts this file, this file wins — open a PR against the SDK to bring the two back into sync._

package/dist/docs/interactions.md

@@ -119,18 +119,37 @@ await SL.interactions.appendEvent(collectionId, {
 
 ### Public Event Submit
 
-Use in client-side app code. Same body shape as `appendEvent` but hits the public endpoint (respects interaction permissions like `allowPublicSubmit`, `requireAuth`).
+Use in client-side app code. Hits the public endpoint and respects interaction permissions (`allowPublicSubmit`, `allowAnonymousSubmit`, `requireAuth`, etc.).
 
 ```typescript
+// Authenticated submission
 await SL.interactions.submitPublicEvent(collectionId, {
   appId: 'my-app',
   interactionId: 'competition-entry',
   outcome: 'entered',
-  userId: currentUser.id,
+  contactId: currentUser.contactId,
   metadata: { answer: 'Paris' },
 });
+
+// Anonymous submission (interaction must have allowAnonymousSubmit: true)
+const response = await SL.interactions.submitPublicEvent(collectionId, {
+  appId: 'my-app',
+  interactionId: 'nps-score',
+  outcome: '9',
+  metadata: {
+    anonId: SL.utils.getAnonId(),  // device-level dedup signal
+  },
+});
+
+if (!response.success) {
+  if (response.reason === 'duplicate_anon') {
+    // this device has already submitted
+  }
+}
 ```
 
+> **Anonymous submissions** — when `allowAnonymousSubmit: true` is set on the interaction, neither `userId` nor `contactId` is required. Use `utils.getAnonId()` to generate a stable browser-local UUID and pass it as `metadata.anonId`; the server will enforce `uniquePerAnonId` if configured.
+
 ### Update an Existing Event
 
 ```typescript
@@ -237,6 +256,8 @@ Set on the interaction type definition via `permissions`:
 | `uniquePerUser` | boolean | Prevent duplicate submissions per user |
 | `uniquePerUserWindowSeconds` | number | Time window for uniqueness (e.g., `86400` = 1 day) |
 | `uniqueOutcome` | string | Outcome tag to check for duplicates (e.g., `"submitted"`) |
+| `uniquePerAnonId` | boolean | Reject a second submission that carries the same `anonId` in metadata |
+| `uniquePerAnonIdWindowSeconds` | number | Time window for `uniquePerAnonId` enforcement; `0` or omitted = all-time |
 | `allowPublicSummary` | boolean | Show counts/aggregates to unauthenticated users |
 | `allowAuthenticatedSummary` | boolean | Show counts/aggregates to authenticated users |
 | `allowOwnRead` | boolean | Let users read their own event history via public API |
@@ -263,8 +284,10 @@ When defining a journey trigger, reference the `interactionId` that should fire
 
 ```typescript
 import type {
-  AppendInteractionBody,          // Event body for appendEvent / submitPublicEvent
+  AppendInteractionBody,          // Event body for appendEvent and submitPublicEvent
   UpdateInteractionBody,          // Event body for updateEvent
+  SubmitInteractionResponse,      // { success: true; eventId: string }
+  SubmitInteractionError,         // { error: 'FORBIDDEN'; reason: string }
   InteractionEventRow,            // Raw event record returned by query()
   OutcomeCount,                   // { outcome: string | null; count: number }
   InteractionPermissions,         // Full permissions config shape

package/dist/docs/overview.md

@@ -70,7 +70,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **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 |
+| **App Records Pattern** | `docs/app-records-pattern.md` | Standard pattern for per-product/facet/variant/batch admin + public widget UIs |
 | **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
 
 ---

package/dist/docs/ui-utils.md

@@ -19,7 +19,7 @@ translate SDK data into consistent admin 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 are building an admin UI for a records-based microapp (see [app-records-pattern.md](app-records-pattern.md))
 - You need a media asset picker, icon picker, or font picker in an admin panel
 - You need a recursive rule/conditions editor for targeting or audience logic
 - You want the standard inheritance/override editor for scoped records
@@ -326,7 +326,7 @@ Props:
 
 Free-text facet entry is **not** supported — admins must pick from defined facets.
 
-See [records-admin-pattern.md §4](records-admin-pattern.md#4-admin-side----recordsadminshell-the-only-thing-you-should-be-writing) for the standalone usage example.
+See [app-records-pattern.md §4](app-records-pattern.md#4-admin-side----recordsadminshell-the-only-thing-you-should-be-writing) for the standalone usage example.
 
 ---
 
@@ -505,6 +505,6 @@ your microapp                        ← domain logic and custom forms
 
 ## Further reading
 
-- [records-admin-pattern.md](records-admin-pattern.md) — the data contract that `RecordsAdminShell` implements
+- [app-records-pattern.md](app-records-pattern.md) — the data contract that `RecordsAdminShell` implements
 - [building-react-components.md](building-react-components.md) — dual-mode rendering rules that apply to all components
 - [app-manifest.md](app-manifest.md) — the `records` manifest block that drives tab generation

package/dist/openapi.yaml

@@ -10355,6 +10355,40 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/PublicInteractionsCountsByOutcomeRequest"
+  /public/collection/{collectionId}/interactions/submit:
+    post:
+      tags:
+        - interactions
+      summary: "POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context."
+      operationId: interactions_submitPublicEvent
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: "#/components/schemas/SubmitInteractionResponse"
+                  - $ref: "#/components/schemas/SubmitInteractionError"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AppendInteractionBody"
   /public/collection/{collectionId}/interactions/{id}:
     get:
       tags:
@@ -20187,6 +20221,10 @@ components:
           type: boolean
         allowOwnRead:
           type: boolean
+        uniquePerAnonId:
+          type: boolean
+        uniquePerAnonIdWindowSeconds:
+          type: number
     InteractionDisplay:
       type: object
       properties:
@@ -20275,6 +20313,26 @@ components:
           type: number
         offset:
           type: number
+    SubmitInteractionResponse:
+      type: object
+      properties:
+        success:
+          type: object
+          additionalProperties: true
+        eventId:
+          type: string
+      required:
+        - success
+        - eventId
+    SubmitInteractionError:
+      type: object
+      properties:
+        error:
+          type: string
+          enum:
+            - FORBIDDEN
+      required:
+        - error
     Job:
       type: object
       properties:

package/dist/types/interaction.d.ts

@@ -162,6 +162,13 @@ export interface InteractionPermissions {
     allowAuthenticatedSummary?: boolean;
     /** Allow an authenticated user to read their own interaction history via the public API. */
     allowOwnRead?: boolean;
+    /** Reject a second submission that carries the same `anonId` in metadata. */
+    uniquePerAnonId?: boolean;
+    /**
+     * Time window in seconds for `uniquePerAnonId` enforcement.
+     * `0` or omitted means all-time deduplication.
+     */
+    uniquePerAnonIdWindowSeconds?: number;
 }
 export interface InteractionDisplay {
     title?: string;
@@ -203,3 +210,11 @@ export interface ListInteractionTypesQuery {
     limit?: number;
     offset?: number;
 }
+export interface SubmitInteractionResponse {
+    success: true;
+    eventId: string;
+}
+export interface SubmitInteractionError {
+    error: 'FORBIDDEN';
+    reason: 'not_public' | 'auth_required' | 'duplicate' | 'duplicate_anon' | 'disabled' | 'before_start' | 'after_end' | 'origin_forbidden';
+}

package/dist/utils/anonId.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Returns a stable anonymous device ID stored in `localStorage`.
+ *
+ * On first call a random UUID is generated and persisted. All subsequent calls
+ * from the same browser return the same value. Returns `null` during SSR or in
+ * any environment without `window` (safe to call universally).
+ *
+ * The value is scoped to the browser's `localStorage` and is cleared if the
+ * user clears site data. It does **not** create any contact or user record on
+ * the server.
+ *
+ * Pass the result in `metadata.anonId` when submitting interactions to enable
+ * device-level deduplication via `uniquePerAnonId`.
+ *
+ * @example
+ * ```ts
+ * import { utils } from '@proveanything/smartlinks'
+ *
+ * const response = await interactions.submitPublicEvent(collectionId, {
+ *   appId: 'my-app',
+ *   interactionId: 'nps-score',
+ *   outcome: '9',
+ *   metadata: { anonId: utils.getAnonId() },
+ * })
+ * ```
+ */
+export declare function getAnonId(): string | null;

package/dist/utils/anonId.js

@@ -0,0 +1,38 @@
+// src/utils/anonId.ts
+const ANON_ID_KEY = '_pa_anon_id';
+/**
+ * Returns a stable anonymous device ID stored in `localStorage`.
+ *
+ * On first call a random UUID is generated and persisted. All subsequent calls
+ * from the same browser return the same value. Returns `null` during SSR or in
+ * any environment without `window` (safe to call universally).
+ *
+ * The value is scoped to the browser's `localStorage` and is cleared if the
+ * user clears site data. It does **not** create any contact or user record on
+ * the server.
+ *
+ * Pass the result in `metadata.anonId` when submitting interactions to enable
+ * device-level deduplication via `uniquePerAnonId`.
+ *
+ * @example
+ * ```ts
+ * import { utils } from '@proveanything/smartlinks'
+ *
+ * const response = await interactions.submitPublicEvent(collectionId, {
+ *   appId: 'my-app',
+ *   interactionId: 'nps-score',
+ *   outcome: '9',
+ *   metadata: { anonId: utils.getAnonId() },
+ * })
+ * ```
+ */
+export function getAnonId() {
+    if (typeof window === 'undefined')
+        return null;
+    let id = window.localStorage.getItem(ANON_ID_KEY);
+    if (!id) {
+        id = crypto.randomUUID();
+        window.localStorage.setItem(ANON_ID_KEY, id);
+    }
+    return id;
+}

package/dist/utils/index.d.ts

@@ -4,3 +4,4 @@
  */
 export * from './paths';
 export * from './conditions';
+export * from './anonId';

package/dist/utils/index.js

@@ -5,3 +5,4 @@
  */
 export * from './paths';
 export * from './conditions';
+export * from './anonId';

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.11.6  |  Generated: 2026-05-01T13:42:06.488Z
+Version: 1.11.8  |  Generated: 2026-05-03T08:12:27.170Z
 
 This is a concise summary of all available API functions and types.
 
@@ -5153,6 +5153,10 @@ interface InteractionPermissions {
   * Authenticated summary visibility (counts, aggregates) when user is signed in.
   allowAuthenticatedSummary?: boolean
   allowOwnRead?: boolean
+  uniquePerAnonId?: boolean
+  * Time window in seconds for `uniquePerAnonId` enforcement.
+  * `0` or omitted means all-time deduplication.
+  uniquePerAnonIdWindowSeconds?: number
 }
 ```
 
@@ -5220,6 +5224,30 @@ interface ListInteractionTypesQuery {
 }
 ```
 
+**SubmitInteractionResponse** (interface)
+```typescript
+interface SubmitInteractionResponse {
+  success: true
+  eventId: string
+}
+```
+
+**SubmitInteractionError** (interface)
+```typescript
+interface SubmitInteractionError {
+  error: 'FORBIDDEN'
+  reason:
+  | 'not_public'
+  | 'auth_required'
+  | 'duplicate'
+  | 'duplicate_anon'
+  | 'disabled'
+  | 'before_start'
+  | 'after_end'
+  | 'origin_forbidden'
+}
+```
+
 ### jobs
 
 **Job** (interface)
@@ -8333,47 +8361,47 @@ POST /admin/collection/:collectionId/interactions/append Appends one interaction
 POST /admin/collection/:collectionId/interactions/append Appends one interaction event.
 
 **submitPublicEvent**(collectionId: string,
-    body: AppendInteractionBody) → `Promise<`
-Appends one interaction event from a public source.
+    body: AppendInteractionBody) → `Promise<SubmitInteractionResponse | SubmitInteractionError>`
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **create**(collectionId: string,
     body: CreateInteractionTypeBody) → `Promise<InteractionTypeRecord>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **list**(collectionId: string,
     query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **get**(collectionId: string,
     id: string) → `Promise<InteractionTypeRecord>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **update**(collectionId: string,
     id: string,
     patchBody: UpdateInteractionTypeBody) → `Promise<InteractionTypeRecord>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **remove**(collectionId: string,
     id: string) → `Promise<void>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicCountsByOutcome**(collectionId: string,
     body: PublicInteractionsCountsByOutcomeRequest,
     authToken?: string) → `Promise<OutcomeCount[]>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicMyInteractions**(collectionId: string,
     body: PublicInteractionsByUserRequest,
     authToken?: string) → `Promise<InteractionEventRow[]>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicList**(collectionId: string,
     query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicGet**(collectionId: string,
     id: string) → `Promise<InteractionTypeRecord>`
-Appends one interaction event from a public source.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 ### jobs
 

package/docs/app-manifest.md

@@ -270,7 +270,7 @@ See the [Deep Link Discovery guide](deep-link-discovery.md) for the full dual-so
 
 #### `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.
+Declares which `app.records` record types the app stores, and which scopes each type supports. Required for any app that follows the [App Records Pattern](app-records-pattern.md). Omit if the app does not use scoped records.
 
 The platform and the `<RecordsAdminShell>` from `@proveanything/smartlinks-utils-ui` read this block to render the right scope tabs, rule editor, and cardinality-appropriate right pane.
 
@@ -294,7 +294,7 @@ The platform and the `<RecordsAdminShell>` from `@proveanything/smartlinks-utils
 | `scopes`          | string[] | — | Allowed scope kinds in resolution order. Valid values: `"collection"`, `"product"`, `"variant"`, `"batch"`, `"facet"`, `"proof"`, `"rule"`. `'rule'` is a synthetic scope holding `facetRule`-targeted records. `'collection'` replaces the legacy empty-ref catch-all — **there is no `'global'` scope**. |
 | `defaultScope`    | string   | — | The scope the "Create new" button targets in the admin shell. Must be one of the declared `scopes`. |
 
-An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`). See [records-admin-pattern.md](records-admin-pattern.md) for the full admin + public pattern.
+An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`). See [app-records-pattern.md](app-records-pattern.md) for the full admin + public pattern.
 
 #### `executor`
 

package/docs/app-objects.md

@@ -445,7 +445,7 @@ const productComments = await app.threads.list(collectionId, appId, {
 - **Usage logs** — record product usage metrics
 - **Audit trails** — immutable logs of actions
 - **Loyalty points** — track points earned/redeemed
-- **Per-product / per-facet configuration** — scoped data that varies by product axis (see [records-admin-pattern.md](records-admin-pattern.md))
+- **Per-product / per-facet configuration** — scoped data that varies by product axis (see [app-records-pattern.md](app-records-pattern.md))
 
 ### Key Features
 
@@ -526,7 +526,7 @@ proof  →  batch  →  variant  →  product  →  rule(*)  →  facet(*)  →
 - `facet(*)` — legacy single-facet anchors, walked alphabetically. Prefer `facetRule` for new work.
 - `collection` — the top of the chain and the catch-all for any record with no anchor fields. **There is no `'global'` tier above collection.**
 
-For a **singleton** record type (one answer wins), use `useResolvedRecord` — it performs this walk server-side and returns the first match plus a `matchedAt` tag. For a **collection** record type (every match is shown), use `useCollectedRecords`. See [records-admin-pattern.md §2](records-admin-pattern.md#2-resolution-order-one-canonical-chain) for the full guide.
+For a **singleton** record type (one answer wins), use `useResolvedRecord` — it performs this walk server-side and returns the first match plus a `matchedAt` tag. For a **collection** record type (every match is shown), use `useCollectedRecords`. See [app-records-pattern.md §2](app-records-pattern.md#2-resolution-order-one-canonical-chain) for the full guide.
 
 ### Singleton Cardinality
 

package/docs/app-records-pattern.md

@@ -0,0 +1,329 @@
+# SmartLinks App Records Pattern
+
+> Canonical guide for microapps that store **per-product**, **per-facet**, **per-variant**, **per-batch**, or **rule-targeted** data.
+>
+> Audience: microapp developers (ingredients, nutrition, allergy, FAQs, recipes, warranty, provenance, …).
+>
+> Status: **standard**. New apps MUST follow this contract; existing apps SHOULD migrate.
+>
+> SDK: `@proveanything/smartlinks` ≥ **1.11**, `@proveanything/smartlinks-utils-ui` ≥ **0.7.6**.
+
+---
+
+## 0. TL;DR — pick your shape, then copy the snippet
+
+Every records-based app fits into a 2×2:
+
+|                          | **Singleton** (one record per scope)                 | **Collection** (many records per scope)                       |
+| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------- |
+| **Best-match (one wins)**| Ingredients, nutrition, washing instructions         | _(rare — usually you want all)_                               |
+| **All matches (aggregate)** | _(rare — usually you want best)_                  | FAQs, recipes, SOPs, care tips, story cards                   |
+
+That choice drives **three** things and nothing else:
+
+1. **Manifest:** `cardinality: 'singleton' | 'collection'` and `allowFacetRules: boolean`.
+2. **Admin (`<RecordsAdminShell>`):** pass `cardinality` + include `'rule'` in `scopes` if `allowFacetRules`.
+3. **Public hook:** `useResolvedRecord` (best match) **or** `useCollectedRecords` / `useResolveAllRecords` (all matches).
+
+If you only remember one rule: **never write your own resolver**. The shell, the hooks, and the SDK already agree on resolution order. Reimplementing it is how apps drift.
+
+---
+
+## 1. The data model in one paragraph
+
+A microapp owns a typed **records table** keyed by `(appId, recordType, id)`. Each `AppRecord` carries a `data` payload plus **either** a structured `scope` (anchored to a node in the chain) **or** a `facetRule` (matches products dynamically by their facets). The server resolves which record(s) apply to a given product context. There is no "global"; the top of the chain is **collection** — anything not explicitly scoped further applies to the whole collection.
+
+```ts
+import * as SL from '@proveanything/smartlinks';
+
+await SL.app.records.upsert(collectionId, appId, {
+  recordType: 'ingredients',
+  scope: { productId: 'prod_abc', variantId: 'var_500ml' }, // server derives the ref
+  data: { /* domain payload */ },
+}, /* admin */ true);
+```
+
+Or, for a rule-targeted record:
+
+```ts
+await SL.app.records.upsert(collectionId, appId, {
+  recordType: 'ingredients',
+  facetRule: {
+    all: [
+      { facetKey: 'brand',    anyOf: ['acme'] },
+      { facetKey: 'category', anyOf: ['bread', 'pastry'] },
+    ],
+  },
+  data: { /* domain payload */ },
+}, true);
+```
+
+`scope` and `facetRule` are **mutually exclusive on save**.
+
+---
+
+## 2. Resolution order (one canonical chain)
+
+The server walks **most-specific → least-specific** and stops at the first match (for best-match) or collects every match (for aggregate):
+
+```
+proof  →  batch  →  variant  →  product  →  rule(*)  →  facet(*)  →  collection
+```
+
+- `rule(*)` — facet-rule records are scored by **specificity** (number of clauses + number of constrained values). The most specific rule wins.
+- `facet(*)` — legacy single-facet anchors, walked deterministically (alphabetical).
+- `collection` — the top of the chain. **There is no "global" tier above collection.** A collection-level record is the catch-all for that collection.
+
+The resolved value comes back tagged with `matchedAt: 'product' | 'rule' | 'facet' | …` so the UI can say things like _"Matched by rule: brand=Acme AND category=bread"_.
+
+> ⚠️ Legacy `scope.facets[]` (colon-delimited single-facet refs) is deprecated and removed in SDK 1.12. Use `facetRule` for everything that isn't a one-off facet pin.
+
+---
+
+## 3. Manifest declaration
+
+Declare each record type once in `app.admin.json`. The shell and the platform read this to render the right scope tabs and disable the wrong affordances.
+
+```json
+{
+  "records": {
+    "ingredients": {
+      "label": "Ingredients",
+      "cardinality": "singleton",
+      "allowFacetRules": true,
+      "scopes": ["collection", "facet", "rule", "product", "variant", "batch"],
+      "defaultScope": "product"
+    },
+    "faq": {
+      "label": "FAQs",
+      "cardinality": "collection",
+      "allowFacetRules": true,
+      "scopes": ["collection", "rule", "product"],
+      "defaultScope": "collection"
+    }
+  }
+}
+```
+
+| Field             | Meaning                                                                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `cardinality`     | `'singleton'` (one per scope, e.g. ingredients) or `'collection'` (many per scope, e.g. FAQs). Default `'singleton'`.                |
+| `allowFacetRules` | `true` to enable the `rule` scope tab + `<FacetRuleEditor>` in the shell. Default `false`.                                           |
+| `scopes`          | Allowed scope kinds in **resolution order**. `'rule'` is a synthetic scope that holds rule-targeted records.                         |
+| `defaultScope`    | Where the "Create new" button lands.                                                                                                 |
+| `label`           | Human-readable label used in headings and toasts.                                                                                    |
+
+---
+
+## 4. Admin side — `<RecordsAdminShell>` (the only thing you should be writing)
+
+The shell owns: scope tabs, browser pane, rule editor, save/discard, dirty navigation, inheritance markers, deletion, CSV, bulk apply, deep linking. **You only supply the editor for one record's `data`.**
+
+```tsx
+import * as SL from '@proveanything/smartlinks';
+import { RecordsAdminShell } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+<RecordsAdminShell<IngredientsConfig>
+  SL={SL}
+  collectionId={collectionId}
+  appId={appId}
+  recordType="ingredients"
+  label="Ingredients"
+  cardinality="singleton"                              // ← from manifest
+  scopes={['collection', 'facet', 'rule', 'product', 'variant', 'batch']}
+  defaultScope="product"
+  defaultData={() => emptyConfig()}
+  renderEditor={(ctx) => (
+    <IngredientsEditor
+      value={ctx.value}
+      onChange={ctx.onChange}
+      // For rule-targeted records, the shell hands you the live rule + setter:
+      facetRule={ctx.facetRule}
+      onFacetRuleChange={ctx.onFacetRuleChange}
+    />
+  )}
+/>
+```
+
+### What the shell gives you for free
+
+- **Scope tabs** including a **`Rule`** tab when `'rule'` is in `scopes`. Selecting it opens `<FacetRuleEditor>` above your editor — no extra wiring.
+- **`EditorContext.facetRule` / `onFacetRuleChange`** for rule-scoped records, plus `canSave: false` until at least one clause has values (avoids server 500s).
+- **Inheritance markers** — when editing a variant, the product baseline is shown; per-field "↩ Inherited" / "● Override" is rendered by the inheritance helpers.
+- **Collection cardinality flow** — set `cardinality="collection"` and the shell turns the right pane into a list of items (table / cards / gallery) with `+ New` and per-item nav.
+- **Telemetry** — `record.save`, `record.delete`, `scope.change`, `csv.import`, `bulk.apply`, `item.create`, etc. via `onTelemetry`.
+
+### Standalone rule editor
+
+If you need a rule editor outside the shell (e.g. on a settings page):
+
+```tsx
+import { FacetRuleEditor } from '@proveanything/smartlinks-utils-ui/facet-rule-editor';
+
+<FacetRuleEditor
+  value={rule}
+  onChange={setRule}
+  collectionId={collectionId}     // lazy-fetches facets via SL.facets.publicList
+  preview={rulePreview}            // optional — wire from useRulePreview
+/>
+```
+
+---
+
+## 5. Public side — pick the right hook (this is where apps go wrong)
+
+> **Admin vs public — the rule is simple:**
+>
+> | Function | Public widget | Admin dashboard |
+> |---|---|---|
+> | `app.records.create(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.list(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.get(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.update(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.remove(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.aggregate(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.match(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.resolveAll(…, false)` | ✅ default — omit the flag | ✅ pass `true` |
+> | `app.records.upsert()` | ❌ admin only — no public path | ✅ |
+> | `app.records.bulkUpsert()` | ❌ admin only — no public path | ✅ |
+> | `app.records.bulkDelete()` | ❌ admin only — no public path | ✅ |
+> | `app.records.restore()` | ❌ admin only — no public path | ✅ |
+> | `app.records.previewRule()` | ❌ admin only — no public path | ✅ |
+>
+> The `admin` parameter on `match()` and `resolveAll()` defaults to `false`, so public widgets that omit it are fine. **Never hardcode `true` in a public widget.** The hooks below always use the public path and are the recommended approach — prefer them over raw SDK calls in widget code.
+
+There is exactly **one decision** to make on the public side, and it follows from the manifest's `cardinality`:
+
+### 5a. Singleton → `useResolvedRecord` (best match wins)
+
+Use this when the app shows **one** answer for the current product (ingredients, nutrition, washing instructions, warranty terms).
+
+```tsx
+import * as SL from '@proveanything/smartlinks';
+import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const { data, source, sourceRef, matchedAt, matchedRule, isLoading } =
+  useResolvedRecord<IngredientsConfig>({
+    SL,
+    appId,
+    collectionId,
+    recordType: 'ingredients',
+    productId,
+    variantId,   // optional
+    batchId,     // optional
+    proofId,     // optional
+  });
+```
+
+The resolver walks `proof → batch → variant → product → rule → facet → collection` and returns the **first match**, plus `matchedAt` so you can render _"From the product record"_ vs _"Matched by rule"_ badges if useful.
+
+> Wrap this once in your app (e.g. `useResolvedIngredientSet`) so the rest of the codebase reads `{ data, isLoading }` and never sees the resolver.
+
+### 5b. Collection → `useCollectedRecords` (every match, ordered)
+
+Use this when the app shows **many** answers aggregated across the chain (FAQs, recipes, SOPs, care tips). Most-specific first by default; pass `sort` to override.
+
+```tsx
+import { useCollectedRecords } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const { items, isLoading } = useCollectedRecords<FaqEntry>({
+  SL,
+  appId,
+  collectionId,
+  recordType: 'faq',
+  productId,
+  // sort: { kind: 'field', field: 'order', direction: 'asc' },
+});
+
+// items: CollectedRecord<FaqEntry>[] — each has { data, scope, ref, depth }
+```
+
+### 5c. Multi-type aggregate → `useResolveAllRecords`
+
+When you need every record of every type that applies to a context (rare; mostly executors and SEO surfaces).
+
+```tsx
+import { useResolveAllRecords } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const { entries, isLoading } = useResolveAllRecords({
+  SL, collectionId, appId,
+  context: { productId, facets: { brand: 'acme', category: ['bread'] } },
+});
+```
+
+### Common mistakes (do not do these)
+
+| ❌ Anti-pattern                                            | ✅ Do this instead                                                |
+| ---------------------------------------------------------- | ----------------------------------------------------------------- |
+| Calling `SL.app.records.list()` and filtering client-side  | `useResolvedRecord` (singleton) or `useCollectedRecords` (collection). The server already knows the chain. |
+| Calling `SL.app.records.list(…, true)` from a public widget | Omit the `admin` flag (defaults to `false`). `list()` has a public path — just don't pass `true`. |
+| Calling `SL.app.records.match(…, true)` from a public widget | Omit the `admin` flag (defaults to `false`) or use `useResolvedRecord` / `useCollectedRecords`. |
+| Calling `SL.app.records.resolveAll(…, true)` from a public widget | Omit the `admin` flag (defaults to `false`) or use `useResolveAllRecords`. |
+| Calling `upsert`, `bulkUpsert`, `bulkDelete`, or `previewRule` from widget code | Those are admin-only. Widget code reads data — it never writes records directly. |
+| Walking the chain by hand with multiple `getConfig` calls  | One hook call. The resolver is tested, cached, and includes rules. |
+| Treating `facet:key:value` refs as the rule mechanism      | Use `facetRule` (`{ all: [{ facetKey, anyOf: [...] }] }`). Multi-condition, scored by specificity. |
+| Reading `matchedAt === 'global'`                           | There is no `'global'`. The top of the chain is `'collection'`.  |
+| Building your own `<FacetRuleEditor>`                      | Use the one from `@proveanything/smartlinks-utils-ui/facet-rule-editor`. |
+
+---
+
+## 6. Reference: the `EditorContext` your `renderEditor` receives
+
+```ts
+interface EditorContext<TData> {
+  value: TData;
+  onChange: (next: TData) => void;
+  source: 'self' | 'inherited' | 'empty';
+  recordId?: string;
+  parentValue?: TData | null;
+  scope: ParsedRef;                  // { kind: 'product' | 'rule' | …, productId?, … }
+
+  // Save lifecycle
+  isDirty: boolean;
+  isSaving?: boolean;
+  saveError?: unknown | null;
+  canSave?: boolean;                 // shell flips to false on empty rules
+  cannotSaveReason?: string;
+  save: () => Promise<void>;
+  reset: () => void;
+
+  // Deletion
+  remove: () => Promise<void>;
+  canRemove: boolean;
+
+  // Rule scope only
+  facetRule?: FacetRule | null;
+  onFacetRuleChange?: (next: FacetRule | null) => void;
+}
+```
+
+---
+
+## 7. Migration checklist (existing apps)
+
+1. **Update SDKs:** `@proveanything/smartlinks@^1.11`, `@proveanything/smartlinks-utils-ui@^0.7.6`.
+2. **Add `cardinality` and `allowFacetRules`** to every entry under `records` in `app.admin.json`.
+3. **Add `'rule'` (and `'collection'` if missing) to `scopes`** wherever `allowFacetRules: true`.
+4. **Pass `cardinality`** to `<RecordsAdminShell>`.
+5. **Replace any handwritten chain walking** with `useResolvedRecord` (singleton) or `useCollectedRecords` (collection).
+6. **Delete any code that constructs `facet:key:value` refs** for matching. Use `facetRule` via the shell or `<FacetRuleEditor>`.
+7. **Search for the word "global"** in your code/docs and rename to "collection" — this is the most common source of confusion.
+
+---
+
+## 8. Where the canonical exports live
+
+| Need                          | Import from                                                            |
+| ----------------------------- | ---------------------------------------------------------------------- |
+| Admin shell                   | `@proveanything/smartlinks-utils-ui/records-admin` → `RecordsAdminShell` |
+| Standalone rule editor        | `@proveanything/smartlinks-utils-ui/facet-rule-editor` → `FacetRuleEditor` |
+| Conditions editor (non-facet) | `@proveanything/smartlinks-utils-ui/conditions-editor` → `ConditionsEditor` |
+| Best-match resolver hook      | `@proveanything/smartlinks-utils-ui/records-admin` → `useResolvedRecord` |
+| All-matches hook              | `@proveanything/smartlinks-utils-ui/records-admin` → `useCollectedRecords` |
+| Multi-type aggregate hook     | `@proveanything/smartlinks-utils-ui/records-admin` → `useResolveAllRecords` |
+| Rule preview ("matches N")    | `@proveanything/smartlinks-utils-ui/records-admin` → `useRulePreview`  |
+| Server-side record CRUD       | `@proveanything/smartlinks` → `SL.app.records.{upsert, list, remove, match, resolveAll}` |
+
+---
+
+_End of doc. If anything below the SDK contradicts this file, this file wins — open a PR against the SDK to bring the two back into sync._

package/docs/interactions.md

@@ -119,18 +119,37 @@ await SL.interactions.appendEvent(collectionId, {
 
 ### Public Event Submit
 
-Use in client-side app code. Same body shape as `appendEvent` but hits the public endpoint (respects interaction permissions like `allowPublicSubmit`, `requireAuth`).
+Use in client-side app code. Hits the public endpoint and respects interaction permissions (`allowPublicSubmit`, `allowAnonymousSubmit`, `requireAuth`, etc.).
 
 ```typescript
+// Authenticated submission
 await SL.interactions.submitPublicEvent(collectionId, {
   appId: 'my-app',
   interactionId: 'competition-entry',
   outcome: 'entered',
-  userId: currentUser.id,
+  contactId: currentUser.contactId,
   metadata: { answer: 'Paris' },
 });
+
+// Anonymous submission (interaction must have allowAnonymousSubmit: true)
+const response = await SL.interactions.submitPublicEvent(collectionId, {
+  appId: 'my-app',
+  interactionId: 'nps-score',
+  outcome: '9',
+  metadata: {
+    anonId: SL.utils.getAnonId(),  // device-level dedup signal
+  },
+});
+
+if (!response.success) {
+  if (response.reason === 'duplicate_anon') {
+    // this device has already submitted
+  }
+}
 ```
 
+> **Anonymous submissions** — when `allowAnonymousSubmit: true` is set on the interaction, neither `userId` nor `contactId` is required. Use `utils.getAnonId()` to generate a stable browser-local UUID and pass it as `metadata.anonId`; the server will enforce `uniquePerAnonId` if configured.
+
 ### Update an Existing Event
 
 ```typescript
@@ -237,6 +256,8 @@ Set on the interaction type definition via `permissions`:
 | `uniquePerUser` | boolean | Prevent duplicate submissions per user |
 | `uniquePerUserWindowSeconds` | number | Time window for uniqueness (e.g., `86400` = 1 day) |
 | `uniqueOutcome` | string | Outcome tag to check for duplicates (e.g., `"submitted"`) |
+| `uniquePerAnonId` | boolean | Reject a second submission that carries the same `anonId` in metadata |
+| `uniquePerAnonIdWindowSeconds` | number | Time window for `uniquePerAnonId` enforcement; `0` or omitted = all-time |
 | `allowPublicSummary` | boolean | Show counts/aggregates to unauthenticated users |
 | `allowAuthenticatedSummary` | boolean | Show counts/aggregates to authenticated users |
 | `allowOwnRead` | boolean | Let users read their own event history via public API |
@@ -263,8 +284,10 @@ When defining a journey trigger, reference the `interactionId` that should fire
 
 ```typescript
 import type {
-  AppendInteractionBody,          // Event body for appendEvent / submitPublicEvent
+  AppendInteractionBody,          // Event body for appendEvent and submitPublicEvent
   UpdateInteractionBody,          // Event body for updateEvent
+  SubmitInteractionResponse,      // { success: true; eventId: string }
+  SubmitInteractionError,         // { error: 'FORBIDDEN'; reason: string }
   InteractionEventRow,            // Raw event record returned by query()
   OutcomeCount,                   // { outcome: string | null; count: number }
   InteractionPermissions,         // Full permissions config shape

package/docs/overview.md

@@ -70,7 +70,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **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 |
+| **App Records Pattern** | `docs/app-records-pattern.md` | Standard pattern for per-product/facet/variant/batch admin + public widget UIs |
 | **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
 
 ---

package/docs/ui-utils.md

@@ -19,7 +19,7 @@ translate SDK data into consistent admin 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 are building an admin UI for a records-based microapp (see [app-records-pattern.md](app-records-pattern.md))
 - You need a media asset picker, icon picker, or font picker in an admin panel
 - You need a recursive rule/conditions editor for targeting or audience logic
 - You want the standard inheritance/override editor for scoped records
@@ -326,7 +326,7 @@ Props:
 
 Free-text facet entry is **not** supported — admins must pick from defined facets.
 
-See [records-admin-pattern.md §4](records-admin-pattern.md#4-admin-side----recordsadminshell-the-only-thing-you-should-be-writing) for the standalone usage example.
+See [app-records-pattern.md §4](app-records-pattern.md#4-admin-side----recordsadminshell-the-only-thing-you-should-be-writing) for the standalone usage example.
 
 ---
 
@@ -505,6 +505,6 @@ your microapp                        ← domain logic and custom forms
 
 ## Further reading
 
-- [records-admin-pattern.md](records-admin-pattern.md) — the data contract that `RecordsAdminShell` implements
+- [app-records-pattern.md](app-records-pattern.md) — the data contract that `RecordsAdminShell` implements
 - [building-react-components.md](building-react-components.md) — dual-mode rendering rules that apply to all components
 - [app-manifest.md](app-manifest.md) — the `records` manifest block that drives tab generation

package/openapi.yaml

@@ -10355,6 +10355,40 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/PublicInteractionsCountsByOutcomeRequest"
+  /public/collection/{collectionId}/interactions/submit:
+    post:
+      tags:
+        - interactions
+      summary: "POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context."
+      operationId: interactions_submitPublicEvent
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: "#/components/schemas/SubmitInteractionResponse"
+                  - $ref: "#/components/schemas/SubmitInteractionError"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AppendInteractionBody"
   /public/collection/{collectionId}/interactions/{id}:
     get:
       tags:
@@ -20187,6 +20221,10 @@ components:
           type: boolean
         allowOwnRead:
           type: boolean
+        uniquePerAnonId:
+          type: boolean
+        uniquePerAnonIdWindowSeconds:
+          type: number
     InteractionDisplay:
       type: object
       properties:
@@ -20275,6 +20313,26 @@ components:
           type: number
         offset:
           type: number
+    SubmitInteractionResponse:
+      type: object
+      properties:
+        success:
+          type: object
+          additionalProperties: true
+        eventId:
+          type: string
+      required:
+        - success
+        - eventId
+    SubmitInteractionError:
+      type: object
+      properties:
+        error:
+          type: string
+          enum:
+            - FORBIDDEN
+      required:
+        - error
     Job:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.11.6",
+  "version": "1.11.8",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",