@molecule/app-react-native 1.0.1 → 1.0.2

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-08-04T01:52:27.270Z
+Generated: 2026-09-15T13:40:29.572Z
 -->
 
 # @molecule/app-react-native
@@ -693,6 +693,16 @@ interface SendMessageOptions {
    * user-initiated one IS that re-engagement — it clears the stop and sends.
    */
   userInitiated?: boolean
+  /**
+   * Send on the SIDE CHANNEL: a human-to-human message (e.g. a team note) the
+   * server intercepts before running any agent turn. When the provider supports
+   * `sendSideMessage`, the send goes out IMMEDIATELY on an independent request —
+   * it never queues behind an active turn, never takes over the streaming
+   * state, and never tears down remote-turn tracking (a viewer's note while
+   * watching a teammate's turn must not stop the watching). Falls back to the
+   * normal send path on providers without side-channel support.
+   */
+  sideChannel?: boolean
 }
 ```
 
@@ -904,6 +914,15 @@ interface UseChatOptions {
   agentName?: string
   /** Load history on mount. */
   loadOnMount?: boolean
+  /**
+   * This client may only WATCH the conversation (e.g. a read-only project
+   * viewer): the hook never issues chat POSTs on its behalf — no resume
+   * request after a reload, no auto-retries. A live turn is followed through
+   * the remote-watch path instead: pushed broadcast frames (applyRemoteEvent)
+   * render it in real time and the history reconcile poll backstops gaps, with
+   * `isRemoteStreaming` driving the activity indicator.
+   */
+  readOnly?: boolean
   /** Called when a file is created or modified by a tool call (path + new content). */
   onFileChange?: (path: string, content: string) => void
   /** Called when the AI switches between plan and execute modes. */
@@ -940,10 +959,21 @@ interface UseChatResult {
    */
   noteRemoteStreamEvent: () => void
   error: string | null
-  /** Metadata about a limit-related error (for contextual upgrade CTAs). */
+  /**
+   * Metadata about a limit-related error, for a contextual call-to-action.
+   * `limitType` names the RULE the backend enforced; `billingAction` names the
+   * REMEDY it resolved (e.g. `add_funds`, `add_payment_method`,
+   * `raise_spend_cap`, `upgrade`, `none`) and is what the button should be
+   * built from — the same limit needs a different button per account.
+   * `upgradeTier` is the plan an upgrade would move to, explicitly `null` when
+   * there is no higher tier. The backend owns these vocabularies, so the
+   * action/tier are plain strings here.
+   */
   errorMeta: {
     limitType?: string
     requiresSignup?: boolean
+    billingAction?: string
+    upgradeTier?: string | null
   } | null
   /** Current agent mode — plan (read-only research) or execute (full access). */
   mode: 'plan' | 'execute'
@@ -1006,6 +1036,35 @@ interface UseChatResult {
     timestamp: number,
     card: NonNullable<ChatMessage['cardEvent']>,
   ) => void
+  /**
+   * Append a COMPLETE, non-streaming chat message (a `message` stream event — e.g.
+   * a teammate's human-only team note) to the ONE message store. Used by the host
+   * (ChatPanel) to render a TEAMMATE's broadcast `message` event live — this
+   * client's OWN `message` events arrive through the stream and are appended
+   * internally. De-duped by the server-assigned message id.
+   */
+  appendCompleteMessage: (message: ChatMessage) => void
+  /**
+   * Ingest ONE pushed (broadcast) stream frame from a turn running elsewhere —
+   * a teammate's send, another tab, a server-side continuation — into the ONE
+   * message store, through the same content applier as an own SSE stream: text/
+   * thinking deltas, tool events, verification, cards, complete messages, done.
+   * The host (ChatPanel) calls this from its push-channel handler for every
+   * broadcast frame of the OPEN conversation. Own echoes are dropped while a
+   * local send is in flight (the SSE stream is authoritative for the sender);
+   * complete id-carrying items (cards, team notes) always apply, de-duped.
+   */
+  applyRemoteEvent: (event: ChatStreamEvent) => void
+  /**
+   * Reload history and converge the local view on the server transcript (and
+   * re-enter a still-streaming turn). The page-lifecycle events run this
+   * automatically; the host should ALSO call it whenever its chat push channel
+   * (re)connects — a broadcast sent while that socket was down (a teammate's
+   * team note against a backgrounded tab or a slept laptop) is otherwise lost
+   * until the next lifecycle event happens to fire. Cheap when nothing changed:
+   * an identical transcript is never re-applied.
+   */
+  reconcileHistory: () => Promise<void>
 }
 ```
 
