@chipmobilesdk/rn-ai 0.1.1 → 0.2.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.
Files changed (12) hide show
  1. package/CHANGELOG.md +71 -20
  2. package/README.md +99 -82
  3. package/package.json +36 -43
  4. package/skills/sdk-rn-ai/SKILL.md +1 -2
  5. package/src/config/behaviorConfig.ts +200 -183
  6. package/src/core/aiClient.ts +278 -230
  7. package/src/diagnostics/errors.ts +74 -71
  8. package/src/diagnostics/messageKeys.ts +27 -27
  9. package/src/index.ts +31 -34
  10. package/src/react/hooks.ts +123 -113
  11. package/src/transport/sseClient.ts +143 -106
  12. package/src/transport/timeouts.ts +53 -0
package/CHANGELOG.md CHANGED
@@ -1,20 +1,71 @@
1
- # Changelog — @chipmobilesdk/rn-ai
2
-
3
- ## 0.1.0 — 2026-07-05
4
-
5
- Initial release (feature `005-azure-ai-gateway`).
6
-
7
- - `createAiClient` — config-driven gateway client: cache-first app behavior
8
- config (ETag/TTL), token acquisition via `@chipmobilesdk/rn-auth`
9
- (`resourceKey`), SSE streaming over zero-dependency XHR transport.
10
- - Multimodal chat requests: `text`, `image` (base64), `audio` (wav/mp3).
11
- - Silent endpoint re-route on designated `404`/`410` signals (max 1 retry);
12
- one automatic fresh-token retry on `401`; no automatic retry on `429`.
13
- - `useAiChat` (idle/loading/streaming/done/error/rate-limited + accumulated
14
- text + `retryAt`) and `useAiQuota` hooks.
15
- - Typed `AiError` codes and `ai.*` message keys with English defaults.
16
- - Per-app kill switch honored (`features.aiEnabled`).
17
-
18
- Adoption: additive — no changes required in existing apps. Requires an
19
- `ai-gateway` resource entry in the rn-auth config and a registered app on the
20
- gateway platform.
1
+ # @chipmobilesdk/rn-ai
2
+
3
+ ## 0.2.1
4
+
5
+ ### Patch Changes
6
+
7
+ - Packaging only; no code change. The package no longer declares `engines.node`: a
8
+ React Native package does not run on Node, so the field only produced install
9
+ warnings in apps on another Node version. rn-i18n's command-line tooling does run
10
+ on Node; its README's compatibility table states the version it needs. ([#14](https://github.com/operationd8979/chip-mobile-sdk/pull/14))
11
+
12
+ ## [0.2.0] — 2026-11-01
13
+
14
+ Fixes a chat or quota call that could hang forever, and errors that never
15
+ reached the app. **No code change is required.**
16
+
17
+ ### Fixed
18
+
19
+ - **Every network call has a time limit.** The chat stream had none, and
20
+ neither did the config or quota fetch, so on a stalled mobile connection
21
+ `useAiChat` stayed in `loading`/`streaming` and `useAiQuota` in `loading`
22
+ until the user gave up — and with no cached config, one hung fetch blocked
23
+ every call. New `timeouts: { connectMs, idleMs, configMs, quotaMs }` option
24
+ (defaults 30 s, 30 s, 10 s, 10 s). The idle limit restarts on every chunk.
25
+ - **No error is swallowed.** Every chat path ended in `.catch(() => undefined)`,
26
+ so a transport that threw (an invalid URL from remote config, for example)
27
+ left the UI in `loading` with nothing to show. Such failures now arrive as
28
+ `AiError('internal')`. The remote `recovery` block is type-checked when
29
+ parsed, so a mistyped value can no longer throw inside the XHR callback.
30
+ - **A cancelled or replaced request stays silent.** A token or config failure
31
+ that landed after `cancel()` (or after the next `send()`) still called
32
+ `onError` and flipped that screen to `error`. The client now routes every
33
+ callback through one guard (nothing after cancel, exactly one of
34
+ `onDone`/`onError`), and `useAiChat` and `useAiQuota` drop callbacks from
35
+ older requests.
36
+
37
+ ### Changed
38
+
39
+ - A stalled stream, a timed-out quota fetch and a dropped connection (status 0)
40
+ report `upstream-error` with `recoverable: true`; status 0 was
41
+ `recoverable: false`.
42
+
43
+ ### Added
44
+
45
+ - `AiClientConfig.timeouts` and the `AiTimeouts` type.
46
+
47
+ ## 0.1.1 — 2026-08-01
48
+
49
+ ### Changed
50
+
51
+ - The package now ships its agent skill (`skills/`), which consuming apps
52
+ copy in with `scripts/sync-sdk-skills.mjs`. No code change.
53
+
54
+ ## 0.1.0 — 2026-07-05
55
+
56
+ Initial release (feature `005-azure-ai-gateway`).
57
+
58
+ - `createAiClient` — config-driven gateway client: cache-first app behavior
59
+ config (ETag/TTL), token acquisition via `@chipmobilesdk/rn-auth`
60
+ (`resourceKey`), SSE streaming over zero-dependency XHR transport.
61
+ - Multimodal chat requests: `text`, `image` (base64), `audio` (wav/mp3).
62
+ - Silent endpoint re-route on designated `404`/`410` signals (max 1 retry);
63
+ one automatic fresh-token retry on `401`; no automatic retry on `429`.
64
+ - `useAiChat` (idle/loading/streaming/done/error/rate-limited + accumulated
65
+ text + `retryAt`) and `useAiQuota` hooks.
66
+ - Typed `AiError` codes and `ai.*` message keys with English defaults.
67
+ - Per-app kill switch honored (`features.aiEnabled`).
68
+
69
+ Adoption: additive — no changes required in existing apps. Requires an
70
+ `ai-gateway` resource entry in the rn-auth config and a registered app on the
71
+ gateway platform.
package/README.md CHANGED
@@ -1,91 +1,108 @@
1
- # @chipmobilesdk/rn-ai
2
-
3
- AI gateway client for ChipMobileSdk-family React Native apps. Streams
4
- multimodal (text + image + audio in, text out) AI responses through the
5
- platform gateway with per-user rate limiting — apps never talk to Azure
1
+ # @chipmobilesdk/rn-ai
2
+
3
+ AI gateway client for ChipMobileSdk-family React Native apps. Streams
4
+ multimodal (text + image + audio in, text out) AI responses through the
5
+ platform gateway with per-user rate limiting — apps never talk to Azure
6
6
  OpenAI directly and hold no AI credentials.
