@qafka/react-native 2.3.7 → 2.3.8

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [2.3.8] — 2026-06-17
+
+### Added
+
+- Ships `docs/qafka-tool-authoring-guide.md` inside the package — a version-matched guide that tells AI coding assistants (and developers) exactly what to configure in the Qafka dashboard and what to implement in code when authoring a tool. The Qafka CLI points a project's `CLAUDE.md` at this file, so the guidance always matches the installed SDK version.
+
 ## [2.1.1] — 2026-06-03
 
 ### Fixed

package/dist/components/MessageBubble.js

@@ -75,7 +75,8 @@ function MessageBubble({ message, role, timestamp, theme, showTimestamp = true,
                 : dataToRender;
             // Check layout preference (default: vertical)
             const layout = response.layout || 'vertical';
-            // If custom layout, pass entire array to component
+            // If custom layout, pass entire array to component.
+            // VoicePage's tool list branch mirrors this same contract — keep both in sync.
             if (layout === 'custom') {
                 return (<react_native_1.View style={{ marginTop: theme.spacing.md }}>
  <CustomComponent data={items} // Full array

package/dist/components/VoicePage.js

@@ -67,6 +67,18 @@ const BASELINE_PHASE_MS = 800;
 const SPIKE_DURATION_MS = 700;
 const SPIKE_THRESHOLD = 0.3;
 const SPIKE_MIN_INTERVAL_MS = 150;
+// Resolve a uiConfig.dataPath ("data" or nested "data.campaigns") against the
+// tool result envelope. Mirrors MessageBubble's text-mode walk byte-for-byte so
+// list/card data is read from the same level in both render paths. No dataPath
+// → the whole envelope (single-card tools that scope nothing).
+function resolveDataPath(envelope, dataPath) {
+    if (!dataPath)
+        return envelope;
+    let cur = envelope;
+    for (const part of dataPath.split('.'))
+        cur = cur?.[part];
+    return cur;
+}
 // --- Default components (used when customer doesn't provide custom ones) ---
 function DefaultVoiceIndicator({ state, amplitude, theme, isMuted }) {
     // Smoothed amplitude (drives ring opacity factor + core scale).
@@ -532,12 +544,18 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
  </react_native_1.View>);
                 }
                 const rt = rtUnion;
+                const ui = rt.tool?.uiConfig;
+                // Resolve list/card data through uiConfig.dataPath BEFORE anything reads it,
+                // so multi-level paths ("data.campaigns") land on the right level instead of
+                // a hardcoded rt.data.data. The empty-data fallback, list slicing and the
+                // non-list branch all read this single resolved value (mirror MessageBubble).
+                const dataToRender = resolveDataPath(rt.data, ui?.dataPath);
+                const isListTool = ui?.responseType === 'list';
                 // Empty-data fallback (matches text chat list-item behavior)
-                const isListTool = rt.tool?.uiConfig?.responseType === 'list';
                 if (isListTool &&
-                    (rt.data?.data === undefined ||
-                        rt.data?.data === null ||
-                        (Array.isArray(rt.data?.data) && rt.data.data.length === 0))) {
+                    (dataToRender === undefined ||
+                        dataToRender === null ||
+                        (Array.isArray(dataToRender) && dataToRender.length === 0))) {
                     return (<react_native_1.View key={rt.toolCallId} style={{
                             padding: 12,
                             backgroundColor: '#f0f0f0',
@@ -546,7 +564,7 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
  <react_native_1.Text>No results.</react_native_1.Text>
  </react_native_1.View>);
                 }
-                const componentKey = rt.tool?.uiConfig?.itemComponent || rt.toolKey;
+                const componentKey = ui?.itemComponent || rt.toolKey;
                 const Component = registeredComponents?.[componentKey];
                 if (!Component) {
                     if (__DEV__) {
@@ -554,18 +572,25 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
                     }
                     return null;
                 }
-                // List rendering: uiConfig.responseType === 'list' + dataPath === 'data'
-                const listData = rt.tool?.uiConfig?.responseType === 'list' && rt.data?.data
-                    ? rt.data.data
-                    : null;
-                if (Array.isArray(listData)) {
-                    const max = rt.tool?.uiConfig?.maxItems || 10;
+                // List rendering: responseType === 'list' over the dataPath-resolved array.
+                if (isListTool && Array.isArray(dataToRender)) {
+                    const max = ui?.maxItems || 10;
+                    const items = dataToRender.slice(0, max);
+                    // Mirror MessageBubble's text-mode contract (renderToolResult, list
+                    // branch): layout === 'custom' hands the whole array to a single
+                    // component; horizontal/vertical render one component per item. Keep
+                    // these two render paths in lockstep so list output can't diverge again.
+                    if (ui?.layout === 'custom') {
+                        return (<react_native_1.View key={rt.toolCallId}>
+ <Component data={items}/>
+ </react_native_1.View>);
+                    }
                     return (<react_native_1.View key={rt.toolCallId} style={{ gap: 10 }}>
- {listData.slice(0, max).map((item, idx) => (<Component key={`${rt.toolCallId}_${idx}`} data={item}/>))}
+ {items.map((item, idx) => (<Component key={`${rt.toolCallId}_${idx}`} data={item}/>))}
  </react_native_1.View>);
                 }
-                // Non-list: render once with full data
-                return <Component key={rt.toolCallId} data={rt.data}/>;
+                // Non-list: render once with the dataPath-resolved data
+                return <Component key={rt.toolCallId} data={dataToRender}/>;
             })}
  </react_native_1.ScrollView>) : null}
  </react_native_1.View>

package/dist/services/BackendService.js

@@ -740,16 +740,40 @@ class BackendService {
                 headers['Authorization'] = `Bearer ${sessionToken}`;
             }
         }
