@proveanything/smartlinks 1.14.10 → 1.14.12

package/dist/openapi.yaml

@@ -2586,6 +2586,113 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /admin/collection/{collectionId}/contacts/search:
+    get:
+      tags:
+        - contact
+      summary: contact.search
+      operationId: contact_search
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: q
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: typeahead
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: email
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: phone
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: id
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: userId
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: source
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: locale
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: createdFrom
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: createdTo
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: externalIdKey
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: externalIdValue
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: customFieldKey
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: customFieldValue
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: offset
+          in: query
+          required: false
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ContactSearchResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
   /admin/collection/{collectionId}/contacts/upsert:
     post:
       tags:
@@ -19580,6 +19687,70 @@ components:
         - items
         - limit
         - offset
+    ContactSearchParams:
+      type: object
+      properties:
+        collectionId:
+          type: string
+        q:
+          type: string
+        typeahead:
+          type: boolean
+        email:
+          type: string
+        phone:
+          type: string
+        id:
+          type: string
+        userId:
+          type: string
+        tags:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        tagsAll:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        source:
+          type: string
+        locale:
+          type: string
+        createdFrom:
+          type: string
+        createdTo:
+          type: string
+        externalIdKey:
+          type: string
+        externalIdValue:
+          type: string
+        customFieldKey:
+          type: string
+        customFieldValue:
+          type: string
+        limit:
+          type: number
+        offset:
+          type: number
+      required:
+        - collectionId
+    ContactSearchResponse:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/Contact"
+        limit:
+          type: number
+        offset:
+          type: number
+      required:
+        - items
+        - limit
+        - offset
     PublicContactUpsertResponse:
       type: object
       properties:

package/dist/types/contact.d.ts

@@ -34,6 +34,32 @@ export interface ContactListResponse {
     limit: number;
     offset: number;
 }
