feat: Add raw request method for calling arbitrary API endpoints

[Abishek-Newar]

Description

This PR adds a rawRequest method to the SDK.
It allows developers to send any HTTP request to any OpenFGA API endpoint, while still using the SDK’s built-in features like authentication, configuration, retries, and error handling.
This is useful as an “escape hatch” for calling new or experimental API endpoints that don’t yet have official SDK methods.
The change adds rawRequest to both OpenFgaApi and OpenFgaClient, introduces new types (HttpMethod and ClientRawRequestParams), and includes a full test suite with 12 tests covering:

• all HTTP methods
• query parameters
• custom headers
• error handling

Closes #282

What problem is being solved?

Currently, the SDK provides typed methods for specific API endpoints (check, write, read, etc.). However, there is no way to call arbitrary OpenFGA API endpoints that may not yet have dedicated SDK methods. This creates a gap when:

New OpenFGA API endpoints are released but SDK updates have not been implemented yet
Experimental endpoints need to be tested
Developers need a temporary alternative while waiting for official SDK support
Without a raw request method, developers are forced to either wait for SDK updates, or fork and modify the SDK code themselves, or call the OpenFGA API directly without the SDK, losing the benefits of SDK authentication, configuration, and error handling patterns. This reduces developer agility and creates friction in adopting new OpenFGA features.

How is it being solved?

A new rawRequest method was added that takes an HTTP method, API path, and optional body and query parameters.
Internally, it uses the existing createRequestFunction, so it automatically handles:

• Authentication – Adds Bearer tokens automatically (including client credentials flow)
• Retry logic – Retries requests on 429 and 5xx errors using exponential backoff
• Error handling – Throws well-defined SDK errors (like FgaApiNotFoundError, FgaApiValidationError, etc.)
• Telemetry – Tracks request and response metrics when telemetry is enabled
  This helps developers use new or experimental OpenFGA features quickly, while still following the same reliable patterns as the rest of the SDK.

What changes are made to solve it?

1. api.ts

• Added a rawRequest method to OpenFgaApiAxiosParamCreator to build request details (HTTP method, path, body, query params, and Content-Type header).
• Added rawRequest to OpenFgaApiFp, wrapping it with createRequestFunction to handle authentication, retries, and telemetry.
• Added rawRequest to OpenFgaApiFactory and the OpenFgaApi class so the method is publicly available.

2. client.ts

• Added an HttpMethod type ("GET" | "POST" | "PUT" | "DELETE" | "PATCH").
• Added a ClientRawRequestParams interface with method, path, optional body, and optional queryParams.
• Added a rawRequest() method to OpenFgaClient that cleanly delegates the call to the underlying API.

3. tests/rawRequest.test.ts (new file)
   Added 12 tests covering all HTTP methods (GET, POST, PUT, DELETE, PATCH), query parameters, custom headers, authentication, and error handling.

References

Closes #282

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

• New Features

  • Introduced raw HTTP request capability to make direct, flexible calls to any OpenFGA endpoint.
  • New rawRequest method supports GET, POST, PUT, DELETE, and PATCH operations with custom bodies, query parameters, and headers.

• Tests

  • Added comprehensive unit tests covering all HTTP methods, error handling, authentication, and custom request scenarios.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

The pull request adds a raw HTTP request capability across the OpenFGA TypeScript SDK, enabling developers to make arbitrary HTTP calls to OpenFGA endpoints. A new rawRequest method is introduced at the API layer, client layer, and includes comprehensive test coverage, without modifying any existing API logic.

Changes

