@skyporch/daykeeper-react-native 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,126 @@
 # Changelog
 
+## 0.2.0 — 2026-09-21
+
+This version introduces the native transport break described below. The
+pre-release candidate was renumbered from `0.1.1` to `0.2.0`; `0.1.1` was never
+released, so every change below is relative to the published `0.1.0`.
+
+### Security
+
+`0.1.0` is no longer supported. Upgrade to `0.2.0`.
+
+- `0.1.0` set no redirect policy. On React Native's default XHR-backed Fetch a
+  redirected request, including its bearer token, could be followed to another
+  endpoint. `0.2.0` sends `redirect: "error"`, `credentials: "omit"` and
+  `cache: "no-store"` on every request, and the native export refuses to run
+  without an explicitly supplied compliant Fetch transport.
+- `0.1.0` replayed every request once after an HTTP 401, including writes, so
+  a message or conversation could be created twice. `0.2.0` never replays a
+  write; only reads refresh credentials and retry once.
+
+### Breaking
+
+- **Native transport must be configured explicitly.** The native export no
+  longer falls back to React Native's XHR-based Fetch. Callers must supply a
+  `fetch` implementation that rejects redirects and omits ambient cookies; on
+  the validated Expo 57 runtime, `fetch` from `expo/fetch`. A client
+  constructed without one now fails before credentials are requested.
+- **Server error codes must look like codes.** `0.1.0` copied any string
+  `error` value into `DaykeeperReactNativeApiError.code`. `0.2.0` passes a value
+  through unchanged only when it matches `^[a-z][a-z0-9_]{2,63}$`, including
+  codes newer than the installed SDK; anything else, such as a free-form English
+  sentence, becomes `daykeeper_request_failed`. The vocabulary stays open, so
+  handle unknown codes safely. (An unreleased candidate briefly used a 23-entry
+  allowlist; it never shipped.)
+- **Writes are never replayed after HTTP 401.** A write rejected with 401 now
+  throws `DaykeeperReactNativeApiError` with status 401 and `retryable: false`.
+  The token provider receives `forceRefresh: true` only for a read. Refresh the
+  session and let the customer send again.
+- **Token provider failures are wrapped.** An error thrown by `getAccessToken`
+  now surfaces as `DaykeeperReactNativeTransportError` with code
+  `TOKEN_PROVIDER_ERROR` and `retryable: false`, not as the original error.
+  Apps that inspected their own provider errors must track that state
+  themselves.
+- **Write errors are never retryable, and uncertain outcomes are explicit.**
+  Every write error now has `retryable: false` (`0.1.0` marked 408, 429 and 5xx
+  retryable). A write that failed after dispatch, or returned 408 or 5xx, also
+  has `outcomeUnknown: true`. Reconcile server state before a deliberate new
+  write.
+
+This package consumes the **customer** contract only, which remains 0.1.0. The
+newly required `Idempotency-Key` header on flow mutations, and the `200`
+returned alongside `201` for a replayed mutation, are **management** contract
+0.2.0 changes and do not apply here. The breaking changes above are this
+package's own. See [`COMPATIBILITY.md`](COMPATIBILITY.md).
+
+### Changes
+
+- Preserve the API-only inbox contract: widget identity and anonymous-thread
+  claim return `409 widget_unavailable` before contacting the provider.
+- Preserve every server error code whose shape is a code. Codes matching
+  `^[a-z][a-z0-9_]{2,63}$` pass through unchanged; only values that fail that
+  shape collapse to `daykeeper_request_failed`. The previous 23-entry
+  allowlist collapsed live gateway codes the consuming app switches on, such
+  as `support_gateway_request_failed`, `widget_token_required`,
+  `invalid_tenant` and `conversation_not_found`. Message projection is
+  unchanged: no raw body text enters the message, stack or serialization.
+- Decide on the HTTP status before parsing an error body. An HTML error page
+  from a proxy or CDN no longer discards the status as `INVALID_RESPONSE`, and
+  a non-JSON 401 still authorizes the single credential refresh on reads.
+- Accept `http://[::1]` and other bracketed IPv6 loopback base URLs for local
+  development. The loopback check compared against an unbracketed `::1` and
+  never matched.
+- Expose `DaykeeperReactNativeApiError.nextAction`, projected through a closed
+  allowlist of `review_usage`, `review_setup` and `refresh_conversation` and
+  included in `toJSON` when present. Unrecognized values become `undefined`.
+  The contract's `message` field remains unread.
+- Verify the vendored contract's provenance in `check:generated`. The new
+  `scripts/check-generated.mjs` recomputes the SHA-256 and Git blob id of
+  `openapi/customer.yaml`, requires both plus the upstream commit to appear in
+  `openapi/SOURCE.md`, and regenerates types into a temporary directory, so a
+  contract edit can no longer pass by regenerating alongside it.
+- Vendor the customer contract from immutable `daykeeper-openapi` tag
+  `v1.1.0` (commit `c9a0175`), where `CustomerError` is
+  `additionalProperties: true` and the `error` code is documented as extensible.
+
+- Set `cache: "no-store"` on every dispatch. Native exports also send
+  `Cache-Control: no-cache, no-store` for transports that ignore Fetch cache mode.
+  Keep browser cache headers under standard Fetch control to avoid changing CORS.
+- Add seeded-cache account-switch, revoked-credential, freshness and no-new-storage
+  probes against real HTTP, with mandatory native positive cache controls.
+
+- Set `redirect: "error"` and `credentials: "omit"` on every SDK request,
+  including credential refresh. Node/web standard Fetch remains the default.
+- Verify native and Node ESM/CJS exports, declarations and installed-package
+  policy behavior independently. Android/release certification remains open.
+
+The following changes were developed in the candidate previously numbered
+`0.1.1` and ship as part of `0.2.0`; `0.1.0` remains the published baseline
+until release approval.
+
+- Never replay writes after authentication failure; classify uncertain write
+  outcomes explicitly and make all write errors non-retryable.
+- Honor first-read HTTP 401 `retryable: false` before credential refresh, within
+  the original deadline and response size limit.
+- Keep raw error bodies out of messages, stacks and serialization. Treat
+  failed native body reads as transport failures.
+- Respect explicit server retry advice for customer API errors, including
+  non-retryable quota ceilings; preserve older status-only read classification.
+- Align vendored OpenAPI license metadata and record the exact source commit
+  and checksum; generated types and runtime behavior are unchanged.
+- Classify credential-provider failures as non-retryable `TOKEN_PROVIDER_ERROR`
+  without exposing raw provider errors; timeout and cancellation stay distinct.
+- Bound credential acquisition, authentication refresh, transport, and buffered
+  or streaming response reads by one cancellable request deadline.
+- Prevent late dispatch, release failed response bodies without waiting for
+  cleanup, and sanitize credential-provider failures.
+- Make public SDK and generated contract documentation
+  infrastructure-provider neutral.
+- Ship a `NOTICE` file recording the Apache-2.0 contract the generated types
+  come from, with the full Apache-2.0 text as `LICENSE-APACHE-2.0`, and list
+  supported versions and a private reporting channel in `SECURITY.md`.
+
 ## 0.1.0
 
 - Add typed customer identity, conversation, message, unread, and seen APIs.

