@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.
- package/CHANGELOG.md +49 -0
- package/LICENSE +4 -0
- package/README.md +111 -0
- package/package.json +60 -0
- package/src/ReturningAIWidget.tsx +601 -0
- package/src/authentication/ReturningAIAccessTokenCache.ts +90 -0
- package/src/authentication/ReturningAIAuthenticationClient.ts +379 -0
- package/src/authentication/nonce.ts +26 -0
- package/src/authentication/sessionAuthClient.ts +35 -0
- package/src/authentication/types.ts +50 -0
- package/src/bridge/ReturningAIBridgeCodec.ts +452 -0
- package/src/bridge/ReturningAIBridgeIdentity.ts +87 -0
- package/src/configuration/ReturningAIFirstPaintColors.ts +46 -0
- package/src/configuration/ReturningAIWidgetConfiguration.ts +488 -0
- package/src/configuration/ReturningAIWidgetContent.ts +59 -0
- package/src/configuration/ReturningAIWidgetDescriptor.ts +54 -0
- package/src/configuration/ReturningAIWidgetDisplayOptions.ts +59 -0
- package/src/configuration/ReturningAIWidgetDomainKey.ts +44 -0
- package/src/configuration/ReturningAIWidgetEndpoints.ts +157 -0
- package/src/configuration/ReturningAIWidgetTheme.ts +25 -0
- package/src/configuration/urls.ts +133 -0
- package/src/controller/ReturningAIWidgetController.ts +149 -0
- package/src/controller/ReturningAIWidgetSessionSnapshot.ts +49 -0
- package/src/coordinator/ReturningAIWidgetCoordinator.ts +787 -0
- package/src/crypto/fillRandomBytes.ts +28 -0
- package/src/errors/ReturningAIWidgetError.ts +150 -0
- package/src/errors/json.ts +227 -0
- package/src/events/ReturningAIWidgetEvent.ts +131 -0
- package/src/index.ts +79 -0
- package/src/navigation/ReturningAINavigationPolicy.ts +89 -0
- package/src/packageInfo.ts +23 -0
- package/src/rendering/htmlRenderer.ts +351 -0
- package/src/rendering/theme.ts +57 -0
- package/src/webview/ReturningAIReactNativeWebViewDriver.ts +136 -0
- package/src/webview/ReturningAIWebViewDriver.ts +141 -0
- package/src/webview/bridgeBootstrap.ts +26 -0
- package/src/webview/errorPolicy.ts +27 -0
- package/src/webview/originWhitelist.ts +22 -0
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Fills a byte buffer with cryptographically secure random values via Web Crypto.
|
|
3
|
+
*
|
|
4
|
+
* Layer: crypto
|
|
5
|
+
* Role: Requires globalThis.crypto.getRandomValues (Expo polyfill when needed); throws
|
|
6
|
+
* unsupportedPlatform otherwise. Does not implement auth nonces or bridge identity itself.
|
|
7
|
+
* See also: authentication/nonce.ts, bridge/ReturningAIBridgeIdentity.ts
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { ReturningAIWidgetError } from "../errors/ReturningAIWidgetError";
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Fills `bytes` in place with cryptographically secure random values.
|
|
14
|
+
* Requires `globalThis.crypto.getRandomValues` (Expo samples polyfill via `expo-crypto`).
|
|
15
|
+
* @param bytes - Destination buffer mutated in place
|
|
16
|
+
* @throws {ReturningAIWidgetError} with `unsupportedPlatform` when Web Crypto is missing
|
|
17
|
+
*/
|
|
18
|
+
export function fillRandomBytes(bytes: Uint8Array): void {
|
|
19
|
+
const webCrypto = (globalThis as { crypto?: Crypto }).crypto;
|
|
20
|
+
if (webCrypto === undefined || typeof webCrypto.getRandomValues !== "function") {
|
|
21
|
+
throw new ReturningAIWidgetError({
|
|
22
|
+
code: "unsupportedPlatform",
|
|
23
|
+
message:
|
|
24
|
+
"Secure random bytes require Web Crypto getRandomValues. The Expo sample installs expo-crypto and polyfills crypto before the widget loads.",
|
|
25
|
+
});
|
|
26
|
+
}
|
|
27
|
+
webCrypto.getRandomValues(bytes);
|
|
28
|
+
}
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Typed ReturningAIWidgetError codes, constructors, and Hermes-safe error narrowing.
|
|
3
|
+
*
|
|
4
|
+
* Layer: errors
|
|
5
|
+
* Role: Defines error codes, redacted toString, invalidConfiguration helper, and conversion from
|
|
6
|
+
* unknown catch values. Does not decide when to fail the widget lifecycle.
|
|
7
|
+
* Security: Messages and hints are redacted so tokens/secrets are not echoed via toString().
|
|
8
|
+
* See also: errors/json.ts, coordinator/ReturningAIWidgetCoordinator.ts
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { redactReturningAISecrets } from "./json";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Stable error codes surfaced to hosts and used for branching in the coordinator.
|
|
15
|
+
* Messages must never include embed tokens, access tokens, or raw request bodies.
|
|
16
|
+
*/
|
|
17
|
+
export type ReturningAIWidgetErrorCode =
|
|
18
|
+
| "invalidConfiguration"
|
|
19
|
+
| "unsupportedPlatform"
|
|
20
|
+
| "tokenProviderFailed"
|
|
21
|
+
| "authenticationFailed"
|
|
22
|
+
| "authenticationTimeout"
|
|
23
|
+
| "malformedAuthenticationResponse"
|
|
24
|
+
| "webViewLoadFailed"
|
|
25
|
+
| "javaScriptRuntimeFailed"
|
|
26
|
+
| "bridgeProtocolFailed"
|
|
27
|
+
| "callbackFailed"
|
|
28
|
+
| "callbackTimeout"
|
|
29
|
+
| "navigationRejected"
|
|
30
|
+
| "invalidControllerState"
|
|
31
|
+
| "cancelled";
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Typed SDK error with redacted stringification.
|
|
35
|
+
* Prefer constructing via helpers or explicit codes; never interpolate credentials into `message`.
|
|
36
|
+
*/
|
|
37
|
+
export class ReturningAIWidgetError extends Error {
|
|
38
|
+
/** Machine-readable failure category. */
|
|
39
|
+
readonly code: ReturningAIWidgetErrorCode;
|
|
40
|
+
/** Optional HTTP status from auth or WebView HTTP errors. */
|
|
41
|
+
readonly statusCode?: number;
|
|
42
|
+
/** Optional host-facing hint (redacted in {@link toString}). */
|
|
43
|
+
readonly hint?: string;
|
|
44
|
+
/** Optional underlying cause retained for diagnostics (not stringified). */
|
|
45
|
+
readonly cause?: unknown;
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Creates a typed widget error.
|
|
49
|
+
* @param input.code - Stable error code
|
|
50
|
+
* @param input.message - Host-safe message (no credentials)
|
|
51
|
+
* @param input.statusCode - Optional HTTP status
|
|
52
|
+
* @param input.hint - Optional hint (redacted on stringify)
|
|
53
|
+
* @param input.cause - Optional underlying error
|
|
54
|
+
*/
|
|
55
|
+
constructor(input: {
|
|
56
|
+
code: ReturningAIWidgetErrorCode;
|
|
57
|
+
message: string;
|
|
58
|
+
statusCode?: number;
|
|
59
|
+
hint?: string;
|
|
60
|
+
cause?: unknown;
|
|
61
|
+
}) {
|
|
62
|
+
super(input.message);
|
|
63
|
+
this.name = "ReturningAIWidgetError";
|
|
64
|
+
this.code = input.code;
|
|
65
|
+
this.statusCode = input.statusCode;
|
|
66
|
+
this.hint = input.hint;
|
|
67
|
+
this.cause = input.cause;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Returns a redacted diagnostic string safe for logs and UI.
|
|
72
|
+
* @returns `ReturningAIWidgetError(code: message…)` with secrets stripped
|
|
73
|
+
*/
|
|
74
|
+
override toString(): string {
|
|
75
|
+
const status = this.statusCode === undefined ? "" : ` statusCode=${this.statusCode}`;
|
|
76
|
+
const redactedHint =
|
|
77
|
+
this.hint === undefined ? "" : ` hint=${redactReturningAISecrets(this.hint)}`;
|
|
78
|
+
return (
|
|
79
|
+
`ReturningAIWidgetError(${this.code}: ` +
|
|
80
|
+
`${redactReturningAISecrets(this.message)}${status}${redactedHint})`
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Convenience constructor for configuration validation failures.
|
|
87
|
+
* @param message - Host-safe validation message
|
|
88
|
+
* @returns Error with code `invalidConfiguration`
|
|
89
|
+
*/
|
|
90
|
+
export function invalidConfiguration(message: string): ReturningAIWidgetError {
|
|
91
|
+
return new ReturningAIWidgetError({
|
|
92
|
+
code: "invalidConfiguration",
|
|
93
|
+
message,
|
|
94
|
+
});
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Hermes-safe type guard for {@link ReturningAIWidgetError}.
|
|
99
|
+
* Falls back to duck-typing because `instanceof` can fail across the RN bridge.
|
|
100
|
+
* @param value - Unknown catch value
|
|
101
|
+
* @returns Whether `value` looks like a ReturningAIWidgetError
|
|
102
|
+
*/
|
|
103
|
+
export function isReturningAIWidgetError(value: unknown): value is ReturningAIWidgetError {
|
|
104
|
+
if (value instanceof ReturningAIWidgetError) {
|
|
105
|
+
return true;
|
|
106
|
+
}
|
|
107
|
+
// Hermes can fail `instanceof` for Error subclasses across the RN bridge.
|
|
108
|
+
return (
|
|
109
|
+
typeof value === "object" &&
|
|
110
|
+
value !== null &&
|
|
111
|
+
(value as { name?: string }).name === "ReturningAIWidgetError" &&
|
|
112
|
+
typeof (value as { message?: string }).message === "string" &&
|
|
113
|
+
typeof (value as { code?: string }).code === "string"
|
|
114
|
+
);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Narrows an unknown catch value into a {@link ReturningAIWidgetError}.
|
|
119
|
+
* Redacts messages from plain `Error` instances; uses `fallbackMessage` when empty.
|
|
120
|
+
* @param caught - Value from a catch clause
|
|
121
|
+
* @param fallbackMessage - Message when `caught` is not a useful Error
|
|
122
|
+
* @returns A typed widget error
|
|
123
|
+
*/
|
|
124
|
+
export function toReturningAIWidgetError(
|
|
125
|
+
caught: unknown,
|
|
126
|
+
fallbackMessage: string,
|
|
127
|
+
): ReturningAIWidgetError {
|
|
128
|
+
if (caught instanceof ReturningAIWidgetError) {
|
|
129
|
+
return caught;
|
|
130
|
+
}
|
|
131
|
+
if (isReturningAIWidgetError(caught)) {
|
|
132
|
+
return new ReturningAIWidgetError({
|
|
133
|
+
code: caught.code,
|
|
134
|
+
message: caught.message,
|
|
135
|
+
statusCode: caught.statusCode,
|
|
136
|
+
hint: caught.hint,
|
|
137
|
+
cause: caught.cause,
|
|
138
|
+
});
|
|
139
|
+
}
|
|
140
|
+
if (caught instanceof Error && caught.message.trim().length > 0) {
|
|
141
|
+
return new ReturningAIWidgetError({
|
|
142
|
+
code: "invalidConfiguration",
|
|
143
|
+
message: redactReturningAISecrets(caught.message),
|
|
144
|
+
});
|
|
145
|
+
}
|
|
146
|
+
return new ReturningAIWidgetError({
|
|
147
|
+
code: "invalidConfiguration",
|
|
148
|
+
message: fallbackMessage,
|
|
149
|
+
});
|
|
150
|
+
}
|
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview JSON-compatible value validation, stable stringify, encode, and secret redaction helpers.
|
|
3
|
+
*
|
|
4
|
+
* Layer: errors
|
|
5
|
+
* Role: Validates finite JSON trees for bridge/config payloads; encodes for script/HTML; redacts
|
|
6
|
+
* token-like substrings from strings. Does not parse bridge envelopes.
|
|
7
|
+
* Security: redactReturningAISecrets strips credential-like material from logs and error text.
|
|
8
|
+
* See also: ReturningAIWidgetError.ts, bridge/ReturningAIBridgeCodec.ts
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { ReturningAIWidgetError } from "./ReturningAIWidgetError";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Finite JSON-compatible value tree used for bridge payloads, custom data, and callback results.
|
|
15
|
+
* Non-finite numbers, functions, and class instances are rejected by validators.
|
|
16
|
+
*/
|
|
17
|
+
export type ReturningAIJsonValue =
|
|
18
|
+
| null
|
|
19
|
+
| boolean
|
|
20
|
+
| number
|
|
21
|
+
| string
|
|
22
|
+
| ReturningAIJsonValue[]
|
|
23
|
+
| { [key: string]: ReturningAIJsonValue };
|
|
24
|
+
|
|
25
|
+
/** Maximum nesting depth accepted by {@link validateReturningAIJsonValue}. */
|
|
26
|
+
const MAX_JSON_DEPTH = 64;
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Validates and freezes a JSON-compatible value tree for bridge/config use.
|
|
30
|
+
* @param value - Unknown input to validate
|
|
31
|
+
* @param depth - Current nesting depth (callers should omit; recursion only)
|
|
32
|
+
* @returns A frozen JSON-compatible value
|
|
33
|
+
* @throws {ReturningAIWidgetError} with `bridgeProtocolFailed` when incompatible or too deep
|
|
34
|
+
*/
|
|
35
|
+
export function validateReturningAIJsonValue(value: unknown, depth = 0): ReturningAIJsonValue {
|
|
36
|
+
if (depth > MAX_JSON_DEPTH) {
|
|
37
|
+
throw new ReturningAIWidgetError({
|
|
38
|
+
code: "bridgeProtocolFailed",
|
|
39
|
+
message: "JSON-compatible values cannot exceed the maximum nesting depth.",
|
|
40
|
+
});
|
|
41
|
+
}
|
|
42
|
+
if (value === null || typeof value === "boolean" || typeof value === "string") {
|
|
43
|
+
return value;
|
|
44
|
+
}
|
|
45
|
+
if (typeof value === "number") {
|
|
46
|
+
if (!Number.isFinite(value)) {
|
|
47
|
+
throw new ReturningAIWidgetError({
|
|
48
|
+
code: "bridgeProtocolFailed",
|
|
49
|
+
message: "JSON-compatible numbers must be finite.",
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
return value;
|
|
53
|
+
}
|
|
54
|
+
if (Array.isArray(value)) {
|
|
55
|
+
const validated = value.map((item) => validateReturningAIJsonValue(item, depth + 1));
|
|
56
|
+
Object.freeze(validated);
|
|
57
|
+
return validated;
|
|
58
|
+
}
|
|
59
|
+
if (isPlainObject(value)) {
|
|
60
|
+
const result: { [key: string]: ReturningAIJsonValue } = {};
|
|
61
|
+
for (const [key, item] of Object.entries(value)) {
|
|
62
|
+
result[key] = validateReturningAIJsonValue(item, depth + 1);
|
|
63
|
+
}
|
|
64
|
+
Object.freeze(result);
|
|
65
|
+
return result;
|
|
66
|
+
}
|
|
67
|
+
throw new ReturningAIWidgetError({
|
|
68
|
+
code: "bridgeProtocolFailed",
|
|
69
|
+
message: "Value is not JSON-compatible.",
|
|
70
|
+
});
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Deterministic string fingerprint of a JSON value (sorted object keys).
|
|
75
|
+
* Used for configuration session fingerprints, not wire encoding.
|
|
76
|
+
* @param value - JSON value or `undefined`
|
|
77
|
+
* @returns Canonical JSON with sorted keys, or empty string for absent input
|
|
78
|
+
*/
|
|
79
|
+
export function jsonStableString(value: ReturningAIJsonValue | undefined): string {
|
|
80
|
+
if (value === undefined) {
|
|
81
|
+
return "";
|
|
82
|
+
}
|
|
83
|
+
if (isPlainObject(value)) {
|
|
84
|
+
const keys = Object.keys(value).sort();
|
|
85
|
+
return `{${keys.map((key) => `${encodeReturningAIJson(key)}:${jsonStableString(value[key])}`).join(",")}}`;
|
|
86
|
+
}
|
|
87
|
+
if (Array.isArray(value)) {
|
|
88
|
+
return `[${value.map((item) => jsonStableString(item)).join(",")}]`;
|
|
89
|
+
}
|
|
90
|
+
return encodeReturningAIJson(value);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Encodes a JSON-compatible value as a compact JSON string without `JSON.stringify`.
|
|
95
|
+
* @param value - Value to encode
|
|
96
|
+
* @returns JSON text
|
|
97
|
+
* @throws {ReturningAIWidgetError} when the value is not JSON-compatible
|
|
98
|
+
*/
|
|
99
|
+
export function encodeReturningAIJson(value: unknown): string {
|
|
100
|
+
if (value === null || value === undefined) {
|
|
101
|
+
return "null";
|
|
102
|
+
}
|
|
103
|
+
if (typeof value === "boolean") {
|
|
104
|
+
return value ? "true" : "false";
|
|
105
|
+
}
|
|
106
|
+
if (typeof value === "number") {
|
|
107
|
+
return String(value);
|
|
108
|
+
}
|
|
109
|
+
if (typeof value === "string") {
|
|
110
|
+
return encodeJsonString(value);
|
|
111
|
+
}
|
|
112
|
+
if (Array.isArray(value)) {
|
|
113
|
+
return `[${value.map((item) => encodeReturningAIJson(item)).join(",")}]`;
|
|
114
|
+
}
|
|
115
|
+
if (isPlainObject(value)) {
|
|
116
|
+
return `{${Object.entries(value)
|
|
117
|
+
.map(([key, item]) => `${encodeJsonString(key)}:${encodeReturningAIJson(item)}`)
|
|
118
|
+
.join(",")}}`;
|
|
119
|
+
}
|
|
120
|
+
throw new ReturningAIWidgetError({
|
|
121
|
+
code: "bridgeProtocolFailed",
|
|
122
|
+
message: "Value is not JSON-compatible.",
|
|
123
|
+
});
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Encodes JSON for safe embedding inside HTML `<script>` contexts.
|
|
128
|
+
* Escapes `<`, `>`, `&`, and U+2028/U+2029 to prevent script breakout.
|
|
129
|
+
* @param value - Value to encode for inline script
|
|
130
|
+
* @returns Script-safe JSON text
|
|
131
|
+
*/
|
|
132
|
+
export function encodeReturningAIJsonForScript(value: unknown): string {
|
|
133
|
+
return encodeReturningAIJson(value)
|
|
134
|
+
.replace(/</g, "\\u003C")
|
|
135
|
+
.replace(/>/g, "\\u003E")
|
|
136
|
+
.replace(/&/g, "\\u0026")
|
|
137
|
+
.replace(/\u2028/g, "\\u2028")
|
|
138
|
+
.replace(/\u2029/g, "\\u2029")
|
|
139
|
+
.replace(/\\\//g, "/");
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Redacts credential-like substrings from diagnostic strings.
|
|
144
|
+
* Covers quoted JSON keys, Authorization headers, Bearer tokens, and request-body markers.
|
|
145
|
+
* @param value - Raw diagnostic text
|
|
146
|
+
* @returns Text with secrets replaced by `[REDACTED]`
|
|
147
|
+
*/
|
|
148
|
+
export function redactReturningAISecrets(value: string): string {
|
|
149
|
+
let redacted = value.replace(QUOTED_CREDENTIAL, '"$1":"[REDACTED]"');
|
|
150
|
+
for (const pattern of CREDENTIAL_PATTERNS) {
|
|
151
|
+
redacted = redacted.replace(pattern, (matched, marker?: string) => {
|
|
152
|
+
const lower = matched.toLowerCase();
|
|
153
|
+
if (lower.startsWith("authorization")) {
|
|
154
|
+
return "Authorization=[REDACTED]";
|
|
155
|
+
}
|
|
156
|
+
if (marker === undefined) {
|
|
157
|
+
return "[REDACTED]";
|
|
158
|
+
}
|
|
159
|
+
if (lower.startsWith("bearer")) {
|
|
160
|
+
return "Bearer [REDACTED]";
|
|
161
|
+
}
|
|
162
|
+
return `${marker}=[REDACTED]`;
|
|
163
|
+
});
|
|
164
|
+
}
|
|
165
|
+
return redacted;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/** Manual JSON string encoder with control-character escapes. */
|
|
169
|
+
function encodeJsonString(value: string): string {
|
|
170
|
+
let encoded = '"';
|
|
171
|
+
for (const character of value) {
|
|
172
|
+
switch (character) {
|
|
173
|
+
case "\\":
|
|
174
|
+
encoded += "\\\\";
|
|
175
|
+
break;
|
|
176
|
+
case '"':
|
|
177
|
+
encoded += '\\"';
|
|
178
|
+
break;
|
|
179
|
+
case "\b":
|
|
180
|
+
encoded += "\\b";
|
|
181
|
+
break;
|
|
182
|
+
case "\f":
|
|
183
|
+
encoded += "\\f";
|
|
184
|
+
break;
|
|
185
|
+
case "\n":
|
|
186
|
+
encoded += "\\n";
|
|
187
|
+
break;
|
|
188
|
+
case "\r":
|
|
189
|
+
encoded += "\\r";
|
|
190
|
+
break;
|
|
191
|
+
case "\t":
|
|
192
|
+
encoded += "\\t";
|
|
193
|
+
break;
|
|
194
|
+
default: {
|
|
195
|
+
const code = character.charCodeAt(0);
|
|
196
|
+
if (code < 0x20) {
|
|
197
|
+
encoded += `\\u${code.toString(16).padStart(4, "0")}`;
|
|
198
|
+
} else {
|
|
199
|
+
encoded += character;
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
return `${encoded}"`;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** True for plain objects (prototype === Object.prototype), not arrays or class instances. */
|
|
208
|
+
function isPlainObject(value: unknown): value is { [key: string]: unknown } {
|
|
209
|
+
return (
|
|
210
|
+
typeof value === "object" &&
|
|
211
|
+
value !== null &&
|
|
212
|
+
!Array.isArray(value) &&
|
|
213
|
+
Object.getPrototypeOf(value) === Object.prototype
|
|
214
|
+
);
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** Matches quoted JSON credential fields for redaction. */
|
|
218
|
+
const QUOTED_CREDENTIAL =
|
|
219
|
+
/"(embedToken|accessToken|authorization|token|refreshToken)"\s*:\s*"[^"]*"/gi;
|
|
220
|
+
|
|
221
|
+
/** Loose credential patterns for free-form diagnostic text. */
|
|
222
|
+
const CREDENTIAL_PATTERNS = [
|
|
223
|
+
/\bauthorization\b\s*[:=]\s*bearer\s+([^\s,;)}]+)/gi,
|
|
224
|
+
/\b(embedToken|accessToken|authorization|token|refreshToken)\b\s*[:=]\s*("[^"]*"|[^\s,;)}]+)/gi,
|
|
225
|
+
/\bbearer\s+([^\s,;)}]+)/gi,
|
|
226
|
+
/\brequest body\b\s*[:=]?\s*("[^"]*"|[^\s,;)}]+)?/gi,
|
|
227
|
+
];
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Typed widget lifecycle, navigation, error, custom, and host-callback event models.
|
|
3
|
+
*
|
|
4
|
+
* Layer: events
|
|
5
|
+
* Role: Defines event subclasses and host-callback request/handler types delivered to hosts.
|
|
6
|
+
* Does not emit events or decode bridge payloads (codec/coordinator do that).
|
|
7
|
+
* See also: bridge/ReturningAIBridgeCodec.ts, ReturningAIWidget.tsx
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import type { ReturningAIJsonValue } from "../errors/json";
|
|
11
|
+
import { type ReturningAIWidgetError } from "../errors/ReturningAIWidgetError";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Base class for typed widget lifecycle and runtime events delivered to hosts via `onEvent`.
|
|
15
|
+
*/
|
|
16
|
+
export abstract class ReturningAIWidgetEvent {}
|
|
17
|
+
|
|
18
|
+
/** Emitted when the coordinator begins loading the shell (before `rai-ready`). */
|
|
19
|
+
export class ReturningAIWidgetLoading extends ReturningAIWidgetEvent {}
|
|
20
|
+
|
|
21
|
+
/** Emitted when the web runtime reports `rai-mounted`. */
|
|
22
|
+
export class ReturningAIWidgetMounted extends ReturningAIWidgetEvent {}
|
|
23
|
+
|
|
24
|
+
/** Emitted when the web runtime reports `rai-ready`. */
|
|
25
|
+
export class ReturningAIWidgetReady extends ReturningAIWidgetEvent {}
|
|
26
|
+
|
|
27
|
+
/** Emitted when the web runtime reports `rai-logout`. */
|
|
28
|
+
export class ReturningAIWidgetLoggedOut extends ReturningAIWidgetEvent {}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Emitted when the web runtime reports `rai-session-expired`.
|
|
32
|
+
* The coordinator clears the cached access token so the next auth uses a fresh exchange.
|
|
33
|
+
*/
|
|
34
|
+
export class ReturningAIWidgetSessionExpired extends ReturningAIWidgetEvent {}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Emitted on `rai-height-change` with a positive height in CSS pixels.
|
|
38
|
+
* The RN shell clamps this to display min/max when `autoHeight` is enabled.
|
|
39
|
+
*/
|
|
40
|
+
export class ReturningAIWidgetHeightChanged extends ReturningAIWidgetEvent {
|
|
41
|
+
/** Requested content height from the widget. */
|
|
42
|
+
readonly height: number;
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* @param height - Positive height in CSS pixels
|
|
46
|
+
*/
|
|
47
|
+
constructor(height: number) {
|
|
48
|
+
super();
|
|
49
|
+
this.height = height;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Emitted when navigation should be handled by the host (policy `delegate` or `window.open`).
|
|
55
|
+
*/
|
|
56
|
+
export class ReturningAIWidgetExternalNavigationRequested extends ReturningAIWidgetEvent {
|
|
57
|
+
/** Absolute URL the host should open externally. */
|
|
58
|
+
readonly uri: URL;
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* @param uri - Absolute navigation URL
|
|
62
|
+
*/
|
|
63
|
+
constructor(uri: URL) {
|
|
64
|
+
super();
|
|
65
|
+
this.uri = uri;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Emitted when a typed SDK error should be surfaced as an event (in addition to `onError`).
|
|
71
|
+
*/
|
|
72
|
+
export class ReturningAIWidgetErrorEvent extends ReturningAIWidgetEvent {
|
|
73
|
+
/** Typed error (messages must not contain embed/access tokens). */
|
|
74
|
+
readonly error: ReturningAIWidgetError;
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* @param error - Typed widget error
|
|
78
|
+
*/
|
|
79
|
+
constructor(error: ReturningAIWidgetError) {
|
|
80
|
+
super();
|
|
81
|
+
this.error = error;
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Catch-all for bridge events whose names are not mapped to a first-class subclass.
|
|
87
|
+
*/
|
|
88
|
+
export class ReturningAIWidgetCustomEvent extends ReturningAIWidgetEvent {
|
|
89
|
+
/** Event name from the bridge body. */
|
|
90
|
+
readonly name: string;
|
|
91
|
+
/** JSON-compatible detail payload. */
|
|
92
|
+
readonly detail: ReturningAIJsonValue;
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* @param name - Event name
|
|
96
|
+
* @param detail - JSON-compatible detail
|
|
97
|
+
*/
|
|
98
|
+
constructor(name: string, detail: ReturningAIJsonValue) {
|
|
99
|
+
super();
|
|
100
|
+
this.name = name;
|
|
101
|
+
this.detail = detail;
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Inbound host-callback request decoded from the bridge after allowlist checks.
|
|
107
|
+
* Payloads never include embed tokens.
|
|
108
|
+
*/
|
|
109
|
+
export class ReturningAIHostCallbackRequest {
|
|
110
|
+
/** Allowlisted callback name (for example `milestoneCtaClick`). */
|
|
111
|
+
readonly name: string;
|
|
112
|
+
/** JSON-compatible payload from the widget. */
|
|
113
|
+
readonly payload: ReturningAIJsonValue;
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* @param name - Allowlisted callback name
|
|
117
|
+
* @param payload - JSON-compatible payload
|
|
118
|
+
*/
|
|
119
|
+
constructor(name: string, payload: ReturningAIJsonValue) {
|
|
120
|
+
this.name = name;
|
|
121
|
+
this.payload = payload;
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* Host handler invoked for an allowlisted widget callback.
|
|
127
|
+
* Return value must be JSON-compatible (or `undefined` → `null` over the bridge).
|
|
128
|
+
*/
|
|
129
|
+
export type ReturningAIHostCallbackHandler = (
|
|
130
|
+
request: ReturningAIHostCallbackRequest,
|
|
131
|
+
) => ReturningAIJsonValue | Promise<ReturningAIJsonValue | undefined> | undefined;
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Public package entry that re-exports the React Native widget SDK surface.
|
|
3
|
+
*
|
|
4
|
+
* Layer: public API
|
|
5
|
+
* Role: Barrel for the host-facing widget component and props types;
|
|
6
|
+
* configuration models (content, descriptor, endpoints, theme, domain key);
|
|
7
|
+
* auth client/types, controller, typed events/host callbacks, and errors/JSON helpers.
|
|
8
|
+
* Does not implement runtime behavior itself.
|
|
9
|
+
* See also: ReturningAIWidget.tsx, packageInfo.ts
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
/** Host-facing widget component and prop/builder types. */
|
|
13
|
+
export {
|
|
14
|
+
ReturningAIWidget,
|
|
15
|
+
type ReturningAIWidgetProps,
|
|
16
|
+
type ReturningAIWidgetLoadingBuilder,
|
|
17
|
+
type ReturningAIWidgetErrorBuilder,
|
|
18
|
+
} from "./ReturningAIWidget";
|
|
19
|
+
/** Published package version and peer runtime pins. */
|
|
20
|
+
export { RETURNING_AI_REACT_NATIVE_PACKAGE } from "./packageInfo";
|
|
21
|
+
/** Aggregated host configuration model. */
|
|
22
|
+
export { ReturningAIWidgetConfiguration } from "./configuration/ReturningAIWidgetConfiguration";
|
|
23
|
+
/** Bundle/page content locator. */
|
|
24
|
+
export { ReturningAIWidgetContent } from "./configuration/ReturningAIWidgetContent";
|
|
25
|
+
/** Custom widget element descriptor. */
|
|
26
|
+
export { ReturningAIWidgetDescriptor } from "./configuration/ReturningAIWidgetDescriptor";
|
|
27
|
+
/** Shell display / auto-height options. */
|
|
28
|
+
export { ReturningAIWidgetDisplayOptions } from "./configuration/ReturningAIWidgetDisplayOptions";
|
|
29
|
+
/** Domain key const + HTML attribute helper. */
|
|
30
|
+
export {
|
|
31
|
+
ReturningAIWidgetDomainKey,
|
|
32
|
+
domainKeyAttributeValue,
|
|
33
|
+
} from "./configuration/ReturningAIWidgetDomainKey";
|
|
34
|
+
/** Named endpoint presets and custom endpoint sets. */
|
|
35
|
+
export { ReturningAIWidgetEndpoints } from "./configuration/ReturningAIWidgetEndpoints";
|
|
36
|
+
/** Optional first-paint color overrides. */
|
|
37
|
+
export { ReturningAIFirstPaintColors } from "./configuration/ReturningAIFirstPaintColors";
|
|
38
|
+
/** Theme preference const object. */
|
|
39
|
+
export { ReturningAIWidgetTheme } from "./configuration/ReturningAIWidgetTheme";
|
|
40
|
+
/** Typed SDK error and error-code union. */
|
|
41
|
+
export {
|
|
42
|
+
ReturningAIWidgetError,
|
|
43
|
+
type ReturningAIWidgetErrorCode,
|
|
44
|
+
} from "./errors/ReturningAIWidgetError";
|
|
45
|
+
/** JSON validation and secret redaction helpers. */
|
|
46
|
+
export {
|
|
47
|
+
validateReturningAIJsonValue,
|
|
48
|
+
redactReturningAISecrets,
|
|
49
|
+
type ReturningAIJsonValue,
|
|
50
|
+
} from "./errors/json";
|
|
51
|
+
/** Host embed-token provider type. */
|
|
52
|
+
export type { ReturningAIEmbedTokenProvider } from "./authentication/types";
|
|
53
|
+
/** Injectable auth fetch transport type. */
|
|
54
|
+
export type { ReturningAIFetch } from "./authentication/ReturningAIAuthenticationClient";
|
|
55
|
+
/** HTTPS embed-token → access-token client. */
|
|
56
|
+
export { ReturningAIAuthenticationClient } from "./authentication/ReturningAIAuthenticationClient";
|
|
57
|
+
/** Imperative reload/retry/theme/logout/session query/invalidate controller. */
|
|
58
|
+
export { ReturningAIWidgetController } from "./controller/ReturningAIWidgetController";
|
|
59
|
+
/** Session phase + redacted snapshot for controller session query. */
|
|
60
|
+
export {
|
|
61
|
+
ReturningAIWidgetSessionPhase,
|
|
62
|
+
ReturningAIWidgetSessionSnapshotDetached,
|
|
63
|
+
type ReturningAIWidgetSessionSnapshot,
|
|
64
|
+
} from "./controller/ReturningAIWidgetSessionSnapshot";
|
|
65
|
+
/** Typed lifecycle events and host-callback request/handler types. */
|
|
66
|
+
export {
|
|
67
|
+
ReturningAIWidgetEvent,
|
|
68
|
+
ReturningAIWidgetLoading,
|
|
69
|
+
ReturningAIWidgetMounted,
|
|
70
|
+
ReturningAIWidgetReady,
|
|
71
|
+
ReturningAIWidgetLoggedOut,
|
|
72
|
+
ReturningAIWidgetSessionExpired,
|
|
73
|
+
ReturningAIWidgetHeightChanged,
|
|
74
|
+
ReturningAIWidgetExternalNavigationRequested,
|
|
75
|
+
ReturningAIWidgetErrorEvent,
|
|
76
|
+
ReturningAIWidgetCustomEvent,
|
|
77
|
+
ReturningAIHostCallbackRequest,
|
|
78
|
+
type ReturningAIHostCallbackHandler,
|
|
79
|
+
} from "./events/ReturningAIWidgetEvent";
|