@returningai/react-native-widget-sdk 0.1.0

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.
Files changed (38) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/LICENSE +4 -0
  3. package/README.md +111 -0
  4. package/package.json +60 -0
  5. package/src/ReturningAIWidget.tsx +601 -0
  6. package/src/authentication/ReturningAIAccessTokenCache.ts +90 -0
  7. package/src/authentication/ReturningAIAuthenticationClient.ts +379 -0
  8. package/src/authentication/nonce.ts +26 -0
  9. package/src/authentication/sessionAuthClient.ts +35 -0
  10. package/src/authentication/types.ts +50 -0
  11. package/src/bridge/ReturningAIBridgeCodec.ts +452 -0
  12. package/src/bridge/ReturningAIBridgeIdentity.ts +87 -0
  13. package/src/configuration/ReturningAIFirstPaintColors.ts +46 -0
  14. package/src/configuration/ReturningAIWidgetConfiguration.ts +488 -0
  15. package/src/configuration/ReturningAIWidgetContent.ts +59 -0
  16. package/src/configuration/ReturningAIWidgetDescriptor.ts +54 -0
  17. package/src/configuration/ReturningAIWidgetDisplayOptions.ts +59 -0
  18. package/src/configuration/ReturningAIWidgetDomainKey.ts +44 -0
  19. package/src/configuration/ReturningAIWidgetEndpoints.ts +157 -0
  20. package/src/configuration/ReturningAIWidgetTheme.ts +25 -0
  21. package/src/configuration/urls.ts +133 -0
  22. package/src/controller/ReturningAIWidgetController.ts +149 -0
  23. package/src/controller/ReturningAIWidgetSessionSnapshot.ts +49 -0
  24. package/src/coordinator/ReturningAIWidgetCoordinator.ts +787 -0
  25. package/src/crypto/fillRandomBytes.ts +28 -0
  26. package/src/errors/ReturningAIWidgetError.ts +150 -0
  27. package/src/errors/json.ts +227 -0
  28. package/src/events/ReturningAIWidgetEvent.ts +131 -0
  29. package/src/index.ts +79 -0
  30. package/src/navigation/ReturningAINavigationPolicy.ts +89 -0
  31. package/src/packageInfo.ts +23 -0
  32. package/src/rendering/htmlRenderer.ts +351 -0
  33. package/src/rendering/theme.ts +57 -0
  34. package/src/webview/ReturningAIReactNativeWebViewDriver.ts +136 -0
  35. package/src/webview/ReturningAIWebViewDriver.ts +141 -0
  36. package/src/webview/bridgeBootstrap.ts +26 -0
  37. package/src/webview/errorPolicy.ts +27 -0
  38. package/src/webview/originWhitelist.ts +22 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,49 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ - Preserves JSON types and structure in custom-data session fingerprints (EC-04).
