### Run All Examples

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/examples/README.md

Command to execute all tests in the examples directory using Bun.

```bash
# Test all examples
bun test examples/
```

--------------------------------

### Running Example Tests

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/examples/README.md

Shows how to execute the example test suite using the 'bun test' command, including options for verbose output and running specific test files.

```bash
# Run all example tests
bun test examples/

# Run with verbose output
bun test examples/ --verbose

# Run specific test
bun test examples/examples.spec.ts
```

--------------------------------

### Run Individual Examples

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/examples/README.md

Commands to run specific example files using Bun or tsx.

```bash
# Run a specific example
bun run examples/ai-sdk-integration.ts

# Or with Node.js
npx tsx examples/ai-sdk-integration.ts
```

--------------------------------

### Installation

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Instructions for installing the StackOne AI SDK using npm, yarn, or bun.

```bash
# Using npm
npm install @stackone/ai

# Using yarn
yarn add @stackone/ai

# Using bun
bun add @stackone/ai
```

--------------------------------

### Clone Repository

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/examples/README.md

Clones the StackOne AI Node.js SDK repository from GitHub.

```bash
git clone https://github.com/StackOneHQ/stackone-ai-node.git
```

--------------------------------

### Set StackOne API Key

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/examples/README.md

Sets the StackOne API key as an environment variable or in a .env file for authentication.

```bash
export STACKONE_API_KEY=your_api_key_here
```

```env
STACKONE_API_KEY=your_api_key_here
```

--------------------------------

### Set OpenAI API Key

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/examples/README.md

Sets the OpenAI API key as an environment variable or in a .env file for OpenAI integrations.

```bash
export OPENAI_API_KEY=your_api_key_here
```

```env
OPENAI_API_KEY=your_api_key_here
```

--------------------------------

### Development Workflow

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/CLAUDE.md

Outlines the typical development cycle for the StackOne AI Node SDK, from fetching OpenAPI specs to committing generated files.

```plaintext
1. OpenAPI specs are fetched from remote sources and stored in `specs/`
2. TypeScript types are generated from these specs into `src/openapi/generated/`
3. The parser transforms OpenAPI operations into Tool instances at runtime
4. Tools can be used directly or through framework-specific adapters

When modifying the codebase:
- Run tests frequently during development
- Use `bun run rebuild` after updating OpenAPI specs
- Ensure all generated files are committed (they're not gitignored)
- Follow the existing patterns for error handling and logging
```

--------------------------------

### Meta Tools: Basic Usage with AI SDK

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Provides a basic example of how to obtain meta tools from StackOneToolSet and prepare them for use with an AI SDK like the AI SDK from Vercel.

```typescript
import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet();
const tools = toolset.getStackOneTools("*", "account-id");

// Get meta tools for dynamic discovery
const metaTools = await tools.metaTools();

// Use with OpenAI
const openAITools = metaTools.toOpenAI();

// Use with AI SDK
const aiSdkTools = metaTools.toAISDK();
```

--------------------------------

### Common Development Commands

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/CLAUDE.md

A collection of essential commands for building, testing, maintaining code quality, and managing documentation within the StackOne AI Node project.

```bash
bun run build
bun run rebuild
bun run dev
bun run fetch:specs
```

```bash
bun run test
bun run test:unit
bun test src/path/to/file.spec.ts
bun test -t "test name"
```

```bash
bun run lint
bun run format
bun run typecheck
bun run lint:fix
```

```bash
bun run docs:build
bun run docs:serve
bun run docs:deploy
```

--------------------------------

### OpenAPIToolSet: Loading from a File

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Shows how to initialize and use the OpenAPIToolSet by loading an OpenAPI specification from a local file path. It covers getting all tools and filtering tools by a pattern.

```typescript
import { OpenAPIToolSet } from "@stackone/ai";
import path from "node:path";

// Create the toolset
const toolset = new OpenAPIToolSet({
  filePath: path.join(import.meta.dirname, "path/to/openapi-spec.json");
});

// Get all tools
const allTools = toolset.getTools();

// Get filtered tools
const filteredTools = toolset.getTools("user_*");
```

--------------------------------

### OpenAI Integration

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Example of integrating StackOneToolSet with OpenAI's library to use SaaS tools as OpenAI functions.