package/COMPATIBILITY.md

@@ -1,17 +1,52 @@
 # React Native compatibility
 
-The initial supported target is Expo 57 with React Native 0.86 and Hermes. The
+## Version matrix
+
+| Package version     | Contract consumed                     | Contract version | Contract tag      | Contract commit                            |
+| ------------------- | ------------------------------------- | ---------------- | ----------------- | ------------------------------------------ |
+| `0.2.0`             | customer (`openapi/customer.yaml`)    | 0.1.0            | `v1.1.0`          | `c9a0175d0053f1a2d57c9329f6d3a36ec6acdb71` |
+| `0.1.0` (published) | customer (`openapi/customer.yaml`)    | 0.1.0            | `v1.0.0`          | `35f5bd45fe0c6a6901766543bff90dae6838b965` |
+| any                 | management (`openapi/daykeeper.yaml`) | 0.2.0            | not consumed here | not consumed here                          |
+
+This package consumes only the **customer** contract. The customer contract
+snapshot is pinned to immutable repository tag `v1.1.0`; its OpenAPI `info.version`
+is `0.1.0`. It has no `Idempotency-Key`
+header. The now-required
+`Idempotency-Key` header on flow mutations, and the `200`-alongside-`201`
+replay response, are **management** contract 0.2.0 changes and do **not** apply
+to this package. The management contract is consumed by `daykeeper-node`,
+`daykeeper-mcp` and `daykeeper-cli`, not here. The 0.2.0 break in this package
+is its own: the native transport policy change and error-code passthrough
+described below.
+
+Every release records the exact customer contract tag and commit used; see
+[`openapi/SOURCE.md`](openapi/SOURCE.md) and [`RELEASING.md`](RELEASING.md).
+
+## Runtime
+
+The initial validation target is Expo 57 with React Native 0.86 and Hermes. The
 package declares React Native 0.79 or newer because Metro enables package
 exports by default from that line onward. Releases must be smoke-tested through
 Metro on both iOS and Android before this matrix is expanded.
 
