From e642b9c8660968ef42b3160157deb2f99a72024a Mon Sep 17 00:00:00 2001
From: Michael Yoon <michael@michaelyoon.com>
Date: Sat, 22 Aug 2026 11:34:53 -0600
Subject: [PATCH] feat: add isDebug option to override __DEV__ detection

__DEV__ is false for every release build, including internal ones such as
TestFlight, so a developer's own pre-release testing is reported as
production data with no way to opt out.

Add an optional isDebug flag to AptabaseOptions that overrides the value
read from the environment. Omitting it keeps the current __DEV__ behavior.
The override lands on the client's environment info, so it applies to both
events and error reports.

This matches the isDebug option in @aptabase/web and the trackingMode
option added to the Swift SDK in 0.3.11.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CHANGELOG.md       |  4 ++++
 README.md          | 19 +++++++++++++++++++
 llms.txt           |  1 +
 src/client.spec.ts | 24 ++++++++++++++++++++++++
 src/client.ts      |  3 +++
 src/types.d.ts     |  5 +++++
 6 files changed, 56 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9ce3d7a..3581e60 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## Unreleased
+
+- Add the optional `isDebug` init option to override the default `__DEV__` detection, so release builds used for internal testing (e.g. TestFlight) can be reported as debug
+
 ## 0.6.0
 
 - Add error reporting: new `trackError(error, { fatal })` function posting structured error reports (type, message, stack trace, severity, kind) with capture-time enrichment and retry on network failures
diff --git a/README.md b/README.md
index dc37e12..f2749b4 100644
--- a/README.md
+++ b/README.md
@@ -99,6 +99,25 @@ A few important notes:
 3. You do not need to await for the `trackEvent` function, it'll run in the background.
 4. Only strings and numbers values are allowed on custom properties
 
+## Debug Mode
+
+Events are flagged as debug based on `__DEV__`, which separates development data from
+production data on your dashboard.
+
+`__DEV__` is false for every release build, including internal ones such as TestFlight or
+an Android internal testing track, so your own pre-release testing counts as production
+data. Pass the `isDebug` option to decide it yourself:
+
+```js
+Aptabase.init("<YOUR_APP_KEY>", {
+  isDebug: __DEV__ || isRunningInternalBuild(),
+});
+```
+
+When omitted, the SDK keeps using `__DEV__`. The flag applies to both events and error
+reports. This mirrors the `isDebug` option in the web SDK and the `trackingMode` option
+in the Swift SDK.
+
 ## Error Reporting
 
 > Error reporting is in beta. Reports appear on the `Errors` page of your Aptabase dashboard.
diff --git a/llms.txt b/llms.txt
index 9151684..0440cdb 100644
--- a/llms.txt
+++ b/llms.txt
@@ -104,6 +104,7 @@ Aptabase.init("<APP_KEY>", {
   flushInterval: 30000, // override flush interval in ms (default: 60s prod, 2s dev)
   enableWeb: true, // enable tracking on React Native Web (disabled by default)
   enableCrashReporting: true, // report uncaught errors and crashes automatically (disabled by default)
+  isDebug: true, // override the default __DEV__ debug detection (e.g. to flag TestFlight builds as debug)
 });
 ```
 
diff --git a/src/client.spec.ts b/src/client.spec.ts
index 77ebd28..4dd9ba4 100644
--- a/src/client.spec.ts
+++ b/src/client.spec.ts
@@ -36,6 +36,30 @@ describe("AptabaseClient", () => {
     expect(body[0].systemProps).toEqual({ ...env, appVersion: "2.0.0" });
   });
 
+  it("should allow override of isDebug", async () => {
+    const client = new AptabaseClient("A-DEV-000", env, {
+      isDebug: true,
+    });
+
+    client.trackEvent("Hello");
+    await client.flush();
+
+    const body = await fetchMock.requests().at(0)?.json();
+    expect(body[0].systemProps).toEqual({ ...env, isDebug: true });
+  });
+
+  it("should keep the environment isDebug when not overridden", async () => {
+    const client = new AptabaseClient("A-DEV-000", env, {
+      appVersion: "2.0.0",
+    });
+
+    client.trackEvent("Hello");
+    await client.flush();
+
+    const body = await fetchMock.requests().at(0)?.json();
+    expect(body[0].systemProps.isDebug).toEqual(env.isDebug);
+  });
+
   it("should send event with correct props", async () => {
     const client = new AptabaseClient("A-DEV-000", env);
 
diff --git a/src/client.ts b/src/client.ts
index 982b28f..c003487 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -33,6 +33,9 @@ export class AptabaseClient {
     if (options?.appVersion) {
       this._env.appVersion = options.appVersion;
     }
+    if (typeof options?.isDebug === "boolean") {
+      this._env.isDebug = options.isDebug;
+    }
 
     const isWeb = this._env.osName === "web";
     const isWebTrackingEnabled = isWeb && options?.enableWeb === true;
diff --git a/src/types.d.ts b/src/types.d.ts
index 947803b..2f79518 100644
--- a/src/types.d.ts
+++ b/src/types.d.ts
@@ -17,6 +17,11 @@ export type AptabaseOptions = {
 
   // Automatically report uncaught errors and crashes (disabled by default)
   enableCrashReporting?: boolean;
+
+  // Override whether the app is running in debug mode. Defaults to `__DEV__`,
+  // which is false for any release build, including internal ones such as
+  // TestFlight. Set it to true there to keep those events out of production data.
+  isDebug?: boolean;
 };
 
 /**