@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/python/client.test.ts

@@ -0,0 +1,320 @@
+/**
+ * Tests for Python client binding injection.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { z } from 'zod';
+import { PythonClientImpl } from './client.js';
+import type { IntegrationConfig } from '../types.js';
+import type { QueryExecutor } from '../registry.js';
+
+/** Helper to compute expected base64-encoded json.loads preamble. */
+function expectedBindingsLine(bindings: Record<string, unknown>): string {
+  const b64 = Buffer.from(JSON.stringify(bindings)).toString('base64');
+  return `_bindings = json.loads(base64.b64decode('${b64}').decode())`;
+}
+
+describe('PythonClientImpl', () => {
+  const createMockConfig = (): IntegrationConfig => ({
+    id: 'test-python-id',
+    name: 'Test Python',
+    pluginId: 'python',
+    configuration: {},
+  });
+
+  const createMockExecutor = (mockResult: unknown): QueryExecutor => {
+    return vi.fn().mockResolvedValue(mockResult);
+  };
+
+  describe('binding injection', () => {
+    it('generates code without bindings when none provided', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ result: 42 });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      await client.run(
+        'return {"result": 42}',
+        z.object({ result: z.number() })
+      );
+
+      expect(mockExecutor).toHaveBeenCalledWith({
+        body: 'return {"result": 42}',
+      });
+    });
+
+    it('injects string bindings as Python variables', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ message: 'Hello World' });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { greeting: 'Hello World' };
+      await client.run(
+        'return {"message": greeting}',
+        z.object({ message: z.string() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      expect(request.body).toContain('import json, base64');
+      expect(request.body).toContain(expectedBindingsLine(bindings));
+      expect(request.body).toContain("greeting = _bindings['greeting']");
+      expect(request.body).toContain('return {"message": greeting}');
+    });
+
+    it('injects number bindings as Python variables', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ result: 14 });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { number: 10 };
+      await client.run(
+        'return {"result": number + 4}',
+        z.object({ result: z.number() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      expect(request.body).toContain('import json, base64');
+      expect(request.body).toContain(expectedBindingsLine(bindings));
+      expect(request.body).toContain("number = _bindings['number']");
+      expect(request.body).toContain('return {"result": number + 4}');
+    });
+
+    it('injects boolean bindings as Python variables', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ active: true });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { isActive: true };
+      await client.run(
+        'return {"active": isActive}',
+        z.object({ active: z.boolean() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      expect(request.body).toContain('import json, base64');
+      expect(request.body).toContain(expectedBindingsLine(bindings));
+      expect(request.body).toContain("isActive = _bindings['isActive']");
+      expect(request.body).toContain('return {"active": isActive}');
+    });
+
+    it('injects null bindings as Python variables', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ value: null });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { nullValue: null };
+      await client.run(
+        'return {"value": nullValue}',
+        z.object({ value: z.null() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      expect(request.body).toContain('import json, base64');
+      expect(request.body).toContain(expectedBindingsLine(bindings));
+      expect(request.body).toContain("nullValue = _bindings['nullValue']");
+      expect(request.body).toContain('return {"value": nullValue}');
+    });
+
+    it('injects array bindings as Python variables', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ count: 3 });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { items: [1, 2, 3] };
+      await client.run(
+        'return {"count": len(items)}',
+        z.object({ count: z.number() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      expect(request.body).toContain('import json, base64');
+      expect(request.body).toContain(expectedBindingsLine(bindings));
+      expect(request.body).toContain("items = _bindings['items']");
+      expect(request.body).toContain('return {"count": len(items)}');
+    });
+
+    it('injects object bindings as Python variables', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ name: 'John' });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { user: { name: 'John', age: 30 } };
+      await client.run(
+        'return {"name": user["name"]}',
+        z.object({ name: z.string() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      expect(request.body).toContain('import json, base64');
+      expect(request.body).toContain(expectedBindingsLine(bindings));
+      expect(request.body).toContain("user = _bindings['user']");
+      expect(request.body).toContain('return {"name": user["name"]}');
+    });
+
+    it('injects multiple bindings as Python variables', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ message: 'Alice is 25 years old' });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { userName: 'Alice', userAge: 25 };
+      await client.run(
+        'return {"message": f"{userName} is {userAge} years old"}',
+        z.object({ message: z.string() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      expect(request.body).toContain('import json, base64');
+      expect(request.body).toContain(expectedBindingsLine(bindings));
+      expect(request.body).toContain("userName = _bindings['userName']");
+      expect(request.body).toContain("userAge = _bindings['userAge']");
+      expect(request.body).toContain('return {"message": f"{userName} is {userAge} years old"}');
+    });
+
+    it('handles strings with special characters', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ text: "It's a \"test\"" });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { text: "It's a \"test\"" };
+      await client.run(
+        'return {"text": text}',
+        z.object({ text: z.string() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      expect(request.body).toContain('import json, base64');
+      // Base64 encoding avoids all string escaping issues
+      expect(request.body).toContain(expectedBindingsLine(bindings));
+      expect(request.body).toContain("text = _bindings['text']");
+      expect(request.body).toContain('return {"text": text}');
+    });
+
+    it('handles strings with newlines and tabs', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ text: 'line1\nline2\ttab' });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { text: 'line1\nline2\ttab' };
+      await client.run(
+        'return {"text": text}',
+        z.object({ text: z.string() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      // Base64 encoding handles newlines/tabs safely
+      expect(request.body).toContain(expectedBindingsLine(bindings));
+      expect(request.body).toContain("text = _bindings['text']");
+    });
+
+    it('handles strings with backslashes', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ path: 'C:\\Users\\test' });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { path: 'C:\\Users\\test' };
+      await client.run(
+        'return {"path": path}',
+        z.object({ path: z.string() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      // Base64 encoding handles backslashes safely
+      expect(request.body).toContain(expectedBindingsLine(bindings));
+      expect(request.body).toContain("path = _bindings['path']");
+    });
+
+    it('preserves code structure with blank line between preamble and user code', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ result: 42 });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { number: 21 };
+      await client.run(
+        'result = number * 2\nreturn {"result": result}',
+        z.object({ result: z.number() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      const lines = (request.body as string).split('\n');
+
+      // Should have: import, _bindings assignment, variable extraction, blank line, then user code
+      expect(lines[0]).toBe('import json, base64');
+      expect(lines[1]).toBe(expectedBindingsLine(bindings));
+      expect(lines[2]).toBe("number = _bindings['number']");
+      expect(lines[3]).toBe('');
+      expect(lines[4]).toBe('result = number * 2');
+    });
+  });
+
+  describe('validation', () => {
+    it('validates result against schema', async () => {
+      const mockExecutor = createMockExecutor({ result: 42 });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const result = await client.run(
+        'return {"result": 42}',
+        z.object({ result: z.number() })
+      );
+
+      expect(result).toEqual({ result: 42 });
+    });
+
+    it('throws CodeExecutionError when validation fails', async () => {
+      const mockExecutor = createMockExecutor({ result: 'not a number' });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      await expect(
+        client.run(
+          'return {"result": "not a number"}',
+          z.object({ result: z.number() })
+        )
+      ).rejects.toThrow('Python execution result validation failed');
+    });
+
+    it('throws CodeExecutionError when execution fails', async () => {
+      const mockExecutor = vi.fn().mockRejectedValue(new Error('Execution error'));
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      await expect(
+        client.run(
+          'return {"result": 42}',
+          z.object({ result: z.number() })
+        )
+      ).rejects.toThrow('Python execution failed');
+    });
+  });
+
+  describe('complex bindings', () => {
+    it('handles nested objects', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ name: 'John Doe' });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { person: { first: 'John', last: 'Doe', address: { city: 'NYC' } } };
+      await client.run(
+        'return {"name": f"{person[\'first\']} {person[\'last\']}"}',
+        z.object({ name: z.string() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      expect(request.body).toContain('import json, base64');
+      expect(request.body).toContain(expectedBindingsLine(bindings));
+      expect(request.body).toContain("person = _bindings['person']");
+    });
+
+    it('handles arrays of objects', async () => {
+      const mockExecutor = vi.fn().mockResolvedValue({ count: 2 });
+      const client = new PythonClientImpl(createMockConfig(), mockExecutor);
+
+      const bindings = { users: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }] };
+      await client.run(
+        'return {"count": len(users)}',
+        z.object({ count: z.number() }),
+        bindings
+      );
+
+      const request = mockExecutor.mock.calls[0][0];
+      expect(request.body).toContain('import json, base64');
+      expect(request.body).toContain(expectedBindingsLine(bindings));
+      expect(request.body).toContain("users = _bindings['users']");
+    });
+  });
+});

