@returningai/react-native-widget-sdk 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.1
4
+
5
+ - Allows native iOS HTML-string WebView origins (`about:srcdoc`, `applewebdata://`)
6
+ in `originWhitelist`, navigation policy, and `onMessage` gating. Expo Go still
7
+ reports `about:blank`; RN CLI / WKWebView on iOS 26 reports `about:srcdoc`,
8
+ which previously blocked the shell and timed out ready.
9
+
3
10
  ## 0.1.0
4
11
 
5
12
  - Preserves JSON types and structure in custom-data session fingerprints (EC-04).
package/README.md CHANGED
@@ -1,54 +1,34 @@
1
- # ReturningAI Widget for React Native
1
+ # @returningai/react-native-widget-sdk
2
2
 
3
- TypeScript SDK for hosting ReturningAI custom product widgets in React Native
4
- CLI and Expo apps.
3
+ [![npm](https://img.shields.io/npm/v/@returningai/react-native-widget-sdk.svg)](https://www.npmjs.com/package/@returningai/react-native-widget-sdk)
5
4
 
6
- The package performs serverless authentication in JavaScript and gives the
7
- WebView only the exchanged short-lived access token. It supports custom
8
- `rai-custom-widget` bundle and page content; first-class web elements are not
9
- mobile APIs.
5
+ Embed ReturningAI custom product widgets in React Native CLI and Expo apps.
10
6
 
11
- Authentication responses have a 1 MiB acceptance limit by default. Stream-capable
12
- fetch implementations are read incrementally and cancelled when that limit is
13
- crossed; the SDK collection buffer stays within the configured limit. Transport
14
- buffers and individual incoming chunks are outside that allocation guarantee.
15
- The standard React Native fetch polyfill buffers before returning its Response,
16
- so its fallback size check happens after allocation. A hard native transport
17
- memory cap is not currently guaranteed (EC-12); oversized responses are rejected.
7
+ The SDK authenticates in JavaScript and gives the WebView only a short-lived
8
+ access token. Hosts custom `rai-custom-widget` bundle and page content.
18
9
 
19
- ## Toolchain (supported hosts)
10
+ ## Install
20
11
 
21
- Supported package peers (do **not** treat older stacks as supported without a
22
- funded widen — see
23
- [`docs/guides/client-integration.md`](../../docs/guides/client-integration.md)
24
- **Supported hosts**):
12
+ ```bash
13
+ npm install @returningai/react-native-widget-sdk react-native-webview
14
+ ```
15
+
16
+ Peer dependencies:
25
17
 
26
- - Expo SDK **57** (`expo@57.0.9` or later; React Native **0.86.2**) when using Expo
27
- - React **^19.2**
18
+ - `react` **^19.2**
28
19
  - `react-native` **^0.86**
29
20
  - `react-native-webview` **^16**
30
21
  - Node.js **22.13+**
31
- - **Dev client** (`expo run:*`) — **Expo Go is unsupported** for embeds
32
- - Loyalty sample enables **New Architecture**; Old Arch is not certified
33
22
 
34
- React **18** / RN **< 0.86** / Expo **< 57**: unsupported today (MOB-55 keep
35
- peers). Web Crypto + single-React Metro notes: cookbook §9.
23
+ Expo hosts need SDK **57** and a **dev client** (`expo run:ios` /
24
+ `expo run:android`). Expo Go is not supported.
36
25
 
37
- This package does not depend on `packages/flutter`, `packages/android`, or
38
- `packages/ios`. A public npm release is deferred. Publish / local `file:` notes:
39
- [`docs/publishing/react-native.md`](../../docs/publishing/react-native.md).
26
+ Install Web Crypto before the widget loads:
40
27
 
41
- ## Status
28
+ - Expo: `expo-crypto`
29
+ - React Native CLI: `react-native-get-random-values`
42
30
 
43
- MOB-37 Tasks 0–7, MOB-42, and MOB-43. Configuration, HTML renderer, serverless
44
- auth, version-1 bridge, navigation policy, coordinator, controller, the
45
- `react-native-webview` surface, the Expo Loyalty App, Jest fake-driver
46
- loopback, Chromium generated-shell TTI, and Jest hot-path CPU budgets are in.
47
-
48
- Do not put `accessId`, `accessKey`, or embed tokens in the app, HTML, bridge,
49
- `injectedJavaScript`, or WebView URLs. `reload()` replays the in-memory HTML
50
- shell with the content-origin `baseUrl`; it never calls native
51
- `WebView.reload()`.
31
+ ## Usage
52
32
 
53
33
  ```tsx
54
34
  import {
@@ -58,11 +38,13 @@ import {
58
38
  } from "@returningai/react-native-widget-sdk";
59
39
 
60
40
  const configuration = ReturningAIWidgetConfiguration.customBundle({
61
- widgetId: "widget123",
41
+ widgetId: "YOUR_WIDGET_ID",
62
42
  bundleUrl: "https://widgets.example/custom-widget/bundle/store/widget.js",
63
43
  clientOrigin: "https://mobile-client.example",
64
44
  });
65
45
 
46
+ const controller = new ReturningAIWidgetController();
47
+
66
48
  <ReturningAIWidget
67
49
  configuration={configuration}
68
50
  embedTokenProvider={async () => hostMintedEmbedToken}
@@ -73,39 +55,27 @@ const configuration = ReturningAIWidgetConfiguration.customBundle({
73
55
  />;
74
56
  ```
75
57
 
76
- ## Sample
58
+ `clientOrigin` must be the exact HTTPS origin allowlisted for the widget in
59
+ ReturningAI.
77
60
 
78
- ```bash
79
- cd examples/react-native/loyalty_app
80
- npm install
81
- npx expo start
82
- ```
61
+ Mint embed tokens on **your** backend. Do not put `accessId`, `accessKey`, or
62
+ embed tokens in the app, HTML, bridge, `injectedJavaScript`, or WebView URLs.
83
63
 
84
- Leave `loyaltyEmbedToken` empty in git. Device steps:
85
- [`examples/react-native/TESTING.md`](../../examples/react-native/TESTING.md).
86
- Client recipe (go-live checklist, pin `runtimeUrl`, crypto polyfill):
87
- [`docs/guides/client-integration.md`](../../docs/guides/client-integration.md).
88
- Loyalty samples use unpkg **latest**.
64
+ Pin `runtimeUrl` in production. The default is unpkg
65
+ `@returningai/widget-sdk` latest.
89
66
 
90
- ## Test
67
+ ## Controller
91
68
 
92
- ```bash
93
- cd packages/react-native
94
- npx playwright install chromium
95
- npm test
96
- npm run typecheck
97
- npm run lint
98
- npm run format:check
69
+ ```ts
70
+ await controller.reload();
71
+ await controller.retry();
72
+ await controller.updateTheme("dark");
73
+ await controller.logout();
74
+ await controller.invalidate();
99
75
  ```
100
76
 
101
- - `lint` — ESLint (typescript-eslint typed rules + react/react-hooks)
102
- - `format` / `format:check` — Prettier
103
- - `typecheck` — `tsc --noEmit` (`strict: true`)
104
-
105
- Jest includes fake-driver loopback reliability, Chromium loopback of the
106
- generated HTML shell, and hot-path CPU budgets. Expo dev-client WebView TTI
107
- lives in `examples/react-native/loyalty_app` (`npm run loopback-tti:ios` /
108
- `loopback-tti:android`) and uses real `ReturningAIWidget` + `react-native-webview`
109
- against a localhost loopback fixture (MOB-44). TTI waits for `rai-ready` only,
110
- uses a generous 20-second budget, and prints `benchmark webview_cold_ready` /
111
- `webview_reload_ready` samples. Expo Go and live CDN TTI are out of scope.
77
+ `reload()` replays the in-memory HTML shell. It does not call native
78
+ `WebView.reload()`.
79
+
80
+ On `rai-session-expired`, return a freshly minted embed token from
81
+ `embedTokenProvider`. Call `invalidate()` when the host user signs out.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@returningai/react-native-widget-sdk",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "React Native SDK for embedding ReturningAI custom product widgets.",
5
5
  "license": "UNLICENSED",
6
6
  "publishConfig": {
@@ -56,7 +56,7 @@ export class ReturningAINavigationPolicy {
56
56
  */
57
57
  decide(uri: URL, isMainFrame: boolean): ReturningAINavigationAction {
58
58
  const scheme = uri.protocol.replace(/:$/, "").toLowerCase();
59
- if (scheme === "about" && uri.href === "about:blank") {
59
+ if (isHtmlShellNavigation(uri, scheme)) {
60
60
  return ReturningAINavigationAction.allow;
61
61
  }
62
62
 
@@ -87,3 +87,18 @@ export class ReturningAINavigationPolicy {
87
87
  return ReturningAINavigationAction.reject;
88
88
  }
89
89
  }
90
+
91
+ /**
92
+ * iOS `loadHTMLString:baseURL:` may navigate to `about:blank`, `about:srcdoc`,
93
+ * or `applewebdata://` instead of the content-origin HTTPS URL.
94
+ */
95
+ function isHtmlShellNavigation(uri: URL, scheme: string): boolean {
96
+ if (scheme === "applewebdata") {
97
+ return true;
98
+ }
99
+ if (scheme !== "about") {
100
+ return false;
101
+ }
102
+ const href = uri.href.toLowerCase();
103
+ return href === "about:blank" || href === "about:srcdoc";
104
+ }
@@ -13,7 +13,7 @@
13
13
  */
14
14
  export const RETURNING_AI_REACT_NATIVE_PACKAGE = {
15
15
  /** Semver of `@returningai/react-native-widget-sdk`. */
16
- version: "0.1.0",
16
+ version: "0.1.1",
17
17
  /** Documented Expo SDK major this package targets. */
18
18
  expoSdk: 57,
19
19
  /** Documented React Native minor this package targets. */
@@ -89,6 +89,11 @@ export function normalizeReturningAIOrigin(origin: string): string {
89
89
  return origin.trim().replace(/\/+$/, "").toLowerCase();
90
90
  }
91
91
 
92
+ function isHtmlShellDocumentUrl(sourceUrl: string): boolean {
93
+ const url = sourceUrl.toLowerCase();
94
+ return url === "about:blank" || url === "about:srcdoc" || url.startsWith("applewebdata:");
95
+ }
96
+
92
97
  /**
93
98
  * Strict main-frame origin equality check for bridge message acceptance.
94
99
  * @param isMainFrame - Must be true
@@ -112,7 +117,8 @@ export function shouldAcceptReturningAIWebMessage(
112
117
  /**
113
118
  * RN-specific gate for delivering `onMessage` payloads to the coordinator.
114
119
  * When no expected origin is configured, delivery is allowed (fail-open only then).
115
- * iOS may report `about:blank` for HTML with a content-origin baseUrl; envelope identity still gates.
120
+ * iOS may report `about:blank`, `about:srcdoc`, or `applewebdata://` for HTML
121
+ * with a content-origin baseUrl; envelope identity still gates.
116
122
  * @param input.sourceUrl - `nativeEvent.url` from react-native-webview
117
123
  * @param input.expectedOrigin - Expected origin from configuration
118
124
  * @returns True when the message should be decoded
@@ -128,9 +134,9 @@ export function shouldDeliverReturningAIWebMessage(input: {
128
134
  if (sourceUrl === undefined || sourceUrl.length === 0) {
129
135
  return false;
130
136
  }
131
- // react-native-webview on iOS reports about:blank for HTML loaded with a
132
- // content-origin baseUrl. Envelope identity still gates the payload.
133
- if (sourceUrl === "about:blank") {
137
+ // Native iOS WKWebView reports about:blank, about:srcdoc, or applewebdata
138
+ // for HTML loaded with a content-origin baseUrl. Envelope identity still gates.
139
+ if (isHtmlShellDocumentUrl(sourceUrl)) {
134
140
  return true;
135
141
  }
136
142
  try {
@@ -4,19 +4,23 @@
4
4
  * Layer: webview
5
5
  * Role: Returns allowed origin patterns for the WebView; debug adds localhost/127.0.0.1 HTTP entries.
6
6
  * Does not decide navigation allow/delegate/reject (navigation policy does).
7
- * Security: Production whitelist is HTTPS + about:blank only.
7
+ * Security: Production whitelist is HTTPS + HTML-shell about:/applewebdata URLs.
8
8
  * See also: navigation/ReturningAINavigationPolicy.ts, ReturningAIWidget.tsx
9
9
  */
10
10
 
11
+ /** Origins used when iOS loads `source={{ html, baseUrl }}` (not a real navigation). */
12
+ const htmlShellOrigins = ["about:blank", "about:srcdoc", "applewebdata://*"] as const;
13
+
11
14
  /**
12
15
  * Builds the `originWhitelist` patterns for `react-native-webview`.
13
- * Production allows HTTPS + `about:blank` only; debug also allows localhost HTTP.
16
+ * Production allows HTTPS plus HTML-string shell origins; debug also allows localhost HTTP.
17
+ * Native iOS WKWebView (not Expo Go) may report `about:srcdoc` for `loadHTMLString`.
14
18
  * @param debug - Configuration debug flag
15
19
  * @returns Origin pattern list for the WebView prop
16
20
  */
17
21
  export function returningAIOriginWhitelist(debug: boolean): string[] {
18
22
  if (debug) {
19
- return ["https://*", "http://localhost*", "http://127.0.0.1*", "about:blank"];
23
+ return ["https://*", "http://localhost*", "http://127.0.0.1*", ...htmlShellOrigins];
20
24
  }
21
- return ["https://*", "about:blank"];
25
+ return ["https://*", ...htmlShellOrigins];
22
26
  }