-        const response = await this.fetchWithRefresh(`${this.baseURL}/tools-v2/${toolId}/files/upload`, {
-            method: 'POST',
-            headers,
-            body: formData,
+        // Expo SDK 56+ installs a WinterCG `fetch` that rejects React Native's
+        // {uri,name,type} FormData file parts ("Unsupported FormDataPart
+        // implementation"). Use XHR (same transport as the chat stream) so the
+        // native multipart path handles the file part directly.
+        const url = `${this.baseURL}/tools-v2/${toolId}/files/upload`;
+        return await new Promise((resolve, reject) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open('POST', url);
+            Object.keys(headers).forEach((k) => xhr.setRequestHeader(k, headers[k]));
+            xhr.timeout = this.timeout;
+            xhr.onload = () => {
+                if (xhr.status >= 200 && xhr.status < 300) {
+                    try {
+                        resolve(JSON.parse(xhr.responseText));
+                    }
+                    catch {
+                        resolve({});
+                    }
+                }
+                else {
+                    let message = `Upload failed: ${xhr.status}`;
+                    try {
+                        message = JSON.parse(xhr.responseText).message || message;
+                    }
+                    catch {
+                        message = `Upload failed: ${xhr.status}`;
+                    }
+                    reject(new Error(message));
+                }
+            };
+            xhr.onerror = () => reject(new Error('Upload failed'));
+            xhr.ontimeout = () => reject(new Error('Upload failed: timeout'));
+            xhr.send(formData);
         });
-        if (!response.ok) {
-            const error = await response.json().catch(() => ({ message: 'Upload failed' }));
-            throw new Error(error.message || `Upload failed: ${response.status}`);
-        }
-        return response.json();
     }
 }
 exports.BackendService = BackendService;

package/docs/qafka-tool-authoring-guide.md

