feat!: produce a dual ESM/CJS build

README.md

@@ -87,6 +87,16 @@ yarn add @openfga/sdk
 
 ### Supported Runtimes
 
+The SDK ships with both CommonJS and ES Module builds, and should work out of the box in Node.js, Deno, Cloudflare Workers, and modern bundlers.
+
+```javascript
+// CommonJS
+const { OpenFgaClient } = require("@openfga/sdk");
+
+// ES Modules
+import { OpenFgaClient } from "@openfga/sdk";
+```
+
 For details on the supported Node.js versions and our support policy, see [SUPPORTED_RUNTIMES.md](./SUPPORTED_RUNTIMES.md).
 
 ## Getting Started
@@ -102,7 +112,7 @@ We strongly recommend you initialize the `OpenFgaClient` only once and then re-u
 #### No Credentials
 
 ```javascript
-const { OpenFgaClient } = require('@openfga/sdk'); // OR import { OpenFgaClient } from '@openfga/sdk';
+import { OpenFgaClient } from '@openfga/sdk';
 
 const fgaClient = new OpenFgaClient({
   apiUrl: process.env.FGA_API_URL, // required
@@ -114,7 +124,7 @@ const fgaClient = new OpenFgaClient({
 #### API Token
 
 ```javascript
-const { OpenFgaClient, CredentialsMethod } = require('@openfga/sdk'); // OR import { OpenFgaClient, CredentialsMethod } from '@openfga/sdk';
+import { OpenFgaClient, CredentialsMethod } from '@openfga/sdk';
 
 const fgaClient = new OpenFgaClient({
   apiUrl: process.env.FGA_API_URL, // required
@@ -132,7 +142,7 @@ const fgaClient = new OpenFgaClient({
 #### Client Credentials
 
 ```javascript
-const { OpenFgaClient, CredentialsMethod } = require('@openfga/sdk'); // OR import { OpenFgaClient, CredentialsMethod } from '@openfga/sdk';
+import { OpenFgaClient, CredentialsMethod } from '@openfga/sdk';
 
 const fgaClient = new OpenFgaClient({
   apiUrl: process.env.FGA_API_URL, // required
@@ -157,7 +167,7 @@ const fgaClient = new OpenFgaClient({
 You can set default headers that will be sent with every request during client initialization:
 
 ```javascript
-const { OpenFgaClient } = require('@openfga/sdk'); // OR import { OpenFgaClient } from '@openfga/sdk';
+import { OpenFgaClient } from '@openfga/sdk';
 
 const fgaClient = new OpenFgaClient({
   apiUrl: process.env.FGA_API_URL,
@@ -195,7 +205,7 @@ const result = await fgaClient.check({
 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';
+import { OpenFgaClient } from '@openfga/sdk';
 
 const fgaClient = new OpenFgaClient(
   {
@@ -954,7 +964,7 @@ This is useful when:
 #### Example: Calling a Custom Endpoint with POST
 
 ```javascript
-const { OpenFgaClient } = require('@openfga/sdk');
+import { OpenFgaClient } from "@openfga/sdk";
 
 const fgaClient = new OpenFgaClient({
   apiUrl: process.env.FGA_API_URL,
@@ -1056,7 +1066,7 @@ To customize this behavior, create an object with `maxRetry` and `minWaitInMs` p
 Apply your custom retry values by setting to `retryParams` on the configuration object passed to the `OpenFgaClient` call.
 
 ```javascript
-const { OpenFgaClient } = require('@openfga/sdk'); // OR import { OpenFgaClient } from '@openfga/sdk';
+import { OpenFgaClient } from '@openfga/sdk';
 
 const fgaClient = new OpenFgaClient({
   apiUrl: process.env.FGA_API_URL, // required

api.ts

@@ -11,7 +11,7 @@
  */
 
 
-import { BaseAPI } from "./base";
+import { BaseAPI } from "./base.js";
 import {
   DUMMY_BASE_URL,
   setSearchParams,
@@ -28,12 +28,12 @@ import {
   RequestBuilderParams,
   RequestBuilderOptions,
   RequestBuilder,
-} from "./common";
+} from "./common.js";
 
 export type { HttpMethod, RequestBuilderParams, RequestBuilderOptions };
-import { Configuration } from "./configuration";
-import { Credentials } from "./credentials";
-import { assertParamExists } from "./validation";
+import { Configuration } from "./configuration.js";
+import { Credentials } from "./credentials/index.js";
+import { assertParamExists } from "./validation.js";
 
 import {
   AbortedMessageResponse,
@@ -122,8 +122,8 @@ import {
   WriteRequest,
   WriteRequestDeletes,
   WriteRequestWrites,
-} from "./apiModel";
-import { TelemetryAttribute, TelemetryAttributes } from "./telemetry/attributes";
+} from "./apiModel.js";
+import { TelemetryAttribute, TelemetryAttributes } from "./telemetry/attributes.js";
 
 
 /**

base.ts

@@ -1,6 +1,6 @@
-import { Configuration, UserConfigurationParams } from "./configuration";
-import { HttpClient } from "./common";
-import { Credentials } from "./credentials";
+import { Configuration, UserConfigurationParams } from "./configuration.js";
+import { HttpClient } from "./common.js";
+import { Credentials } from "./credentials/index.js";
 
 const DEFAULT_CONNECTION_TIMEOUT_IN_MS = 10000;
 

client.ts

@@ -1,7 +1,7 @@
-import asyncPool = require("tiny-async-pool");
+import { asyncPool } from "./utils/utils-lite/async-pool.js";
 
-import { OpenFgaApi, HttpMethod, RequestBuilderParams, RequestBuilderOptions } from "./api";
-import type { FgaResponse, HttpClient } from "./common";
+import { OpenFgaApi, HttpMethod, RequestBuilderParams, RequestBuilderOptions } from "./api.js";
+import type { FgaResponse, HttpClient } from "./common.js";
 export type { HttpMethod, RequestBuilderParams, RequestBuilderOptions };
 import {
   Assertion,
@@ -40,19 +40,19 @@ import {
   WriteRequest,
   WriteRequestWritesOnDuplicate,
   WriteRequestDeletesOnMissing,
-} from "./apiModel";
-import { BaseAPI } from "./base";
-import { CallResult, PromiseResult } from "./common";
-import { Configuration, RetryParams, UserConfigurationParams } from "./configuration";
-import { FgaApiAuthenticationError, FgaRequiredParamError, FgaValidationError } from "./errors";
+} from "./apiModel.js";
+import { BaseAPI } from "./base.js";
+import { CallResult, PromiseResult } from "./common.js";
+import { Configuration, RetryParams, UserConfigurationParams } from "./configuration.js";
+import { FgaApiAuthenticationError, FgaRequiredParamError, FgaValidationError } from "./errors.js";
 import {
   chunkArray,
   generateRandomIdWithNonUniqueFallback,
   setHeaderIfNotSet,
-} from "./utils";
-import { isWellFormedUlidString } from "./validation";
-import SdkConstants from "./constants";
-import { parseNDJSONStream } from "./streaming";
+} from "./utils/index.js";
+import { isWellFormedUlidString } from "./validation.js";
+import SdkConstants from "./constants/index.js";
+import { parseNDJSONStream } from "./streaming.js";
 
 export type UserClientConfigurationParams = UserConfigurationParams & {
   storeId?: string;

common.ts

@@ -1,6 +1,6 @@
-import { Configuration, RetryParams } from "./configuration";
-import SdkConstants from "./constants";
-import type { Credentials } from "./credentials";
+import { Configuration, RetryParams } from "./configuration.js";
+import SdkConstants from "./constants/index.js";
+import type { Credentials } from "./credentials/index.js";
 import {
   FgaApiError,
   FgaApiInternalError,
@@ -11,11 +11,11 @@ import {
   FgaError,
   FgaValidationError,
   HttpErrorContext,
-} from "./errors";
-import { setNotEnumerableProperty } from "./utils";
-import { TelemetryAttribute, TelemetryAttributes } from "./telemetry/attributes";
-import { TelemetryConfiguration } from "./telemetry/configuration";
-import { TelemetryHistograms } from "./telemetry/histograms";
+} from "./errors.js";
+import { setNotEnumerableProperty } from "./utils/index.js";
+import { TelemetryAttribute, TelemetryAttributes } from "./telemetry/attributes.js";
+import { TelemetryConfiguration } from "./telemetry/configuration.js";
+import { TelemetryHistograms } from "./telemetry/histograms.js";
 
 /**
  *

configuration.ts

@@ -1,8 +1,8 @@
-import { ApiTokenConfig, AuthCredentialsConfig, ClientCredentialsConfig, CredentialsMethod } from "./credentials/types";
-import { FgaValidationError, } from "./errors";
-import { assertParamExists, isWellFormedUriString } from "./validation";
-import { TelemetryConfig, TelemetryConfiguration } from "./telemetry/configuration";
-import SdkConstants from "./constants";
+import { ApiTokenConfig, AuthCredentialsConfig, ClientCredentialsConfig, CredentialsMethod } from "./credentials/types.js";
+import { FgaValidationError, } from "./errors.js";
+import { assertParamExists, isWellFormedUriString } from "./validation.js";
+import { TelemetryConfig, TelemetryConfiguration } from "./telemetry/configuration.js";
+import SdkConstants from "./constants/index.js";
 
 // default maximum number of retry
 const DEFAULT_MAX_RETRY = SdkConstants.DefaultMaxRetry;

credentials/credentials.ts

@@ -13,15 +13,15 @@
 
 import * as jose from "jose";
 
-import { assertParamExists, isWellFormedUriString } from "../validation";
-import { FgaApiAuthenticationError, FgaApiError, FgaValidationError } from "../errors";
-import { attemptHttpRequest, HttpClient } from "../common";
-import { AuthCredentialsConfig, PrivateKeyJWTConfig, ClientCredentialsConfig, ClientSecretConfig, CredentialsMethod } from "./types";
-import { TelemetryAttributes } from "../telemetry/attributes";
-import { TelemetryCounters } from "../telemetry/counters";
-import { TelemetryConfiguration } from "../telemetry/configuration";
+import { assertParamExists, isWellFormedUriString } from "../validation.js";
+import { FgaApiAuthenticationError, FgaApiError, FgaValidationError } from "../errors.js";
+import { attemptHttpRequest, HttpClient } from "../common.js";
+import { AuthCredentialsConfig, PrivateKeyJWTConfig, ClientCredentialsConfig, ClientSecretConfig, CredentialsMethod } from "./types.js";
+import { TelemetryAttributes } from "../telemetry/attributes.js";
+import { TelemetryCounters } from "../telemetry/counters.js";
+import { TelemetryConfiguration } from "../telemetry/configuration.js";
 import { randomUUID } from "crypto";
-import SdkConstants from "../constants";
+import SdkConstants from "../constants/index.js";
 
 interface ClientSecretRequest {
   client_id: string;

credentials/index.ts

@@ -11,5 +11,5 @@
  */
 
 
-export * from "./credentials";
-export * from "./types";
+export * from "./credentials.js";
+export * from "./types.js";

errors.ts

@@ -2,7 +2,21 @@ import {
   ErrorCode,
   InternalErrorCode,
   NotFoundErrorCode,
-} from "./apiModel";
+} from "./apiModel.js";
+
+/**
+ * Context extracted from a failed HTTP request/response,
+ * used to construct SDK error classes without coupling to any HTTP library.
+ */
+export interface HttpErrorContext {
+  status?: number;
+  statusText?: string;
+  headers?: Record<string, string>;
+  data?: any;
+  requestUrl?: string;
+  requestMethod?: string;
+  requestData?: any;
+}
 
 /**
  * Context extracted from a failed HTTP request/response,

index.ts

@@ -11,17 +11,17 @@
  */
 
 
-export * from "./api";
-export * from "./client";
-export * from "./apiModel";
-export { Configuration, UserConfigurationParams, GetDefaultRetryParams } from "./configuration";
-export { Credentials, CredentialsMethod } from "./credentials";
-export * from "./telemetry/attributes";
-export * from "./telemetry/configuration";
-export * from "./telemetry/counters";
-export * from "./telemetry/histograms";
-export * from "./telemetry/metrics";
-export * from "./errors";
-export { FgaResponse, HttpClient, CallResult, PromiseResult } from "./common";
-export { parseNDJSONStream } from "./streaming";
+export * from "./api.js";
+export * from "./client.js";
+export * from "./apiModel.js";
+export { Configuration, UserConfigurationParams, GetDefaultRetryParams } from "./configuration.js";
+export { Credentials, CredentialsMethod } from "./credentials/index.js";
+export * from "./telemetry/attributes.js";
+export * from "./telemetry/configuration.js";
+export * from "./telemetry/counters.js";
+export * from "./telemetry/histograms.js";
+export * from "./telemetry/metrics.js";
+export * from "./errors.js";
+export { FgaResponse, HttpClient, CallResult, PromiseResult } from "./common.js";
+export { parseNDJSONStream } from "./streaming.js";