chore: update changelog & documentation

Author: rhamzeh

CHANGELOG.md

@@ -3,6 +3,12 @@
 
 ## [Unreleased](https://github.com/openfga/js-sdk/compare/v0.9.4...HEAD)
 
+- feat!: replace axios with native `fetch` for cross-platform support (Node.js, browsers, Deno, Cloudflare Workers, Vercel Edge).
+  - **BREAKING**: `AxiosResponse` is no longer exposed on `$response`. The new type is `FgaResponse<T>` (with `status`, `statusText`, `headers`, `data`).
+  - **BREAKING**: `AxiosInstance` injection is replaced by the `HttpClient` interface (`{ fetch, defaultHeaders, defaultTimeout }`).
+  - Timeouts now use `AbortSignal.timeout()`.
+- chore: all `options?: any` parameters in the API layer are now properly typed as `RequestBuilderOptions`.
+
 ## v0.9.4
 
 ### [v0.9.4](https://github.com/openfga/js-sdk/compare/v0.9.3...v0.9.4) (2026-03-31)

README.md

@@ -18,6 +18,7 @@ This is an autogenerated JavaScript SDK for OpenFGA. It provides a wrapper aroun
 - [Getting Started](#getting-started)
   - [Initializing the API Client](#initializing-the-api-client)
   - [Custom Headers](#custom-headers)
+  - [Custom HTTP Client](#custom-http-client)
   - [Get your Store ID](#get-your-store-id)
   - [Calling the API](#calling-the-api)
     - [Stores](#stores)
@@ -84,7 +85,7 @@ Using [yarn](https://yarnpkg.com):
 yarn add @openfga/sdk
 ```
 
-#### Supported Node.js Versions
+### Supported Runtimes
 
 For details on the supported Node.js versions and our support policy, see [SUPPORTED_RUNTIMES.md](./SUPPORTED_RUNTIMES.md).
 
@@ -94,7 +95,7 @@ For details on the supported Node.js versions and our support policy, see [SUPPO
 
 [Learn how to initialize your SDK](https://openfga.dev/docs/getting-started/setup-sdk-client)
 
-We strongly recommend you initialize the `OpenFgaClient` only once and then re-use it throughout your app, otherwise you will incur the cost of having to re-initialize multiple times or at every request, the cost of reduced connection pooling and re-use, and would be particularly costly in the client credentials flow, as that flow will be performed on every request.
+We strongly recommend you initialize the `OpenFgaClient` only once and then re-use it throughout your app, otherwise you will incur the cost of having to re-initialize multiple times or at every request, and would be particularly costly in the client credentials flow, as that flow will be performed on every request. In Node.js, connection pooling is handled automatically by the runtime's native `fetch` implementation.
 
 > The `OpenFgaClient` will by default retry API requests up to 3 times on 429 and 5xx errors.
 
@@ -189,6 +190,55 @@ const result = await fgaClient.check({
 });
 ```
 
+### Custom HTTP Client
+
+The SDK uses the native `fetch` API by default. You can provide a custom `HttpClient` to control the underlying HTTP behavior.
+
+```javascript
+const { OpenFgaClient } = require('@openfga/sdk'); // OR import { OpenFgaClient } from '@openfga/sdk';
+
+const fgaClient = new OpenFgaClient({
+  apiUrl: process.env.FGA_API_URL,
+  storeId: process.env.FGA_STORE_ID,
+  httpClient: {
+    fetch: globalThis.fetch.bind(globalThis), // or a custom fetch implementation
+    defaultHeaders: {
+      "X-Custom-Header": "value",
+    },
+    defaultTimeout: 15000, // timeout in milliseconds (default: 10000)
+  },
+});
+```
+
+The `HttpClient` interface accepts:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `fetch` | `typeof globalThis.fetch` | The fetch function to use for HTTP requests |
+| `defaultHeaders` | `Record<string, string>` | *(Optional)* Headers to include with every request |
+| `defaultTimeout` | `number` | *(Optional)* Default request timeout in milliseconds |
+
+#### Response Type
+
+Most SDK methods that are a direct call to the API return an `FgaResponse<T>` on the `$response` property:
+
+```typescript
+interface FgaResponse<T> {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  data: T;
+}
+```
+
+You can access it via the `$response` property on the method's return value:
+
+```javascript
+const { headers, status } = await fgaClient.getStore().$response;
+```
+
+Methods that have custom logic, such as `clientBatchCheck`, `listRelations` and non-transactional `write` operations, will not contain this field.
+
 ### Get your Store ID
 
 You need your store id to call the OpenFGA API (unless it is to call the [CreateStore](#create-store) or [ListStores](#list-stores) methods).

SUPPORTED_RUNTIMES.md

@@ -1,8 +1,10 @@
-## Node.js Support Policy for OpenFGA JS SDK
+## Runtime Support Policy for OpenFGA JS SDK
+
+### Node.js Support
 
 The OpenFGA JavaScript SDK follows the upstream [Node.js release policy](https://nodejs.org/en/about/previous-releases). We support Node.js versions that are currently in **LTS** or **Maintenance** status.
 
-### Currently Supported Versions
+#### Currently Supported Versions
 
 | Node.js Version | Upstream Support Status | Tested in CI/CD Pipelines |
 |:----------------|:------------------------|:-------------------------:|
@@ -11,12 +13,16 @@ The OpenFGA JavaScript SDK follows the upstream [Node.js release policy](https:/
 | **24**          | LTS                     |            Yes            |
 | **25**          | Current                 |            Yes            |
 
-### Support Details
+#### Support Details
 
-#### Best-Effort Support
+##### Best-Effort Support
 
 We will make a best effort to maintain compatibility with Node.js versions that have reached End-of-Life (EOL), but **we will not test** against them in our CI/CD pipelines. This means you may be able to use the JS SDK with older versions of Node.js (with yarn you can use the `--ignore-engines` flag), but you may not be able to run tests (because many of our testing dependencies have dropped support for EOL versions).
 
-#### Long-term plan
+##### Long-term plan
 
 This best-effort support will not continue indefinitely. We plan to modernize our JS SDK, adopt more functionality now native to the language, and add support for alternate runtimes such as Deno, Cloudflare Workers, and Vercel Edge.
+
+### Alternate Runtimes
+
+Support for alternate runtimes such as Deno, Cloudflare Workers, and Vercel Edge is being gradually added. We will provide updates on our progress in the future.