-The client depends only on the React Native web-compatible globals `fetch`,
-`Headers`, `URL`, and `AbortController`. It handles both standards-based
+The client uses an explicitly configured native Fetch transport plus the
+web-compatible globals `Headers`, `URL`, and `AbortController`. It handles both standards-based
 streaming responses and React Native's buffered `Response.text()` response. A
 custom `fetch` implementation must preserve those request and response
-semantics.
+semantics and enforce `redirect: "error"` plus `credentials: "omit"` before
+forwarding anything. It must also honor `Cache-Control: no-cache, no-store`;
+the native export adds this because Expo 57 ignores Fetch's `cache` option.
+All exports set `cache: "no-store"`. Native entry types require `fetch`; runtime validation
+rejects an omitted transport before credentials are requested. Standard
+Node/web Fetch remains the non-native default. Expo is not an SDK dependency.
+
+Writes never automatically replay, including after 401. Read credential refresh
+honors explicit non-retryable advice before a second dispatch. An uncertain
+write result is marked `outcomeUnknown: true` and `retryable: false`; reconcile
+server state before a deliberate retry. This is not server-side idempotency.
+See the recovery contract in the README.
 
-Version 0.1 is headless and ships no native module. It does not yet provide a
+The SDK is headless and ships no native module. It does not yet provide a
 messenger UI, push-notification registration, attachment selection/upload,
 deep-link routing, persistent offline queues, or background delivery. Consumers
 own those surfaces until they are added here behind reviewed native interfaces.
@@ -19,3 +54,54 @@ own those surfaces until they are added here behind reviewed native interfaces.
 Tokens must be short-lived and customer-scoped. Keep them in memory where
 possible; if persistence is unavoidable, use an OS-backed secret store and
 never AsyncStorage.
+
+## Error codes: open vocabulary
+
+The gateway's error vocabulary is open and grows without an SDK release, so
+the SDK does not keep a list of known codes. Any `error` value shaped like a
+code -- ASCII lowercase snake_case, 3 to 64 characters, matching
+`^[a-z][a-z0-9_]{2,63}$` -- reaches the caller as
+`DaykeeperReactNativeApiError.code` unchanged, including codes newer than the
+installed SDK. Anything else, including the free-form English messages the
+gateway returns for some 4xx failures, collapses to
+`daykeeper_request_failed`. The error message is always the code alone: the
+contract's `message` and `nextAction` fields are never projected into the
+message, stack or serialization. Consuming apps must still handle an unknown
+code safely, and must not treat `daykeeper_request_failed` as a specific
+condition.
+
+`nextAction` is the exception and stays a closed vocabulary of exactly
+`review_usage`, `review_setup` and `refresh_conversation`, typed as
+`DaykeeperReactNativeNextAction`. A code is only ever compared, so an unknown
+one is inert; a next action is an instruction the app acts on, so an
+unrecognized value is dropped to `undefined` and omitted from serialization
+rather than surfaced. The contract's `message` field is still never read.
+
+## Native network boundary: release gate
+
+Candidate 0.2.0 sets strict redirect/cookie policy on every dispatch and refuses
+implicit native transport selection. Supply explicit Expo57 `expo/fetch` on the
+validated host or a custom compliant native implementation. A caller-provided
+function remains trusted to implement those semantics; the SDK cannot repair
+an XHR wrapper that ignores them. Checking `response.url` afterward cannot
+prevent an already-forwarded request.
+
+The synthetic two-listener fixture in [`smoke/boundary`](smoke/boundary/README.md)
+measures arrivals, partial bodies, cookies and authorization without retaining
+credential or message values. Direct positive controls must pass before a
+rejected redirect is credited as a boundary. All four writes and one read are
+tested against 301, 302, 303, 307 and 308, within and across origins.
+
+On iOS 26.5 / React Native 0.86.2 / Hermes, the XHR-backed Fetch implementation
+followed redirects despite `redirect: "error"`. Explicit `credentials: "omit"`
+did omit a seeded cookie in this runtime. Explicit Expo 57 `expo/fetch` with
+both options rejected all 50 redirects before receiver arrival and omitted the
+cookie; its five direct API controls succeeded. These are observations for that
+specific runtime, not a supported transport migration or Android certification.
+
+Before release, verify each consumer's actual transport, rerun packed-package
+tests on iOS and Android plus release builds, and certify standalone bare-native
+transport coverage. Do not silently require Expo or claim that passing Fetch
+flags fixes XHR redirect behavior. Exact gateway
+URLs must not rely on canonicalization redirects. Do not broaden native HTTP
+exceptions for this fixture or use it on signed-in devices.

