feat(core,sdk): TriggerClient falls back to env vars at construction

`new TriggerClient()` with no constructor config now resolves
accessToken, previewBranch, and baseURL from the process env
(TRIGGER_SECRET_KEY / TRIGGER_PREVIEW_BRANCH / TRIGGER_API_URL /
VERCEL_GIT_COMMIT_REF / TRIGGER_ACCESS_TOKEN). Explicit constructor
values still win, so multiple instances pointing at different
projects stay isolated. Matches conventions of other env-var-backed
SDKs (OpenAI, Anthropic, Stripe) and removes friction of forcing
\`accessToken: process.env.TRIGGER_SECRET_KEY!\` everywhere.

Mechanics: new \`apiClientManager.resolveApiClientConfig(partial)\`
helper resolves env-derived defaults for missing fields. Both the
TriggerClient constructor and \`apiClientManager.runWithConfig\` (used
by auth.withAuth) feed their config through it before opening a
scope, so the resolution happens once at scope creation and the
scoped getters in apiClientManager just read scope values directly.
Single source of truth replaces the inheritContext-gated env fallback
that was previously sprinkled across the scoped getters.

Constructor early throw dropped — missing auth now surfaces via
ApiClientMissingError at first API call, same as the global API path.

Author: ericallam

packages/core/src/v3/apiClientManager/index.ts

@@ -31,17 +31,9 @@ export class APIClientManagerAPI {
   }
 
   get baseURL(): string | undefined {
-    // baseURL is plumbing (where the API lives), not identity. Scoped
-    // instances read their own config first but still fall back to the
-    // process-level TRIGGER_API_URL so local-dev / CI overrides don't
-    // require passing baseURL into every `new TriggerClient(...)`.
     const scoped = sdkScope.getStore();
     if (scoped) {
-      return (
-        scoped.apiClientConfig.baseURL ??
-        getEnvVar("TRIGGER_API_URL") ??
-        "https://api.trigger.dev"
-      );
+      return scoped.apiClientConfig.baseURL ?? "https://api.trigger.dev";
     }
     const config = this.#getConfig();
     return config?.baseURL ?? getEnvVar("TRIGGER_API_URL") ?? "https://api.trigger.dev";
@@ -50,18 +42,7 @@ export class APIClientManagerAPI {
   get accessToken(): string | undefined {
     const scoped = sdkScope.getStore();
     if (scoped) {
-      const value = scoped.apiClientConfig.accessToken ?? scoped.apiClientConfig.secretKey;
-      if (value !== undefined) return value;
-      // `inheritContext: true` scopes (e.g. `auth.withAuth` partial
-      // overrides) still fall back to the process env so callers who
-      // rely on TRIGGER_SECRET_KEY don't lose auth when they only
-      // wanted to override baseURL. Isolated scopes (TriggerClient)
-      // intentionally do not fall back — the constructor enforces
-      // accessToken is provided.
-      if (scoped.inheritContext) {
-        return getEnvVar("TRIGGER_SECRET_KEY") ?? getEnvVar("TRIGGER_ACCESS_TOKEN");
-      }
-      return undefined;
+      return scoped.apiClientConfig.accessToken ?? scoped.apiClientConfig.secretKey;
     }
     const config = this.#getConfig();
     return (
@@ -76,16 +57,7 @@ export class APIClientManagerAPI {
     const scoped = sdkScope.getStore();
     if (scoped) {
       const value = scoped.apiClientConfig.previewBranch;
-      if (value) return value;
-      // Same inheritContext gating as accessToken: withAuth-style
-      // scopes inherit env-derived branch; TriggerClient instances
-      // stay isolated from process env for identity.
-      if (scoped.inheritContext) {
-        const envValue =
-          getEnvVar("TRIGGER_PREVIEW_BRANCH") ?? getEnvVar("VERCEL_GIT_COMMIT_REF");
-        return envValue ? envValue : undefined;
-      }
-      return undefined;
+      return value ? value : undefined;
     }
     const config = this.#getConfig();
     const value =
@@ -96,6 +68,24 @@ export class APIClientManagerAPI {
     return value ? value : undefined;
   }
 
+  public resolveApiClientConfig(partial: ApiClientConfiguration = {}): ApiClientConfiguration {
+    return {
+      baseURL: partial.baseURL ?? getEnvVar("TRIGGER_API_URL"),
+      accessToken:
+        partial.accessToken ??
+        partial.secretKey ??
+        getEnvVar("TRIGGER_SECRET_KEY") ??
+        getEnvVar("TRIGGER_ACCESS_TOKEN"),
+      secretKey: partial.secretKey,
+      previewBranch:
+        partial.previewBranch ??
+        getEnvVar("TRIGGER_PREVIEW_BRANCH") ??
+        getEnvVar("VERCEL_GIT_COMMIT_REF"),
+      requestOptions: partial.requestOptions,
+      future: partial.future,
+    };
+  }
+
   get client(): ApiClient | undefined {
     if (!this.baseURL || !this.accessToken) {
       return undefined;
@@ -130,18 +120,14 @@ export class APIClientManagerAPI {
     config: ApiClientConfiguration,
     fn: R
   ): Promise<ReturnType<R>> {
-    const merged: ApiClientConfiguration = { ...this.#getConfig(), ...config };
+    const merged = this.resolveApiClientConfig({ ...this.#getConfig(), ...config });
 
-    // Use the AsyncLocalStorage scope when installed (Node-side code
-    // that has loaded TriggerClient or auth) — concurrency-safe.
     if (sdkScope.hasStorage()) {
       return sdkScope.withScope({ apiClientConfig: merged, inheritContext: true }, fn);
     }
 
-    // Fallback: in-place global mutation. Matches pre-existing behavior
-    // and works in any runtime (browser, Edge, Workers, Node without
-    // the storage installed). Not concurrency-safe — parallel callers
-    // with different configs will stomp on each other.
+    // No ALS available (browser, edge, workers). Fall back to in-place
+    // mutation — same as pre-existing behavior, not concurrency-safe.
     const original = this.#getConfig();
     registerGlobal(API_NAME, merged, true);
     return fn().finally(() => {

packages/core/src/v3/sdkScope/index.ts

@@ -2,14 +2,6 @@ import type { SdkScope, SdkScopeStorage } from "./types.js";
 
 export type { SdkScope, SdkScopeStorage } from "./types.js";
 
-// Storage slot. Filled at runtime by a Node-only module
-// (`@trigger.dev/core/v3/sdk-scope-storage`) that owns the
-// AsyncLocalStorage instance. Left undefined in environments that
-// never import that module (browsers, edge runtimes), where
-// `sdkScope.withScope` falls through to invoking the callback
-// directly. `sdkScope/index.ts` deliberately does not statically
-// import `node:async_hooks` or `storage-node.ts` so it is safe to
-// include in any browser-side bundle that reaches `@trigger.dev/core/v3`.
 let installedStorage: SdkScopeStorage | undefined;
 
 export function _installSdkScopeStorage(storage: SdkScopeStorage): void {

packages/core/src/v3/sdkScope/storage-node.ts

@@ -2,11 +2,6 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { _installSdkScopeStorage } from "./index.js";
 import type { SdkScope } from "./types.js";
 
-// Importing this module installs an AsyncLocalStorage-backed
-// `SdkScopeStorage` into the slot exposed by `sdkScope/index.ts`. The
-// SDK side-effect-imports this from server-only modules
-// (TriggerClient, auth) so that browser-bundled code that never
-// touches those modules never pulls `node:async_hooks` either.
 const als = new AsyncLocalStorage<SdkScope>();
 
 _installSdkScopeStorage({

packages/trigger-sdk/src/v3/auth.ts

@@ -4,10 +4,6 @@ import {
   RealtimeRunSkipColumns,
 } from "@trigger.dev/core/v3";
 import { generateJWT as internal_generateJWT } from "@trigger.dev/core/v3";
-
-// Install the Node AsyncLocalStorage-backed storage so `auth.withAuth`
-// (and the public-token helpers that route through it) actually scope
-// API client config. See `triggerClient.ts` for the same import.
 import "@trigger.dev/core/v3/sdk-scope-storage";
 
 /**

packages/trigger-sdk/src/v3/triggerClient.test.ts

@@ -52,8 +52,21 @@ describe("TriggerClient", () => {
     vi.unstubAllEnvs();
   });
 
-  it("requires an accessToken at construction", () => {
-    expect(() => new TriggerClient({})).toThrow(/accessToken/);
+  it("throws on first API call when no accessToken is configured anywhere", () => {
+    const client = new TriggerClient();
+    expect(() => client.runs.list({ limit: 1 })).toThrow(/TRIGGER_SECRET_KEY/);
+  });
+
+  it("falls back to env vars when constructor config is empty", async () => {
+    vi.stubEnv("TRIGGER_SECRET_KEY", "tr_dev_env_token");
+    vi.stubEnv("TRIGGER_PREVIEW_BRANCH", "env-branch");
+
+    const client = new TriggerClient();
+    await client.runs.retrieve("run_abc").catch(() => undefined);
+
+    expect(fetchSpy.captured).toHaveLength(1);
+    expect(fetchSpy.captured[0]!.authorization).toBe("Bearer tr_dev_env_token");
+    expect(fetchSpy.captured[0]!.branch).toBe("env-branch");
   });
 
   it("uses the instance accessToken and previewBranch on outgoing requests", async () => {
@@ -70,24 +83,31 @@ describe("TriggerClient", () => {
     expect(req.branch).toBe("signup-flow");
   });
 
-  it("does not fall back to env vars for identity fields, but DOES for baseURL", async () => {
-    vi.stubEnv("TRIGGER_PREVIEW_BRANCH", "from-env-branch");
-    vi.stubEnv("TRIGGER_API_URL", "https://from-env.example.com");
+  it("fills missing fields from env, but explicit constructor values still win", async () => {
+    vi.stubEnv("TRIGGER_SECRET_KEY", "tr_env_token");
+    vi.stubEnv("TRIGGER_PREVIEW_BRANCH", "env-branch");
+    vi.stubEnv("TRIGGER_API_URL", "https://env.example.com");
 
-    const client = new TriggerClient({
-      accessToken: "tr_preview_instance_token",
-      // no previewBranch, no baseURL
+    const explicit = new TriggerClient({
+      accessToken: "tr_explicit",
+      previewBranch: "explicit-branch",
     });
+    const fromEnv = new TriggerClient();
 
-    await client.runs.retrieve("run_abc").catch(() => undefined);
+    await Promise.all([
+      explicit.runs.retrieve("run_a").catch(() => undefined),
+      fromEnv.runs.retrieve("run_b").catch(() => undefined),
+    ]);
 
-    expect(fetchSpy.captured).toHaveLength(1);
-    const req = fetchSpy.captured[0]!;
-    // Identity (branch) must NOT be filled from env when instance is used.
-    expect(req.branch).toBeUndefined();
-    // Plumbing (baseURL) DOES fall back to TRIGGER_API_URL so local-dev /
-    // CI overrides apply without forcing every consumer to pass baseURL.
-    expect(req.url, `actual url=${req.url}`).toMatch(/^https:\/\/from-env\.example\.com\//);
+    const byRun = Object.fromEntries(
+      fetchSpy.captured.map((r) => [r.url.split("/runs/")[1]?.split(/[/?]/)[0], r])
+    );
+
+    expect(byRun["run_a"]!.authorization).toBe("Bearer tr_explicit");
+    expect(byRun["run_a"]!.branch).toBe("explicit-branch");
+    expect(byRun["run_b"]!.authorization).toBe("Bearer tr_env_token");
+    expect(byRun["run_b"]!.branch).toBe("env-branch");
+    expect(byRun["run_a"]!.url.startsWith("https://env.example.com/")).toBe(true);
   });
 
   it("does not leak instance config to the global apiClientManager", async () => {

packages/trigger-sdk/src/v3/triggerClient.ts

@@ -1,14 +1,9 @@
 import {
   type ApiClientConfiguration,
+  apiClientManager,
   sdkScope,
   type SdkScope,
 } from "@trigger.dev/core/v3";
-
-// Install the Node AsyncLocalStorage-backed storage. Kept as a
-// side-effect import so it is never reached from browser bundles
-// that don't transitively import TriggerClient (relies on
-// `sideEffects: false` in this package + the v3 root not importing
-// storage-node statically).
 import "@trigger.dev/core/v3/sdk-scope-storage";
 
 import { auth } from "./auth.js";
@@ -26,21 +21,10 @@ import {
 } from "./shared.js";
 
 export type TriggerClientConfig = ApiClientConfiguration & {
-  /**
-   * When `true`, instance methods inherit the ambient task context
-   * (`parentRunId`, `lockToVersion`, `isTest`, current task's `taskContext`)
-   * when invoked from inside a task. Default `false` — instance calls are
-   * fully isolated from the surrounding task runtime, which is what you
-   * want when the instance points at a different project, environment, or
-   * preview branch than the task is running in.
-   */
+  /** Inherit ambient task context (parentRunId, lockToVersion, isTest) when called from inside a task. Default `false`. */
   inheritContext?: boolean;
 };
 
-// Curated instance surfaces — drop methods that are inside-task-only
-// (e.g. `batch.triggerAndWait`, which depends on the runtime manager) or
-// task-definition-time (e.g. `schedules.task`, `prompts.define`), and
-// drop helpers that don't need a client (`schedules.timezones`).
 const tasksApi = { trigger, batchTrigger, triggerAndSubscribe };
 const batchInstanceKeys = ["trigger", "triggerByTask", "retrieve"] as const;
 const schedulesInstanceKeys = [
@@ -89,21 +73,11 @@ export class TriggerClient {
   readonly schedules: SchedulesApi;
   readonly auth: AuthApi;
 
-  constructor(config: TriggerClientConfig) {
-    if (!config.accessToken && !config.secretKey) {
-      throw new Error("TriggerClient: accessToken (or secretKey) is required");
-    }
-
+  constructor(config: TriggerClientConfig = {}) {
+    const { inheritContext, ...partial } = config;
     const scope: SdkScope = {
-      apiClientConfig: {
-        baseURL: config.baseURL,
-        accessToken: config.accessToken,
-        secretKey: config.secretKey,
-        previewBranch: config.previewBranch,
-        requestOptions: config.requestOptions,
-        future: config.future,
-      },
-      inheritContext: config.inheritContext ?? false,
+      apiClientConfig: apiClientManager.resolveApiClientConfig(partial),
+      inheritContext: inheritContext ?? false,
     };
 
     this.tasks = bindToScope(tasksApi, scope);