@@ -0,0 +1,328 @@
+# Qafka Tool Authoring Guide
+
+**Audience:** AI coding assistants (and developers) working in an app that has the
+`@qafka/react-native` SDK installed. When the developer says *"I need a tool that does X"*,
+this document is the authoritative reference for **exactly what to configure in the Qafka
+dashboard** and **what to implement in code**.
+
+> **This guide ships inside the SDK package**, so it always matches the SDK version that is
+> actually installed in this project. If a capability is **not described here, it does not
+> exist in this SDK version** — do not tell the developer to enable a field or pass a prop
+> that this guide does not mention. Inventing tool features that aren't real is the single
+> most common way this goes wrong: the assistant says "turn on feature Y", the developer
+> looks for it, it isn't there, and they're stuck. Don't do that.
+
+---
+
+## 1. Mental model: a tool lives in two places
+
+A Qafka tool always has **two halves**, and they are configured in two different places:
+
+| Half | Where it lives | Who configures it |
+|------|----------------|-------------------|
+| **Definition** (name, when to use it, parameters, execution behavior, side effects, result UI) | The **Qafka dashboard** (Tool V2) | The **developer**, by hand, in the web dashboard |
+| **Client behavior** (running on-device actions, rendering custom result UI, supplying transient data, handling file uploads) | The app's **code**, on the `<Qafka />` / `<QafkaProvider />` element | The **developer / you, the assistant** |
+
+**You (the AI assistant) cannot edit the dashboard.** You have no access to it. So your job
+when asked to build a tool is always **hybrid**:
+
+1. Produce **clear, step-by-step dashboard instructions** for the developer ("Create a tool
+   named `…`, set its description to `…`, set execution mode to `…`, add a parameter `…`,
+   turn on `…`").
+2. **Implement only the code side** yourself (handlers, components, props on `<Qafka />`).
+
+Never claim you "created the tool" — you set up the code side and instructed the developer on
+the dashboard side.
+
+> **Auth note:** in production the SDK authenticates via device attestation, not an API key in
+> the bundle. You don't need to handle auth when authoring tools; the only required identity
+> props are `projectId` and `endUserId` (see §6).
+
+---
+
+## 2. The workflow to follow when asked for a tool
+
+When the developer describes a tool, resolve these five questions **before** writing anything.
+If the answer to any of them isn't clear from the request, ask:
+
+1. **What does it do?** — the parameters it needs, where each value comes from, and whether it
+   reads/writes anything (an API call, an email, a navigation).
+2. **Execution mode** — `server`, `custom`, or `custom-with-ai` (§3). This is the most
+   important decision; it determines whether you write client code at all.
+3. **Modality** — should it be available in `text`, `voice`, or both (§4)?
+4. **Result UI** — nothing, a built-in inline display, a custom component, or a card (§6).
+5. **Side effects** — does completing it email someone / call a webhook (§5, *actions*)?
+
+Then produce the two outputs: **dashboard steps** + **code changes**.
+
+---
+
+## 3. Execution mode (the key decision)
+
+A tool's `executionMode` is one of three values. Default is `custom`.
+
+### `server`
+The **backend** calls the tool's configured endpoint, then the AI writes the final answer
+narrating the result. **`onToolSuggested` is NOT fired** — your app does not run anything for
+this tool, so **no client handler code is needed**.
+
+- Use when the action is a server-side API call and you want the AI to answer using the result.
+- The developer configures the **endpoint** (URL, method, body, headers) in the dashboard (§5).
+- Set a **loading message** in the dashboard so the wait feels natural.
+
+### `custom`
+The SDK emits a tool suggestion to your app; **your code runs the action** via the
+`onToolSuggested` prop and reports the result back. There is **no second AI turn** — what your
+handler renders is the final result.
+
+- Use when the action must run **in the app / on-device**: navigate a screen, read local
+  state, call a device API, or hit an endpoint the AI shouldn't see.
+- You **must implement `onToolSuggested`** (§6).
+
+### `custom-with-ai`
+Like `custom` (your code runs the action), **but** after your handler returns data the SDK
+sends it back so the AI produces a follow-up narration.
+
+- Use when the action runs in the app **and** you want the AI to summarize/explain the result.
+- You **must implement `onToolSuggested`** (§6). Set a **loading message** in the dashboard.
+
+> Decision shortcut:
+> *Backend does the work, AI narrates* → **`server`** (no client code).
+> *App does the work, no narration* → **`custom`**.
+> *App does the work, AI narrates the outcome* → **`custom-with-ai`**.
+
+---
+
+## 4. Modality — `availableIn`
+
+In the dashboard, **Available in** controls where the tool can be selected: **Both**,
+**Text only**, or **Voice only** (stored as `availableIn: ["text","voice"]`, `["text"]`, or
+`["voice"]`; default is both). Voice-only requires that voice is enabled for the project — the
+dashboard disables that option otherwise.
+
+---
+
+## 5. Dashboard fields (what you tell the developer to fill in)
+
+These are the fields a developer sets on a Tool V2 in the dashboard. Tell them which to fill
+based on the tool you're building. **Only these exist** — don't reference others.
+
+### Identity & selection
+- **`name`** *(required)* — the tool's identifier.
+- **`description`** *(required)* — **the full behavior protocol the chat AI reads** once the
+  tool is selected. Put the real instructions here: what the tool does, how to use each
+  parameter, what to say. This is the substantive field.
+- **`whenToUse`** *(optional)* — a **short, one-line selector hint** used only to decide *when*
+  to pick this tool. Keep it brief (~200 chars; longer values are truncated for selection). It
+  is **not** a place for behavior detail — that goes in `description`.
+- **`category`**, **`tags`**, **`usageExamples`** — optional metadata to aid organization and
+  selection.
+
+### Parameters
+Each parameter has:
+- **`name`**, **`type`** (`string` | `number` | `boolean` | `object` | `array`),
+  **`required`**, **`description`**.
+- **`source`** — where the value comes from: `ai` (the model fills it), `user_input` (asked
+  from the user), or `context` (pulled from the runtime `context` you pass on `<Qafka />`; use
+  **`contextKey`** to name the context field).
+- For AI-sourced parameters you can also set **`defaultValue`**, **`label`**, **`enumLabels`**
+  (a slug→display-label map so the AI emits a clean slug while the UI/email shows a friendly
+  label), and **`hiddenInEmail`** (omit this parameter from action emails).
+
+### Execution & UX
+- **`executionMode`** — `custom` | `server` | `custom-with-ai` (§3).
+- **`loadingMessage`** — shown while the tool runs; configure for `server` and `custom-with-ai`.
+- **`availableIn`** — modality (§4).
+- **`riskLevel`** (`low` | `medium` | `high`) and **`requiresConfirmation`** — gate sensitive
+  actions behind a confirmation step.
+- **`enabled`** and **`status`** (`DRAFT` / `PUBLISHED`) — a tool must be published & enabled
+  to be used.
+
+### Calling an endpoint (for `server` / `custom` API tools)
+- **Endpoint config:** `url`, `method` (`GET`/`POST`/`PUT`/`DELETE`/`PATCH`), optional
+  `bodyTemplate`, optional `headers`, and `requiredContext` (context keys that must be present).
+- **Token substitution:** in endpoint/webhook/header/description values you can use
+  `{{user.*}}`, `{{system.*}}`, and `{{tool.trackingId}}`; they resolve at runtime.
+
+### Side effects — actions (email / webhook)
+A tool can run actions when it completes (`trigger` is always *on complete*):
+- **Email:** the recipient `to` can be a **single address or multiple targets**, and each
+  target may carry a natural-language **condition** so the AI decides whether to send to it.
+  The action itself can also have an overall **condition**. Options include `subjectPrefix`,
+  `includeConversation`, `attachFile`, and `includeUserContextKeys` (opt-in: which
+  `userContext`/`context` keys to include — nothing about the user is sent unless listed).
+- **Webhook:** `url`, `method` (`POST`/`PUT`), custom `headers` (with token substitution),
+  `include*` toggles (extraction, file, conversation, selected context keys), file delivery
+  format (`url` | `base64` | `formdata`), and an optional `secret` for an HMAC signature.
+
+### Result UI
+- **`uiConfig`** — how structured results render: `responseType` of `list` | `detail` | `card`
+  | `table` | `summary`, plus `dataPath`, `maxItems`, layout/position, and `itemComponent` (the
+  name of a custom component you register in code — see §6). `list`/`detail`/`card`/`table`
+  have built-in default renderers; `summary` has **no** built-in component in this SDK version,
+  so only pick it if you supply your own component via `itemComponent` + the `components` prop.
+- **Card template** — for rich cards, the dashboard has an **AI-assisted card designer** (you
+  describe the card, it generates a template); the tool stores a `cardTemplateId`. The SDK
+  renders the card automatically; card buttons (CTAs) are routed to the `onCard*` props (§6).
+- **`trackingIdFormat`** — optional human-readable tracking id format for the tool run.
+
+### File-upload tools
+- **`fileInput`** — accepted types, max size, allowed sources.
+- **`documentExtractor`** — an extraction prompt + the fields to pull out + a model. After the
+  user uploads a file, the result arrives via `onExtractionResult` in code (§6).
+
+### Response channel (built-ins, automatic)
+- **`responseChannel`** toggle — "send response as a tool action". Turning this on
+  **auto-creates** the built-in `qafka_response_status` / `qafka_add_followup` tools. **Never
+  tell the developer to create those by hand** — they're server-managed and shown locked in the
+  dashboard.
+
+### Versioning (optional, advanced)
+A tool can have multiple **versions**, each with its own `minClientVersion` and `status`
+(`draft` / `staging` / `published`). At chat time the highest version compatible with the app's
+version and the request modality is resolved. Most tools don't need this; mention it only if
+the developer asks about rolling out a change without breaking older app builds.
+
+---
+
+## 6. Code side (what you implement on `<Qafka />`)
+
+The SDK exposes two render components — **`QafkaProvider`** (a floating launcher by default,
+or `inline`/`fullscreen`) and **`Qafka`** (the chat/voice surface itself). The Qafka CLI
+scaffolds one of these into a screen; you add tool-related props to that element.
+
+```tsx
+import { Qafka } from '@qafka/react-native';
+```
+
+### Always-required props
+- **`projectId`** *(required)* — which Qafka project this app talks to.
+- **`endUserId`** *(required, `string | number`)* — stable id for the end user (≤256 chars; not
+  sent to the LLM).
+
+### Running tools in your app — `onToolSuggested`
+Implement this for **`custom`** and **`custom-with-ai`** tools (not needed for `server`):
+
+```tsx
+<Qafka
+  projectId="…"
+  endUserId={user.id}
+  onToolSuggested={async (tools, addResponse) => {
+    for (const tool of tools) {
+      if (tool.name === 'go_to_orders') {
+        navigation.navigate('Orders');
+        // addResponse(data, tool, mode?)  mode: 'ui' | 'data' | 'both' (default 'both')
+        addResponse({ navigated: true }, tool, 'data');
+      }
+    }
+  }}
+/>
+```
+
+`addResponse(data, tool, mode?)` reports the result back:
+- `'ui'` — update the rendered UI only (keeps the flow open),
+- `'data'` — commit the result data without touching the UI,
+- `'both'` *(default)* — both.
+
+For `custom-with-ai` tools, the data you pass is forwarded so the AI can narrate a follow-up.
+
+### Custom result components — the `components` prop
+When a tool returns structured data with a `uiConfig`, the SDK renders it with built-in
+defaults (`DefaultCard`, `DefaultList`, `DefaultDetail`, `DefaultTable`). Override them by
+registering your own by name:
+
+```tsx
+<Qafka
+  components={{ OrderCard: MyOrderCard }}  // matches uiConfig.itemComponent = "OrderCard"
+/>
+```
+
+Each component receives `{ data, tool?, theme?, onAction? }`.
+
+### Transient / lazy data — `onToolDataRequested`
+When a tool needs data the AI shouldn't see or that you don't want persisted, supply it
+on-demand. The SDK calls this just before the tool runs and uses the returned bag for that run
+only (it is not written to the conversation or sent to the LLM):
+
+```tsx
+<Qafka
+  onToolDataRequested={(tool) => {            // tool: { key, name }
+    if (tool.key === 'current_cart') return { items: cart.items };
+    return {};
+  }}
+/>
+```
+
+### File-upload tools — `onFileUploadRequest` + `onExtractionResult`
+There is **no built-in file picker** in this SDK version. For a tool with `fileInput`, you wire
+your own picker:
+
+```tsx
+<Qafka
+  onFileUploadRequest={({ toolId, fileInput, submit, cancel }) => {
+    // open your picker honoring fileInput.accept / maxSize / sources,
+    // then call submit({ uri, name, type }) or cancel()
+  }}
+  onExtractionResult={(result) => { /* { fileId, toolId, data, status, incompleteFields? } */ }}
+/>
+```
+
+### Card CTAs
+If a tool uses a card template, the card renders automatically. Its buttons are delivered to
+these props (wire the ones your cards use): `onCardDeepLink`, `onCardSuggestMessage`,
+`onCardExternalNavigation`, `onCardShare`, `onCardCopy`, `onCardToolTrigger`, `onCardCTAClick`.
+
+### Inline key/value display — `qafka_display` (built-in)
+`qafka_display` is a **built-in tool**: there is nothing to create in the dashboard and nothing
+to handle in code. It shows a small set of key/value chips (or routes text to the transcript).
+You may optionally restyle the chips via `voiceComponents.dataChipList` / `voiceComponents.dataChip`.
+
+### Useful context props
+- **`context`** + **`contextDescription`** — a runtime data bag passed to the AI, with a
+  description of what its keys mean. (Tool parameters with `source: 'context'` read from here.)
+- **`endUserData`** — non-LLM metadata about the user (≤8KB).
+- **`subProjectId`** — multi-tenant routing.
+- **`locale`** — BCP-47 locale.
+
+---
+
+## 7. Recipes (common asks → config + code)
+
+**A. "Call our backend and let the AI answer."**
+Dashboard: execution mode `server`, fill endpoint config, set a loading message, `availableIn`
+both. Code: nothing — `server` tools don't fire `onToolSuggested`.
+
+**B. "Do something in the app (navigate / read local state) and show the result."**
+Dashboard: execution mode `custom` (or `custom-with-ai` if you want the AI to narrate). Add
+parameters. Optionally set `uiConfig`/card for the result. Code: implement `onToolSuggested`;
+register a component via `components` if you used `uiConfig.itemComponent`.
+
+**C. "Collect some info and email it to the team."**
+Dashboard: add an **email action**; use multiple targets with conditions if routing depends on
+the input; opt into the context keys you want via `includeUserContextKeys`. Code: usually none
+(the action runs on completion); add a handler only if the tool also does on-device work.
+
+**D. "User uploads a document; extract fields from it."**
+Dashboard: configure `fileInput` + `documentExtractor` on the tool. Code: implement
+`onFileUploadRequest` (your picker → `submit(...)`) and read `onExtractionResult`.
+
+**E. "Show a couple of key values inline."**
+Use the built-in `qafka_display` — nothing in the dashboard, nothing in code.
+
+---
+
+## 8. Guardrails (read before you answer)
+
+- **Don't invent capabilities.** If it isn't in this guide, it isn't in this SDK version.
+  Don't tell the developer to toggle a field or pass a prop that doesn't exist here.
+- **You can't touch the dashboard.** Always give explicit dashboard steps for the developer and
+  implement only the code side yourself.
+- **`description` carries behavior, `whenToUse` is just a short selector hint.** Don't stuff
+  protocol detail into `whenToUse`.
+- **Built-in tools aren't created by hand** — `qafka_display`, and the `responseChannel`
+  built-ins (`qafka_response_status` / `qafka_add_followup`), appear automatically.
+- **`server` mode means no client handler.** Only `custom` / `custom-with-ai` use
+  `onToolSuggested`.
+- **This guide is version-matched** to the `@qafka/react-native` package it ships inside (see
+  its `package.json` `version`). If the developer is on a different version, the dashboard or
+  props may differ — defer to the dashboard's own field set when in doubt.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qafka/react-native",
-  "version": "2.3.7",
+  "version": "2.3.8",
   "description": "Drop-in AI assistant for React Native: chat, voice, and tool execution with screen-aware navigation.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,6 +15,7 @@
     "react-native.config.js",
     "qafka.config.js",
     "qafka.config.d.ts",
+    "docs",
     "README.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",