feat: add APIExecutor dedicated examples

[SoulPancake]

Description

What problem is being solved?

How is it being solved?

What changes are made to solve it?

References

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

Release Notes

• Documentation
  • Added API Executor example section with documentation and runnable script demonstrating how to call OpenFGA endpoints using low-level SDK methods for both standard and streaming requests

[coderabbitai]

Walkthrough

Adds a new "API Executor" example demonstrating low-level SDK methods (executeApiRequest and executeStreamedApiRequest) for calling OpenFGA endpoints directly, including documentation, runnable example code with sequential API operations, and package configuration.

Changes

Cohort / File(s)	Summary
Documentation example/README.md, example/api-executor/README.md	Added reference to API Executor example in main README and comprehensive documentation covering prerequisites, usage patterns for standard and streaming requests, path parameter substitution, custom headers, and expected terminal output.
Example Code example/api-executor/apiExecutor.mjs	Implemented runnable example script demonstrating sequential API operations: listing stores, creating/retrieving stores, writing authorization models and tuples, checking access with headers, listing objects, executing streaming list-objects with NDJSON parsing, and cleanup deletion.
Configuration example/api-executor/package.json	Added package manifest with start script, local SDK dependency reference, and Node engine requirement (>=16.13.0).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• chore: improve api executor flow #345 — Introduces the executeApiRequest and executeStreamedApiRequest low-level methods that this example directly demonstrates.
• release: v0.9.3 #342 — Release PR v0.9.3 that includes the "Add APIExecutor" feature corresponding to these example additions.

Suggested reviewers

• rhamzeh

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding dedicated examples for the APIExecutor feature, which aligns with the changeset that introduces three new example files (README, implementation script, and package.json) demonstrating low-level SDK methods.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/add-api-executor-examples

---

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.}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.79%. Comparing base (85b005d) to head (c26ba96).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #385   +/-   ##
=======================================
  Coverage   85.79%   85.79%           
=======================================
  Files          26       26           
  Lines        1267     1267           
  Branches      249      225   -24     
=======================================
  Hits         1087     1087           
  Misses        110      110           
  Partials       70       70           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Adds a new runnable example under example/api-executor/ to demonstrate using OpenFgaClient’s low-level executeApiRequest and executeStreamedApiRequest APIs, including an NDJSON streaming workflow.

Changes:

• Added api-executor example script exercising multiple OpenFGA endpoints via the generic request executors (including streaming).
• Added dedicated README for the new example with setup/run instructions and usage notes.
• Updated the examples index README to mention the new API Executor example.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
example/api-executor/package.json	Defines the new example’s Node entrypoint, dependency wiring, and runtime constraints.
example/api-executor/apiExecutor.mjs	End-to-end example invoking OpenFGA endpoints via executeApiRequest / executeStreamedApiRequest.
example/api-executor/README.md	Documentation for when/how to use the low-level executor APIs and how to run the demo.
example/README.md	Adds a short description of the new example to the examples list.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

example/api-executor/apiExecutor.mjs (1)

29-34: Avoid exiting inside handleError; it can skip cleanup.

process.exit(1) on Line 33 bypasses the normal control flow, so failures after store creation can leave test stores undeleted. Prefer throwing and doing best-effort delete in finally.

Also applies to: 332-341

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@example/api-executor/apiExecutor.mjs` around lines 29 - 34, The handleError
function should not call process.exit(1); instead, remove the process.exit call
and rethrow the error (or throw a new Error with context) so callers can perform
cleanup; update any other error-handler occurrences noted (the similar block at
lines 332-341) to follow the same pattern and ensure callers wrap operations
that create test stores in try/catch/finally where the finally block attempts
best-effort deletion of created stores (log failures but do not hard-exit).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@example/api-executor/package.json`:
- Line 3: The package.json currently sets the "private" field as a string
("true"); change it to a boolean (true) so npm treats it correctly and prevents
accidental publish — locate the "private" entry in package.json and replace the
string value with the boolean literal true.

In `@example/api-executor/README.md`:
- Around line 125-170: The README's multi-line example block is missing a
language tag which triggers MD040; update the fenced code block in
example/api-executor/README.md (the OpenFGA executeApiRequest Example block) to
include a language identifier such as text or bash by changing the opening ```
to ```text (or ```bash) so markdownlint no longer flags it.

---

Nitpick comments:
In `@example/api-executor/apiExecutor.mjs`:
- Around line 29-34: The handleError function should not call process.exit(1);
instead, remove the process.exit call and rethrow the error (or throw a new
Error with context) so callers can perform cleanup; update any other
error-handler occurrences noted (the similar block at lines 332-341) to follow
the same pattern and ensure callers wrap operations that create test stores in
try/catch/finally where the finally block attempts best-effort deletion of
created stores (log failures but do not hard-exit).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2bd78af5-590e-4c85-bd9e-17dc4aed6ee1

📥 Commits

Reviewing files that changed from the base of the PR and between 85b005d and c26ba96.

📒 Files selected for processing (4)

• example/README.md
• example/api-executor/README.md
• example/api-executor/apiExecutor.mjs
• example/api-executor/package.json