6
+
7
+ - Decodes bridge responses as UTF-8 so Unicode callback keys and values survive the WebView round trip (EC-03).
8
+
9
+ - Normalizes host provider/callback exceptions and omits raw authentication causes from public errors (EC-02).
10
+
11
+ - Uses fixed authentication failure text and omits server hints to prevent opaque credential reflection (EC-01).
12
+
13
+ - Adds the `@returningai/react-native-widget-sdk` npm package foundation (Task 0).
14
+ - Locks Expo SDK 57, React Native 0.86, React 19.2, and `react-native-webview` 16.
15
+ - Ports immutable configuration, validation, redaction, and deterministic HTML
16
+ with `ReturningAIReactNativeBridge` (Task 1).
17
+ - Ports serverless `fetch` authentication, 30s access-token cache skew, and
18
+ redacted public errors (Task 2).
19
+ - Ports the version-1 bridge codec, navigation matrix, session coordinator, and
20
+ controller (Task 3).
21
+ - Hosts one `react-native-webview` from `ReturningAIWidget`. Reload replays
22
+ stored HTML + content-origin `baseUrl` and never calls native
23
+ `WebView.reload()` (Task 4).
24
+ - Adds the Expo Loyalty App under `examples/react-native/loyalty_app` with the
25
+ same Custom embeds / Embed token / More examples home as Flutter, Android, and
26
+ iOS (Task 5). The checked-in embed token stays empty. Widget surface types
27
+ match `react-native-webview` 16 / React Native 0.86 so the sample typechecks.
28
+ - Adds Jest loopback coverage for auth → ready, language /
29
+ `milestoneCtaClick` / session-expired renewal, repeated disposal, and
30
+ cold-start/reload TTI (Task 6). TTI waits for `rai-ready` only, uses a 20s
31
+ budget, and prints local samples. Parked RN CI is not a green.
32
+ - Documents the React Native transport name `ReturningAIReactNativeBridge` in
33
+ the integration contract. RN CI stays parked (Task 7).
34
+ - Reads serverless auth response bodies with `Uint8Array` and `TextDecoder`
35
+ instead of Node `Buffer`, so the exchange works on Hermes.
36
+ - Drops `onMessage` payloads with a missing document URL. Accepts
37
+ `about:blank` because iOS `react-native-webview` reports that URL for HTML
38
+ loaded with a content-origin `baseUrl`. Production `originWhitelist` is
39
+ HTTPS + `about:blank`; debug adds localhost HTTP (MOB-42).
40
+ - Reload tags the replayed HTML so `react-native-webview` actually reloads
41
+ instead of skipping an unchanged `source.html`. Native `WebView.reload()` is
42
+ still never called.
43
+ - Adds Jest hot-path CPU budgets for HTML render, configuration, bridge,
44
+ navigation, and coordinator start (MOB-42). Parked RN CI is not a green.
45
+ - Adds Chromium loopback TTI for the generated HTML shell: auth → ready,
46
+ language / `milestoneCtaClick` / session-expired, repeated disposal, and
47
+ cold-start/reload time-to-ready (MOB-43). TTI waits for `rai-ready` only.
48
+ This is not Expo Go or `react-native-webview`. Live CDN TTI stays out of
49
+ scope.
package/LICENSE ADDED
@@ -0,0 +1,4 @@
1
+ Copyright (c) 2026 ReturningAI. All rights reserved.
2
+
3
+ No permission is granted to use, copy, modify, distribute, sublicense, or
4
+ sell this software without prior written authorization from ReturningAI.
package/README.md ADDED
@@ -0,0 +1,111 @@
1
+ # ReturningAI Widget for React Native
2
+
3
+ TypeScript SDK for hosting ReturningAI custom product widgets in React Native
4
+ CLI and Expo apps.
5
+
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.
10
+
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.
18
+
19
+ ## Toolchain (supported hosts)
20
+
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**):
25
+
26
+ - Expo SDK **57** (`expo@57.0.9` or later; React Native **0.86.2**) when using Expo
27
+ - React **^19.2**
28
+ - `react-native` **^0.86**
29
+ - `react-native-webview` **^16**
30
+ - 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
+
34
+ React **18** / RN **< 0.86** / Expo **< 57**: unsupported today (MOB-55 keep
35
+ peers). Web Crypto + single-React Metro notes: cookbook §9.
36
+
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).
40
+
41
+ ## Status
42
+
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()`.
52
+
53
+ ```tsx
54
+ import {
55
+ ReturningAIWidget,
56
+ ReturningAIWidgetConfiguration,
57
+ ReturningAIWidgetController,
58
+ } from "@returningai/react-native-widget-sdk";
59
+
60
+ const configuration = ReturningAIWidgetConfiguration.customBundle({
61
+ widgetId: "widget123",
62
+ bundleUrl: "https://widgets.example/custom-widget/bundle/store/widget.js",
63
+ clientOrigin: "https://mobile-client.example",
64
+ });
65
+
66
+ <ReturningAIWidget
67
+ configuration={configuration}
68
+ embedTokenProvider={async () => hostMintedEmbedToken}
69
+ controller={controller}
70
+ onEvent={onEvent}
71
+ onError={onError}
72
+ onExternalNavigation={onExternalNavigation}
73
+ />;
74
+ ```
75
+
76
+ ## Sample
77
+
78
+ ```bash
79
+ cd examples/react-native/loyalty_app
80
+ npm install
81
+ npx expo start
82
+ ```
83
+
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**.
89
+
90
+ ## Test
91
+
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
99
+ ```
100
+
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.
package/package.json ADDED
@@ -0,0 +1,60 @@
1
+ {
2
+ "name": "@returningai/react-native-widget-sdk",
3
+ "version": "0.1.0",
4
+ "description": "React Native SDK for embedding ReturningAI custom product widgets.",
5
+ "license": "UNLICENSED",
6
+ "publishConfig": {
7
+ "access": "public"
8
+ },
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "git+https://github.com/ReturningAI/rai-widget-mobile-sdks.git",
12
+ "directory": "packages/react-native"
13
+ },
14
+ "main": "./src/index.ts",
15
+ "types": "./src/index.ts",
16
+ "files": [
17
+ "src",
18
+ "README.md",
19
+ "CHANGELOG.md",
20
+ "LICENSE"
21
+ ],
22
+ "sideEffects": false,
23
+ "scripts": {
24
+ "test": "jest",
25
+ "typecheck": "tsc --noEmit",
26
+ "playwright:install": "playwright install chromium",
27
+ "lint": "eslint .",
28
+ "lint:fix": "eslint . --fix",
29
+ "format": "prettier --write .",
30
+ "format:check": "prettier --check ."
31
+ },
32
+ "engines": {
33
+ "node": ">=22.13.0"
34
+ },
35
+ "peerDependencies": {
36
+ "react": "^19.2.0",
37
+ "react-native": "^0.86.0",
38
+ "react-native-webview": "^16.0.0"
39
+ },
40
+ "devDependencies": {
41
+ "@eslint/js": "^9.39.5",
42
+ "@types/jest": "^29.5.14",
43
+ "@types/node": "^22.18.0",
44
+ "@types/react": "^19.2.0",
45
+ "@types/react-test-renderer": "^19.1.0",
46
+ "eslint": "^9.39.5",
47
+ "eslint-config-prettier": "^10.1.8",
48
+ "eslint-plugin-react": "^7.37.5",
49
+ "eslint-plugin-react-hooks": "^5.2.0",
50
+ "globals": "^16.5.0",
51
+ "jest": "^29.7.0",
52
+ "playwright": "^1.55.0",
53
+ "prettier": "^3.9.6",
54
+ "react": "^19.2.0",
55
+ "react-test-renderer": "^19.2.0",
56
+ "ts-jest": "^29.4.1",
57
+ "typescript": "^5.9.2",
58
+ "typescript-eslint": "^8.69.0"
59
+ }
60
+ }