@proveanything/smartlinks 1.14.11 → 1.14.13

package/dist/docs/portal-request-login.md

@@ -0,0 +1,236 @@
+# Requesting Login from the Portal
+
+This is the **recommended** way for a micro-app to get a logged-in user. The
+sub-app does not render any auth UI of its own — it asks the portal to run
+its standard AuthKit flow and awaits a result. The portal owns the modal,
+WhatsApp / OAuth / magic-link redirects, session persistence, and the
+header avatar swap.
+
+Use `requestLogin` whenever the answer to "what do I want?" is simply
+*"a logged-in user before I continue"*. Only fall back to
+[publishing your own session](./portal-auth-broadcast.md) when the app runs
+a genuinely custom auth flow (e.g. its own bidder API).
+
+---
+
+## Why this exists
+
+Historically every sub-app imported `@proveanything/smartlinks-auth-ui` and
+rendered its own login modal. That meant:
+
+- Two React copies of `AuthContext` could exist at once → silent session
+  desync between the header and the sub-app.
+- Each app re-implemented the same WhatsApp / OAuth / magic-link flow.
+- Redirect bounces would land back on the portal with no memory of which
+  sub-app had triggered the login.
+
+The portal now owns the entire flow. Sub-apps just declare intent.
+
+---
+
+## Container / Widget Apps (Same React Tree)
+
+These share the portal's React context. Use `useSafeAuth()` from the
+portal framework:
+
+```tsx
+import { useSafeAuth } from '@proveanything/portal-framework';
+
+function PlaceBidButton() {
+  const auth = useSafeAuth();
+
+  async function onClick() {
+    const result = await auth?.requestLogin?.({ reason: 'bid' });
+    if (result?.status === 'success' || result?.status === 'already-authenticated') {
+      // auth.user / auth.token are now populated.
+      await api.placeBid(...);
+    }
+    // 'cancelled' → user dismissed the modal.
+    // 'unavailable' → portal has no AuthKit configured.
+  }
+
+  return <button onClick={onClick}>Place bid</button>;
+}
+```
+
+`requestLogin` is also exposed as `useAuthRequest().requestLogin` if you
+prefer a dedicated hook, but the folded `useSafeAuth()` shape is preferred
+so callers have one entry point for both session reads and login intent.
+
+### Options
+
+```ts
+auth.requestLogin({
+  reason?: string,                       // analytics / copy hint
+  mode?: 'login' | 'signup' | 'either',  // default 'either'
+  signupProminence?: SignupProminence,   // overrides modal default
+  resolveIfAuthenticated?: boolean,      // default true
+});
+```
+
+| Option | Default | Effect |
+|---|---|---|
+| `reason` | — | Free-form tag. Surfaced to analytics; some templates use it for copy. |
+| `mode` | `'either'` | `'signup'` biases the modal to the registration tab. |
+| `signupProminence` | portal default | One of `'minimal' | 'balanced' | 'emphasized'`. |
+| `resolveIfAuthenticated` | `true` | When already logged in, resolve immediately without showing the modal. Set `false` to force a fresh prompt (e.g. re-auth before a sensitive action). |
+
+### Result
+
+```ts
+type LoginRequestResult = {
+  status: 'success' | 'already-authenticated' | 'cancelled' | 'unavailable';
+  user?:  PortalAuthBridgeUser | null;
+  token?: string | null;
+};
+```
+
+- `success` — fresh login completed inside the modal.
+- `already-authenticated` — there was already a session; nothing was shown.
+- `cancelled` — user dismissed the modal without logging in.
+- `unavailable` — no AuthKit is configured on this portal. Treat as
+  not-logged-in and surface an appropriate message; the user cannot log
+  in from this portal at all.
+
+---
+
+## Iframe Apps (Cross-Origin)
+
+Iframe apps don't share React context with the portal. They post a request
+message and listen for a single correlated reply:
+
+```ts
+const requestId = crypto.randomUUID();
+
+window.addEventListener('message', function handler(ev) {
+  const d = ev.data;
+  if (!d || d._smartlinksIframeMessage !== true) return;
+  if (d.type !== 'smartlinks:authkit:login-result') return;
+  if (d.payload?.requestId !== requestId) return;
+  window.removeEventListener('message', handler);
+
+  const { status, user, token } = d.payload;
+  if (status === 'success' || status === 'already-authenticated') {
+    // user + token populated — resume the action that needed auth
+    placeBid();
+  }
+});
+
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:request-login',
+  payload: {
+    requestId,
+    reason: 'bid',
+    mode: 'either',
+    resolveIfAuthenticated: true,
+  },
+}, '*');
+```
+
+The portal opens its modal, runs the standard AuthKit flow (including any
+WhatsApp / OAuth / magic-link redirect bounces), then posts exactly one
+`login-result` back with the same `requestId`.
+
+### Message contract
+
+**Request — child → parent**
+
+```ts
+{
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:request-login',
+  payload: {
+    requestId: string,             // generate per request; echoed in the reply
+    reason?: string,
+    mode?: 'login' | 'signup' | 'either',
+    signupProminence?: 'minimal' | 'balanced' | 'emphasized',
+    resolveIfAuthenticated?: boolean,
+  }
+}
+```
+
+**Reply — parent → child**
+
+```ts
+{
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:authkit:login-result',
+  payload: {
+    requestId: string,             // matches the request
+    status: 'success' | 'already-authenticated' | 'cancelled' | 'unavailable',
+    user?:  { uid, email?, displayName?, photoURL?, phoneNumber?, accountData? } | null,
+    token?: string | null,
+  }
+}
+```
+
+Only one reply is sent per `requestId`. Stacking multiple request-logins
+cancels prior pending requests — they receive `status: 'cancelled'`.
+
+---
+
+## Redirect-Bounce Flows (WhatsApp, OAuth, Magic Link)
+
+These are handled **inside the portal's AuthModal by AuthKit itself** —
+your iframe stays mounted at the same URL throughout. There is no
+sub-app state restoration to wire up; the modal closes when the redirect
+resolves and the portal posts back your `login-result`.
+
+If you have a sub-app that lives on a route the user navigates away from
+during the redirect, snapshot whatever you need into your own
+`sessionStorage` before calling `requestLogin`, the same as for any other
+async UX. The portal does not (yet) snapshot sub-app state on your behalf.
+
+---
+
+## Reading the Current Session
+
+You don't need to call `requestLogin` just to read the current session —
+that comes for free:
+
+```tsx
+// Container / widget
+import { useSafeAuth } from '@proveanything/portal-framework';
+const { user, token, isAuthenticated } = useSafeAuth() ?? {};
+```
+
+```ts
+// Iframe — the IframeResponder caches the parent's user under `cache.user`.
+// Read via the SDK's standard hooks/helpers.
+```
+
+---
+
+## Anti-Patterns
+
+❌ Sub-apps importing `@proveanything/smartlinks-auth-ui` and rendering
+   their own `<SmartlinksAuthUI />` modal. This is what `requestLogin`
+   replaces — duplicate React contexts cause silent header desync.
+
+❌ Posting `request-login` and then also opening a local fallback modal.
+   Pick one; the portal modal is canonical.
+
+❌ Reusing a single `requestId` across multiple calls. Generate a new ID
+   per request so replies can be correlated unambiguously.
+
+❌ Treating `unavailable` as an error to retry. It means the portal has no
+   AuthKit configured — surface a "login isn't available here" message.
+
+❌ Setting `resolveIfAuthenticated: false` for normal "gate this action"
+   use cases — you'll re-prompt logged-in users for no reason. Only use
+   it for genuine step-up auth.
+
+---
+
+## Relationship to `portal-auth-broadcast.md`
+
+| Concern | Use |
+|---|---|
+| "Log the user in so I can call my API" | **`requestLogin`** (this doc) |
+| "I ran my own custom auth flow, here's the resulting session" | [`portal-auth-broadcast.md`](./portal-auth-broadcast.md) |
+| "Log the user out of the whole portal" | `useAuth().logout()` (container/widget) or `smartlinks:authkit:logout` postMessage (iframe) |
+
+Both flows ultimately drive the same `PortalAuthProvider.login` /
+`logout` calls and produce the same observable side effects (header
+avatar, `useAuth()` re-render, `setBearerToken` on the SDK).

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.14.11  |  Generated: 2026-05-19T10:35:51.071Z
+Version: 1.14.13  |  Generated: 2026-05-19T11:49:34.090Z
 
 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)

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

