From 36e13af2a13464c7737feaf85ffc9be41564eb78 Mon Sep 17 00:00:00 2001
From: ryoppippi <1560508+ryoppippi@users.noreply.github.com>
Date: Fri, 12 Dec 2025 14:32:30 +0000
Subject: [PATCH 1/6] docs(readme): reorganise structure and add new
integration examples
Reorganise README for improved readability and discoverability:
- Move Development Environment section to the bottom
- Convert integrations to collapsible details sections
- Add Anthropic Claude integration with toAnthropic() usage
- Add OpenAI Responses API integration with toOpenAIResponses()
- Include installation commands within each integration section
- Add bun as a package manager option throughout
- Remove separate "Optional: AI SDK Integration" section
The collapsible sections reduce visual clutter while keeping all
integration documentation easily accessible. Each integration now
includes its required dependencies inline.
---
README.md | 134 +++++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 103 insertions(+), 31 deletions(-)
diff --git a/README.md b/README.md
index ab32b8a..06b2758 100644
--- a/README.md
+++ b/README.md
@@ -21,48 +21,94 @@ yarn add @stackone/ai
# Using pnpm
pnpm add @stackone/ai
+
+# Using bun
+bun add @stackone/ai
```
-### Optional: AI SDK Integration
+## Integrations
+
+The StackOneToolSet makes it super easy to use StackOne APIs as tools in your AI applications.
-If you plan to use the AI SDK integration (Vercel AI SDK), install it separately:
+
+With OpenAI Chat Completions API
```bash
-# Using npm
-npm install ai
+npm install openai # or: yarn add openai / pnpm add openai / bun add openai
+```
-# Using yarn
-yarn add ai
+```typescript
+import { OpenAI } from "openai";
+import { StackOneToolSet } from "@stackone/ai";
-# Using pnpm
-pnpm add ai
+const toolset = new StackOneToolSet({
+ baseUrl: "https://api.stackone.com",
+ accountId: "your-account-id",
+});
+
+const tools = await toolset.fetchTools();
+
+await openai.chat.completions.create({
+ model: "gpt-5.1",
+ messages: [
+ {
+ role: "system",
+ content: "You are a helpful HR assistant using BambooHR.",
+ },
+ {
+ role: "user",
+ content: "Create a time-off request for employee id cxIQ5764hj2",
+ },
+ ],
+ tools: tools.toOpenAI(),
+});
```
-## Development Environment
+[View full example](examples/openai-integration.ts)
-### Using Nix Flake
+
-This project includes a Nix flake for reproducible development environments. If you have Nix installed with flakes enabled, you can use it to set up your development environment:
+
+With OpenAI Responses API
```bash
-# Enter development shell
-nix develop
+npm install openai # or: yarn add openai / pnpm add openai / bun add openai
+```
-# Or use direnv for automatic activation
-echo "use flake" > .envrc
-direnv allow
+```typescript
+import OpenAI from "openai";
+import { StackOneToolSet } from "@stackone/ai";
+
+const toolset = new StackOneToolSet({
+ baseUrl: "https://api.stackone.com",
+ accountId: "your-account-id",
+});
+
+const tools = await toolset.fetchTools();
+
+const openai = new OpenAI();
+
+await openai.responses.create({
+ model: "gpt-5.1",
+ instructions: "You are a helpful HR assistant.",
+ input: "What is the phone number for employee c28xIQ?",
+ tools: tools.toOpenAIResponses(),
+});
```
-The flake provides all necessary development dependencies including Node.js, pnpm, and other build tools.
+[View full example](examples/openai-responses-integration.ts)
-## Integrations
+
-The StackOneToolSet makes it super easy to use StackOne APIs as tools in your AI applications.
+
+With Anthropic Claude
-### With OpenAI library
+```bash
+npm install @anthropic-ai/sdk # or: yarn/pnpm/bun add @anthropic-ai/sdk
+```
```typescript
-import { OpenAI } from "openai";
+import Anthropic from "@anthropic-ai/sdk";
import { StackOneToolSet } from "@stackone/ai";
const toolset = new StackOneToolSet({
@@ -72,25 +118,32 @@ const toolset = new StackOneToolSet({
const tools = await toolset.fetchTools();
-await openai.chat.completions.create({
- model: "gpt-5.1",
+const anthropic = new Anthropic();
+
+await anthropic.messages.create({
+ model: "claude-haiku-4-5-20241022",
+ max_tokens: 1024,
+ system: "You are a helpful HR assistant.",
messages: [
- {
- role: "system",
- content: "You are a helpful HR assistant using BambooHR.",
- },
{
role: "user",
- content: "Create a time-off request for employee id cxIQ5764hj2",
+ content: "What is the phone number for employee c28xIQ?",
},
],
- tools: tools.toOpenAI(),
+ tools: tools.toAnthropic(),
});
```
-[View full example](examples/openai-integration.ts)
+[View full example](examples/anthropic-integration.ts)
+
+
+
+
+With AI SDK by Vercel
-### AI SDK by Vercel
+```bash
+npm install ai @ai-sdk/openai # or: yarn/pnpm/bun add ai @ai-sdk/openai
+```
```typescript
import { openai } from "@ai-sdk/openai";
@@ -113,6 +166,8 @@ await generateText({
[View full example](examples/ai-sdk-integration.ts)
+
+
## Usage
```typescript
@@ -436,3 +491,20 @@ When AI agents use this tool, they will:
5. **Report results**: Show which accounts received the feedback successfully
The tool description includes clear instructions for AI agents to always ask for explicit user consent before submitting feedback.
+
+## Development Environment
+
+### Using Nix Flake
+
+This project includes a Nix flake for reproducible development environments. If you have Nix installed with flakes enabled, you can use it to set up your development environment:
+
+```bash
+# Enter development shell
+nix develop
+
+# Or use direnv for automatic activation
+echo "use flake" > .envrc
+direnv allow
+```
+
+The flake provides all necessary development dependencies including Node.js, pnpm, and other build tools.
From 648a1da8d045ef33a96ce947f7a5415a1f016b9b Mon Sep 17 00:00:00 2001
From: ryoppippi <1560508+ryoppippi@users.noreply.github.com>
Date: Fri, 12 Dec 2025 14:36:17 +0000
Subject: [PATCH 2/6] docs(readme): move Integrations section after Usage
Reorder sections for better logical flow:
1. Installation - how to install the package
2. Usage - basic usage with authentication and account IDs
3. Integrations - framework-specific examples (OpenAI, Anthropic, etc.)
4. Features - advanced functionality
5. Development Environment - contributor setup
Users should understand basic usage patterns before seeing
framework-specific integration examples.
---
README.md | 110 +++++++++++++++++++++++++++---------------------------
1 file changed, 55 insertions(+), 55 deletions(-)
diff --git a/README.md b/README.md
index 06b2758..0cb62fb 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,61 @@ pnpm add @stackone/ai
bun add @stackone/ai
```
+## Usage
+
+```typescript
+import { StackOneToolSet } from "@stackone/ai";
+
+const toolset = new StackOneToolSet({
+ baseUrl: "https://api.stackone.com",
+ accountId: "your-account-id",
+});
+
+const tools = await toolset.fetchTools();
+const employeeTool = tools.getTool("bamboohr_list_employees");
+const employees = await employeeTool.execute();
+```
+
+[View full example](examples/index.ts)
+
+### Authentication
+
+Set the `STACKONE_API_KEY` environment variable:
+
+```bash
+export STACKONE_API_KEY=
+```
+
+or load from a .env file using your preferred environment variable library.
+
+### Account IDs
+
+StackOne uses account IDs to identify different integrations. You can specify the account ID at different levels:
+
+```typescript
+import { StackOneToolSet } from "@stackone/ai";
+
+// Single account - simplest approach
+const toolset = new StackOneToolSet({ accountId: "your-bamboohr-account" });
+const tools = await toolset.fetchTools();
+
+// Multiple accounts - returns tools from both integrations
+const multiAccountToolset = new StackOneToolSet();
+const allTools = await multiAccountToolset.fetchTools({
+ accountIds: ["bamboohr-account-123", "workday-account-456"],
+});
+
+// Filter to specific integration when using multiple accounts
+const bamboohrOnly = await multiAccountToolset.fetchTools({
+ accountIds: ["bamboohr-account-123", "workday-account-456"],
+ actions: ["bamboohr_*"], // Only BambooHR tools
+});
+
+// Set directly on a tool instance
+tools.setAccountId("direct-account-id");
+const currentAccountId = tools.getAccountId(); // Get the current account ID
+```
+
## Integrations
The StackOneToolSet makes it super easy to use StackOne APIs as tools in your AI applications.
@@ -168,61 +223,6 @@ await generateText({
-## Usage
-
-```typescript
-import { StackOneToolSet } from "@stackone/ai";
-
-const toolset = new StackOneToolSet({
- baseUrl: "https://api.stackone.com",
- accountId: "your-account-id",
-});
-
-const tools = await toolset.fetchTools();
-const employeeTool = tools.getTool("bamboohr_list_employees");
-const employees = await employeeTool.execute();
-```
-
-[View full example](examples/index.ts)
-
-### Authentication
-
-Set the `STACKONE_API_KEY` environment variable:
-
-```bash
-export STACKONE_API_KEY=
-```
-
-or load from a .env file using your preferred environment variable library.
-
-### Account IDs
-
-StackOne uses account IDs to identify different integrations. You can specify the account ID at different levels:
-
-```typescript
-import { StackOneToolSet } from "@stackone/ai";
-
-// Single account - simplest approach
-const toolset = new StackOneToolSet({ accountId: "your-bamboohr-account" });
-const tools = await toolset.fetchTools();
-
-// Multiple accounts - returns tools from both integrations
-const multiAccountToolset = new StackOneToolSet();
-const allTools = await multiAccountToolset.fetchTools({
- accountIds: ["bamboohr-account-123", "workday-account-456"],
-});
-
-// Filter to specific integration when using multiple accounts
-const bamboohrOnly = await multiAccountToolset.fetchTools({
- accountIds: ["bamboohr-account-123", "workday-account-456"],
- actions: ["bamboohr_*"], // Only BambooHR tools
-});
-
-// Set directly on a tool instance
-tools.setAccountId("direct-account-id");
-const currentAccountId = tools.getAccountId(); // Get the current account ID
-```
-
## Features
### Filtering Tools with fetchTools()
From 772eb31de0ebe678949249f01a5b1bb0cf3ae02d Mon Sep 17 00:00:00 2001
From: ryoppippi <1560508+ryoppippi@users.noreply.github.com>
Date: Fri, 12 Dec 2025 16:30:54 +0000
Subject: [PATCH 3/6] docs(readme): remove duplicate Optional AI SDK section
Each integration example already includes its own installation
instructions within the collapsible details section.
---
README.md | 15 ---------------
1 file changed, 15 deletions(-)
diff --git a/README.md b/README.md
index a7dae01..f422588 100644
--- a/README.md
+++ b/README.md
@@ -26,21 +26,6 @@ pnpm add @stackone/ai
bun add @stackone/ai
```
-### Optional: AI SDK Integration
-
-If you plan to use the AI SDK integration (Vercel AI SDK), install it separately:
-
-```bash
-# Using npm
-npm install ai
-
-# Using yarn
-yarn add ai
-
-# Using pnpm
-pnpm add ai
-```
-
## Usage
```typescript
From 3a6074c2b396ebc5611d57ec8f94487314a56db5 Mon Sep 17 00:00:00 2001
From: ryoppippi <1560508+ryoppippi@users.noreply.github.com>
Date: Fri, 12 Dec 2025 16:34:55 +0000
Subject: [PATCH 4/6] docs(readme): add @stackone/ai to all integration install
commands
Each integration example now includes @stackone/ai in the npm install
command to ensure users install all required dependencies.
---
README.md | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/README.md b/README.md
index f422588..654bac2 100644
--- a/README.md
+++ b/README.md
@@ -87,7 +87,7 @@ The StackOneToolSet makes it super easy to use StackOne APIs as tools in your AI
With OpenAI Chat Completions API
```bash
-npm install openai # or: yarn add openai / pnpm add openai / bun add openai
+npm install @stackone/ai openai # or: yarn/pnpm/bun add
```
```typescript
@@ -125,7 +125,7 @@ await openai.chat.completions.create({
With OpenAI Responses API
```bash
-npm install openai # or: yarn add openai / pnpm add openai / bun add openai
+npm install @stackone/ai openai # or: yarn/pnpm/bun add
```
```typescript
@@ -157,7 +157,7 @@ await openai.responses.create({
With Anthropic Claude
```bash
-npm install @anthropic-ai/sdk # or: yarn/pnpm/bun add @anthropic-ai/sdk
+npm install @stackone/ai @anthropic-ai/sdk # or: yarn/pnpm/bun add
```
```typescript
@@ -195,7 +195,7 @@ await anthropic.messages.create({
With AI SDK by Vercel
```bash
-npm install ai @ai-sdk/openai # or: yarn/pnpm/bun add ai @ai-sdk/openai
+npm install @stackone/ai ai @ai-sdk/openai # or: yarn/pnpm/bun add
```
```typescript
@@ -225,7 +225,7 @@ await generateText({
With TanStack AI
```bash
-npm install @tanstack/ai @tanstack/ai-openai zod # or: yarn/pnpm/bun add
+npm install @stackone/ai @tanstack/ai @tanstack/ai-openai zod # or: yarn/pnpm/bun add
```
```typescript
@@ -275,7 +275,7 @@ for await (const chunk of stream) {
With Claude Agent SDK
```bash
-npm install @anthropic-ai/claude-agent-sdk zod # or: yarn/pnpm/bun add
+npm install @stackone/ai @anthropic-ai/claude-agent-sdk zod # or: yarn/pnpm/bun add
```
```typescript
From efc0eedec758365b4df891ada7b62991d779ef60 Mon Sep 17 00:00:00 2001
From: ryoppippi <1560508+ryoppippi@users.noreply.github.com>
Date: Fri, 12 Dec 2025 16:35:26 +0000
Subject: [PATCH 5/6] docs(readme): use gpt-5.1 model in TanStack AI example
---
README.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 654bac2..2fced92 100644
--- a/README.md
+++ b/README.md
@@ -257,7 +257,7 @@ const getEmployeeTool = {
const adapter = openai();
const stream = chat({
adapter,
- model: "gpt-4o",
+ model: "gpt-5.1",
messages: [{ role: "user", content: "Get employee with id: abc123" }],
tools: [getEmployeeTool],
});
From 8b1484f47c886310081bad60357f17efe9dc7d6c Mon Sep 17 00:00:00 2001
From: ryoppippi <1560508+ryoppippi@users.noreply.github.com>
Date: Fri, 12 Dec 2025 16:35:43 +0000
Subject: [PATCH 6/6] docs(examples): use gpt-5.1 model in TanStack AI example
---
examples/tanstack-ai-integration.ts | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/examples/tanstack-ai-integration.ts b/examples/tanstack-ai-integration.ts
index b81e7f0..fc20358 100644
--- a/examples/tanstack-ai-integration.ts
+++ b/examples/tanstack-ai-integration.ts
@@ -55,7 +55,7 @@ const tanstackAiIntegration = async (): Promise => {
const adapter = openai();
const stream = chat({
adapter,
- model: 'gpt-4o',
+ model: 'gpt-5.1',
messages: [
{
role: 'user',