@vinaverse/react-native 0.1.0-alpha.2 → 0.1.0-alpha.4

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)}
     />
@@ -65,6 +69,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).
 
@@ -76,8 +86,53 @@ kit share one copy of `@vinaverse/client`.
 | `onOpenLink(link, card)` | a card's link (it already passed the deep-link rule): route by the page it names |
 | `onCardAction(card, action)` | a card action without a link (also sent to the session) |
 | `onPickPhoto(question, card)` | a photo question: pick, upload to your backend, return `{ upload_ref }` |
+| `failureAction` | `{ label?, onPress(state) }`: a way out on a failed turn and on "couldn't connect" ([When the agent fails](#when-the-agent-fails)) |
 | `onWarning(message)` | development warnings: a hard-to-read theme, copy that says "assistant" |
 
+## When the agent fails
+
+Two failures need a way out for the person: a turn that failed before any reply ("Something went wrong.") and no
+session to talk to ("Couldn't connect.", with "Try again"). Give one action for both, drawn as a button by the kit's
+own parts, so a person is always the way out:
+
+```tsx
+<VinaverseChat
+  conversation={conversation}
+  failureAction={{ onPress: (state) => openSupport(state.conversationId) }} // "Talk to a person", in the person's language
+/>
+```
+
+`label` replaces "Talk to a person" (the copy's `talkToPerson`, which `copy` can also change). Or replace either part:
+`components.Error` (the failed turn) and `components.Unavailable` (the banner) each get the `state` and the kit's own
+part as `Default`. With neither, the kit draws both as before.
+
+| `state` | |
+|---|---|
+| `kind` | `turn_failed` or `unavailable` |
+| `reason` | the turn's error code (`internal`, `timeout`, …), or `unavailable` / `unauthorized` |
+| `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