refactor(toolsets): stop reading STACKONE_ACCOUNT_ID

Match the Python SDK (stackone-ai-python#23): the account id must be
passed as accountId/accountIds, and STACKONE_API_KEY stays the only
credential read from the environment. In 3.0 an unset account means
every active account, so an environment variable silently setting it
changed a toolset's scope without the code saying so.

The README and examples now read STACKONE_ACCOUNT_ID themselves and pass
it as accountId; unset, it is undefined and the toolset discovers the
key's accounts. MIGRATION.md shows the before and after.

BREAKING CHANGE: STACKONE_ACCOUNT_ID is no longer read. Pass the account
id as accountId or accountIds; without one, the toolset discovers every
active account linked to the API key.

Author: willleeney

.env.example

@@ -1,7 +1,8 @@
 # Required for all examples
 STACKONE_API_KEY=your-stackone-api-key
 
-# Optional: without it, the SDK uses every active account linked to the API key
+# Optional: the examples read this and pass it as accountId (the SDK itself never reads it).
+# Without it, the SDK uses every active account linked to the API key
 STACKONE_ACCOUNT_ID=your-account-id
 
 # Required for OpenAI examples (openai-integration, openai-responses-integration, ai-sdk-integration)

MIGRATION.md

@@ -179,6 +179,16 @@ await toolset.execute('linear_list_comments', { headers: { 'x-request-id': 'abc'
 
 **With no account id, the SDK discovers your accounts.** In 2.x, calling `fetchTools()` with no account listed tools without an `x-account-id`, which the API refuses. In 3.0 it asks `GET /accounts` (also available as `toolset.fetchAccounts()`) and lists the catalog of every active account. If you have many accounts, pass `accountId`, `accountIds` or call `setAccounts()` so the SDK does not fetch every catalog.
 
+**`STACKONE_ACCOUNT_ID` is no longer read.** Pass the account id as `accountId` or `accountIds`. Since an unset account now means every active account, an environment variable that set it implicitly could widen or narrow a toolset's scope without the code saying so. `STACKONE_API_KEY` is still read. To keep the variable, read it yourself; unset, it is `undefined` and the toolset discovers your accounts:
+
+```typescript
+// 2.x: STACKONE_ACCOUNT_ID picked up implicitly
+const toolset = new StackOneToolSet();
+
+// 3.0
+const toolset = new StackOneToolSet({ accountId: process.env.STACKONE_ACCOUNT_ID });
+```
+
 **Listings are merged in sorted account order.** When two accounts serve the same tool name, `getTool()` returns the first one listed — now the one on the lowest account id, where 2.x followed the order you passed. A warning names the clashing tools. Pass `accountIds` to choose the account yourself.
 
 **`fetchTools()` returns fresh tool instances on every call**, never the cached `Tools`, so `setAccountId()` on one tool no longer changes what later callers get. An account whose listing fails is skipped with a warning, unless every account fails.

README.md

@@ -77,13 +77,13 @@ for (const account of await toolset.fetchAccounts()) {
 
 ### Account IDs
 
-StackOne uses account IDs to identify different integrations. You can specify the account ID at different levels (a per-call `accountIds` wins, then `setAccounts()`, then the constructor's `accountIds`, then `accountId` or `STACKONE_ACCOUNT_ID`, then discovery):
+StackOne uses account IDs to identify different integrations. You can specify the account ID at different levels (a per-call `accountIds` wins, then `setAccounts()`, then the constructor's `accountIds`, then `accountId`, then discovery). The SDK never reads an account id from the environment, so an environment variable cannot silently change which accounts a toolset reaches. To keep yours in `STACKONE_ACCOUNT_ID`, read it yourself:
 
 ```typescript
 import { StackOneToolSet } from '@stackone/ai';
 
-// Simplest: set STACKONE_ACCOUNT_ID environment variable
-const toolset = new StackOneToolSet();
+// Single account, read from your own environment variable. Unset means discovery
+const toolset = new StackOneToolSet({ accountId: process.env.STACKONE_ACCOUNT_ID });
 const tools = await toolset.fetchTools();
 
 // Explicit single account
@@ -125,8 +125,8 @@ npm install @stackone/ai openai  # or: yarn/pnpm/bun add
 import { OpenAI } from 'openai';
 import { StackOneToolSet } from '@stackone/ai';
 
-// Reads STACKONE_API_KEY and STACKONE_ACCOUNT_ID from environment
-const toolset = new StackOneToolSet();
+// Reads STACKONE_API_KEY from the environment. Without an account id, every active account is used
+const toolset = new StackOneToolSet({ accountId: process.env.STACKONE_ACCOUNT_ID });
 
 const tools = await toolset.fetchTools({ actions: ['workday_*'] });
 const openai = new OpenAI();
@@ -163,8 +163,8 @@ npm install @stackone/ai openai  # or: yarn/pnpm/bun add
 import OpenAI from 'openai';
 import { StackOneToolSet } from '@stackone/ai';
 
-// Reads STACKONE_API_KEY and STACKONE_ACCOUNT_ID from environment
-const toolset = new StackOneToolSet();
+// Reads STACKONE_API_KEY from the environment. Without an account id, every active account is used
+const toolset = new StackOneToolSet({ accountId: process.env.STACKONE_ACCOUNT_ID });
 
 const tools = await toolset.fetchTools();
 
@@ -193,8 +193,8 @@ npm install @stackone/ai @anthropic-ai/sdk  # or: yarn/pnpm/bun add
 import Anthropic from '@anthropic-ai/sdk';
 import { StackOneToolSet } from '@stackone/ai';
 
-// Reads STACKONE_API_KEY and STACKONE_ACCOUNT_ID from environment
-const toolset = new StackOneToolSet();
+// Reads STACKONE_API_KEY from the environment. Without an account id, every active account is used
+const toolset = new StackOneToolSet({ accountId: process.env.STACKONE_ACCOUNT_ID });
 
 const tools = await toolset.fetchTools();
 
@@ -232,8 +232,8 @@ import { openai } from '@ai-sdk/openai';
 import { generateText, stepCountIs } from 'ai';
 import { StackOneToolSet } from '@stackone/ai';
 
-// Reads STACKONE_API_KEY and STACKONE_ACCOUNT_ID from environment
-const toolset = new StackOneToolSet();
+// Reads STACKONE_API_KEY from the environment. Without an account id, every active account is used
+const toolset = new StackOneToolSet({ accountId: process.env.STACKONE_ACCOUNT_ID });
 
 const tools = await toolset.fetchTools();
 
@@ -259,8 +259,8 @@ npm install @stackone/ai @anthropic-ai/claude-agent-sdk zod  # or: yarn/pnpm/bun
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { StackOneToolSet } from '@stackone/ai';
 
-// Reads STACKONE_API_KEY and STACKONE_ACCOUNT_ID from environment
-const toolset = new StackOneToolSet();
+// Reads STACKONE_API_KEY from the environment. Without an account id, every active account is used
+const toolset = new StackOneToolSet({ accountId: process.env.STACKONE_ACCOUNT_ID });
 
 // Fetch tools and convert to Claude Agent SDK format
 const tools = await toolset.fetchTools();

examples/README.md

@@ -16,7 +16,7 @@ Set your credentials using either approach:
 
 ```bash
 export STACKONE_API_KEY=your-stackone-api-key
-export STACKONE_ACCOUNT_ID=your-account-id     # optional: accounts are discovered otherwise
+export STACKONE_ACCOUNT_ID=your-account-id     # optional: the examples pass it as accountId
 export OPENAI_API_KEY=your-openai-api-key       # for OpenAI/AI SDK examples
 export ANTHROPIC_API_KEY=your-anthropic-api-key  # for Anthropic examples
 ```
@@ -79,6 +79,6 @@ Walks through every way to configure API keys and account IDs: reading from envi
 | Variable              | Required                     | Used By                                                                             |
 | --------------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
 | `STACKONE_API_KEY`    | Yes                          | All examples                                                                        |
-| `STACKONE_ACCOUNT_ID` | Optional                     | All examples (read automatically; without it, accounts are discovered from the key) |
+| `STACKONE_ACCOUNT_ID` | Optional                     | Read by the examples and passed as `accountId`; without it, accounts are discovered |
 | `OPENAI_API_KEY`      | For OpenAI / AI SDK examples | `openai-integration.ts`, `openai-responses-integration.ts`, `ai-sdk-integration.ts` |
 | `ANTHROPIC_API_KEY`   | For Anthropic examples       | `anthropic-integration.ts`, `claude-agent-sdk-integration.ts`                       |

examples/ai-sdk-integration.ts

@@ -28,8 +28,9 @@ if (!process.env.OPENAI_API_KEY) {
 }
 
 const aiSdkIntegration = async (): Promise<void> => {
-	// Initialize StackOne — reads STACKONE_API_KEY and STACKONE_ACCOUNT_ID from env
-	const toolset = new StackOneToolSet();
+	// Initialize StackOne — reads STACKONE_API_KEY from env. The account id is passed explicitly;
+	// without one, the toolset uses every active account linked to the key
+	const toolset = new StackOneToolSet({ accountId: process.env.STACKONE_ACCOUNT_ID });
 
 	// Filter to specific tools to keep token usage manageable
 	const tools = await toolset.fetchTools({

examples/anthropic-integration.ts

@@ -17,8 +17,9 @@ if (!process.env.ANTHROPIC_API_KEY) {
 }
 
 const anthropicIntegration = async (): Promise<void> => {
-	// Initialize StackOne — reads STACKONE_API_KEY and STACKONE_ACCOUNT_ID from env
-	const toolset = new StackOneToolSet();
+	// Initialize StackOne — reads STACKONE_API_KEY from env. The account id is passed explicitly;
+	// without one, the toolset uses every active account linked to the key
+	const toolset = new StackOneToolSet({ accountId: process.env.STACKONE_ACCOUNT_ID });
 
 	// Filter for any relevant tools
 	const tools = await toolset.fetchTools({

examples/auth-management.ts

@@ -6,7 +6,8 @@
  * Run with:
  *   STACKONE_API_KEY=xxx npx tsx examples/auth-management.ts
  *
- * STACKONE_ACCOUNT_ID is optional: without it, accounts are discovered from the API key.
+ * STACKONE_ACCOUNT_ID is optional, and only read by this example: the SDK never reads it. Without
+ * it, accounts are discovered from the API key.
  */
 
 import process from 'node:process';
@@ -21,7 +22,7 @@ if (!process.env.STACKONE_API_KEY) {
 const apiKeyFromEnv = async (): Promise<void> => {
 	console.log('=== 1a. API Key from environment ===\n');
 
-	// Reads STACKONE_API_KEY (and STACKONE_ACCOUNT_ID, if set) from env automatically
+	// Reads STACKONE_API_KEY from env automatically. No account is configured, so it discovers them
 	const toolset = new StackOneToolSet();
 	const tools = await toolset.fetchTools();
 	console.log(`  Loaded ${tools.toOpenAI().length} tools using env API key\n`);
@@ -51,11 +52,12 @@ const apiKeyAlone = async (): Promise<void> => {
 const accountIdFromEnv = async (): Promise<void> => {
 	console.log('=== 2. Account ID from environment ===\n');
 
-	// The Node SDK reads STACKONE_ACCOUNT_ID from env automatically
+	// The SDK only reads the API key from env; read the account id yourself and pass it.
+	// Unset, it is undefined and the toolset discovers every active account instead.
 	const accountId = process.env.STACKONE_ACCOUNT_ID;
 	console.log(`  STACKONE_ACCOUNT_ID is ${accountId ? 'set' : 'not set'}`);
 
-	const toolset = new StackOneToolSet();
+	const toolset = new StackOneToolSet({ accountId });
 	const tools = await toolset.fetchTools();
 	console.log(`  Loaded ${tools.toOpenAI().length} tools for account from env\n`);
 };

examples/claude-agent-sdk-integration.ts

@@ -23,8 +23,9 @@ if (!process.env.ANTHROPIC_API_KEY) {
 }
 
 const claudeAgentSdkIntegration = async (): Promise<void> => {
-	// Initialize StackOne — reads STACKONE_API_KEY and STACKONE_ACCOUNT_ID from env
-	const toolset = new StackOneToolSet();
+	// Initialize StackOne — reads STACKONE_API_KEY from env. The account id is passed explicitly;
+	// without one, the toolset uses every active account linked to the key
+	const toolset = new StackOneToolSet({ accountId: process.env.STACKONE_ACCOUNT_ID });
 
 	// Fetch tools from StackOne and convert to Claude Agent SDK format
 	const tools = await toolset.fetchTools();

examples/openai-integration.ts

@@ -17,8 +17,9 @@ if (!process.env.OPENAI_API_KEY) {
 }
 
 const openaiIntegration = async (): Promise<void> => {
-	// Initialize StackOne — reads STACKONE_API_KEY and STACKONE_ACCOUNT_ID from env
-	const toolset = new StackOneToolSet();
+	// Initialize StackOne — reads STACKONE_API_KEY from env. The account id is passed explicitly;
+	// without one, the toolset uses every active account linked to the key
+	const toolset = new StackOneToolSet({ accountId: process.env.STACKONE_ACCOUNT_ID });
 
 	// Filter to specific tools to stay within OpenAI's 128-tool limit
 	const tools = await toolset.fetchTools({

examples/openai-responses-integration.ts

@@ -17,8 +17,9 @@ if (!process.env.OPENAI_API_KEY) {
 }
 
 const openaiResponsesIntegration = async (): Promise<void> => {
-	// Initialize StackOne — reads STACKONE_API_KEY and STACKONE_ACCOUNT_ID from env
-	const toolset = new StackOneToolSet();
+	// Initialize StackOne — reads STACKONE_API_KEY from env. The account id is passed explicitly;
+	// without one, the toolset uses every active account linked to the key
+	const toolset = new StackOneToolSet({ accountId: process.env.STACKONE_ACCOUNT_ID });
 
 	// Fetch tools via MCP
 	const tools = await toolset.fetchTools({