@vinaverse/react-native 0.1.0-alpha.3 → 0.1.0-alpha.5

package/README.md

@@ -2,12 +2,13 @@
 
 A ready, themeable conversation with your Vinaverse agent for React Native and Expo apps. Drop it into a screen,
 give it a conversation whose session comes from your backend, and it draws everything the realtime protocol defines:
-streaming replies, cards (people, services, bookings, questions, proposals, next steps), held and unsent messages, a
+streaming replies, cards (photo cards for people and places, services, bookings, questions, proposals, next steps,
+your own help pages), held and unsent messages, a
 person from your business taking over, and every way a session ends. No native module; New Architecture; FlashList 2.3.2 or later.
 
 ```tsx
 import { createConversation } from '@vinaverse/client/conversation';
-import { VinaverseChat } from '@vinaverse/react-native';
+import { CardCarousel, VinaverseChat } from '@vinaverse/react-native';
 
 // Outside the screen: it connects early and survives navigation.
 const conversation = createConversation({
@@ -15,6 +16,8 @@ const conversation = createConversation({
   locale: 'es-US',
   deepLinkPrefixes: ['yourapp://bookings/'],
 });
+// Opt-in: a turn's listing cards in one swipeable row (without it they stack). Module level: a stable object.
+const components = { CardGroup: CardCarousel };
 
 export function AgentScreen() {
   return (
@@ -22,6 +25,7 @@ export function AgentScreen() {
       conversation={conversation}
       locale="es-US"
       theme={{ light: { primary: '#7A2E8E', personBubble: '#7A2E8E' } }}
+      components={components}
       onProposal={(card, decision) => api.decideProposal(card, decision)} // your backend, the person's token
       onOpenLink={(link) => router.push(link)}
     />
@@ -29,6 +33,72 @@ export function AgentScreen() {
 }
 ```
 
