@chipmobilesdk/rn-ai 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,118 @@
 # @chipmobilesdk/rn-ai
 
+## 0.4.0
+
+### Minor Changes
+
+- A 401 retry now gets a token the provider had to fetch again. `TokenProvider.requestAccessToken` takes `{ forceRefresh }`, which rn-auth implements by dropping the cached token for that resource, so the retry no longer re-sends the token the gateway had just refused — a cached token is still unexpired by the device's clock when the server rejects it. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  Failures an app can tell apart. `network` is a request that never arrived (no connection, a timeout, a dropped stream) and is retryable; `session-expired` is a session the user must renew. `AiError.cause` carries the code from the layer underneath — the gateway's own code, or rn-auth's — so a screen can explain *why*, and `retryAfterSeconds` is read from the `Retry-After` header when the body omits it. Both new codes have user copy, and the gateway's full code list is mapped rather than guessed from the status.
+
+  The remote behavior config is checked before it is trusted. `configUrl` and the document's `api.baseUrl` must be https (localhost excepted), the document must name the app it is for, its `schemaVersion` must be one this release understands, and `allowedHosts` pins where the client may send its bearer token. A broken TTL no longer means a revalidation on every request, and a retry count is bounded. A not-modified answer against a cache that is no longer there asks again without the ETag instead of reporting the 304 as a failure.
+
+  `configCacheFromKeyValue(port)` makes a durable config cache out of rn-core's `KeyValuePort`, so a second launch uses the last-good document instead of waiting for the network.
+
+  One quota figure: a chat's `done` event and `getQuota()` both record it on the client (`lastQuota()`), so `useAiQuota` and `useAiChat` cannot disagree, and a quota response that does not match the contract is refused rather than displayed. `getQuota()` recovers like a chat: a designated 404/410 reloads the configuration and retries, and a 401 retries once.
+
+  Streamed text reaches the screen on an interval (50 ms by default, `useAiChat(client, { flushIntervalMs })`) rather than once per token, and whatever arrived is flushed with the terminal state, so a half-answer stays on screen when a stream fails. A stream framed with CRLF is parsed incrementally, as the SSE specification allows. The transport seam is a published `StreamTransport` port instead of the internal reader's signature.
+
+- The gateway↔client contract has one definition. `GatewayErrorCode`, `GATEWAY_ERROR_STATUS`, `QUOTA_HEADERS`, `GatewayErrorBody`, `GatewayStreamEvent`, `GatewayQuota`, `GatewayUsage` and `SSE_DONE_SENTINEL` are exported from this package, and the gateway service imports the same types, so an error code, a header name or a stream event added on one side does not compile until the other handles it. The three codes the gateway could already answer with and the client had never heard of — `BAD_REQUEST`, `ENDPOINT_RETIRED`, `INTERNAL` — now map to a typed error instead of a guess from the HTTP status. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+### Patch Changes
+
+- The gateway service (not published to npm) now shares one credential across the process and refuses unauthenticated requests before reading storage. No client-facing change; the entry is here so the release notes record the service work that went with this version. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+- Internal: no module in these packages is over 500 lines any more. The camera controller's session I/O moved to `sessionRuntime` and its contract to `contract.ts`; the Play adapter's shape translation to `iapShapes`; the purchase flow's failure mapping and its receipt-validation hook to modules of their own; the AI client's quota request to `quotaRequest`; the in-memory adapter's attachments and the fake ads engine's clock likewise. Behaviour is unchanged — the splits are by responsibility, and every package's suite passes as it stood. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  The repository also measures what it promised: `npm run perf` prints the median of nine runs of the deterministic hot paths against written budgets (recurrence expansion, theme construction, translation lookup, chart geometry, filter compilation), the demo app has a Performance screen reporting startup phases, time to interactive and the same benchmarks on Hermes, and `npm run check:file-size` keeps the limit from drifting. The budgets and the measured figures are recorded in `docs/standards.md` §VI.
+
+## 0.3.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Timers, retries and bounds now come from `@chipmobilesdk/rn-core`, and the drift
+  between the copies is fixed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a retry policy out of bounds throws `retry_out_of_bounds`, as documented,
+    instead of `timeout_out_of_bounds`; a placement's `minRequestIntervalMs` out of
+    bounds throws `invalid_config`.
+  - rn-payment: backoff validates `initialDelayMs` (100 ms to 60 s, not above
+    `maxDelayMs`) and `factor` (1 to 10); `factor: 0` used to retry at once, forever.
+    Every timeout, backoff or interval out of bounds now throws the new
+    `PAYMENT_INVALID_CONFIG` instead of `PAYMENT_INVALID_CATALOG`, which is about
+    products.
+  - rn-ai: concurrent calls share one behavior-config request, so a cold start makes
+    one instead of one per call. A silent retry after a config reload waits
+    `recovery.retryBackoffMs`, which was parsed but never applied.
+
+- Hooks read through `useSyncExternalStore` (rn-core's `useExternalStore`) and
+  re-render only when what they return changes. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: `useProfile` and `useAccessTier` no longer re-render for a status change,
+    and the provider's context no longer changes on every transition. New
+    `useAuthSelector`. `auth.getState()` returns the same frozen object until the state
+    changes, instead of a copy per call.
+  - rn-payment: `useEntitlement` re-renders only when its own entitlement changes; the
+    engine keeps unchanged entitlement objects across syncs and does not notify for a
+    sync that changed nothing.
+  - rn-ads: `usePlacementState` and `useAdsStatus` read tear-free; `useAdsEvents` keeps
+    one subscription when given an inline listener.
+  - rn-i18n: `useTranslation` returns the same `t` until the locale changes, and
+    `useLocale`'s `setLocale` is stable.
+  - rn-ai: new `useAiBehaviorState`, with `client.subscribe` and a stable
+    `client.getBehaviorState()`.
+
+- Every package's own copy is an rn-core message catalog that an app can translate. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-i18n: new `runtimeEntriesFromCatalog(catalog)` registers any SDK catalog in one
+    line, converting `{name}` variables to `{{name}}`.
+  - rn-ai: new `messageKeyForError(error)` gives the copy for every error code, and
+    `aiMessageSet`. The input placeholder default is neutral ("Type a message…"), and
+    two keys were added for errors that had none (`ai.error.signIn`, `ai.error.generic`).
+  - rn-auth: new `authMessages`, the catalog split into user and developer copy.
+  - rn-payment: new `paymentMessages`.
+  - rn-chart: summaries, announcements, adjustable-action labels, built-in state text
+    and legend hints come from `chartStrings`; pass `strings` to translate them. The
+    `accessibility.summaryFormatter` prop, declared before, now replaces the summary.
+
+### Patch Changes
+
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -12,9 +12,12 @@ OpenAI directly and hold no AI credentials.
 - **Entrypoint**: `@chipmobilesdk/rn-ai`
 - **Native code**: none
 
-- Contract: [rn-ai-public-api](../../specs/005-azure-ai-gateway/contracts/rn-ai-public-api.md)
-- Gateway API: [gateway-api](../../specs/005-azure-ai-gateway/contracts/gateway-api.md)
-- Behavior config: [app-behavior-config](../../specs/005-azure-ai-gateway/contracts/app-behavior-config.md)
+- **Gateway contract**: the error codes, quota headers and stream events this
+  client and the gateway share are exported from this package
+  (`GatewayErrorCode`, `QUOTA_HEADERS`, `GatewayStreamEvent`), and the gateway
+  imports the same definitions — see `## Public API`. The feature's original
+  contract documents live in the repository under
+  `specs/005-azure-ai-gateway/legacy/contracts/` and are not shipped here.
 
 ## Install
 
@@ -39,7 +42,10 @@ resources: [
 2. Create the client (one per app):
 
 ```ts
-import { createAiClient } from '@chipmobilesdk/rn-ai';
+import { configCacheFromKeyValue, createAiClient } from '@chipmobilesdk/rn-ai';
+import { openDurable } from '@chipmobilesdk/rn-core';
+import { createMMKV } from 'react-native-mmkv';
+
 import { auth } from './auth/setup';
 
 export const aiClient = createAiClient({
@@ -47,10 +53,21 @@ export const aiClient = createAiClient({
   configUrl: 'https://<config-host>/appconfig/config/scan-food.json',
   resourceKey: 'ai-gateway',
   auth,
-  // storage: inject a persistent AiConfigCache for offline launches
+  // Cache the behavior config where it survives a restart, so the next launch
+  // does not wait for the network. Any `AiConfigCache` will do; this one is
+  // rn-core's key-value port over MMKV.
+  storage: configCacheFromKeyValue(openDurable(() => createMMKV({ id: 'app.ai' }))),
+  // Optional: pin the hosts the remote config may point the client at.
+  allowedHosts: ['gw.example.com'],
 });
 ```
 
+The config document decides where this client sends its bearer token, so both
+`configUrl` and the document's `api.baseUrl` must be `https` (plain `http` is
+accepted only for `localhost`), the document must name this `appId`, and its
+`schemaVersion` must be one this release understands. Anything else is a
+`config-unavailable` error rather than a request to an unvetted host.
+
 3. Use the hooks:
 
 ```tsx
@@ -77,32 +94,52 @@ send({
   request. A fresh cache entry is used immediately; a stale entry is used
   immediately and revalidated in the background with its ETag. With no cache,
   the first operation waits for the config request, for at most `configMs`.
-  Designated `404`/`410`
-  responses invalidate config and retry against the refreshed endpoint.
-- **Auth**: acquires tokens via rn-auth (`requestAccessToken('ai-gateway')`);
-  on `401`, reacquires a token and retries once.
+  Concurrent calls share one config request, so a cold start that asks for a
+  chat and the quota together fetches the config once. Designated `404`/`410`
+  responses invalidate config and retry against the refreshed endpoint, after
+  waiting `recovery.retryBackoffMs[n]` (the last step repeats, each capped at
+  30 s), at most `recovery.maxSilentRetries` times. A chat cancelled during the
+  wait is not retried.
+- **Auth**: acquires tokens via rn-auth
+  (`requestAccessToken('ai-gateway')`); on `401` it asks for a token the
+  provider had to fetch again (`{ forceRefresh: true }`) and retries once. The
+  cached token is unexpired by the device's clock after a 401, so without that
+  the retry would re-send the token the gateway just refused.
+- **Quota**: one figure, wherever it came from. A chat's `done` event and
+  `getQuota()` both record it on the client, so `useAiQuota` and `useAiChat`
+  never disagree, and a quota display does not go stale when a chat finishes.
+  `getQuota()` recovers like a chat does: a designated `404`/`410` reloads the
+  configuration and retries, and a `401` retries once with a fresh token.
 - **Timeouts**: every network call is bounded. Override any of them with
   `createAiClient({ timeouts: { ... } })`:
 
   | | Default | Fails with |
   |---|---|---|
-  | `connectMs` — chat request sent → headers | 30 s | `upstream-error`, `recoverable: true` |
-  | `idleMs` — silence between two stream chunks | 30 s | `upstream-error`, `recoverable: true` |
+  | `connectMs` — chat request sent → headers | 30 s | `network`, `retryable: true` |
+  | `idleMs` — silence between two stream chunks | 30 s | `network`, `retryable: true` |
   | `configMs` — behavior-config fetch | 10 s | stale cache if any, else `config-unavailable` |
-  | `quotaMs` — quota fetch | 10 s | `upstream-error`, `recoverable: true` |
+  | `quotaMs` — quota fetch | 10 s | `network`, `retryable: true` |
 
   The gateway sends headers only after the model answers, so `connectMs` also
   covers time to first token. A dropped connection (HTTP status 0) is likewise
-  `upstream-error` with `recoverable: true`.
+  `network` with `retryable: true`: the request never reached the service, which
+  is a different thing to tell the user than a service that failed.
 - **Callbacks**: each `chat()` delivers exactly one of `onDone` / `onError`,
   and nothing after `cancel()`. An unexpected exception anywhere on the way
   (including in your own `onDelta`) is reported as `internal`, never dropped.
 - **Rate limits**: `429` surfaces as `status: 'rate-limited'` with `retryAt`;
   the SDK never hammers and never enforces limits locally (display only).
-- **Typed errors** (`AiError.code`): `auth-invalid`, `not-entitled`,
-  `user-blocked`, `app-unknown`, `rate-limited`, `upstream-busy`,
-  `payload-too-large`, `modality-not-allowed`, `config-unavailable`,
-  `upstream-error`, `internal`.
+- **Streamed text** reaches the screen on an interval (50 ms by default), not
+  once per token: `useAiChat(client, { flushIntervalMs })` tunes it, and `0`
+  renders per token. Whatever had arrived is always flushed with the terminal
+  state, so a half-answer stays on screen when a stream fails.
+- **Typed errors** (`AiError.code`): `auth-invalid`, `session-expired`,
+  `not-entitled`, `user-blocked`, `app-unknown`, `rate-limited`,
+  `upstream-busy`, `payload-too-large`, `modality-not-allowed`,
+  `config-unavailable`, `network`, `upstream-error`, `internal`.
+  `AiError.cause` carries the code the layer underneath used — the gateway's own
+  code, or rn-auth's — so a screen can say *why*. `retryAfterSeconds` is read
+  from the body, or from the `Retry-After` header when the body omits it.
 - **Copy keys**: `ai.*` defaults in `aiMessages` — map through your i18n.
 
 ## Public API
@@ -110,15 +147,28 @@ send({
 Everything is exported from `@chipmobilesdk/rn-ai`; internal `config/`,
 `transport/`, `core/`, `react/`, and `diagnostics/` paths are not public.
 
-- Client: `createAiClient`, `AiClient`, `AiClientConfig`, `TokenProvider`
+- Client: `createAiClient`, `AiClient`, `AiClientConfig`, `TokenProvider`,
+  `AccessTokenRequestOptions`
 - Chat: `ChatRequest`, `ChatMessage`, `ContentPart`, `ChatStreamHandlers`,
   `ChatHandle`, `Usage`
 - Behavior and cache: `AppBehaviorConfig`, `AiBehaviorState`, `BehaviorState`,
-  `AiConfigCache`, `QuotaSnapshot`
-- React: `useAiChat`, `useAiQuota`, `AiChatStatus`, `UseAiChatResult`,
-  `UseAiQuotaResult`
+  `AiConfigCache`, `configCacheFromKeyValue`, `SUPPORTED_SCHEMA_VERSION`,
+  `QuotaSnapshot`
+- Transport: `StreamTransport` and its `SseRequest` / `SseHandlers` /
+  `SseHandle` / `SseResponseInfo` types. `createAiClient({ transport })` takes
+  any implementation; the default is an XHR reader.
+- The gateway contract, shared with the service so both sides cannot drift:
+  `GatewayErrorCode`, `GatewayErrorBody`, `GatewayQuota`, `GatewayUsage`,
+  `GatewayStreamEvent`, `GATEWAY_ERROR_STATUS`, `QUOTA_HEADERS`,
+  `SSE_DONE_SENTINEL`
+- React: `useAiChat`, `useAiQuota`, `useAiBehaviorState`, `AiChatStatus`,
+  `UseAiChatOptions`, `UseAiChatResult`, `UseAiQuotaResult`. `useAiBehaviorState(client)` re-renders when
+  the config loads or the `aiEnabled` kill switch flips; `client.subscribe` and
+  `client.getBehaviorState()` give the same outside React.
 - Diagnostics and copy: `AiError`, `AiErrorCode`, `isAiError`, `aiMessages`,
-  `aiMessage`, `AiMessageKey`
+  `aiMessage`, `AiMessageKey`, `aiMessageSet` (the same catalog as an rn-core message
+  set), `messageKeyForError(error)` (the copy to show for any error code). Register the
+  copy with rn-i18n in one line: `runtimeEntriesFromCatalog(aiMessageSet.user)`.
 
 ## App responsibilities
 
@@ -136,10 +186,6 @@ Everything is exported from `@chipmobilesdk/rn-ai`; internal `config/`,
 React ≥19 · React Native ≥0.85 (Hermes) · iOS + Android · Node ≥22.11 for
 tooling.
 
-The repository contains `src/screens/AiDemoScreen.tsx` and its component test.
-The current demo sidebar does not expose that screen yet, so it must be wired
-into `ScreenKey`, `Sidebar`, and `ActiveScreen` before it is reachable in-app.
-
 ## Validation
 
 Run from the repository root:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-ai",
-	"version": "0.2.1",
+	"version": "0.4.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -21,9 +21,12 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"@chipmobilesdk/rn-auth": ">=0.2.0",
 		"react": ">=19",

package/skills/sdk-rn-ai/SKILL.md

@@ -31,18 +31,49 @@ read it before assuming a behaviour is built in.
 screen unmounts, otherwise the response resolves against a dead component. Verify
 teardown on every screen that uses it.
 
+## Cache the config, or every launch waits for the network
+
+`createAiClient({ storage })` takes an `AiConfigCache`. Without one the behavior config
+lives in memory only, so each cold start blocks the first chat on a network fetch.
+`configCacheFromKeyValue(port)` adapts rn-core's `KeyValuePort` (MMKV through
+`openDurable`), which is how the demo app wires it.
+
+## What the config document is allowed to say
+
+`configUrl` and the document's `api.baseUrl` must be https (localhost excepted), the
+document must name the same `appId`, and its `schemaVersion` must be one the installed
+release supports. `allowedHosts` pins the hosts the document may point at. A document
+that breaks any of these is a `config-unavailable` error, not a request sent anyway:
+this is where the app's bearer token would go.
+
+## Errors carry a reason
+
+`AiError.code` is what happened; `AiError.cause` is the code underneath (the gateway's,
+or rn-auth's). `network` means the request never arrived and a retry may work;
+`session-expired` means sign-in is needed; `not-entitled` means premium. Use
+`messageKeyForError(error)` for the copy — one key per code, nothing to map by hand.
+
 ## Public API
 
 Runtime:
 
-- `createAiClient(...)` — transport-level client
-- `useAiChat(...)` → `UseAiChatResult`, with `AiChatStatus` for state
-- `useAiQuota(...)` → `UseAiQuotaResult`
+- `createAiClient(...)` — the client: `chat`, `getQuota`, `lastQuota`, `reloadConfig`,
+  `getBehaviorState`, `subscribe`
+- `useAiChat(client, { flushIntervalMs })` → `UseAiChatResult` (`send`, `cancel`,
+  `status`, `text`, `error`, `retryAt`, `quota`), with `AiChatStatus` for state
+- `useAiQuota(...)` → `UseAiQuotaResult`; `useAiBehaviorState(...)` for the kill switch
+- `configCacheFromKeyValue(port)`, `SUPPORTED_SCHEMA_VERSION`
 - `AiError`, `isAiError` — narrow before reading `AiErrorCode`
-- `aiMessages`, `aiMessage` — user-facing strings keyed by `AiMessageKey`
+- `aiMessages`, `aiMessage`, `aiMessageSet`, `messageKeyForError`
+- `GATEWAY_ERROR_STATUS`, `QUOTA_HEADERS`, `SSE_DONE_SENTINEL` — the gateway contract
 
 Use `aiMessage` for anything shown to the user. Never render `AiError.message` directly.
 
+## Streamed text is batched
+
+`useAiChat` flushes accumulated deltas every 50 ms rather than rendering per token; pass
+`flushIntervalMs: 0` for per-token rendering. Do not add your own buffering on top.
+
 ## Where the detail lives
 
 Read one section of `node_modules/@chipmobilesdk/rn-ai/README.md`: