This directory contains practical examples demonstrating how to use the StackOne AI SDK across different use cases and integrations.

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

Set your StackOne API key as an environment variable:

export STACKONE_API_KEY=your_api_key_here

Or create a .env file in the project root:

STACKONE_API_KEY=your_api_key_here

Optional: Set an OpenAI API key as an environment variable:

export OPENAI_API_KEY=your_api_key_here

Or create a .env file in the project root:

OPENAI_API_KEY=your_api_key_here

Update the account IDs in constants.ts with your actual integration account IDs:

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",
  },
};

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

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

# Test all examples
bun test examples/

Basic example showing how to initialize the toolset and make your first API call.

• Account ID: HRIS
• API Calls: Yes
• Key Features: Basic tool usage, employee listing

Demonstrates integration with Vercel's AI SDK for building AI agents.

• Account ID: HRIS
• API Calls: Via AI agent
• Key Features: AI SDK tools conversion, automated agent workflows

Shows how to use StackOne tools with OpenAI's function calling.

• Account ID: HRIS
• API Calls: Via OpenAI function calls
• Key Features: OpenAI tools format, function calling

Demonstrates different ways to set and manage account IDs.

• Account ID: TEST (multiple)
• API Calls: No (dry run)
• Key Features: Account ID precedence, override patterns

Shows how to use custom base URLs for development or self-hosted instances.

• Account ID: None
• API Calls: No (dry run)
• Key Features: Custom API endpoints, development setup

Illustrates how to pull the latest tool catalog from StackOne and execute a tool with the fetched definitions.

• Account ID: HRIS
• API Calls: Yes (requires valid credentials)
• Key Features: Catalog refresh, zero local specs, production-style execution

⚠️ EXPERIMENTAL: Advanced document handling with schema overrides.

• Account ID: HRIS
• API Calls: No (dry run)
• Key Features: Schema transformation, file processing, multi-source documents

Demonstrates complex filtering and query parameter serialization.

• Account ID: TEST
• API Calls: No (dry run)
• Key Features: Deep object serialization, complex filters, proxy parameters

Shows how to implement human-in-the-loop workflows for validation.

• Account ID: HRIS
• API Calls: Conditional
• Key Features: Manual approval workflows, UI integration patterns

Demonstrates loading and using OpenAPI specifications directly.

• Account ID: None
• API Calls: No (dry run)
• Key Features: File loading, URL loading, OpenAPI parsing

🚧 CLOSED BETA: Advanced workflow planning with StackOne's planning agent.

• Account ID: ATS, HRIS
• API Calls: Planning API
• Key Features: Multi-step workflows, caching, complex business processes

Comprehensive error handling patterns and best practices.

• Account ID: TEST (invalid)
• API Calls: Intentionally failing calls
• Key Features: Error types, validation, graceful degradation

Examples that are stable and recommended for production use:

• index.ts
• ai-sdk-integration.ts
• openai-integration.ts
• account-id-usage.ts
• custom-base-url.ts
• filters.ts
• error-handling.ts
• openapi-toolset.ts

Examples showcasing advanced or experimental features:

• experimental-document-handling.ts (⚠️ API may change)
• human-in-the-loop.ts

Examples requiring special access:

• planning.ts (🚧 Closed beta only)

Most examples support dry run mode to inspect requests without making API calls:

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

All production examples include proper error handling:

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);
  }
}

Examples demonstrate different ways to provide account IDs:

// 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");

The examples include a comprehensive test suite:

# Run all example tests
bun test examples/

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

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

1. Authentication Errors: Ensure STACKONE_API_KEY is set correctly
2. Account ID Errors: Update account IDs in constants.ts with your actual values
3. Network Errors: Check if you're behind a proxy or firewall
4. TypeScript Errors: Ensure you're using compatible Node.js and TypeScript versions

• Check the main README for general setup instructions
• Review the StackOne documentation
• Open an issue on GitHub for bug reports or feature requests

When adding new examples:

1. Follow the existing naming convention
2. Add the example to this README
3. Include proper error handling
4. Add TypeScript types
5. Test with the examples test suite
6. Update constants.ts if new account IDs are needed

These examples are part of the StackOne AI SDK and are subject to the same license terms.