package/docs/portal-back-button.md

@@ -1,20 +1,36 @@
-# Portal Back Button
+# Portal Back Button — "Up" Navigation Inside Sub-Apps
 
-> **For sub-app authors.** This guide explains how to make the portal's top back button behave like hierarchy-aware "up" navigation inside an embedded app.
+> **For sub-app authors.** Drop this file into the SmartLinks SDK docs (e.g.
+> `docs/portal-back-button.md`) and link it from `routing.md` / `mpa.md` so
+> microapp authors discover it.
 
-When a SmartLinks app is embedded inside the portal shell, the shell can render a top-level back button. By default that button exits the app entirely. That is correct for flat screens, but wrong for apps with internal hierarchy such as lists, detail pages, wizards, or nested checkout flows.
+When a sub-app is embedded by a portal shell, the shell renders a top-level
+back button. By default that button **exits the app entirely** when tapped —
+which is wrong for any app with internal hierarchy (lists → detail, wizards,
+etc.).
 
-This document describes the contract for telling the portal where "up" goes from the current screen so the shell can keep the app mounted and route to the correct parent screen instead of leaving the embed.
+This document describes the contract for telling the portal where "up" goes
+from the current screen, so the top back button performs **hierarchy-aware
+"up" navigation** inside your app instead.
 