package/LICENSE-APACHE-2.0

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 SkyPorch
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,11 @@
+Daykeeper React Native SDK
+Copyright (c) 2026 SkyPorch
+
+Licensed under the MIT License. See the LICENSE file.
+
+The TypeScript types in this package are generated from the Daykeeper customer
+OpenAPI description, copied from SkyPorch/daykeeper-openapi and licensed under
+the Apache License, Version 2.0. A copy of that license, taken verbatim from
+SkyPorch/daykeeper-openapi, ships in this package as `LICENSE-APACHE-2.0`.
+The source repository keeps that description under `openapi/customer.yaml` and
+records the exact tag and commit in `openapi/SOURCE.md`.

package/README.md

@@ -1,28 +1,45 @@
 # `@skyporch/daykeeper-react-native`
 
 The official headless React Native client for customer-facing Daykeeper support
-experiences. It is generated from the Daykeeper customer API contract and is
+experiences. Its types come from the Daykeeper customer API contract; its transport is
 designed for Expo and bare React Native applications on iOS and Android.
 
 This package contains no native module and no embedded support UI. It provides
 typed identity, conversation, message, unread, seen, and anonymous-claim APIs.
 Push notifications, attachments, deep links, and native UI can be added here
 without coupling consuming applications to Daykeeper's private platform or to
-Chatwoot.
+any infrastructure provider.
+
+API-only inbox gateways support customer conversations, messages, unread state,
+and seen markers. They do not provide widget identity or anonymous-conversation
+claim operations: those calls return `409` with `widget_unavailable` before the
+conversation provider is contacted. Use a widget-enabled gateway for those
+operations.
+
+This README describes the unreleased `0.2.0` candidate. Production certification
+is still open; a successful Metro build or Node test does not establish native
+parity. See [`COMPATIBILITY.md`](COMPATIBILITY.md) before a release or upgrade.
 
 ## Install
 
+After the candidate is approved and published:
+
 ```sh
-npm install @skyporch/daykeeper-react-native
+npm install @skyporch/daykeeper-react-native@0.2.0
 ```
 
+Before publication, test with the reviewed packed tarball. An unversioned npm
+install may select the older published SDK, which does not enforce this policy.
+
 ## Use
 
 ```ts
 import { createDaykeeperReactNativeClient } from "@skyporch/daykeeper-react-native";
+import { fetch as expoFetch } from "expo/fetch";
 
 const daykeeper = createDaykeeperReactNativeClient({
   baseUrl: "https://support.example.com/support-api",
+  fetch: expoFetch,
   getAccessToken: async ({ forceRefresh }) => {
     // Exchange the signed-in app session for a short-lived, customer-scoped
     // Daykeeper token using your own backend. Bypass any local token cache when
@@ -34,9 +51,29 @@ const daykeeper = createDaykeeperReactNativeClient({
 const { conversations } = await daykeeper.listConversations();
 ```
 
+The native export requires an explicit Fetch implementation. This example uses
+the host's existing Expo 57 installation; the SDK does not install Expo. Bare
+React Native applications may supply their own native Fetch implementation,
+but it must reject redirects before following them, omit ambient cookies,
+honor request Cache-Control directives, and support cancellation. The XHR-backed React Native global is not compliant;
+wrapping it or setting Fetch flags does not repair its redirect behavior. Do not
+pass it as the native transport. Omitting `fetch` fails before token acquisition.
+
+Every request sets `redirect: "error"`, `credentials: "omit"`, and `cache: "no-store"`.
+The native export also sends `Cache-Control: no-cache, no-store`, because the
+validated Expo runtime ignores the standard Fetch cache option. This revalidates
+existing cache entries and prevents new storage, including across account
+changes. Node/web uses standard Fetch cache semantics without adding a custom
+browser request header. Keep the API's response `Cache-Control: no-store` too.
+A custom Fetch
+function is a caller-owned trust boundary: the SDK cannot prevent an injected
+implementation from ignoring those options. Use an exact HTTPS gateway URL,
+not one that redirects. Node/web exports can use standard global Fetch.
+
 The token provider runs for every request so the consuming app can rotate
