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