7
7
 
8
8
  > **License:** `UNLICENSED`. Published publicly for use by the owner's
9
9
  > applications; no open-source license is granted.
10
10
 
11
- - **Version**: `0.1.0`
11
+ - **Version**: see [CHANGELOG](CHANGELOG.md)
12
12
  - **Entrypoint**: `@chipmobilesdk/rn-ai`
13
13
  - **Native code**: none
14
-
15
- - Contract: [rn-ai-public-api](../../specs/005-azure-ai-gateway/contracts/rn-ai-public-api.md)
16
- - Gateway API: [gateway-api](../../specs/005-azure-ai-gateway/contracts/gateway-api.md)
17
- - Behavior config: [app-behavior-config](../../specs/005-azure-ai-gateway/contracts/app-behavior-config.md)
18
-
19
- ## Install
20
-
21
- ```bash
22
- npm install @chipmobilesdk/rn-ai @chipmobilesdk/rn-auth
23
- ```
24
-
25
- Peers: `react >=19`, `react-native >=0.85`, `@chipmobilesdk/rn-auth >=0.2.0`.
26
- **Zero runtime dependencies**; streaming uses React Native's standard
27
- `XMLHttpRequest` (no native code, Hermes-compatible, iOS + Android).
28
-
29
- ## Setup
30
-
31
- 1. Add the gateway resource to your rn-auth config:
32
-
33
- ```ts
34
- resources: [
35
- { key: 'ai-gateway', scopes: ['api://aiapp-gateway/AI.Access'] },
36
- ]
37
- ```
38
-
39
- 2. Create the client (one per app):
40
-
41
- ```ts
42
- import { createAiClient } from '@chipmobilesdk/rn-ai';
43
- import { auth } from './auth/setup';
44
-
45
- export const aiClient = createAiClient({
46
- appId: 'scan-food',
47
- configUrl: 'https://<config-host>/appconfig/config/scan-food.json',
48
- resourceKey: 'ai-gateway',
49
- auth,
50
- // storage: inject a persistent AiConfigCache for offline launches
51
- });
52
- ```
53
-
54
- 3. Use the hooks:
55
-
14
+
15
+ - Contract: [rn-ai-public-api](../../specs/005-azure-ai-gateway/contracts/rn-ai-public-api.md)
16
+ - Gateway API: [gateway-api](../../specs/005-azure-ai-gateway/contracts/gateway-api.md)
17
+ - Behavior config: [app-behavior-config](../../specs/005-azure-ai-gateway/contracts/app-behavior-config.md)
18
+
19
+ ## Install
20
+
21
+ ```bash
22
+ npm install @chipmobilesdk/rn-ai @chipmobilesdk/rn-auth
23
+ ```
24
+
25
+ Peers: `react >=19`, `react-native >=0.85`, `@chipmobilesdk/rn-auth >=0.2.0`.
26
+ **Zero runtime dependencies**; streaming uses React Native's standard
27
+ `XMLHttpRequest` (no native code, Hermes-compatible, iOS + Android).
28
+
29
+ ## Setup
30
+
31
+ 1. Add the gateway resource to your rn-auth config:
32
+
33
+ ```ts
34
+ resources: [
35
+ { key: 'ai-gateway', scopes: ['api://aiapp-gateway/AI.Access'] },
36
+ ]
37
+ ```
38
+
39
+ 2. Create the client (one per app):
40
+
41
+ ```ts
42
+ import { createAiClient } from '@chipmobilesdk/rn-ai';
43
+ import { auth } from './auth/setup';
44
+
45
+ export const aiClient = createAiClient({
46
+ appId: 'scan-food',
47
+ configUrl: 'https://<config-host>/appconfig/config/scan-food.json',
48
+ resourceKey: 'ai-gateway',
49
+ auth,
50
+ // storage: inject a persistent AiConfigCache for offline launches
51
+ });
52
+ ```
53
+
54
+ 3. Use the hooks:
55
+
56
56
  ```tsx
57
57
  import { useAiChat, useAiQuota } from '@chipmobilesdk/rn-ai';
58
58
  import { aiClient } from './ai/setup';
59
59
 
60
60
  const { send, cancel, status, text, error, retryAt } = useAiChat(aiClient);
61
61
  const { quota } = useAiQuota(aiClient);
62
-
63
- send({
64
- messages: [{
65
- role: 'user',
66
- content: [
67
- { type: 'text', text: 'What dish is this? Estimate calories.' },
68
- { type: 'image', mimeType: 'image/jpeg', dataBase64: photoBase64 },
69
- ],
70
- }],
71
- });
72
- ```
73
-
62
+
63
+ send({
64
+ messages: [{
65
+ role: 'user',
66
+ content: [
67
+ { type: 'text', text: 'What dish is this? Estimate calories.' },
68
+ { type: 'image', mimeType: 'image/jpeg', dataBase64: photoBase64 },
69
+ ],
70
+ }],
71
+ });
72
+ ```
73
+
74
74
  ## Runtime behavior
75
75
 
76
76
  - **Config-driven endpoint**: resolved lazily on the first quota or chat
77
77
  request. A fresh cache entry is used immediately; a stale entry is used
78
78
  immediately and revalidated in the background with its ETag. With no cache,
79
- the first operation waits for the config request. Designated `404`/`410`
79
+ the first operation waits for the config request, for at most `configMs`.
80
+ Designated `404`/`410`
80
81
  responses invalidate config and retry against the refreshed endpoint.
81
82
  - **Auth**: acquires tokens via rn-auth (`requestAccessToken('ai-gateway')`);
82
83
  on `401`, reacquires a token and retries once.
83
- - **Rate limits**: `429` surfaces as `status: 'rate-limited'` with `retryAt`;
84
- the SDK never hammers and never enforces limits locally (display only).
85
- - **Typed errors** (`AiError.code`): `auth-invalid`, `not-entitled`,
86
- `user-blocked`, `app-unknown`, `rate-limited`, `upstream-busy`,
87
- `payload-too-large`, `modality-not-allowed`, `config-unavailable`,
88
- `upstream-error`, `internal`.
84
+ - **Timeouts**: every network call is bounded. Override any of them with
85
+ `createAiClient({ timeouts: { ... } })`:
86
+
87
+ | | Default | Fails with |
88
+ |---|---|---|
89
+ | `connectMs` — chat request sent → headers | 30 s | `upstream-error`, `recoverable: true` |
90
+ | `idleMs` — silence between two stream chunks | 30 s | `upstream-error`, `recoverable: true` |
91
+ | `configMs` — behavior-config fetch | 10 s | stale cache if any, else `config-unavailable` |
92
+ | `quotaMs` — quota fetch | 10 s | `upstream-error`, `recoverable: true` |
93
+
94
+ The gateway sends headers only after the model answers, so `connectMs` also
95
+ covers time to first token. A dropped connection (HTTP status 0) is likewise
96
+ `upstream-error` with `recoverable: true`.
97
+ - **Callbacks**: each `chat()` delivers exactly one of `onDone` / `onError`,
98
+ and nothing after `cancel()`. An unexpected exception anywhere on the way
99
+ (including in your own `onDelta`) is reported as `internal`, never dropped.
100
+ - **Rate limits**: `429` surfaces as `status: 'rate-limited'` with `retryAt`;
101
+ the SDK never hammers and never enforces limits locally (display only).
102
+ - **Typed errors** (`AiError.code`): `auth-invalid`, `not-entitled`,
103
+ `user-blocked`, `app-unknown`, `rate-limited`, `upstream-busy`,
104
+ `payload-too-large`, `modality-not-allowed`, `config-unavailable`,
105
+ `upstream-error`, `internal`.
89
106
  - **Copy keys**: `ai.*` defaults in `aiMessages` — map through your i18n.
90
107
 
91
108
  ## Public API
@@ -102,18 +119,18 @@ Everything is exported from `@chipmobilesdk/rn-ai`; internal `config/`,
102
119
  `UseAiQuotaResult`
103
120
  - Diagnostics and copy: `AiError`, `AiErrorCode`, `isAiError`, `aiMessages`,
104
121
  `aiMessage`, `AiMessageKey`
105
-
106
- ## App responsibilities
107
-
108
- - **AI disclosure (store policy)**: user text/images/audio are processed by
109
- the platform's AI service. Update your privacy policy, Apple App Privacy,
110
- and Google Play Data Safety before shipping, and disclose AI processing
111
- in-app (POL-005/006 in the feature spec).
112
- - Camera/microphone permissions for capture UIs are yours; the SDK only
113
- accepts already-captured data and adds no permissions.
114
- - Respect `payload-too-large` (default cap 10 MB/request) by resizing images
115
- and bounding audio length.
116
-
122
+
123
+ ## App responsibilities
124
+
125
+ - **AI disclosure (store policy)**: user text/images/audio are processed by
126
+ the platform's AI service. Update your privacy policy, Apple App Privacy,
127
+ and Google Play Data Safety before shipping, and disclose AI processing
128
+ in-app (POL-005/006 in the feature spec).
129
+ - Camera/microphone permissions for capture UIs are yours; the SDK only
130
+ accepts already-captured data and adds no permissions.
131
+ - Respect `payload-too-large` (default cap 10 MB/request) by resizing images
132
+ and bounding audio length.
133
+
117
134
  ## Compatibility
118
135
 
119
136
  React ≥19 · React Native ≥0.85 (Hermes) · iOS + Android · Node ≥22.11 for
@@ -128,7 +145,7 @@ into `ScreenKey`, `Sidebar`, and `ActiveScreen` before it is reachable in-app.
128
145
  Run from the repository root:
129
146
 
130
147
  ```bash
131
- npm run typecheck:ai
132
- npm run pack:ai
133
- npm run validate:ai
148
+ npm run typecheck --workspace @chipmobilesdk/rn-ai
149
+ npm run pack:check --workspace @chipmobilesdk/rn-ai
150
+ npm run validate
134
151
  ```
package/package.json CHANGED
@@ -1,43 +1,36 @@
1
- {
2
- "name": "@chipmobilesdk/rn-ai",
3
- "version": "0.1.1",
4
- "private": false,
5
- "license": "UNLICENSED",
6
- "main": "src/index.ts",
7
- "types": "src/index.ts",
8
- "exports": {
9
- ".": {
10
- "types": "./src/index.ts",
11
- "react-native": "./src/index.ts",
12
- "default": "./src/index.ts"
13
- }
14
- },
15
- "files": [
16
- "src/index.ts",
17
- "src/config",
18
- "src/transport",
19
- "src/core",
20
- "src/react",
21
- "src/diagnostics",
22
- "skills",
23
- "README.md",
24
- "CHANGELOG.md"
25
- ],
26
- "sideEffects": false,
27
- "scripts": {
28
- "typecheck": "tsc -p tsconfig.json --noEmit",
29
- "pack:dry-run": "npm pack --dry-run"
30
- },
31
- "peerDependencies": {
32
- "@chipmobilesdk/rn-auth": ">=0.2.0",
33
- "react": ">=19",
34
- "react-native": ">=0.85"
35
- },
36
- "engines": {
37
- "node": ">=22.11.0"
38
- },
39
- "publishConfig": {
40
- "access": "public",
41
- "registry": "https://registry.npmjs.org/"
42
- }
43
- }
1
+ {
2
+ "name": "@chipmobilesdk/rn-ai",
3
+ "version": "0.2.1",
4
+ "private": false,
5
+ "license": "UNLICENSED",
6
+ "main": "src/index.ts",
7
+ "types": "src/index.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./src/index.ts",
11
+ "react-native": "./src/index.ts",
12
+ "default": "./src/index.ts"
13
+ }
14
+ },
15
+ "files": [
16
+ "src",
17
+ "!src/**/__tests__",
18
+ "skills",
19
+ "README.md",
20
+ "CHANGELOG.md"
21
+ ],
22
+ "sideEffects": false,
23
+ "scripts": {
24
+ "typecheck": "tsc -p tsconfig.json --noEmit",
25
+ "pack:check": "npm pack --dry-run"
26
+ },
27
+ "peerDependencies": {
28
+ "@chipmobilesdk/rn-auth": ">=0.2.0",
29
+ "react": ">=19",
30
+ "react-native": ">=0.85"
31
+ },
32
+ "publishConfig": {
33
+ "access": "public",
34
+ "registry": "https://registry.npmjs.org/"
35
+ }
36
+ }
package/skills/sdk-rn-ai/SKILL.md CHANGED
@@ -3,7 +3,6 @@ name: sdk-rn-ai
3
3
  description: "AI chat and quota via @chipmobilesdk/rn-ai: createAiClient, useAiChat, useAiQuota, streaming status, AI error codes. Use when adding an AI chat feature, showing quota, or handling AI request failures and cancellation."
4
4
  metadata:
5
5
  package: "@chipmobilesdk/rn-ai"
6
- packageVersion: "0.1.0"
7
6
  user-invocable: true
8
7
  disable-model-invocation: false
9
8
  ---
@@ -32,7 +31,7 @@ read it before assuming a behaviour is built in.
32
31
  screen unmounts, otherwise the response resolves against a dead component. Verify
33
32
  teardown on every screen that uses it.
34
33
 
35
- ## Public API (v0.1.0)
34
+ ## Public API
36
35
 
37
36
  Runtime:
38
37