-short-lived credentials. If the gateway returns HTTP 401, the SDK asks the
-provider for one forced refresh and retries exactly once. Keep customer tokens
+short-lived credentials. For a GET returning HTTP 401 without an explicit
+`retryable: false`, the SDK asks the provider for one forced refresh and retries
+the read once. Writes never refresh and replay automatically. Keep customer tokens
 in memory where possible. Never place them in URLs, analytics, crash reports,
 or application logs.
 
@@ -51,8 +88,69 @@ or application logs.
 See [`COMPATIBILITY.md`](COMPATIBILITY.md) for the supported runtime contract
 and release certification matrix.
 
+## Deadlines and cancellation
+
+`timeoutMs` defaults to 30 seconds (allowed range: 1–60 seconds). One budget
+covers token acquisition, both authentication attempts, and streaming or
+buffered response reads. Token providers receive an optional `signal` alongside
+`forceRefresh`; pass it to your backend exchange to cancel that work too.
+
+Every customer API method accepts `{ signal }` request options. Use a caller
+`AbortController` when a screen unmounts or the signed-in identity changes.
+Pre-aborted calls do not invoke credentials or send a request. A late token
+cannot start a request after cancellation or timeout.
+
+Errors preserve `REQUEST_ABORTED` or `REQUEST_TIMEOUT` even if a credential
+provider or native response stalls. Cancellation does not undo a message or
+conversation the server already accepted. Reconcile history before retrying a
+write with an uncertain outcome; network failures and timeouts are not
+automatically replayed.
+
+Credential-provider failures use the non-retryable `TOKEN_PROVIDER_ERROR`
+code, distinct from network failures. Raw provider errors are not exposed.
+Handle sign-in recovery in the token provider or the application; deadline and
+caller cancellation still use their dedicated error codes.
+
+## Safe recovery
+
+All four writes (`createConversation`, `sendMessage`, `markConversationSeen`, and
+`claimAnonymousConversation`) dispatch at most once per call, including after
+HTTP 401. Their errors always have `retryable: false`, even when a server hint
+says otherwise. Refresh credentials in your app before a deliberate new write;
+do not wrap writes in a generic retry loop.
+
+Both exported error classes include `outcomeUnknown` in their properties and
+`toJSON()` output. It is true when a write may have reached the server but the
+SDK cannot confirm its result: a timeout, cancellation, transport/body failure
+after dispatch, or HTTP 408/5xx. Preserve the draft and read conversation history
+before offering another send. Cancellation cannot roll back an accepted write.
+`outcomeUnknown: false` is not an exactly-once guarantee or proof of no side
+effects. The customer API has no SDK-supported idempotency-key contract yet.
+The SDK's dispatch bound is not a wire-level guarantee: a native HTTP stack may
+retry internally (observed for a dropped GET on iOS). Never treat this SDK as
+an exactly-once delivery mechanism.
+
+For reads, `DaykeeperReactNativeApiError.retryable` respects an explicit server
+boolean; older responses fall back to status-based classification (408, 429,
+and 5xx). No automatic backoff or rate-limit retry is performed. Only a first
+read 401 without an explicit false hint permits one credential refresh. A
+stalled, oversized, cancelled, or failed 401 body does not permit that refresh;
+a completed legacy empty/non-JSON 401 does.
+
+A usage ceiling can return HTTP 429 with `retryable: false`. Show suitable local
+copy for its stable code and let a workspace administrator review usage.
+Server error codes matching `^[a-z][a-z0-9_]{2,63}$` are preserved in SDK
+errors, including codes introduced after this release. Handle unfamiliar codes
+with a generic recovery message. Malformed codes become
+`daykeeper_request_failed`. Raw server messages, next-action URLs, and
+credential/transport errors are not copied.
+
+On logout or account change, abort outstanding calls, clear customer UI/history
+and in-memory token caches, and ignore results belonging to the old session.
+The headless SDK does not own the app's login state or persistent storage.
+
 ## Release status
 
-Version `0.1.0` is generated from the customer contract recorded in
+Candidate `0.2.0` is generated from the customer contract recorded in
 [`openapi/SOURCE.md`](openapi/SOURCE.md). Releases use the protected,
 provenance-producing process in [`RELEASING.md`](RELEASING.md).