package/src/integrations/python/client.ts

@@ -0,0 +1,127 @@
+/**
+ * Python client implementation.
+ *
+ * Executes Python code via the orchestrator with type-safe bindings.
+ */
+
+import type { z } from 'zod';
+import type { PartialMessage } from '@bufbuild/protobuf';
+import type { Plugin as PythonPlugin } from '@superblocksteam/types/dist/src/plugins/python/v1/plugin_pb';
+import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
+import type { QueryExecutor } from '../registry.js';
+import type { PythonClient } from './types.js';
+import { CodeExecutionError } from '../../errors.js';
+
+/**
+ * Python plugin request type derived from proto definition.
+ * Using PartialMessage allows optional fields.
+ */
+export type PythonRequest = PartialMessage<PythonPlugin>;
+
+/**
+ * Internal implementation of PythonClient.
+ *
+ * This implementation communicates with the orchestrator to execute Python code.
+ * The orchestrator handles {{}} binding resolution and script execution.
+ */
+export class PythonClientImpl implements PythonClient, IntegrationClientImpl {
+  readonly name: string;
+  readonly pluginId: string;
+  readonly config: IntegrationConfig;
+
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.name = config.name;
+    this.pluginId = config.pluginId;
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  /**
+   * Build Python plugin request with injected bindings.
+   *
+   * Bindings are injected as Python variables in a preamble before the user code.
+   * This allows the user code to reference binding keys directly as Python variables.
+   *
+   * @param code - User's Python code string
+   * @param bindings - Bindings to inject as Python variables
+   * @returns Request object matching the proto schema with bindings injected
+   */
+  private buildRequest(code: string, bindings?: Record<string, unknown>): PythonRequest {
+    // If no bindings, just return the code as-is
+    if (!bindings || Object.keys(bindings).length === 0) {
+      return {
+        body: code,
+      };
+    }
+
+    // Inject bindings as Python variables using base64 to avoid string escaping issues.
+    // Format: import json,base64\n_bindings = json.loads(base64.b64decode('...').decode())\nvar1 = _bindings['var1']\n...\n\n<user code>
+    const bindingLines: string[] = ['import json, base64'];
+
+    // Base64-encode the JSON to avoid issues with special characters (\n, \t, \\, quotes)
+    // that JSON.stringify produces and Python's string parser would interpret
+    const bindingsB64 = Buffer.from(JSON.stringify(bindings)).toString('base64');
+    bindingLines.push(`_bindings = json.loads(base64.b64decode('${bindingsB64}').decode())`);
+
+    // Extract each binding as a local variable
+    for (const key of Object.keys(bindings)) {
+      bindingLines.push(`${key} = _bindings['${key}']`);
+    }
+
+    // Combine binding preamble with user code
+    const fullCode = `${bindingLines.join('\n')}\n\n${code}`;
+
+    return {
+      body: fullCode,
+    };
+  }
+
+  async run<T>(
+    code: string,
+    schema: z.ZodSchema<T>,
+    bindings?: Record<string, unknown>
+  ): Promise<T> {
+    // Build request with bindings injected as Python variables
+    const request = this.buildRequest(code, bindings);
+
+    try {
+      // Execute the Python code with injected bindings
+      // No need to pass bindings as input since they're already in the code
+      const result = await this.executeQuery(
+        request as unknown as Record<string, unknown>
+      );
+
+      // Validate result against schema
+      const parseResult = schema.safeParse(result);
+
+      if (!parseResult.success) {
+        throw new CodeExecutionError(
+          `Python execution result validation failed: ${parseResult.error.message}`,
+          {
+            code,
+            bindings,
+            result,
+            zodError: parseResult.error,
+          }
+        );
+      }
+
+      return parseResult.data;
+    } catch (error) {
+      if (error instanceof CodeExecutionError) {
+        throw error;
+      }
+
+      throw new CodeExecutionError(
+        'Python execution failed',
+        {
+          code,
+          bindings,
+          originalError: error,
+        }
+      );
+    }
+  }
+}