```typescript
import { OpenAI } from "openai";
import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet();

const tools = toolset.getTools("hris_*", "<stackone-account-id>").toOpenAI();

await openai.chat.completions.create({
  model: "gpt-5",
  messages: [
    {
      role: "system",
      content: "You are a helpful HR assistant.",
    },
    {
      role: "user",
      content: "Create a time-off request for employee id cxIQ5764hj2",
    },
  ],
  tools: tools,
});
```

--------------------------------

### Account ID Management

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/examples/README.md

Illustrates various methods for providing and managing account IDs within the StackOne SDK, including initialization, tool retrieval, and direct tool setting.

```typescript
// 1. At toolset initialization
const toolset = new StackOneToolSet({ accountId: "account_123" });

// 2. When getting tools
const tools = toolset.getStackOneTools("hris_*"), "account_123");

// 3. Directly on individual tools
tool.setAccountId("account_123");
```

--------------------------------

### Meta Tools: Dynamic Tool Discovery with AI SDK

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Shows an example of using meta tools with the AI SDK to dynamically discover and execute tools based on a natural language prompt. It includes setting the model and maxSteps.

```typescript
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai("gpt-4o-mini"),
  tools: aiSdkTools,
  prompt: "Find tools for managing employees and create a time off request",
  maxSteps: 3, // Allow multiple tool calls
});
```

--------------------------------

### AI SDK by Vercel Integration

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Example of integrating StackOneToolSet with Vercel's AI SDK for use in AI applications.

```typescript
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";
import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet();

const aiSdkTools = toolset.getTools("hris_*").toAISDK();
await generateText({
  model: openai("gpt-5"),
  tools: aiSdkTools,
  maxSteps: 3,
});
```

--------------------------------

### Configure Account IDs

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/examples/README.md

Defines and configures account IDs for various integrations like HRIS, ATS, CRM, and Documents within the constants.ts file.

```typescript
export const ACCOUNT_IDS = {
  // Human Resources Information System
  HRIS: "your_hris_account_id",

  // Applicant Tracking System
  ATS: "your_ats_account_id",

  // Customer Relationship Management
  CRM: "your_crm_account_id",

  // Document Management System
  DOCUMENTS: "your_documents_account_id",

  // Test account IDs (used in examples that don't make real API calls)
  TEST: {
    VALID: "test_account_id",
    OVERRIDE: "test_account_id_override",
    DIRECT: "test_account_id_direct",
    INVALID: "invalid_test_account_id",
  },
};
```

--------------------------------

### Dry Run for Testing

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/examples/README.md

Demonstrates how to use the dry run mode to inspect API requests without executing them. This is useful for testing and debugging.

```typescript
const result = await tool.execute(params, { dryRun: true });
console.log(result.url); // The URL that would be called
console.log(result.method); // HTTP method
console.log(result.headers); // Request headers
console.log(result.body); // Request body
```

--------------------------------

### Key Design Patterns

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/CLAUDE.md

Highlights the core design principles employed in the StackOne AI Node SDK, emphasizing schema-driven development and framework agnosticism.

```plaintext
Schema-First: Everything is driven by JSON Schema definitions from OpenAPI specs
Type Safety: Comprehensive TypeScript types generated from OpenAPI ensure compile-time safety
Framework Agnostic: Core logic is independent of AI frameworks, with adapters for OpenAI and Vercel AI
Lazy Loading: Tools are created on-demand to minimize memory usage
Extensibility: Hooks for parameter transformation and pre-execution logic
```

--------------------------------

### Error Handling

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/examples/README.md

Provides a robust error handling mechanism for API calls using StackOneAPIError. It differentiates between API-specific errors and other unexpected errors.

```typescript
try {
  const result = await tool.execute(params);
  // Handle success
} catch (error) {
  if (error instanceof StackOneAPIError) {
    console.error("API Error:", error.statusCode, error.responseBody);
  } else {
    console.error("Unexpected error:", error.message);
  }
}
```

--------------------------------

### File Upload with StackOneToolSet

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Demonstrates how to use the StackOneToolSet for file uploads. It shows how to get the 'storage_file_upload' tool and execute it with a file path, automatically deriving other file properties.

```typescript
import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet();
const tools = toolset.getTools("*file_upload*");
const fileUploadTool = tools.getTool("storage_file_upload");

// Execute with just the file_path parameter
// The file_content, file_name, and file_format will be derived automatically
const result = await fileUploadTool.execute({ file_path: "/path/to/file.pdf" });
```

