expo-invoke 1.0.0

package/MIGRATION.md

@@ -0,0 +1,125 @@
+# Migration Guide
+
+## From `expo-errands-assistant`
+
+The `expo-errands-assistant` local module was hardcoded for a single Siri action with no parameters, no Android support, and no reusability. `expo-invoke` replaces it entirely.
+
+### Step 1 — Replace the import
+
+```diff
+- import { useErrandsAssistant } from '../modules/expo-errands-assistant';
++ import { useInvokeInit, useInvoke } from 'expo-invoke';
+```
+
+### Step 2 — Replace the root-level init
+
+```diff
+// app/_layout.tsx
+- useErrandsAssistant(); // old
++ useInvokeInit();       // new — same cold/warm start behaviour
+```
+
+### Step 3 — Replace the intent listener
+
+```diff
+// Before
+- const { action } = useErrandsAssistant();
+- if (action === 'CreateErrand') { router.push('/create'); }
+
+// After
++ const { intent } = useInvoke({ intentId: 'create_errand' });
++ useEffect(() => { if (intent) router.push('/create'); }, [intent]);
+```
+
+### Step 4 — Move the native intent to app.json
+
+Delete the hardcoded Swift intent file. The config plugin generates it:
+
+```json
+// app.json
+{
+  "plugins": [["expo-invoke", {
+    "intents": [{
+      "id": "create_errand",
+      "title": "Create an Errand",
+      "phrases": ["Create an errand in ${applicationName}"]
+    }]
+  }]]
+}
+```
+
+---
+
+## From `react-native-siri-shortcut`
+
+### Install expo-invoke
+
+```bash
+npx expo install expo-invoke
+npx expo uninstall react-native-siri-shortcut
+```
+
+### Replace donation calls
+
+```diff
+- import SiriShortcuts from 'react-native-siri-shortcut';
+- SiriShortcuts.donateShortcut({ identifier: 'create', title: 'Create', userInfo: {} });
+
++ import { useDonation } from 'expo-invoke';
++ const { donate } = useDonation();
++ donate({ intentId: 'create_errand', title: 'Create an Errand' });
+```
+
+### Replace the shortcut listener
+
+```diff
+- import { ShortcutListener } from 'react-native-siri-shortcut';
+- <ShortcutListener onShortcutReceived={({ identifier }) => { ... }} />
+
++ import { useInvoke } from 'expo-invoke';
++ const { intent } = useInvoke();
++ // intent.intentId === 'create_errand' when fired
+```
+
+---
+
+## From `expo-siri-shortcut`
+
+### Install expo-invoke
+
+```bash
+npx expo install expo-invoke
+npx expo uninstall expo-siri-shortcut
+```
+
+### Replace the shortcut button
+
+```diff
+- import { SiriShortcutButton } from 'expo-siri-shortcut';
+- <SiriShortcutButton shortcut={{ activityType: 'create', title: 'Create' }} />
+
++ import { AddToSiriButton } from 'expo-invoke';
++ <AddToSiriButton intentId="create_errand" />
+```
+
+### Replace the activity listener
+
+The old `expo-siri-shortcut` used `NSUserActivity`. `expo-invoke` uses the modern App Intents API. Replace the app delegate hook with `useInvokeInit()` and receive via `useInvoke()`.
+
+---
+
+## Key Behavioural Differences
+
+| Behaviour | Old packages | expo-invoke |
+|---|---|---|
+| iOS API | SiriKit (deprecated) | App Intents (iOS 16+) |
+| Android | None | Google App Actions BII |
+| Multi-intent | No | Yes — unlimited |
+| Parameters | None / manual | 8 typed parameter types |
+| Widget bridge | No | Yes — WidgetKit + AppWidgetProvider |
+| Dynamic Island | No | Yes |
+| Cold start TTL | None | 30s default, configurable |
+| Intent deduplication | No | Yes (2s window) |
+| Source attribution | No | 20 surfaces |
+| Testing utilities | No | mockInvoke, simulateColdStart |
+| CLI | No | validate, generate, test |