-## Why "up", not browser back
+---
 
-Browser back replays history. If a user navigates `list -> item A -> list -> item B`, browser back can yo-yo between detail and list screens in a way that feels wrong for an app chrome back button.
+## Why "up", not "back"
 
-"Up" navigates the content hierarchy instead: `item B -> list -> exit app`. It is single-direction and idempotent. Only your app's router knows that hierarchy, so the portal cannot infer it on its own.
+Browser back replays history. If a user navigates **list → item A → list →
+item B**, browser back yo-yos:  `B → list → A → list → ...`. That is not what
+users expect from an "up arrow" in app chrome.
 
-## The contract
+"Up" navigates the **content hierarchy**:  `B → list → exit app`. It is
+single-direction and idempotent. Only your app's router knows the hierarchy,
+so the portal can't infer it — your app must declare it.
 
-When your app posts `smartlinks-route-change` messages, include a `parentPath` field inside `state` for the current screen:
+---
+
+## The Contract
+
+With every `smartlinks-route-change` your app already posts (via
+`useDeepLinkSync` or directly), include a `parentPath` field inside `state`:
 
 ```ts
 window.parent.postMessage({
@@ -22,7 +38,8 @@ window.parent.postMessage({
   path: '/items/123',
   context: { collectionId: 'auction-2026', appId: 'auction' },
   state: {
-    parentPath: '/items',
+    parentPath: '/items',   // ← where "up" goes from /items/123
+    // ... your other app state
   },
   appId: 'auction',
 }, '*');
@@ -30,43 +47,68 @@ window.parent.postMessage({
 
 | `state.parentPath` value | Portal back-button behaviour |
 | --- | --- |
-| `'/items'` (or any string) | The portal posts `smartlinks-navigate` to the iframe with that path and keeps the app mounted. |
-| `''`, missing, or omitted | The portal falls back to the default behaviour and exits the app. |
+| `'/items'` (or any string) | Posts `smartlinks-navigate` to the iframe with that path. App stays mounted. |
+| `''` / missing / omitted   | Default: clears the active app and returns to the portal homepage. |
+
+When the portal sends the up-navigation message, your app must respond by
+navigating to that path. If you use `useDeepLinkSync` with an SDK release
+that includes the inbound `smartlinks-navigate` listener, this is automatic —
+otherwise add a listener (see "Receiving the up-message" below).
 
-The portal only uses `parentPath` when it is present on the current route. Query-string changes, tab switches, and modal state should keep the same parent path.
+---
 
-## Recommended pattern
+## Recommended sub-app pattern (React Router)
 
-Keep the hierarchy mapping close to your route definitions:
+Keep "what's above this route" co-located with your route definitions:
 
 ```ts