--------------------------------

### Testing Strategy

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/CLAUDE.md

Explains the testing approach for the StackOne AI Node SDK, utilizing Bun's test runner and common testing techniques like mocking and snapshot testing.

```plaintext
Tests use Bun's built-in test runner with a Jest-compatible API.
Key patterns:
- Mock HTTP requests using `bun:test` mock functions
- Snapshot testing for generated outputs
- Comprehensive unit tests for parsing logic
- Integration tests with example usage
```

--------------------------------

### StackOne AI Node Architecture Overview

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/CLAUDE.md

Details the core components and design patterns of the StackOne AI Node SDK, which transforms OpenAPI specifications into AI-friendly tools.

```typescript
// src/tool.ts
// The fundamental building block that wraps API operations into a format consumable by AI agents.
// Each tool represents a single API endpoint with schema validation and execution logic.
```

```typescript
// src/toolsets/
// Collections of tools that work together
// OpenAPIToolSet: Generic toolset that can parse any OpenAPI spec
// StackOneToolSet: Pre-configured toolset for StackOne's unified APIs (ATS, CRM, HRIS, etc.)
```

```typescript
// src/openapi/
// loader.ts: Fetches and loads OpenAPI specifications
// parser.ts: Transforms OpenAPI operations into Tool instances
// generated/: Auto-generated TypeScript definitions from OpenAPI specs
```

```typescript
// src/modules/requestBuilder.ts
// Handles the complex logic of transforming tool inputs into properly formatted HTTP requests,
// including file uploads and authentication.
```

--------------------------------

### StackOneToolSet Basic Usage

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Demonstrates basic usage of the StackOneToolSet to retrieve and execute a specific tool.

```typescript
import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet();
const tools = toolset.getTools("hris_*", "your-account-id");
const employeeTool = tools.getTool("hris_list_employees");
const employees = await employeeTool.execute();
```

--------------------------------

### StackOne API Key Authentication

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Instructions for setting the STACKONE_API_KEY environment variable for authentication.

```bash
export STACKONE_API_KEY=<your-api-key>
```

--------------------------------

### OpenAPIToolSet: Loading from a URL

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Demonstrates how to load an OpenAPI specification from a remote URL using the `fromUrl` factory method of the OpenAPIToolSet.

```typescript
import { OpenAPIToolSet } from "@stackone/ai";

// Create the toolset using the factory method
const toolset = await OpenAPIToolSet.fromUrl({
  url: "https://example.com/path/to/openapi-spec.json",
});
```

--------------------------------

### Meta Tools: Direct Usage Without AI SDK

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Demonstrates how to use meta tools directly for tool discovery and execution without integrating with an AI SDK. It covers searching for tools and then executing a specific discovered tool.

```typescript
// Step 1: Discover relevant tools
const filterTool = metaTools.getTool("meta_search_tools");
const searchResult = await filterTool.execute({
  query: "employee time off vacation",
  limit: 5,
  minScore: 0.3, // Minimum relevance score (0-1)
});

// Step 2: Execute a discovered tool
const executeTool = metaTools.getTool("meta_execute_tool");
const result = await executeTool.execute({
  toolName: "hris_create_time_off",
  params: {
    employeeId: "emp_123",
    startDate: "2024-01-15",
    endDate: "2024-01-19",
  },
});
```

--------------------------------

### OpenAPIToolSet: Basic Authentication

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Illustrates how to configure Basic Authentication for the OpenAPIToolSet when loading specifications from a file.

```typescript
// Basic Authentication
const toolsetWithBasicAuth = new OpenAPIToolSet({
  filePath: "path/to/spec.json",
  authentication: {
    type: "basic",
    credentials: {
      username: "user",
      password: "pass",
    },
  },
});
```

--------------------------------

### StackOne Account ID Management

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Demonstrates different methods for setting the StackOne account ID, including initialization, tool retrieval, and direct tool instance setting.

```typescript
import { StackOneToolSet } from "@stackone/ai";

// Method 1: Set at toolset initialization
const toolset = new StackOneToolSet({ accountId: "your-account-id" });

// Method 2: Set when getting tools (overrides toolset account ID)
const tools = toolset.getTools("hris_*", "override-account-id");

// Method 3: Set directly on a tool instance
tools.setAccountId("direct-account-id");
const currentAccountId = tools.getAccountId(); // Get the current account ID
```

