@proveanything/smartlinks 1.14.11 → 1.14.13

package/docs/portal-request-action.md

@@ -0,0 +1,289 @@
+# Requesting Built-in Portal Actions
+
+`requestAction` is the general-purpose sibling of
+[`requestLogin`](./portal-request-login.md). It lets a sub-app
+(container, widget, or iframe) trigger any of the portal's built-in
+capabilities — open the QR scanner, log out, copy the current link,
+navigate to another app — and await a result.
+
+Use it whenever the answer to *"what do I want?"* is one of the
+portal's standardized capabilities. The portal owns the implementation;
+your sub-app declares intent.
+
+---
+
+## Why this exists
+
+Linkpage-style apps, action grids and CTAs across the platform all need
+the same primitives: scan a QR, take a photo, copy a link, jump to
+another app, log the user out. Without a shared contract every app
+re-implemented these against direct browser APIs, fragmenting UX and
+breaking cross-iframe boundaries. `requestAction` is the contract.
+
+---
+
+## Container / Widget Apps (Same React Tree)
+
+```tsx
+import { usePortalActions } from '@proveanything/portal-framework';
+
+function ShareButton() {
+  const portal = usePortalActions();
+  async function onClick() {
+    const result = await portal?.requestAction('__share', {
+      title: 'Check this out',
+      url: window.location.href,
+    });
+    // result.status === 'success' | 'cancelled' | 'unavailable' | 'error' | 'triggered'
+  }
+  return <button onClick={onClick}>Share</button>;
+}
+```
+
+`usePortalActions()` returns `null` when no `ActionRequestProvider` is
+mounted upstream — treat that the same as `status: 'unavailable'`.
+
+### Discovering available actions
+
+```ts
+const ids = portal?.getAvailableActions() ?? [];
+// → ['__refresh','__share','__copyLink','__navigate','__login','__logout',
+//    '__account','__qrScanner','__barcodeScanner','__nfcScanner', ...]
+```
+
+Combine with `BUILTIN_ACTION_META` (also exported) for labels/icons in
+your action pickers.
+
+---
+
+## Iframe Apps (Cross-Origin)
+
+```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:action:result') return;
+  if (d.payload?.requestId !== requestId) return;
+  window.removeEventListener('message', handler);
+
+  const { status, value, error } = d.payload;
+  // …handle result
+});
+
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:action:request',
+  payload: {
+    requestId,
+    actionId: '__copyLink',
+    params: { url: window.location.href },
+  },
+}, '*');
+```
+
+### Capabilities probe
+
+```ts
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:action:capabilities',
+  payload: { requestId },
+}, '*');
+// reply: type 'smartlinks:action:capabilities:result'
+//   payload: { requestId, actions: string[], meta: Record<id, {label, icon, description, available}> }
+```
+
+Use this to hide actions the host doesn't support (e.g. `__nfcScanner`
+on iOS web).
+
+---
+
+## Built-in actions
+
+| Action ID | Kind | Params | Success value |
+|---|---|---|---|
+| `__refresh` | sync | — | — |
+| `__share` | sync | `{ title?, text?, url? }` | `{ method: 'native' \| 'clipboard' }` |
+| `__copyLink` | sync | `{ text?, url? }` | `{ url }` |
+| `__navigate` | sync | `{ appId, deepLink?, deepLinkParams? }` | — |
+| `__login` | sync | `{ reason?, mode?, resolveIfAuthenticated? }` | `{ user, token }` |
+| `__logout` | sync | — | — |
+| `__account` | sync | login params | login → `{ user, token }`; logout → — |
+| `__qrScanner` | overlay | `{ suppressNavigation?: boolean }` | `{ text, format, resolved?: { collectionId, productId?, proofId? } }` |
+| `__barcodeScanner` | overlay | `{ suppressNavigation?: boolean }` | `{ text, format }` |
+| `__nfcScanner` | overlay | `{ suppressNavigation?: boolean }` | `{ serial, payload? }` (Android only) |
+| `__language` | overlay | — | — |
+| `__profile` | page | — | — |
+| `__settings` | page | — | — |
+
+> **`__login` vs `requestLogin`:** For the common case of "I just need a
+> logged-in user before continuing", prefer
+> [`requestLogin`](./portal-request-login.md) — it is a typed convenience
+> wrapper around `requestAction('__login', ...)` with a richer result
+> contract. Use `__login` / `__account` via `requestAction` only when you
+> are composing with other built-in actions in the same flow.
+
+---
+
+## App-registered actions
+
+Sub-apps may register their own action IDs via `siteInjections.actions`
+on `OrchestratedPortal`. Those IDs become callable through the same
+`requestAction` / postMessage contract as built-ins. Unlike built-ins they
+are not guaranteed to be present on every portal — always probe
+`getAvailableActions()` before using them.
+
+---
+
+## Result shape
+
+```ts
+type ActionRequestResult = {
+  status:
+    | 'success'      // action completed (sync actions may carry a value; capture overlays always do)
+    | 'cancelled'    // user dismissed the overlay without completing
+    | 'unavailable'  // unknown action or capability not present on this host
+    | 'error';       // action threw
+  value?: unknown;
+  error?: string;
+  requestId?: string; // echoed on postMessage replies
+};
+```
+
+All actions now resolve to one of these four terminal statuses. There is no
+`triggered` intermediate status — capture-mode overlays (QR, barcode, NFC)
+keep the caller's promise pending until the user completes the scan or
+dismisses the overlay.
+
+---
+
+## Scanner actions in detail
+
+QR, barcode, and NFC scanner actions open the portal's scanner overlay and
+**await user input** — the promise (or postMessage reply) is held open until
+the user either completes a scan or dismisses the overlay.
+
+By default the portal also performs its standard navigation after a
+successful scan (e.g. resolving a SmartLinks proof URL). Pass
+`suppressNavigation: true` when you want the raw value and no portal routing.
+
+```ts
+// Container / widget — get the scanned value, skip portal navigation
+const result = await portal.requestAction('__qrScanner', {
+  suppressNavigation: true,
+})
+if (result.status === 'success') {
+  const { text, format, resolved } = result.value as QrScanResult
+  // text    — raw scanned string
+  // format  — e.g. 'QR_CODE', 'EAN_13'
+  // resolved — if the text decoded to a SmartLinks URL:
+  //   { collectionId, productId?, proofId? }
+}
+if (result.status === 'cancelled') {
+  // user closed the scanner without scanning
+}
+```
+
+```ts
+// Container / widget — let the portal navigate AND get the value
+const result = await portal.requestAction('__qrScanner')
+// portal navigates to the scanned link; sub-app also gets the value
+```
+
+```ts
+// Iframe — same contract via postMessage
+const requestId = crypto.randomUUID()
+
+window.addEventListener('message', function handler(ev) {
+  const d = ev.data
+  if (!d?._smartlinksIframeMessage) return
+  if (d.type !== 'smartlinks:action:result') return
+  if (d.payload?.requestId !== requestId) return
+  window.removeEventListener('message', handler)
+
+  if (d.payload.status === 'success') {
+    const { text, format, resolved } = d.payload.value
+    // use the scan result
+  }
+})
+
+window.parent.postMessage({
+  _smartlinksIframeMessage: true,
+  type: 'smartlinks:action:request',
+  payload: {
+    requestId,
+    actionId: '__qrScanner',
+    params: { suppressNavigation: true },
+  },
+}, '*')
+```
+
+### Scan value types
+
+```ts
+type QrScanResult = {
+  text: string
+  format: string                           // 'QR_CODE', 'EAN_13', etc.
+  resolved?: {
+    collectionId: string
+    productId?: string
+    proofId?: string
+  }
+}
+
+type BarcodeScanResult = {
+  text: string
+  format: string
+}
+
+type NfcScanResult = {
+  serial: string
+  payload?: string
+}
+```
+
+---
+
+## Relationship to `LinkTarget`
+
+Linkpage-style UIs persist a `LinkTarget` of kind `'action'`:
+
+```ts
+type ActionLinkTarget = {
+  kind: 'action';
+  actionId: string;
+  params?: Record<string, unknown>;
+};
+```
+
+At runtime, resolve it through the portal:
+
+```ts
+await portal?.requestAction(target.actionId, target.params);
+```
+
+Never persist a resolved URL when an action is intended — the action
+contract may change platform-side, the persisted ID won't.
+
+---
+
+## Anti-patterns
+
+❌ Calling `navigator.share` / `clipboard.writeText` directly from a
+   sub-app when `__share` / `__copyLink` exist — you lose host-level
+   error handling and capability negotiation.
+
+❌ Re-implementing logout by clearing your own state. Always go through
+   `__logout` (or `useAuth().logout()` in-tree) so the whole portal
+   session ends cleanly.
+
+❌ Hard-coding action IDs the host might not support. Probe
+   `getAvailableActions()` or the capabilities postMessage first.
+
+❌ Reusing a single `requestId` across postMessage calls.
+
+❌ Not awaiting the result of capture-mode scanner actions. The promise
+   stays pending until the user scans or cancels — fire and forget will
+   leak the listener.

package/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/package.json

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