+// routes.ts
 const PARENTS: Record<string, (params: any) => string | null> = {
-  '/': () => null,
-  '/items': () => null,
-  '/items/:id': () => '/items',
-  '/items/:id/bid': ({ id }) => `/items/${id}`,
-  '/checkout': () => '/items',
+  '/':                () => null,           // home — back exits the app
+  '/items':           () => null,           // list — back exits the app
+  '/items/:id':       () => '/items',       // detail — back goes to list
+  '/items/:id/bid':   ({ id }) => `/items/${id}`,
+  '/checkout':        () => '/items',
 };
 
 export function getParentPath(pathname: string): string | null {
-  // Use your router's path matching here and return the parent route.
-  return null;
+  // matchPath against PARENTS keys — return parent or null
+  // (use react-router's matchPath in your real implementation)
 }
 ```
 
-Then emit `parentPath` whenever the route changes:
+```tsx
+// App.tsx
+import { useDeepLinkSync } from '@/hooks/useDeepLinkSync';
+import { getParentPath } from './routes';
+
+function App() {
+  useDeepLinkSync({
+    getParentPath: ({ pathname }) => getParentPath(pathname),
+  });
+  // ...
+}
+```
+
+If your app does not use `useDeepLinkSync`, post the message yourself:
 
 ```ts
-useDeepLinkSync({
-  getParentPath: ({ pathname }) => getParentPath(pathname),
-});
+useEffect(() => {
+  if (window.parent === window) return;
+  window.parent.postMessage({
+    type: 'smartlinks-route-change',
+    path: location.pathname,
+    context: { /* ... */ },
+    state: { parentPath: getParentPath(location.pathname) ?? '' },
+  }, '*');
+}, [location.pathname]);
 ```
 
-If you do not use `useDeepLinkSync`, post the message yourself and include `parentPath` in `state`.
+---
 
-## Receiving the up-message
+## Receiving the up-message (`smartlinks-navigate`)
 
-When the portal consumes `parentPath`, it posts `smartlinks-navigate` back to the iframe:
+When the portal back button consumes a `parentPath`, it posts:
 
 ```ts
 {
@@ -78,18 +120,68 @@ When the portal consumes `parentPath`, it posts `smartlinks-navigate` back to th
 }
 ```
 
-Your app should listen for that message and route accordingly. If your SDK release already includes the inbound `smartlinks-navigate` listener, this can be automatic; otherwise add a small `message` listener and call your router manually.
+Your app must listen for this and route accordingly. A minimal hook:
+
+```ts
+import { useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+
+export function useParentNavigation() {
+  const navigate = useNavigate();
+  useEffect(() => {
+    const onMessage = (e: MessageEvent) => {
+      if (e.data?.type !== 'smartlinks-navigate') return;
+      if (typeof e.data.path !== 'string') return;
+      navigate(e.data.path);
+    };
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+  }, [navigate]);
+}
+```
+
+---
+
+## Reference: Updated `RouteChangeMessage`
+
+`state` is an open `Record<string, string>` — `parentPath` is a recognised
+optional convention; everything else flows through unchanged.
+
+```ts
+interface RouteChangeMessage {
+  type: 'smartlinks-route-change';
+  path: string;
+  context: Record<string, string>;
+  state: Record<string, string> & {
+    /**
+     * Optional. The "up" target from the current screen. When present, the
+     * portal's top back button posts smartlinks-navigate with this path
+     * instead of exiting the app. Empty / missing → exits the app.
+     */
+    parentPath?: string;
+  };
+  appId?: string;
+}
+```
 
-## Reference
+No breaking change: existing apps that don't emit `parentPath` keep today's
+behaviour (one tap of the portal back exits the app).
 
-`state` remains a general `Record<string, string>`. `parentPath` is a recognised optional convention, not a breaking protocol change.
+---
 
 ## FAQ
 
-**Do I need to push every query-param change as a navigation step?** No. `parentPath` is hierarchy, not history.
+**Q: Do I need to push every query-param change as a navigation step?**
+No. `parentPath` is hierarchy, not history. A filter toggle, a tab switch,
+or a modal open on the same screen should keep the same `parentPath`.
 
-**What if my up target leaves the app?** Set `parentPath` to `''` or omit it.
+**Q: What if my "up" leaves the app?**
+Set `parentPath` to `''` (or omit it). The portal will exit the app on back.
 
-**Can I disable the portal back button on certain screens?** Not via this protocol. Use the existing `homeScope: 'entry'` portal behaviour if you need the shell back button suppressed.
+**Q: Can I disable the portal back button on certain screens?**
+Not directly via this protocol. Use the existing portal `homeScope: 'entry'`
+mechanism if you need the entire portal back button suppressed.
 
-**What about an in-app back button?** Keep it if you want. The portal back is shell chrome; an in-content back is part of the app UI.
+**Q: What about the in-app back button I already render?**
+Keep it if you want — they're not mutually exclusive. The portal back is
+chrome; an in-content back is content. Many apps will only need one.