+## Hosting the agent (the runtime)
+
+An app that hosts the agent writes its backend once (`createAgentRuntime`, `@vinaverse/client/agent`) and draws the
+parts; which conversation, keeping it across screens, waiting the backend out, a conversation that ended, the backend
+out of reach, status, name, ratings and sign-out are the runtime's.
+
+```tsx
+import { createAgentRuntime } from '@vinaverse/client/agent';
+import { AgentChat, AgentLauncher, AgentRuntimeProvider, AskAboutRow, CardCarousel } from '@vinaverse/react-native';
+
+const agent = createAgentRuntime({ backend: { openSession, refreshSecret, status }, conversation: { locale } });
+const components = { CardGroup: CardCarousel, Image: ExpoImage }; // module level: stable
+const imagePolicy = { hosts: ['images.example.com'], aspectRatio: 1.6, Placeholder: BrandTile }; // stable too
+
+<AgentRuntimeProvider runtime={agent}>
+  <Tabs />
+  <AgentLauncher subject={user?.id ?? null} mode={side} Mark={YourMark}
+    route={currentTab} routes={['home', 'explore']} hidden={sheetOpen}  // never with the keyboard up
+    storage={preferences} onOpen={({ route, mode }) => openChat(route, mode)}
+    style={{ position: 'absolute', right: 16, bottom: tabBarHeight + 16 }} />
+</AgentRuntimeProvider>
+
+// The chat screen
+<AgentChat
+  agentKey={{ subject: user?.id ?? null, mode: side, scope: businessId }}
+  place={{ screen: 'professional', entity: { type: 'professional', id } }}
+  askAbout={`Tell me about ${name}`}        // offered when the session was told another place
+  starters={startersFor(screen)}            // when the session brings no welcome
+  components={components}
+  onOpenTarget={(t) => router.push(routeFor(t))}   // a card about a professional, a space, a booking
+  onOpenLink={openLink}
+  onContact={() => router.push('/contact')}       // a person, when the agent fails or is unavailable
+  onOpenPrivacy={() => router.push('/privacy')}
+  prefetchImage={(url) => Image.prefetch(url)}
+  imagePolicy={imagePolicy}
+/>
+
+// On the app's own page about a professional
+<AskAboutRow title={`Ask ${agentName} about ${name}`} onPress={() => openChat('professional', side)} />
+```
+
+- **Parts:** `AgentChat` draws the conversation, a conversation that ended (`components.Ended`, start over), the backend
+  out of reach (`components.Unreachable`, try again), no agent at all (`components.UnavailableScreen`, the whole
+  screen: off, or the session refused, with a person through `onContact`), and under the composer thumbs on the newest
+  whole reply and the privacy link (`components.Footer`, `null` to hide); each slot gets the kit's part as `Default`,
+  to wrap it. `opener` is a first question as a chip the person taps (a flow that asks for itself), until they say
+  anything; nothing is ever sent in their name. `AgentLauncher` is a round button with
+  a greeting bubble once per person and mode (`storage`: your preferences store; `greeting`: words or words by mode,
+  read through `announce`; `storageKey` maps the record to one your app already keeps, so nobody is greeted twice),
+  your `Mark` inside, floating where `placement` says (`edge`, `bottom` above your tab bar, `inset`; `style` after it),
+  with `appearance` (a `ring`, the `shadow`, the bubble's `tail`), shown on your `routes` only, never with the keyboard
+  up (`hideWithKeyboard`), stepping aside when you say (`hidden`), and only when the status offers it; its button,
+  bubble and entrance are slots (`LauncherButton`, `LauncherGreeting`, `LauncherEntrance`: a short fade and scale,
+  none with reduced motion). `AskAboutRow` is "ask the agent about this" on
+  your own pages, shown when the agent is available, decided once per visit.
+- **Policies and adapters:** `imagePolicy` (photo hosts, frame, the stand-in for a missing photo) applies to every card
+  and every fetch ahead; `announce` reads finished replies and the greeting your way; `onChip` hears a tapped chip.
+  Card renderers get the card read once (`read`).
+- **Hooks** for your own parts: `useAgentConversation`, `useAgentStatus`, `useAgentFeatures`, `useAgentProfile`,
+  `useAgentName`, `useAgentLauncher`, `useAgentRuntime`.
+- **Events** for analytics through `onEvent`: sessions, ratings, chips, targets and links opened, the launcher shown,
+  opened, greeted and its greeting closed.
+- **StrictMode, in development only:** React mounts, unmounts and mounts again, so a conversation still opening is let
+  go with the first unmount and the second mount asks your backend for another session: two `openSession` calls per
+  opening in development, one in a release build. The first request's answer is dropped, never shown.
+
 ## Install
 
 ```sh
@@ -65,6 +135,12 @@ kit share one copy of `@vinaverse/client`.
 - **Background**: the kit tells the conversation when the app goes to the background and comes back (`AppState`).
   By default the connection stays, without pings; `createConversation({ closeInBackground: true, refreshSecret })`
   closes it in the background and opens it again, with a fresh secret, in the foreground. Nothing typed is lost.
+- **A session's end**: pass `expires_at` on from the session your backend created. Past it (the tenant's tool token
+  with it), the person's next message gets a new session for the same conversation from `getSession`; the old one is
+  never reopened with a fresh secret. A reconnect keeps everything drawn: the session's transcript merges by id.
+- **Modes**: a customer and a professional each get their own conversation, `createConversationsByMode`, and the
+  screen draws `conversations.select(mode)`. Each mode keeps its own history on the device, and `getSession` gets the
+  `mode` so your backend creates the session for that mode's agent.
 - **Language**: the agent answers in `subject.locale`, which your backend sets when it creates the session; the kit's
   `locale` prop is only for its own words, dates and money (and is passed to `getSession` as a hint you may ignore).
 
@@ -103,6 +179,26 @@ part as `Default`. With neither, the kit draws both as before.
 | `retry` | try again, when it can be: the person's text once more, for a turn the server allows to retry (once); a new session for `unavailable`. Undefined otherwise |
 | `conversationId` | the conversation, once a session named it: for your support records |
 
+## Listings, carousels, links and the welcome
+
+- **Professionals and spaces** draw as photo cards: the hero photo (through your `Image` slot, so `expo-image`'s cache
+  applies), the name's monogram when there is none or it fails, rating with its count, "From $45" and the next open
+  time.
+- **A carousel** for the cards a turn draws together: add the kit's `CardCarousel`. Without it they draw one under
+  another; it is opt-in so an app that does not use it does not ship it.
+
+  ```tsx
+  import { CardCarousel, VinaverseChat } from '@vinaverse/react-native';
+  const components = { Image: ExpoImage, CardGroup: CardCarousel }; // module level: a stable object
+  <VinaverseChat conversation={conversation} components={components} onOpenLink={openLink} />;
+  ```
+
+- **Links**: when your scope keeps the agent from answering, it shows your own help, support, policy, contact or
+  feedback pages. Each opens through `onOpenLink` (an https page too: your in-app browser), a deep link only when it
+  passes your deep-link prefixes.
+- **The welcome**: pass `welcome` on from the session your backend created; the kit greets an empty conversation with
+  it and its chips (no model call). A chip sends its message as the person's own. An `EmptyState` slot gets both.
+
 ## The keyboard
 
 `keyboardBehavior` keeps the composer above the keyboard: `padding` on iOS by default, nothing on Android (the window