package/src/integrations/python/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Python code execution client.
+ */
+
+export type { PythonClient } from './types.js';
+export { PythonClientImpl } from './client.js';

package/src/integrations/python/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Python code execution client types.
+ */
+
+import type { z } from 'zod';
+import type { BaseIntegrationClient } from '../../types.js';
+
+/**
+ * Python code execution client.
+ *
+ * Executes Python scripts with type-safe inputs and outputs.
+ * Bindings are passed as a map and referenced in code using {{key}} syntax.
+ * The orchestrator resolves bindings before execution.
+ *
+ * @example
+ * ```typescript
+ * const python = ctx.python('Python Runtime');
+ *
+ * const result = await python.run(
+ *   `
+ *   import time
+ *
+ *   user_id = {{userId}}
+ *   current_time = int(time.time())
+ *
+ *   return {
+ *     "greeting": f"Hello user {user_id}!",
+ *     "timestamp": current_time
+ *   }
+ *   `,
+ *   z.object({
+ *     greeting: z.string(),
+ *     timestamp: z.number(),
+ *   }),
+ *   {
+ *     userId,
+ *   }
+ * );
+ * ```
+ */
+export interface PythonClient extends BaseIntegrationClient {
+  /**
+   * Execute Python code with validated output.
+   *
+   * The Python code must return a value using a `return` statement.
+   * Bindings are referenced using {{key}} syntax and resolved by the
+   * orchestrator before execution.
+   *
+   * @param code - Python script to execute (use {{key}} for bindings)
+   * @param schema - Zod schema for validating the return value
+   * @param bindings - Optional key/value pairs accessible via {{key}} in code
+   * @returns Validated result matching the schema
+   *
+   * @throws {CodeExecutionError} If execution fails or validation fails
+   *
+   * @example
+   * ```typescript
+   * const result = await python.run(
+   *   `
+   *   user_id = {{userId}}
+   *   return {"message": f"Hello {user_id}"}
+   *   `,
+   *   z.object({ message: z.string() }),
+   *   { userId: "123" }
+   * );
+   * ```
+   */
+  run<T>(
+    code: string,
+    schema: z.ZodSchema<T>,
+    bindings?: Record<string, unknown>
+  ): Promise<T>;
+}