expo-invoke 1.0.0

package/README.md

@@ -0,0 +1,942 @@
+# expo-invoke
+
+The complete native-surface-to-JS bridge for Expo. Define one intent in `app.json` and it automatically works from **every surface** — Siri, Google Assistant, home screen widgets, Dynamic Island, app icon long-press menus, notification action buttons, NFC tags, QR codes, deep links, and more — all through a single `useInvoke()` hook.
+
+**No manual Swift or Kotlin required.** The config plugin generates all native code from your `app.json`.
+
+---
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [useInvoke() — Full API](#useinvoke--full-api)
+- [Hooks](#hooks)
+  - [useInvokeInit](#useinvokeinit)
+  - [useInvoke](#useinvoke)
+  - [useDonation — Siri Suggestions](#usedonation--siri-suggestions)
+  - [useShortcuts — Launcher Long-Press Menu](#useshortcuts--launcher-long-press-menu)
+  - [useWidgetData — Push State to Widgets](#usewidgetdata--push-state-to-widgets)
+  - [useSpotlight — iOS Spotlight Search](#usespotlight--ios-spotlight-search)
+  - [useFocusFilter — iOS Focus Mode](#usefocusfilter--ios-focus-mode)
+  - [useAddToSiri](#useaddtosiri)
+  - [useQuickTile — Android Quick Settings](#usequicktile--android-quick-settings)
+  - [useHandoff — Apple Handoff](#usehandoff--apple-handoff)
+  - [useLiveActivityIntent — Dynamic Island](#useliveactivityintent--dynamic-island)
+  - [useInvokeHistory](#useinvokehistory)
+  - [useInvokeAnalytics](#useinvokeanalytics)
+- [Components](#components)
+- [Parameter Types](#parameter-types)
+- [app.json Config Reference](#appjson-config-reference)
+  - [intents](#intents)
+  - [widgets](#widgets)
+  - [notificationActions](#notificationactions)
+  - [liveActivityIntents](#liveactivityintents)
+  - [Plugin options](#plugin-options)
+- [Intent TTL](#intent-ttl)
+- [CLI](#cli)
+- [TypeScript Codegen](#typescript-codegen)
+- [Testing](#testing)
+- [Supported Surfaces](#supported-surfaces)
+
+---
+
+## Requirements
+
+| Platform | Minimum |
+|---|---|
+| iOS | 16.0 (App Intents API) |
+| Android | API 24 / Android 7.0 |
+| Expo SDK | 50+ |
+| expo-modules-core | 1.12+ |
+
+---
+
+## Installation
+
+```bash
+npx expo install expo-invoke
+```
+
+Then rebuild your native app:
+
+```bash
+npx expo prebuild
+npx expo run:ios
+npx expo run:android
+```
+
+---
+
+## Quick Start
+
+### 1. Configure your intents in `app.json`
+
+```json
+{
+  "plugins": [
+    ["expo-invoke", {
+      "intents": [
+        {
+          "id": "create_errand",
+          "title": "Create an Errand",
+          "phrases": ["Create an errand in ${applicationName}"],
+          "shortTitle": "Create Errand",
+          "icon": "shippingbox"
+        }
+      ]
+    }]
+  ]
+}
+```
+
+> `${applicationName}` is required in every Siri phrase so the system knows which app to launch.
+
+### 2. Initialize in your root layout
+
+```tsx
+// app/_layout.tsx
+import { useInvokeInit } from 'expo-invoke';
+
+export default function RootLayout() {
+  useInvokeInit(); // handles cold start AND warm start — call once, here only
+  return <Stack />;
+}
+```
+
+### 3. React to intents anywhere in your app
+
+```tsx
+import { useEffect } from 'react';
+import { useInvoke } from 'expo-invoke';
+
+export default function HomeScreen() {
+  const { intent, clear } = useInvoke({ intentId: 'create_errand' });
+
+  useEffect(() => {
+    if (!intent) return;
+    router.push('/create-errand');
+    clear();
+  }, [intent]);
+
+  return <View />;
+}
+```
+
+---
+
+## useInvoke() — Full API
+
+```tsx
+const { intent, parameters, source, clear } = useInvoke({
+  // Filter to a specific intent (optional)
+  intentId: 'create_errand',
+
+  // Filter to specific surfaces (optional — defaults to all)
+  source: ['siri', 'widget', 'nfc'],
+
+  // Inline handler (optional — alternative to watching the returned value)
+  onFire: (intent) => {
+    console.log(intent.intentId, intent.source, intent.parameters);
+  },
+});
+
+// intent    — ResolvedIntent | null
+// parameters — Record<string, ParameterValue>  (shorthand for intent?.parameters)
+// source    — InvokeSource | undefined
+// clear()   — clears the pending intent so it doesn't re-fire on re-render
+```
+
+**`ResolvedIntent` shape:**
+
+```ts
+{
+  intentId: string;           // e.g. "create_errand"
+  source: InvokeSource;       // e.g. "siri"
+  timestamp: number;          // ms since epoch
+  parameters: Record<string, ParameterValue>;
+  rawUrl?: string;            // present when source is 'deep_link' | 'nfc' | 'qr'
+}
+```
+
+---
+
+## Hooks
+
+### useInvokeInit
+
+Call **once** in your root layout. Handles two start paths:
+
+- **Cold start** — app was not running; Siri/widget wrote the intent to native storage before JS loaded. `useInvokeInit` reads it on mount.
+- **Warm start** — app was backgrounded; intent fires as a native event. `useInvokeInit` subscribes and routes it to `useInvoke`.
+
+```tsx
+// app/_layout.tsx
+import { useInvokeInit } from 'expo-invoke';
+
+export default function RootLayout() {
+  useInvokeInit();
+  return <Stack />;
+}
+```
+
+---
+
+### useInvoke
+
+The universal receiver. Works the same regardless of which surface fired the intent.
+
+```tsx
+// No filter — receive any intent from any surface
+const { intent, clear } = useInvoke();
+
+// Filter by intentId
+const { intent } = useInvoke({ intentId: 'track_errand' });
+
+// Filter by source
+const { intent } = useInvoke({ source: ['widget', 'notification'] });
+
+// Inline handler
+useInvoke({
+  intentId: 'create_errand',
+  onFire: ({ parameters }) => {
+    createErrand({ pickup: parameters.pickup });
+  },
+});
+```
+
+---
+
+### useDonation — Siri Suggestions
+
+Donating an action tells Siri the user performed it. After several donations, Siri surfaces the phrase as a suggestion on the lock screen, in Spotlight, and in the Siri watch face.
+
+```tsx
+import { useDonation } from 'expo-invoke';
+
+function CreateErrandScreen() {
+  const { donate, remove, removeAll } = useDonation();
+
+  const handleCreate = async (errand) => {
+    await createErrand(errand);
+
+    // Donate after a successful action — Siri learns the pattern
+    donate({
+      intentId: 'create_errand',
+      title: `Create errand to ${errand.destination}`,
+      parameters: { pickup: errand.pickup },
+    });
+  };
+
+  // Remove a specific donation (e.g. when errand is cancelled)
+  const handleCancel = () => remove('create_errand');
+
+  // Remove all donations for a fresh start
+  const handleReset = () => removeAll();
+}
+```
+
+> Donations accumulate over time. The more a user performs an action the higher Siri ranks it.
+
+---
+
+### useShortcuts — Launcher Long-Press Menu
+
+Dynamic shortcuts appear when the user long-presses your app icon. They update in real time based on what the user does most.
+
+```tsx
+import { useShortcuts } from 'expo-invoke';
+
+function App() {
+  const { setShortcuts, clear } = useShortcuts();
+
+  useEffect(() => {
+    // Called after login — show personalized shortcuts
+    setShortcuts([
+      {
+        id: 'recent_errand',
+        title: 'Resume Last Errand',
+        subtitle: 'Pick up from Accra Mall',
+        icon: 'arrow.clockwise',
+        intentId: 'track_errand',
+        parameters: { errandId: '123' },
+      },
+      {
+        id: 'new_errand',
+        title: 'Create Errand',
+        icon: 'plus',
+        intentId: 'create_errand',
+      },
+    ]);
+  }, [userId]);
+}
+```
+
+Static shortcuts (always visible, defined at install time) are configured via the `shortTitle` field in `app.json` and generated automatically by the config plugin.
+
+---
+
+### useWidgetData — Push State to Widgets
+
+Push live app state to home screen widgets without the user opening the app. The widget reads from the same shared storage.
+
+```tsx
+import { useWidgetData } from 'expo-invoke';
+
+function TrackingScreen({ errand }) {
+  const { set } = useWidgetData('active_errand');
+
+  useEffect(() => {
+    // Widget reads this to display current status
+    set({
+      title: errand.title,
+      status: errand.status,
+      eta: errand.estimatedArrival,
+    });
+  }, [errand]);
+}
+```
+
+On iOS, data is stored in an App Group shared `UserDefaults` container. Configure the App Group in `app.json`:
+
+```json
+["expo-invoke", { "appGroupId": "group.com.myapp.invoke" }]
+```
+
+---
+
+### useSpotlight — iOS Spotlight Search
+
+Index items so users can find them via iOS Spotlight (swipe down on home screen). Tapping a result fires the associated intent.
+
+```tsx
+import { useSpotlight } from 'expo-invoke';
+
+function ErrandsListScreen({ errands }) {
+  const { index, deindex } = useSpotlight();
+
+  useEffect(() => {
+    index(
+      errands.map((e) => ({
+        id: `errand-${e.id}`,
+        title: e.title,
+        description: e.description,
+        keywords: ['errand', 'delivery', e.destination],
+        intentId: 'track_errand',
+        intentParameters: { errandId: e.id },
+      }))
+    );
+
+    return () => deindex(errands.map((e) => `errand-${e.id}`));
+  }, [errands]);
+}
+```
+
+---
+
+### useFocusFilter — iOS Focus Mode
+
+Read the active iOS Focus mode (Work, Personal, Sleep, etc.) and adapt your UI or behaviour accordingly.
+
+```tsx
+import { useFocusFilter } from 'expo-invoke';
+
+function NotificationSettings() {
+  const focus = useFocusFilter();
+  // focus: 'work' | 'personal' | 'sleep' | 'do_not_disturb' | 'driving' | null
+
+  return (
+    <View>
+      {focus === 'work' && <Text>Work mode — showing only work shortcuts</Text>}
+      {focus === 'sleep' && <Text>Sleep mode — notifications silenced</Text>}
+      {focus === null && <Text>No active focus</Text>}
+    </View>
+  );
+}
+```
+
+Re-reads automatically every time the app comes to the foreground.
+
+---
+
+### useAddToSiri
+
+Programmatically open the native "Add to Siri" sheet so users can record a custom voice phrase for any intent.
+
+```tsx
+import { useAddToSiri } from 'expo-invoke';
+// or use the pre-built <AddToSiriButton /> component
+
+function IntentSettings() {
+  const addToSiri = useAddToSiri('create_errand');
+
+  return (
+    <TouchableOpacity onPress={addToSiri}>
+      <Text>Add "Create Errand" to Siri</Text>
+    </TouchableOpacity>
+  );
+}
+```
+
+---
+
+### useQuickTile — Android Quick Settings
+
+Show a tile in the Android Quick Settings panel (swipe down twice). The tile can be tapped even when the app is closed.
+
+```tsx
+import { useQuickTile } from 'expo-invoke';
+
+function TrackingScreen({ isTracking }) {
+  const { update } = useQuickTile();
+
+  useEffect(() => {
+    update(
+      isTracking ? 'active' : 'inactive',
+      isTracking ? 'Tracking errand' : 'Start tracking'
+    );
+  }, [isTracking]);
+}
+```
+
+States: `'active'` (tinted) · `'inactive'` (dimmed) · `'unavailable'` (greyed out, not tappable)
+
+The tile maps to the `quick_tile` intent source — configure which intent the tile fires in `app.json` with `"supportsQuickTile": true` on the intent.
+
+---
+
+### useHandoff — Apple Handoff
+
+Let users continue an in-progress action on another Apple device (iPhone → iPad → Mac).
+
+```tsx
+import { useHandoff } from 'expo-invoke';
+
+function CreateErrandScreen({ draft }) {
+  const { advertise, stop, received } = useHandoff();
+
+  useEffect(() => {
+    // Broadcast: "I'm creating an errand, any device can continue"
+    advertise('create_errand', { draft: JSON.stringify(draft) });
+    return () => stop();
+  }, [draft]);
+
+  useEffect(() => {
+    if (!received) return;
+    // Another device handed off to this one — restore the draft
+    const restoredDraft = JSON.parse(received.parameters.draft as string);
+    setDraft(restoredDraft);
+  }, [received]);
+}
+```
+
+---
+
+### useLiveActivityIntent — Dynamic Island
+
+Link a Live Activity to an intent so tapping the Dynamic Island compact view or Lock Screen banner fires that intent.
+
+```tsx
+import { useLiveActivityIntent } from 'expo-invoke';
+
+function ErrandTrackingScreen({ activityId }) {
+  const { set } = useLiveActivityIntent(activityId);
+
+  useEffect(() => {
+    // Tapping the Dynamic Island fires track_errand
+    set('track_errand');
+  }, [activityId]);
+}
+```
+
+Received via `useInvoke({ source: ['live_activity'] })`.
+
+Configure at the plugin level for static linking:
+
+```json
+["expo-invoke", {
+  "liveActivityIntents": {
+    "errandInProgress": "track_errand"
+  }
+}]
+```
+
+---
+
+### useInvokeHistory
+
+Access the last N intents that fired (persisted in memory for the session).
+
+```tsx
+import { useInvokeHistory } from 'expo-invoke';
+
+function RecentActionsScreen() {
+  const history = useInvokeHistory(10); // last 10
+
+  return (
+    <FlatList
+      data={history}
+      renderItem={({ item }) => (
+        <Text>{item.intentId} via {item.source}</Text>
+      )}
+    />
+  );
+}
+```
+
+Returns `ResolvedIntent[]` in reverse-chronological order (most recent first).
+
+---
+
+### useInvokeAnalytics
+
+Track how often intents fire and from which surfaces — useful for optimising which shortcuts to promote.
+
+```tsx
+import { useInvokeAnalytics } from 'expo-invoke';
+
+function AnalyticsDashboard() {
+  const { fired, donated } = useInvokeAnalytics();
+  // fired:   { create_errand: 42, track_errand: 17 }
+  // donated: { create_errand: 8 }
+
+  return (
+    <View>
+      {Object.entries(fired).map(([id, count]) => (
+        <Text key={id}>{id}: {count} fires</Text>
+      ))}
+    </View>
+  );
+}
+```
+
+Tap into the global analytics bus to forward events to Segment, Amplitude, etc.:
+
+```tsx
+import { onIntentFired } from 'expo-invoke';
+
+// In your analytics bootstrap (once, at app start)
+onIntentFired((intent) => {
+  analytics.track('Intent Fired', {
+    intentId: intent.intentId,
+    source: intent.source,
+  });
+});
+```
+
+---
+
+## Components
+
+### `<AddToSiriButton />`
+
+Renders the native "Add to Siri" button on iOS. No-op on Android.
+
+```tsx
+import { AddToSiriButton } from 'expo-invoke';
+
+<AddToSiriButton
+  intentId="create_errand"
+  onPress={() => console.log('Sheet opened')}
+  style={{ alignSelf: 'center', marginTop: 16 }}
+/>
+```
+
+### `<ShortcutChip />`
+
+A tappable chip representing a dynamic shortcut. Pressing it promotes the shortcut to the top of the launcher long-press list.
+
+```tsx
+import { ShortcutChip } from 'expo-invoke';
+
+<ShortcutChip
+  shortcutId="quick_errand"
+  label="Quick Errand"
+  icon="📦"
+  onPress={() => router.push('/create-errand')}
+/>
+```
+
+### `<InvokeDebugger />`
+
+A dev-only floating overlay that shows the current pending intent, its source, and the last 5 intents from history. Renders `null` in production automatically.
+
+```tsx
+// app/_layout.tsx — add it once, forget it
+import { InvokeDebugger } from 'expo-invoke';
+
+export default function RootLayout() {
+  useInvokeInit();
+  return (
+    <>
+      <Stack />
+      <InvokeDebugger />
+    </>
+  );
+}
+```
+
+---
+
+## Parameter Types
+
+The 8 supported parameter types and the JavaScript value shape you receive in `intent.parameters`:
+
+| Type | Config | JS value |
+|---|---|---|
+| `text` | `{ "type": "text" }` | `string` |
+| `number` | `{ "type": "number", "min": 1, "max": 100 }` | `number` |
+| `boolean` | `{ "type": "boolean" }` | `boolean` |
+| `date` | `{ "type": "date" }` | `number` (ms timestamp) |
+| `location` | `{ "type": "location" }` | `{ latitude: number, longitude: number, name?: string }` |
+| `person` | `{ "type": "person" }` | `{ displayName?: string, phoneNumber?: string, emailAddress?: string, contactIdentifier?: string }` |
+| `enum` | `{ "type": "enum", "options": [{ "id": "...", "title": "..." }] }` | `string` (the selected option `id`) |
+| `array` | `{ "type": "array", "itemType": "text" \| "number" \| "location" }` | `string[]`, `number[]`, or location object `[]` |
+
+**Example: reading typed parameters**
+
+```tsx
+useInvoke({
+  intentId: 'create_errand',
+  onFire: ({ parameters }) => {
+    const pickup = parameters.pickup as { latitude: number; longitude: number; name?: string };
+    const type = parameters.type as string; // enum id e.g. "delivery"
+    const quantity = parameters.quantity as number;
+  },
+});
+```
+
+> Use `npx expo-invoke generate` to generate a typed `invoke-types.d.ts` so TypeScript knows the exact shape of every intent's parameters.
+
+---
+
+## app.json Config Reference
+
+### intents
+
+Each intent becomes a Siri phrase, an Android App Action, an app icon shortcut, and a widget button — all from one config entry.
+
+```json
+{
+  "id": "create_errand",
+  "title": "Create an Errand",
+  "description": "Quickly create a new delivery errand",
+  "phrases": [
+    "Create an errand in ${applicationName}",
+    "New delivery in ${applicationName}"
+  ],
+  "shortTitle": "Create Errand",
+  "icon": "shippingbox",
+  "requiresConfirmation": false,
+  "spokenResponse": "Opening ${applicationName} to create your errand",
+  "openAppWhenRun": true,
+  "supportsCarPlay": false,
+  "supportsWatch": false,
+  "supportsControlCenter": false,
+  "supportsQuickTile": false,
+  "deepLinkPatterns": ["myapp://errands/create"],
+  "ttl": 30,
+  "parameters": [
+    { "name": "pickup", "type": "location", "title": "Pickup location", "optional": true },
+    { "name": "type", "type": "enum", "title": "Errand type",
+      "options": [{ "id": "delivery", "title": "Delivery" }, { "id": "pickup", "title": "Pickup" }] },
+    { "name": "notes", "type": "text", "title": "Notes", "optional": true }
+  ]
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Stable unique identifier. Never rename after shipping. |
+| `title` | `string` | Shown in Siri and system UI. |
+| `description` | `string?` | Subtitle in Shortcuts.app. |
+| `phrases` | `string[]` | Siri voice phrases. Must include `${applicationName}`. |
+| `shortTitle` | `string?` | Short label for app icon menus and widget buttons (≤ 10 chars for Android). |
+| `icon` | `string?` | SF Symbol name (iOS) or Material icon name (Android). |
+| `requiresConfirmation` | `boolean?` | Show a Siri confirmation dialog before running (default: `false`). |
+| `spokenResponse` | `string?` | Text Siri reads aloud after the intent runs. Supports `${paramName}` substitution. |
+| `openAppWhenRun` | `boolean?` | Whether to bring the app to foreground (default: `true`). |
+| `supportsCarPlay` | `boolean?` | Enable in CarPlay. Phrase works automatically in CarPlay when `true`. |
+| `supportsWatch` | `boolean?` | Enable companion button on watchOS / Wear OS. |
+| `supportsControlCenter` | `boolean?` | iOS 18+ Control Center control. |
+| `supportsQuickTile` | `boolean?` | Android Quick Settings tile. |
+| `deepLinkPatterns` | `string[]?` | URL patterns that fire this intent (e.g. `"myapp://errands/create"`). |
+| `ttl` | `number?` | Seconds before a stored intent expires (default: `30`). |
+| `parameters` | `IntentParameter[]?` | Typed parameters Siri / Google can collect. |
+
+### widgets
+
+Define home screen widgets. The config plugin generates the native WidgetKit extension (iOS) and AppWidgetProvider (Android) automatically.
+
+```json
+"widgets": [
+  {
+    "id": "quick_errand",
+    "title": "Quick Errand",
+    "description": "One-tap errand creation",
+    "sizes": ["small", "medium"],
+    "backgroundColor": "#1C1C1E",
+    "actions": [
+      { "label": "Create", "intentId": "create_errand", "icon": "plus" },
+      { "label": "Track", "intentId": "track_errand", "icon": "location" }
+    ]
+  }
+]
+```
+
+Widget button taps fire the intent with `source: 'widget'`. Use `useWidgetData()` to push live data into the widget from the app.
+
+**Supported sizes:** `small` · `medium` · `large` · `extraLarge` · `accessory` (iOS lock screen)
+
+### notificationActions
+
+Wire notification action buttons to intents. The config plugin registers the `UNNotificationCategory` (iOS) and `NotificationCompat.Action` (Android) automatically.
+
+```json
+"notificationActions": [
+  {
+    "categoryId": "ERRAND_UPDATE",
+    "tapIntent": "track_errand",
+    "actions": [
+      { "id": "track", "title": "Track", "intentId": "track_errand" },
+      { "id": "cancel", "title": "Cancel", "intentId": "cancel_errand", "destructive": true },
+      { "id": "confirm", "title": "Confirm", "intentId": "confirm_errand", "foreground": true }
+    ]
+  }
+]
+```
+
+- `tapIntent` — intent fired when the user taps the notification *body* (not a button). Received as `source: 'notification_tap'`.
+- `destructive: true` — renders the button in red on iOS.
+- `foreground: true` — brings the app to foreground when tapped.
+
+When sending a notification from your server, include the category ID:
+
+```json
+{ "aps": { "category": "ERRAND_UPDATE", "alert": "Your errand has an update" } }
+```
+
+### liveActivityIntents
+
+Map Live Activity names to intents. Tapping the Dynamic Island or Lock Screen banner fires the mapped intent.
+
+```json
+"liveActivityIntents": {
+  "errandInProgress": "track_errand",
+  "paymentPending": "confirm_payment"
+}
+```
+
+Received as `source: 'live_activity'`. Override dynamically with `useLiveActivityIntent()`.
+
+### Plugin options
+
+```json
+["expo-invoke", {
+  "intents": [...],
+  "widgets": [...],
+  "notificationActions": [...],
+  "liveActivityIntents": { ... },
+  "voiceUsageDescription": "Use voice commands to create and track errands.",
+  "appGroupId": "group.com.myapp.invoke"
+}]
+```
+
+| Option | Description |
+|---|---|
+| `voiceUsageDescription` | iOS `NSSiriUsageDescription` / `NSVoiceUsageDescription` in Info.plist. |
+| `appGroupId` | iOS App Group for widget data sharing via `useWidgetData()`. |
+
+---
+
+## Intent TTL
+
+When an intent fires while the app is closed, it is written to native storage before JS loads. `useInvokeInit()` reads it on mount.
+
+The default TTL is **30 seconds**. If the app takes longer than 30s to fully load and call `useInvokeInit()`, the intent is discarded. You can override per intent:
+
+```json
+{ "id": "create_errand", "ttl": 60, ... }
+```
+
+This prevents a stale intent from firing long after the user has moved on. The TTL countdown starts from when the intent was stored natively (before the app launched), not from when JS mounts.
+
+---
+
+## CLI
+
+```bash
+# Validate your app.json expo-invoke config
+npx expo-invoke validate
+
+# Generate TypeScript types from your config
+npx expo-invoke generate
+
+# Run the expo-invoke test suite
+npx expo-invoke test
+```
+
+### validate
+
+Catches:
+- Missing `${applicationName}` in phrases
+- Phrases longer than 140 characters
+- Conflicting phrases across intents
+- Duplicate intent or parameter IDs
+- Invalid identifier format
+- iOS shortcut count > 10 (warning)
+- Android shortcut count > 5 (warning)
+
+```bash
+$ npx expo-invoke validate
+Validating expo-invoke config in /my-app ...
+
+⚠️  1 warning(s):
+  • [intents] 11 intents with shortTitle — Android allows max 5 launcher shortcuts.
+
+✅  Configuration is valid.
+```
+
+### generate
+
+Outputs `invoke-types.d.ts` in your project root with per-intent parameter types (see [TypeScript Codegen](#typescript-codegen)).
+
+---
+
+## TypeScript Codegen
+
+Run `npx expo-invoke generate` after editing your `app.json`. It produces `invoke-types.d.ts`:
+
+```ts
+// invoke-types.d.ts (auto-generated)
+import type { ResolvedIntent } from "expo-invoke";
+
+export type InvokeIntentId = "create_errand" | "track_errand" | "cancel_errand";
+
+export interface CreateErrandIntent extends ResolvedIntent {
+  intentId: "create_errand";
+  parameters: {
+    pickup?: { latitude: number; longitude: number; name?: string };
+    type: "delivery" | "pickup";
+    notes?: string;
+  };
+}
+```
+
+Use it for type-safe intent handling:
+
+```tsx
+import type { CreateErrandIntent } from '../invoke-types';
+
+useInvoke({
+  intentId: 'create_errand',
+  onFire: (intent) => {
+    const typed = intent as CreateErrandIntent;
+    console.log(typed.parameters.type); // "delivery" | "pickup"
+  },
+});
+```
+
+---
+
+## Testing
+
+```tsx
+import {
+  mockInvoke,
+  simulateColdStart,
+  simulateWarmStart,
+  createMockIntent,
+} from 'expo-invoke';
+```
+
+### mockInvoke
+
+Feeds an intent directly into the action store. `useInvoke()` will fire on the next render.
+
+```ts
+mockInvoke({ intentId: 'create_errand', source: 'siri' });
+mockInvoke({ intentId: 'track_errand', source: 'widget', parameters: { errandId: '42' } });
+```
+
+### simulateColdStart
+
+Simulates the app being closed when the intent fired. The intent is stored with a slightly past timestamp.
+
+```ts
+simulateColdStart({ intentId: 'create_errand', ageMs: 500 });
+// ageMs: how old the intent is (default 100ms) — keep under your TTL
+```
+
+### simulateWarmStart
+
+Simulates the app being backgrounded when the intent fired (same as `mockInvoke` but named for clarity).
+
+```ts
+simulateWarmStart({ intentId: 'create_errand', source: 'notification' });
+```
+
+### createMockIntent
+
+Creates a `ResolvedIntent` object for use in assertions without storing it.
+
+```ts
+const intent = createMockIntent({ intentId: 'test', source: 'nfc', parameters: { tag: 'abc' } });
+expect(intent.source).toBe('nfc');
+```
+
+### Jest example
+
+```ts
+import { mockInvoke } from 'expo-invoke';
+import { renderHook, act } from '@testing-library/react-hooks';
+import { useInvoke } from 'expo-invoke';
+
+test('fires handler when matching intent arrives', () => {
+  const handler = jest.fn();
+  renderHook(() => useInvoke({ intentId: 'create_errand', onFire: handler }));
+
+  act(() => {
+    mockInvoke({ intentId: 'create_errand', source: 'siri' });
+  });
+
+  expect(handler).toHaveBeenCalledTimes(1);
+  expect(handler.mock.calls[0][0].source).toBe('siri');
+});
+```
+
+---
+
+## Supported Surfaces
+
+| Surface | iOS | Android | Source value |
+|---|---|---|---|
+| Voice (Siri) | ✓ App Intents (iOS 16+) | — | `siri` |
+| Voice (Google Assistant) | — | ✓ App Actions BII | `google` |
+| App icon long-press | ✓ App Shortcuts | ✓ Static/dynamic shortcuts | `shortcut` |
+| Home screen widget | ✓ WidgetKit | ✓ AppWidgetProvider | `widget` |
+| Dynamic Island tap | ✓ iOS 16.1+ | — | `live_activity` |
+| Lock screen Live Activity | ✓ iOS 16.1+ | — | `live_activity` |
+| Notification action button | ✓ UNNotificationAction | ✓ NotificationCompat.Action | `notification` |
+| Notification body tap | ✓ | ✓ | `notification_tap` |
+| iOS Spotlight | ✓ NSUserActivity | — | `spotlight` |
+| iOS Control Center | ✓ iOS 18+ ControlWidget | — | `control_center` |
+| Android Quick Settings | — | ✓ TileService | `quick_tile` |
+| NFC tag tap | ✓ | ✓ | `nfc` |
+| QR code scan | ✓ | ✓ | `qr` |
+| Universal Link / App Link | ✓ | ✓ | `deep_link` |
+| Custom URL scheme | ✓ | ✓ | `deep_link` |
+| Share sheet | ✓ UIActivityViewController | ✓ Intent.ACTION_SEND | `share` |
+| Apple Handoff | ✓ NSUserActivity | — | `handoff` |
+| CarPlay | ✓ (phrases work automatically) | — | `carplay` |
+| Android Auto | — | ✓ (via App Actions) | `android_auto` |
+| Shortcuts automation | ✓ (automatic via App Intents) | — | `automation` |
+| Siri Suggestions | ✓ via `useDonation()` | — | `siri` |
+| watchOS tap/voice | ✓ WCSession | ✓ Wear Data Layer | `watch` |
+
+---
+
+## License
+
+MIT — SmartHive Labs