fix!: remove unified API integration and migrate to connector-based naming

[ryoppippi]

Summary

This PR removes the legacy Unified API integration and migrates all tool naming from category-based prefixes (hris_*, ats_*, crm_*) to integration-specific names (bamboohr_*, workday_*, salesforce_*).

What Changed

• Removed unified API handlers: Deleted mocks/handlers.stackone-hris.ts and all unified endpoint mocks
• Tool naming migration: Replaced category prefixes with actual integration provider names across:
  • All mock handlers
  • Test fixtures and assertions
  • Example code
  • README documentation
• Simplified examples: Removed unnecessary tool filtering from single-account examples
• Added validation: Reject unified API tools with clear error message
• Documentation improvements: Added practical multi-account usage examples

Why

The unified API approach (unified_hris_list_employees) is legacy and doesn't align with StackOne's actual integration model where:

• Each account links to a specific provider (BambooHR, Workday, etc.)
• Tools are scoped to provider implementations, not abstract categories
• Version information is tied to specific connectors

Integration-based naming (bamboohr_list_employees) makes:

• Tool filtering more intuitive for end users
• Account configuration requirements clearer
• Multi-account scenarios easier to understand

Testing

All 304 tests pass including new validation test for unified API rejection.

---

Summary by cubic

Removed the legacy Unified API and switched tool/action names from category prefixes (hris_, ats_, crm_) to specific integration names (bamboohr_, workday_, salesforce_) for clarity and alignment with StackOne connectors. Added validation to reject unified_* tools and updated docs, examples, mocks, and tests.

• Refactors

  • Removed unified API handlers and mocks (e.g., handlers.stackone-hris.ts).
  • Renamed tools/actions across codebase to integration-specific names.
  • Updated search/indexing to use “integration” instead of “category”.
  • Changed OAS mock server URL to the base API (removed /unified).
  • Added UNIFIED_API_PREFIX and validation to block unified_* tools.

• Migration

  • Replace hris_, ats_, crm_* with bamboohr_, workday_, salesforce_* (e.g., hris_list_employees → bamboohr_list_employees).
  • Provide accountId for single-account usage; use integration globs for multi-account filtering (e.g., bamboohr_*).
  • Update RPC and test references to new action names.
  • If you see a unified_* tool error, fix the account’s connector/version configuration.
  • Adjust meta tool usage and examples to reference integration names.

^{Written for commit c7ca930. Summary will update automatically on new commits.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/StackOneHQ/stackone-ai-node/@stackone/ai@219

commit: c7ca930

[cubic-dev-ai]

1 issue found across 20 files

Prompt for AI agents (all 1 issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="examples/openai-responses-integration.ts">

<violation number="1" location="examples/openai-responses-integration.ts:25">
P1: Mismatch between fetched tools and expected tool call: The filter `*_list_*` only fetches list operations, but the assertion expects `bamboohr_get_employee` (a get operation) which won&#39;t be available. Either change the filter to include get operations (e.g., `[&#39;*_list_*&#39;, &#39;*_get_*&#39;]`) or update the assertion to expect a list tool.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

[cubic-dev-ai]

P1: Mismatch between fetched tools and expected tool call: The filter *_list_* only fetches list operations, but the assertion expects bamboohr_get_employee (a get operation) which won't be available. Either change the filter to include get operations (e.g., ['*_list_*', '*_get_*']) or update the assertion to expect a list tool.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At examples/openai-responses-integration.ts, line 25:

<comment>Mismatch between fetched tools and expected tool call: The filter `*_list_*` only fetches list operations, but the assertion expects `bamboohr_get_employee` (a get operation) which won&#39;t be available. Either change the filter to include get operations (e.g., `[&#39;*_list_*&#39;, &#39;*_get_*&#39;]`) or update the assertion to expect a list tool.</comment>

<file context>
@@ -20,9 +20,9 @@ const openaiResponsesIntegration = async (): Promise&lt;void&gt; =&gt; {
+	// Fetch tools via MCP
 	const tools = await toolset.fetchTools({
-		actions: [&#39;_list_*&#39;],
+		actions: [&#39;*_list_*&#39;],
 	});
 	const openAIResponsesTools = tools.toOpenAIResponses();
</file context>

Suggested change

	actions: ['*_list_*'],
	actions: ['*_list_*', '*_get_*'],

[Copilot]

Pull request overview

This PR removes the legacy Unified API integration and migrates the codebase from category-based tool naming (e.g., hris_*, ats_*, crm_*) to integration-specific naming (e.g., bamboohr_*, workday_*, salesforce_*). This aligns the naming convention with StackOne's actual integration model where each account is linked to a specific provider.

Key changes:

• Added validation to reject unified API tools with clear error messaging
• Updated all tool references across tests, mocks, examples, and documentation
• Removed the legacy unified HRIS handler and related mock endpoints

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/consts.ts	Added UNIFIED_API_PREFIX constant to identify legacy unified API tools
src/toolsets.ts	Implemented validateToolName method to reject unified API tools during fetch
src/toolsets.test.ts	Added comprehensive test coverage for unified API validation; updated glob pattern tests with integration-specific names
src/tool.ts	Renamed category variable to integration throughout for clarity and accuracy
src/tool.test.ts	Updated all mock tools and test assertions from category-based to integration-specific names
src/utils/tfidf-index.test.ts	Updated test fixtures to use integration-specific tool names
src/rpc-client.test.ts	Updated RPC action test examples to use integration-specific names
mocks/handlers.ts	Removed import and reference to deleted stackoneHrisHandlers
mocks/handlers.stackone-hris.ts	Deleted entire file containing legacy unified HRIS endpoint handlers
mocks/handlers.stackone-rpc.ts	Updated mock RPC handlers to use integration-specific action names
mocks/handlers.stackone-ai.ts	Updated AI handler mocks with integration-specific tool names and adjusted server URL
mocks/handlers.openai.ts	Updated OpenAI mock handlers to return integration-specific tool calls
examples/index.ts	Simplified quickstart to fetch all account tools; updated tool name references
examples/openai-integration.ts	Removed unnecessary filtering; updated account ID placeholder and assertions
examples/openai-responses-integration.ts	Updated account ID placeholder, tool name assertions, and filter pattern
examples/ai-sdk-integration.ts	Removed unnecessary filtering; updated account ID placeholder
examples/fetch-tools.ts	Updated tool name examples to use integration-specific names
examples/meta-tools.ts	Updated all account ID placeholders, tool filters, and tool name references to integration-specific naming
examples/planning.ts	Updated account ID variable names and values; changed tool filters to integration-specific patterns
README.md	Added accountId to examples; updated system prompt references; improved multi-account usage documentation with practical examples

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[glebedel]

Please double check that the actions in the example actually exist for Bamboohr (not sure if it was just a replace of hris_ or if you took a real action name)