refactor: flatten client structure and add Zod validation to RPC client

mocks/handlers.ts

@@ -214,6 +214,77 @@ export const handlers = [
  });
  }),
 
+ // ============================================================
+ // StackOne Actions RPC endpoint
+ // ============================================================
+ http.post('https://api.stackone.com/actions/rpc', async ({ request }) => {
+ const authHeader = request.headers.get('Authorization');
+
+ // Check for authentication
+ if (!authHeader || !authHeader.startsWith('Basic ')) {
+ return HttpResponse.json(
+ { error: 'Unauthorized', message: 'Missing or invalid authorization header' },
+ { status: 401 }
+ );
+ }
+
+ const body = (await request.json()) as {
+ action?: string;
+ body?: Record<string, unknown>;
+ headers?: Record<string, string>;
+ path?: Record<string, string>;
+ query?: Record<string, string>;
+ };
+
+ // Validate action is provided
+ if (!body.action) {
+ return HttpResponse.json(
+ { error: 'Bad Request', message: 'Action is required' },
+ { status: 400 }
+ );
+ }
+
+ // Return mock response based on action
+ if (body.action === 'hris_get_employee') {
+ return HttpResponse.json({
+ data: {
+ id: body.path?.id || 'test-id',
+ name: 'Test Employee',
+ ...(body.body || {}),
+ },
+ });
+ }
+
+ if (body.action === 'hris_list_employees') {
+ return HttpResponse.json({
+ data: [
+ { id: '1', name: 'Employee 1' },
+ { id: '2', name: 'Employee 2' },
+ ],
+ });
+ }
+
+ if (body.action === 'test_error_action') {
+ return HttpResponse.json(
+ { error: 'Internal Server Error', message: 'Test error response' },
+ { status: 500 }
+ );
+ }
+
+ // Default response for other actions
+ return HttpResponse.json({
+ data: {
+ action: body.action,
+ received: {
+ body: body.body,
+ headers: body.headers,
+ path: body.path,
+ query: body.query,
+ },
+ },
+ });
+ }),
+
  // ============================================================
  // StackOne Unified HRIS endpoints
  // ============================================================

package.json