+export interface ContactSearchParams {
+    collectionId: string;
+    q?: string;
+    typeahead?: boolean;
+    email?: string;
+    phone?: string;
+    id?: string;
+    userId?: string;
+    tags?: string | string[];
+    tagsAll?: string | string[];
+    source?: string;
+    locale?: string;
+    createdFrom?: string;
+    createdTo?: string;
+    externalIdKey?: string;
+    externalIdValue?: string;
+    customFieldKey?: string;
+    customFieldValue?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface ContactSearchResponse {
+    items: Contact[];
+    limit: number;
+    offset: number;
+}
 export type PublicContactUpsertRequest = Partial<Pick<Contact, "email" | "phone" | "userId" | "firstName" | "lastName" | "displayName" | "company" | "tags" | "source" | "notes" | "avatarUrl" | "locale" | "timezone" | "externalIds">> & {
     customFields?: ContactCustomFields;
 };

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.14.10  |  Generated: 2026-05-16T17:03:23.904Z
+Version: 1.14.12  |  Generated: 2026-05-19T11:25:45.278Z
 
 This is a concise summary of all available API functions and types.
 
@@ -36,6 +36,11 @@ For detailed guides on specific features:
 - **[Product Facets SDK](PRODUCT_FACETS_SDK.md)** - Admin and public product facet endpoints and TypeScript interfaces
 - **[Attestations](attestations.md)** - Append-only fact log with cryptographic chain integrity, time-series analytics, and public/owner/admin visibility
 - **[Auth Kit](auth-kit.md)** - End-user authentication flows (email/password, magic link, OTP, OAuth) for microapps
+- **[Portal Request Login](portal-request-login.md)** - Sub-apps delegate user authentication to the portal; `useSafeAuth().requestLogin` hook and iframe postMessage contract, redirect-bounce handling
+- **[Portal Auth Broadcast](portal-auth-broadcast.md)** - Publishing a custom-flow session to the portal so the header, sibling apps, and SDK all stay in sync
+- **[Portal Request Action](portal-request-action.md)** - Invoking portal built-in actions (`__qrScanner`, `__share`, `__logout`, etc.) from containers, widgets, and iframes
+- **[Portal Back Button](portal-back-button.md)** - `parentPath` contract for hierarchy-aware "up" navigation; `useDeepLinkSync` integration
+- **[Contact Search](contact-search.md)** - Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination
 - **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
 - **[Forms](forms.md)** - Platform-managed form definitions, submissions, and schema-driven React form UI
 - **[App Objects: Cases, Threads & Records](app-objects.md)** - Generic app-scoped building blocks for support cases, discussions, bookings, registrations, and more
@@ -89,7 +94,7 @@ The Smartlinks SDK is organized into the following namespaces:
 — Identity & Access —
 - **auth** - Admin authentication and account ops: login/logout, tokens, account info.
 - **authKit** - End‑user auth flows (email/password, OAuth, phone); profiles and verification.
-- **contact** - Manage customer contacts; CRUD, lookup, upsert, erase.
+- **contact** - Manage customer contacts; CRUD, lookup, upsert, erase, and admin search. → [Guide](contact-search.md)
 
 — Messaging & Audience —
 - **comms** - Send notifications (push, email, wallet); templating, severity, delivery status. → [Guide](comms.md)
@@ -4460,6 +4465,40 @@ interface ContactListResponse {
 }
 ```
 
+**ContactSearchParams** (interface)
+```typescript
+interface ContactSearchParams {
+  collectionId: string
+  q?: string
+  typeahead?: boolean
+  email?: string
+  phone?: string
+  id?: string
+  userId?: string
+  tags?: string | string[]
+  tagsAll?: string | string[]
+  source?: string
+  locale?: string
+  createdFrom?: string
+  createdTo?: string
+  externalIdKey?: string
+  externalIdValue?: string
+  customFieldKey?: string
+  customFieldValue?: string
+  limit?: number
+  offset?: number
+}
+```
+
+**ContactSearchResponse** (interface)
+```typescript
+interface ContactSearchResponse {
+  items: Contact[]
+  limit: number
+  offset: number
+}
+```
+
 **PublicContactUpsertResponse** (interface)
 ```typescript
 interface PublicContactUpsertResponse {
@@ -8629,6 +8668,28 @@ Returns all proof type definitions. Proof types are templates that specify which
 **list**(collectionId: string,
     params?: { limit?: number; offset?: number; includeDeleted?: boolean }) → `Promise<ContactListResponse>`
 
+**search**({
+    collectionId,
+    q,
+    typeahead,
+    email,
+    phone,
+    id,
+    userId,
+    tags,
+    tagsAll,
+    source,
+    locale,
+    createdFrom,
+    createdTo,
+    externalIdKey,
+    externalIdValue,
+    customFieldKey,
+    customFieldValue,
+    limit,
+    offset,
+  }: ContactSearchParams) → `Promise<ContactSearchResponse>`
+
 **get**(collectionId: string,
     contactId: string,
     params?: { includeDeleted?: boolean }) → `Promise<ContactResponse>`

package/docs/contact-search.md

@@ -0,0 +1,162 @@
+# Contact Search
+
+Admin-scoped endpoint for querying contacts within a collection. Supports
+free-text search, type-ahead, identity lookup, structured filters, and JSONB
+field queries. All parameters are optional and composable.
+
+**Base path:** `GET /api/admin/:collectionId/contacts/search`
+
+---
+
+## Quick examples
+
+```ts
+// Type-ahead while user types "joh" into a search box
+await contact.search({ collectionId, q: "joh", typeahead: true })
+
+// Find contacts by partial email
+await contact.search({ collectionId, email: "acme.com" })
+
+// Exact contact by UUID
+await contact.search({ collectionId, id: "uuid-here" })
+
+// All contacts tagged "vip" created this year
+await contact.search({
+  collectionId,
+  tags: ["vip"],
+  createdFrom: "2026-01-01",
+})
+
+// Find by external ID (e.g. Shopify customer ID)
+await contact.search({
+  collectionId,
+  externalIdKey: "shopify_id",
+  externalIdValue: "123456",
+})
+```
+
+---
+
+## Parameters
+
+### Free-text
+
+| Param | Type | Description |
+|---|---|---|
+| `q` | `string` | General search term. Searches `first_name`, `last_name`, `display_name`, `company`, and all identity values (`email`, `phone`). When the value contains `@` only email identities are searched; when it matches a phone pattern only phone identities are searched. |
+| `typeahead` | `boolean` | When `true`, uses prefix (`startsWith`) operators instead of substring (`contains`). Significantly cheaper per keystroke. Default limit becomes `10`; minimum `q` length is 2 characters. Use this for live search-as-you-type UIs. |
+
+### Identity filters
+
+| Param | Type | Description |
+|---|---|---|
+| `email` | `string` | Partial match against normalised email identity values. Case-insensitive. |
+| `phone` | `string` | Partial match against normalised phone identity values. |
+
+### Exact lookups
+
+These short-circuit all text/filter logic and return at most one contact.
+
+| Param | Type | Description |
+|---|---|---|
+| `id` | `string` (UUID) | Contact primary key. |
+| `userId` | `string` | Firebase auth UID linked to the contact. |
+
+### Structured filters
+
+All filters are ANDed with each other and with any text search.
+
+| Param | Type | Description |
+|---|---|---|
+| `tags` | `string \| string[]` | Comma-separated string or repeated param. Contacts must have **any** of these tags. |
+| `tagsAll` | `string \| string[]` | Contacts must have **all** of these tags. |
+| `source` | `string` | Exact match on the `source` field. |
+| `locale` | `string` | Exact match on the `locale` field (e.g. `"en-US"`). |
+| `createdFrom` | `string` (ISO-8601) | Lower bound on `created_at`. |
+| `createdTo` | `string` (ISO-8601) | Upper bound on `created_at`. |
+
+### JSONB field filters
+
+Searches inside the `external_ids` or `custom_fields` JSONB columns by
+key/value pair. Both params in a pair must be supplied together.
+
+| Param | Type | Description |
+|---|---|---|
+| `externalIdKey` | `string` | Top-level key in `externalIds` (e.g. `"shopify_id"`). |
+| `externalIdValue` | `string` | Expected value at that key. |
+| `customFieldKey` | `string` | Top-level key in `customFields`. |
+| `customFieldValue` | `string` | Expected value at that key. |
+
+### Pagination
+
+| Param | Type | Default | Max |
+|---|---|---|---|
+| `limit` | `number` | `20` (`10` in typeahead mode) | `100` (`10` in typeahead mode) |
+| `offset` | `number` | `0` | — |
+
+---
+
+## Response
+
+```ts
+{
+  items: Contact[],
+  limit: number,
+  offset: number,
+}
+```
+
+Each `Contact` item follows the shape defined in `src/types/contact.ts`.
+
+---
+
+## SDK usage
+
+```ts
+import { contact } from '@proveanything/smartlinks'
+
+const results = await contact.search({
+  collectionId: "my-collection",
+  q: "jane",
+  tags: ["vip"],
+  limit: 20,
+})
+
+for (const c of results.items) {
+  console.log(c.displayName, c.email)
+}
+```
+
+---
+
+## Performance notes
+
+The search endpoint is backed by **PostgreSQL trigram GIN indexes** via the
+`pg_trgm` extension (migration `20260519000001`). This makes `ILIKE '%query%'`
+scans fast even with millions of contacts per org.
+
+**What is a trigram?** PostgreSQL decomposes every string into overlapping
+3-character windows ("trigrams") and stores them in an inverted index. A query
+for `"acme"` is converted into trigrams `" ac", "acm", "cme", "me "` and the
+index returns only rows containing those windows — so Postgres never scans rows
+that can't match, regardless of whether the query is a prefix, suffix, or
+middle-of-word substring.
+
+**Type-ahead mode** (`typeahead: true`) is the recommended pattern for
+keystroke-by-keystroke UI. It emits `LIKE 'query%'` (prefix) operators instead
+of `LIKE '%query%'` (substring). Prefix scans are cheaper because they require
+fewer trigram lookups, making them safe to call on every keypress. Minimum query
+length is enforced at 2 characters server-side to prevent over-broad scans.
+
+**Future scale path:** At very high volumes, routing `search` through
+Elasticsearch would add typo-tolerance and relevance ranking. The API surface is
+intentionally implementation-agnostic so the backing engine can be swapped
+without client changes.
+
+---
+
+## Error codes
+
+| Code | HTTP | Meaning |
+|---|---|---|
+| `SEARCH_REQUIRED` | 400 | No searchable parameter was provided. |

package/docs/overview.md

@@ -65,6 +65,7 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Executors** | `docs/executor.md` | Building executor bundles for SEO, LLM content, programmatic config |
 | **Deep Linking** | `docs/deep-link-discovery.md` | URL state management, navigable states, portal menus, AI nav |
 | **Portal Back Button** | `docs/portal-back-button.md` | Hierarchy-aware "up" navigation inside embedded apps |
+| **Portal Request Action** | `docs/portal-request-action.md` | Triggering portal built-in actions (__qrScanner, __share, __logout, etc.) from sub-apps |
 | **Interactions** | `docs/interactions.md` | Business events, outcomes, voting, competitions, and journey triggers |
 | **AI-Native Manifests** | `docs/manifests.md` | `app.manifest.json`, `app.admin.json`, `ai-guide.md` structure |
 | **App Config Files** | `docs/app-manifest.md` | Full field-by-field reference for both JSON config files |
@@ -74,7 +75,9 @@ 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 |
+| **Portal Request Login** | `docs/portal-request-login.md` | How sub-apps ask the portal to authenticate the user; hook and iframe postMessage contracts |
 | **Portal Auth Broadcast** | `docs/portal-auth-broadcast.md` | Publishing custom auth flows to the portal; syncing sessions across containers and iframes |
+| **Contact Search** | `docs/contact-search.md` | Admin contact search: free-text, typeahead, identity/tag/JSONB filters, and pagination |
 | **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/portal-auth-broadcast.md

@@ -1,6 +1,12 @@
 # Publishing Auth State to the Portal
 
-> **For sub-app authors.** This guide explains how to broadcast authentication state changes to the portal so the header, account UI, and sibling apps stay in sync.
+> **⚠️ Read [`portal-request-login.md`](./portal-request-login.md) first.**
+> The recommended pattern for "I need a logged-in user before I continue"
+> is `requestLogin` — the sub-app asks the portal to run its standard
+> AuthKit flow and awaits a result. This doc covers the *other* case:
+> a sub-app that runs its **own** authentication flow and needs to
+> publish the resulting session up to the portal so the header, account
+> UI, and sibling apps stay in sync.
 
 A SmartLinks micro-app may need to run its own custom authentication flow —
 typical cases: an auction app that calls a bidder API, a competition app
@@ -11,6 +17,7 @@ app pick up the new session.
 
 This doc describes the contract the portal framework already implements.
 
+
 ---
 
 ## Container / Widget Apps (Same React Tree)
@@ -52,18 +59,28 @@ function BidButton() {
 
 ## Iframe Apps (Cross-Origin)
 
-Iframe apps don't share React context. Post messages directly from the
-iframe to its parent — the portal's `IframeResponder` listens for these:
+Iframe apps don't share React context with the portal. They publish their
+session by posting framework-recognised messages on `window.parent`. The
+portal's `IframeResponder` listens for these and routes them into the same
+`login` / `logout` calls the built-in `AuthModal` makes.
+
+> **Note:** There is no `authKit.publishLogin` / `publishLogout` helper in
+> the SmartLinks SDK today. Use the raw `postMessage` calls below. If a
+> helper ships later it will wrap exactly these payloads.
 
 ```ts
-// LOGIN
+// LOGIN — after your custom auth flow returns a token + user
 window.parent.postMessage({
   _smartlinksIframeMessage: true,
   type: 'smartlinks:authkit:login',
   payload: {
     token: '<bearer>',
-    user: { uid: 'usr_123', email: 'bidder@example.com', displayName: 'Jane' },
-    accountData: { /* optional */ },
+    user: {
+      uid: 'usr_123',
+      email: 'bidder@example.com',
+      displayName: 'Jane Bidder',
+    },
+    accountData: { tier: 'gold' }, // optional, free-form
   },
 }, '*');
 
@@ -114,8 +131,9 @@ through the standard portal UI.
    wiped.
 
 ❌ Implementing logout by just clearing your own state. Always call
-   `useAuth().logout()` (container/widget) or post `smartlinks:authkit:logout`
-   (iframe) so the whole portal session ends cleanly.
+   `useAuth().logout()` (container/widget) or post the
+   `smartlinks:authkit:logout` message (iframe) so the whole portal
+   session ends cleanly.
 
 ---