--------------------------------

### OpenAPIToolSet: Custom Headers

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Demonstrates how to directly set custom headers, such as Authorization, for the OpenAPIToolSet.

```typescript
const toolsetWithHeaders = new OpenAPIToolSet({
  filePath: "path/to/spec.json",
  headers: {
    Authorization: "Bearer your-bearer-token",
  },
});
```

--------------------------------

### OpenAPIToolSet: Bearer Authentication

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Shows how to configure Bearer Authentication for the OpenAPIToolSet when loading specifications from a URL.

```typescript
// Bearer Authentication
const toolsetWithBearerAuth = await OpenAPIToolSet.fromUrl({
  url: "https://example.com/spec.json",
  authentication: {
    type: "bearer",
    credentials: {
      token: "your-bearer-token",
    },
  },
});
```

--------------------------------

### Advanced Parameter Transformations with Schema Override and PreExecute

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Demonstrates how to simplify complex file upload parameters for a tool by overriding the schema and transforming parameters before execution. This involves defining a schema override to change input parameters and a preExecute function to convert simplified inputs back to the required API format.

```typescript
import { StackOneToolSet } from "@stackone/ai";
import type {
  Experimental_SchemaOverride,
  Experimental_PreExecuteFunction,
} from "@stackone/ai";

// 1. Schema Override: Simplify the input schema
const documentSchemaOverride: Experimental_SchemaOverride = (
  originalSchema
) => {
  // Replace complex file parameters with simple doc_id
  const newProperties = { ...originalSchema.properties };
  delete newProperties.content;
  delete newProperties.name;
  delete newProperties.file_format;

  newProperties.doc_id = {
    type: "string",
    description: "Document path or identifier",
  };

  return { ...originalSchema, properties: newProperties };
};

// 2. PreExecute: Transform the simplified parameters back to API format
const documentPreExecute: Experimental_PreExecuteFunction = async (params) => {
  const { doc_id, ...otherParams } = params;

  // Read file and convert to required API format
  const fileContent = readFileSync(doc_id);
  const base64Content = fileContent.toString("base64");
  const fileName = basename(doc_id);
  const extension = extname(doc_id).slice(1);

  return {
    ...otherParams,
    content: base64Content,
    name: fileName,
    file_format: { value: extension },
  };
};

// Use the experimental transformation
const toolset = new StackOneToolSet();
const tools = toolset.getStackOneTools("hris_*", "account_id");

const documentTool = tools.getTool("hris_upload_employee_document", {
  experimental_schemaOverride: documentSchemaOverride,
  experimental_preExecute: documentPreExecute,
});

// Now you can use the simplified schema
const result = await documentTool.execute({
  doc_id: "/path/to/document.pdf", // Simplified input
  id: "employee_123",
  category: { value: "shared" },
});

```

--------------------------------

### Testing Tool Execution with dryRun Option

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Demonstrates how to use the `dryRun` option to inspect the API arguments generated by a tool call without executing the actual API request. This is useful for debugging and understanding how parameters are mapped and transformed.

```javascript
import { StackOneToolSet } from "stackone-ai-node";
import assert from "node:assert";

// Initialize the toolset
const toolset = new StackOneToolSet();
const fileUploadTool = toolset
  .getTools("*file_upload*")
  .getTool("storage_file_upload");

// Use dryRun to see how the file path is derived into other parameters
const dryRunResult = await fileUploadTool.execute(
  { file_path: "/path/to/file.pdf" },
  { dryRun: true }
);

// Verify the derived parameters
assert("file_content" in dryRunResult.mappedParams);
assert("file_name" in dryRunResult.mappedParams);
assert("file_format" in dryRunResult.mappedParams);

```

--------------------------------

### StackOneToolSet: Custom Base URL

Source: https://github.com/stackonehq/stackone-ai-node/blob/main/README.md

Illustrates how to configure a custom base URL for the StackOneToolSet, useful for targeting different environments like development or staging.

```typescript
import { StackOneToolSet } from "@stackone/ai";

const toolset = new StackOneToolSet({ baseUrl: "https://api.example-dev.com" });
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.