Cohort / File(s)	Summary
API Layer Additions api.ts	Added rawRequest(method, path, body?, queryParams?, options?) method across four API abstraction layers: AxiosParamCreator (returns RequestArgs), FP interface (returns callable), Factory interface (returns PromiseResult), and OpenFgaApi class (public method returning Promise). Each supports GET, POST, PUT, DELETE, PATCH methods with optional body and query parameters.
Client Layer & Types client.ts	Introduced HttpMethod type union ("GET" | "POST" | "PUT" | "DELETE" | "PATCH") and ClientRawRequestParams interface (method, path, body?, queryParams?). Added public rawRequest(request, options?) method to OpenFgaClient delegating to the underlying API layer. Minor formatting adjustments to existing type definitions.
Unit Tests tests/rawRequest.test.ts	New comprehensive test suite covering GET, POST, PUT, DELETE, and PATCH requests; query parameters; custom headers; Content-Type header injection; full Axios response access via $response; error handling (404 FgaApiNotFoundError, 400 FgaApiValidationError); and authentication header injection. Tests use Nock for HTTP mocking.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• [All SDKs] Add raw request method to SDKs for calling arbitrary API endpoints sdk-generator#658: This PR implements the non-streaming rawRequest escape hatch across TypeScript SDK layers as requested in the linked SDK generator feature issue.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	The PR implementation fully satisfies issue #282 requirements: rawRequest method added with full SDK feature support (authentication, retries, error handling, telemetry) across api.ts, client.ts; comprehensive tests added.
Out of Scope Changes check	✅ Passed	All changes are directly related to the rawRequest feature. Minor formatting adjustments in client.ts types are incidental and do not introduce out-of-scope functionality.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a raw request method to enable arbitrary API endpoint calls in the SDK.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[dosubot]

Related Documentation

Checked 7 published document(s) in 1 knowledge base(s). No updates required.

^{How did I do? Any feedback?}  

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (4)

tests/rawRequest.test.ts (3)

100-119: Consider using a more meaningful assertion.

The test relies on the implicit behavior that nock will fail if the header is not matched. While this works, the expect(true).toBe(true) assertion on line 118 is a code smell. Consider adding an explicit assertion that provides more value.

🔎 Suggested improvement

-            // If we get here without error, the Content-Type header was correctly applied
-            expect(true).toBe(true);
+            // Nock would have thrown if the Content-Type header was missing
+            expect(nock.isDone()).toBe(true);

---

191-195: Same pattern of trivial assertion.

This applies to the custom headers test as well. Consider using expect(nock.isDone()).toBe(true) for a more meaningful assertion.

---

246-250: Same pattern of trivial assertion in authentication test.

Consider using expect(nock.isDone()).toBe(true) here as well for consistency.

api.ts (1)

833-836: Consider also handling DELETE with body.

While less common, HTTP DELETE requests can also have a body. The current implementation only sets Content-Type for POST/PUT/PATCH. If a user passes a body with DELETE, it will be serialized (line 841-843) but without the Content-Type header.

🔎 Suggested fix to include DELETE with body support

       // Set Content-Type for requests with body