@@ -1386,6 +1445,57 @@ interface UseTranslationResult {
 }
 ```
 
+#### `UseVerifyPaymentReturnOptions`
+
+Options for {@link useVerifyPaymentReturn}.
+
+```typescript
+interface UseVerifyPaymentReturnOptions {
+  /**
+   * Provider name to verify with, when the return URL carries no `provider`
+   * query parameter. Leave unset to verify only what the URL names.
+   */
+  provider?: string
+  /** Set `false` to skip verification entirely (e.g. behind a feature flag). */
+  enabled?: boolean
+  /**
+   * Remove the provider's query parameters from the address bar once the
+   * purchase is verified, so a reload (or a shared link) cannot replay the
+   * verification. Defaults to `true`.
+   */
+  cleanUrl?: boolean
+  /** Called once, after the purchase verifies. */
+  onVerified?: () => void
+  /** Called when verification fails. */
+  onError?: (error: Error) => void
+}
+```
+
+#### `UseVerifyPaymentReturnResult`
+
+State of the post-checkout verification.
+
+```typescript
+interface UseVerifyPaymentReturnResult {
+  /**
+   * `idle` when this page load is not a checkout return (no transaction id in
+   * the URL) or auth is still hydrating; `verifying` while the API call is in
+   * flight; then `verified` or `failed`.
+   */
+  status: VerifyPaymentReturnStatus
+  /** `true` when the URL identifies a purchase to verify. */
+  isReturn: boolean
+  /** The provider named by the URL (or the `provider` option). */
+  provider: string | null
+  /** The provider transaction/session id read from the URL. */
+  transactionId: string | null
+  /** Why verification failed, when it did. */
+  error: Error | null
+  /** Re-run the verification — wire this to a retry button. */
+  retry: () => void
+}
+```
+
 #### `UseVersionResult`
 
 Hook return type.
@@ -1461,6 +1571,14 @@ type UseCapacitorAppResult = CapacitorAppState & {
 }
 ```
 
+#### `VerifyPaymentReturnStatus`
+
+How far the return-page verification has got.
+
+```typescript
+type VerifyPaymentReturnStatus = 'idle' | 'verifying' | 'verified' | 'failed'
+```
+
 ### Functions
 
 #### `AuthProvider(props)`
@@ -1538,6 +1656,25 @@ function I18nProvider({
 
 **Returns:** The rendered i18n provider element.
 
+#### `localOnlyMessages(prev, history)`
+
+The messages only the local store holds, given a server history: optimistic
+bubbles and session-local cards, minus the optimistic ECHO of a send the
+server already persisted. A local user message carries a local id
+(`user-N`), the server's copy a server id, so ids never match — content does.
+Without this, the dashboard's first prompt (auto-sent by the workspace,
+then merged back in from history by the remote-stream poll) rendered as two
+identical user bubbles in every new project (2026-09-08).
+
+```typescript
+function localOnlyMessages(prev: ChatMessage[], history: ChatMessage[]): ChatMessage[]
+```
+
+- `prev` — The store's current messages.
+- `history` — The server's history.
+
+**Returns:** The local-only messages to keep after the merged history.
+
 #### `LoggerProvider(props)`
 
 Provider for logging.
@@ -2428,6 +2565,35 @@ function useUser(): T | null
 
 **Returns:** The authenticated user or null
 
+#### `useVerifyPaymentReturn(options)`
+
+Reads the payment id a provider put in the return URL and confirms the
+purchase server-side with `POST /users/:id/verify-payment/:provider`.
+
+**This is why a hosted checkout returns the buyer to the APP and not the
+API.** Session cookies are host-only on the app's origin, so a top-level
+redirect from the provider straight to an authenticated API callback on a
+different host arrives with NO credentials — it answers 401 and the paid plan
+is never granted. The request this hook makes is a same-origin call from a
+loaded app page, so the credentials apply. It waits for auth to hydrate
+first: after the redirect the page is a cold load, and the session is
+restored from the httpOnly cookie via `GET /users/me`.
+
+Verification is idempotent server-side (first-claim-wins on the transaction),
+and this hook additionally runs at most once per transaction id per page.
+Safe on pages that are also reached normally: with no id in the URL it stays
+`idle` and issues no request.
+
+```typescript
+function useVerifyPaymentReturn(
+  options?: UseVerifyPaymentReturnOptions,
+): UseVerifyPaymentReturnResult
+```
+
+- `options` — Provider fallback + lifecycle callbacks (see {@link UseVerifyPaymentReturnOptions}).
+
+**Returns:** The verification state (see {@link UseVerifyPaymentReturnResult}).
+
 #### `useVersion()`
 
 Hook for version state and update actions.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@molecule/app-react-native",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "React Native framework bindings for molecule.dev",
+  "homepage": "https://www.molecule.dev/packages/app-react-native",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,11 +33,11 @@
     "directory": "packages/app/frameworks/react-native"
   },
   "devDependencies": {
-    "@molecule/app-react": "1.0.1",
+    "@molecule/app-react": "1.5.1",
     "@types/node": "26.1.2",
     "react": "19.2.8",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "peerDependencies": {
     "@molecule/app-keyboard": "^1.0.1",