@@ -33,7 +33,6 @@
  "dependencies": {
  "@modelcontextprotocol/sdk": "catalog:prod",
  "@orama/orama": "catalog:prod",
- "@stackone/stackone-client-ts": "catalog:prod",
  "json-schema": "catalog:prod"
  },
  "devDependencies": {

pnpm-workspace.yaml

@@ -32,16 +32,12 @@ catalogs:
  prod:
  '@modelcontextprotocol/sdk': ^1.19.1
  '@orama/orama': ^3.1.11
- '@stackone/stackone-client-ts': 4.32.2
  json-schema: ^0.4.0
 
 enablePrePostScripts: true
 
 minimumReleaseAge: 1440
 
-minimumReleaseAgeExclude:
- - '@stackone/stackone-client-ts'
-
 onlyBuiltDependencies:
  - '@biomejs/biome'
  - esbuild

src/rpc-client.spec.ts

@@ -0,0 +1,104 @@
+import { RpcClient } from './rpc-client';
+import { StackOneAPIError } from './utils/errors';
+
+test('should successfully execute an RPC action', async () => {
+ const client = new RpcClient({
+ security: { username: 'test-api-key' },
+ });
+
+ const response = await client.actions.rpcAction({
+ action: 'hris_get_employee',
+ body: { fields: 'name,email' },
+ path: { id: 'emp-123' },
+ });
+
+ // Response matches server's ActionsRpcResponseApiModel structure
+ expect(response).toHaveProperty('data');
+ expect(response.data).toMatchObject({
+ id: 'emp-123',
+ name: 'Test Employee',
+ });
+});
+
+test('should send correct payload structure', async () => {
+ const client = new RpcClient({
+ security: { username: 'test-api-key' },
+ });
+
+ const response = await client.actions.rpcAction({
+ action: 'custom_action',
+ body: { key: 'value' },
+ headers: { 'x-custom': 'header' },
+ path: { id: '123' },
+ query: { filter: 'active' },
+ });
+
+ // Response matches server's ActionsRpcResponseApiModel structure
+ expect(response.data).toMatchObject({
+ action: 'custom_action',
+ received: {
+ body: { key: 'value' },
+ headers: { 'x-custom': 'header' },
+ path: { id: '123' },
+ query: { filter: 'active' },
+ },
+ });
+});
+
+test('should handle list actions with array data', async () => {
+ const client = new RpcClient({
+ security: { username: 'test-api-key' },
+ });
+
+ const response = await client.actions.rpcAction({
+ action: 'hris_list_employees',
+ });
+
+ // Response data can be an array (matches RpcActionResponseData union type)
+ expect(Array.isArray(response.data)).toBe(true);
+ expect(response.data).toMatchObject([
+ { id: expect.any(String), name: expect.any(String) },
+ { id: expect.any(String), name: expect.any(String) },
+ ]);
+});
+
+test('should throw StackOneAPIError on server error', async () => {
+ const client = new RpcClient({
+ security: { username: 'test-api-key' },
+ });
+
+ await expect(
+ client.actions.rpcAction({
+ action: 'test_error_action',
+ })
+ ).rejects.toThrow(StackOneAPIError);
+});
+
+test('should include request body in error for debugging', async () => {
+ const client = new RpcClient({
+ security: { username: 'test-api-key' },
+ });
+
+ await expect(
+ client.actions.rpcAction({
+ action: 'test_error_action',
+ body: { debug: 'data' },
+ })
+ ).rejects.toMatchObject({
+ statusCode: 500,
+ requestBody: { action: 'test_error_action' },
+ });
+});
+
+test('should work with only action parameter', async () => {
+ const client = new RpcClient({
+ security: { username: 'test-api-key' },
+ });
+
+ const response = await client.actions.rpcAction({
+ action: 'simple_action',
+ });
+
+ // Response has data field (server returns { data: { action, received } })
+ expect(response).toHaveProperty('data');
+});

src/rpc-client.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+import { StackOneAPIError } from './utils/errors';
+
+/**
+ * Zod schema for RPC action request validation
+ * @see https://docs.stackone.com/platform/api-reference/actions/make-an-rpc-call-to-an-action
+ */
+const rpcActionRequestSchema = z.object({
+ action: z.string(),
+ body: z.record(z.unknown()).optional(),
+ headers: z.record(z.unknown()).optional(),
+ path: z.record(z.unknown()).optional(),
+ query: z.record(z.unknown()).optional(),
+});
+
+/**
+ * RPC action request payload
+ */
+export type RpcActionRequest = z.infer<typeof rpcActionRequestSchema>;
+
+/**
+ * Zod schema for RPC action response data
+ */
+const rpcActionResponseDataSchema = z.union([
+ z.record(z.unknown()),
+ z.array(z.record(z.unknown())),
+ z.null(),
+]);
+
+/**
+ * Zod schema for RPC action response validation
+ *
+ * The server returns a flexible JSON structure. Known fields:
+ * - `data`: The main response data (object, array, or null)
+ * - `next`: Pagination cursor for fetching next page
+ *
+ * Additional fields from the connector response are passed through.
+ * @see unified-cloud-api/src/unified-api-v2/unifiedAPIv2.service.ts processActionCall
+ */
+const rpcActionResponseSchema = z
+ .object({
+ next: z.string().nullish(),
+ data: rpcActionResponseDataSchema.optional(),
+ })
+ .passthrough();
+
+/**
+ * RPC action response data type - can be object, array of objects, or null
+ */
+export type RpcActionResponseData = z.infer<typeof rpcActionResponseDataSchema>;
+
+/**
+ * RPC action response from the StackOne API
+ * Contains known fields (data, next) plus any additional fields from the connector
+ */
+export type RpcActionResponse = z.infer<typeof rpcActionResponseSchema>;
+
+/**
+ * Zod schema for RPC client configuration validation
+ */
+const rpcClientConfigSchema = z.object({
+ serverURL: z.string().optional(),
+ security: z.object({
+ username: z.string(),
+ password: z.string().optional(),
+ }),
+});
+
+/**
+ * Configuration for the RPC client
+ */
+export type RpcClientConfig = z.infer<typeof rpcClientConfigSchema>;
+
+/**
+ * Custom RPC client for StackOne API.
+ * Replaces the @stackone/stackone-client-ts dependency.
+ *
+ * @see https://docs.stackone.com/platform/api-reference/actions/list-all-actions-metadata
+ * @see https://docs.stackone.com/platform/api-reference/actions/make-an-rpc-call-to-an-action
+ */
+export class RpcClient {
+ private readonly baseUrl: string;
+ private readonly authHeader: string;
+
+ constructor(config: RpcClientConfig) {
+ const validatedConfig = rpcClientConfigSchema.parse(config);
+ this.baseUrl = validatedConfig.serverURL || 'https://api.stackone.com';
+ const username = validatedConfig.security.username;
+ const password = validatedConfig.security.password || '';
+ this.authHeader = `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+ }
+
+ /**
+ * Actions namespace containing RPC methods
+ */
+ readonly actions = {
+ /**
+ * Execute an RPC action
+ * @param request The RPC action request
+ * @returns The RPC action response matching server's ActionsRpcResponseApiModel
+ */
+ rpcAction: async (request: RpcActionRequest): Promise<RpcActionResponse> => {
+ const validatedRequest = rpcActionRequestSchema.parse(request);
+ const url = `${this.baseUrl}/actions/rpc`;
+
+ const requestBody = {
+ action: validatedRequest.action,
+ body: validatedRequest.body,
+ headers: validatedRequest.headers,
+ path: validatedRequest.path,
+ query: validatedRequest.query,
+ } as const satisfies RpcActionRequest;
+
+ const response = await fetch(url, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ Authorization: this.authHeader,
+ 'User-Agent': 'stackone-ai-node',
+ },
+ body: JSON.stringify(requestBody),
+ });
+
+ const responseBody: unknown = await response.json();
+
+ if (!response.ok) {
+ throw new StackOneAPIError(
+ `RPC action failed for ${url}`,
+ response.status,
+ responseBody,
+ requestBody
+ );
+ }
+
+ const validation = rpcActionResponseSchema.safeParse(responseBody);
+
+ if (!validation.success) {
+ throw new StackOneAPIError(
+ `Invalid RPC action response for ${url}`,
+ response.status,
+ responseBody,
+ requestBody
+ );
+ }
+
+ return validation.data;
+ },
+ };
+}