-      if (body !== undefined && (method === "POST" || method === "PUT" || method === "PATCH")) {
+      if (body !== undefined) {
         localVarHeaderParameter["Content-Type"] = "application/json";
       }

Alternatively, if you want to keep the current behavior to avoid unexpected Content-Type headers on bodyless requests, the current implementation is acceptable since this is an escape hatch and users can manually set headers via options.headers.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d902be2 and 6719b0b.

📒 Files selected for processing (3)

• api.ts
• client.ts
• tests/rawRequest.test.ts

🧰 Additional context used

🧬 Code graph analysis (2)

client.ts (2)

apiModel.ts (3)

• CheckRequest (277-314)
• TupleKey (1432-1457)
• CheckRequestTupleKey (322-341)

common.ts (1)

• PromiseResult (116-116)

api.ts (2)

common.ts (8)

• setSearchParams (51-66)
• DUMMY_BASE_URL (23-23)
• serializeDataIfNeeded (88-96)
• toPathString (102-104)
• RequestArgs (30-33)
• PromiseResult (116-116)
• createRequestFunction (280-347)
• CallResult (112-114)

base.ts (1)

• RequestArgs (15-18)

🔇 Additional comments (12)

tests/rawRequest.test.ts (4)

1-30: Test setup and imports look correct.

The test file follows the existing test patterns in the codebase, properly setting up nock mocking and disabling network connections.

---

32-80: GET request tests are comprehensive and well-structured.

The tests cover successful GET requests, query parameters, and $response access pattern. Good coverage.

---

140-153: Good test coverage for DELETE with 204 No Content response.

The test correctly handles the 204 status code scenario and validates via $response.status.

---

198-231: Error handling tests properly validate SDK error mapping.

Tests correctly verify that 404 responses map to FgaApiNotFoundError and 400 responses map to FgaApiValidationError, ensuring the rawRequest inherits SDK error handling.

client.ts (3)

261-278: Well-documented type definitions for rawRequest.

The HttpMethod type and ClientRawRequestParams interface are clearly defined with JSDoc comments. This follows the existing patterns in the codebase.

---

967-1013: rawRequest method is well-implemented with excellent documentation.

The method:

• Has comprehensive JSDoc with examples showing different use cases
• Properly delegates to the underlying API layer
• Uses PromiseResult<any> which is appropriate for an escape hatch that can return arbitrary response data
• Follows the existing patterns of other client methods

---

122-124: Minor formatting changes - no behavioral impact.

These are just formatting adjustments to the existing type definitions.

api.ts (5)

811-849: rawRequest implementation follows SDK patterns correctly.

The implementation:

• Uses the same URL construction pattern as other endpoints
• Properly handles query parameters via the existing setSearchParams utility
• Only sets Content-Type: application/json for methods with body (POST/PUT/PATCH)
• Uses serializeDataIfNeeded for body serialization, consistent with other endpoints

---

1126-1143: OpenFgaApiFp rawRequest properly integrates with telemetry.

The method correctly uses createRequestFunction which provides authentication, retry logic, and telemetry tracking. The telemetry attribute FgaClientRequestMethod: "RawRequest" is appropriately set for observability.

---

1344-1358: OpenFgaApiFactory rawRequest follows established patterns.

The factory implementation correctly delegates to the functional programming interface.

---

1593-1608: OpenFgaApi class rawRequest method is well-documented.

The public method has comprehensive JSDoc documentation and correctly delegates through the layers.

---

811-812: Path parameter is passed directly without validation.

The path parameter is used directly in URL construction without validation. This is intentional for an "escape hatch" method, but consider documenting that:

1. The path should start with /
2. Path traversal characters could lead to unexpected behavior

This is acceptable given the method's purpose as an escape hatch for advanced users who know what they're doing.

Ensure the documentation or README mentions that users are responsible for constructing valid paths. The inline JSDoc example '/stores/{store_id}/my-endpoint' provides good guidance.

[dyeam0]

Reposting my issue comment here:

Without having anyone reviewed it yet, I will ask a general request. We have a requirement to maintain consistency across all languages SDKs, as much as possible, with the exception of language-specific idiomatic code. Would you be able to review the existing Go implementation (PR openfga/go-sdk#258) and look to maintain consistency with that SDK before we proceed to a team review? Thank you.

[SoulPancake]

Thanks for the PR @Abishek-Newar
Can you add a section documenting this too
similar to the go-sdk https://github.com/openfga/go-sdk?tab=readme-ov-file#calling-other-endpoints

Examples should be nice to have

[Abishek-Newar]

@SoulPancake I have made the reviewed changes

[Abishek-Newar]

Hi @SoulPancake , I’m seeing test case failures in the CI environment, but everything passes locally on my machine.
Could you help me understand what might be causing this difference?

[SoulPancake]

@Abishek-Newar
Taking a look, seems similar to something related to nocks failing on CI.

[Abishek-Newar]

Hi @SoulPancake , I’m trying to diagnose why the tests are failing in GitHub Actions, even though they’re passing locally. I’d really appreciate it if you could share any hints or guidance when you have a moment. Thank you!

[SoulPancake]

@Abishek-Newar It seems to be a known issue with nocks in CI. Once we investigate it, we will let you know.
Thanks.

[Abishek-Newar]

@SoulPancake ok sure

[Abishek-Newar]

Hi @SoulPancake , is it possible to go for nocks@13, until this issue with nocks and @mswjs/interceptors is resolved ?