@superblocksteam/sdk-api 2.0.93 → 2.0.94-next.0

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

@@ -2,23 +2,23 @@
  * 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';
+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');
+  const b64 = Buffer.from(JSON.stringify(bindings)).toString("base64");
   return `_bindings = json.loads(base64.b64decode('${b64}').decode())`;
 }
 
-describe('PythonClientImpl', () => {
+describe("PythonClientImpl", () => {
   const createMockConfig = (): IntegrationConfig => ({
-    id: 'test-python-id',
-    name: 'Test Python',
-    pluginId: 'python',
+    id: "test-python-id",
+    name: "Test Python",
+    pluginId: "python",
     configuration: {},
   });
 
@@ -26,14 +26,14 @@ describe('PythonClientImpl', () => {
     return vi.fn().mockResolvedValue(mockResult);
   };
 
-  describe('binding injection', () => {
-    it('generates code without bindings when none provided', async () => {
+  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() })
+        z.object({ result: z.number() }),
       );
 
       expect(mockExecutor).toHaveBeenCalledWith({
@@ -41,25 +41,27 @@ describe('PythonClientImpl', () => {
       });
     });
 
-    it('injects string bindings as Python variables', async () => {
-      const mockExecutor = vi.fn().mockResolvedValue({ message: 'Hello World' });
+    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' };
+      const bindings = { greeting: "Hello World" };
       await client.run(
         'return {"message": greeting}',
         z.object({ message: z.string() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
-      expect(request.body).toContain('import json, base64');
+      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 () => {
+    it("injects number bindings as Python variables", async () => {
       const mockExecutor = vi.fn().mockResolvedValue({ result: 14 });
       const client = new PythonClientImpl(createMockConfig(), mockExecutor);
 
@@ -67,17 +69,17 @@ describe('PythonClientImpl', () => {
       await client.run(
         'return {"result": number + 4}',
         z.object({ result: z.number() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
-      expect(request.body).toContain('import json, base64');
+      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 () => {
+    it("injects boolean bindings as Python variables", async () => {
       const mockExecutor = vi.fn().mockResolvedValue({ active: true });
       const client = new PythonClientImpl(createMockConfig(), mockExecutor);
 
@@ -85,17 +87,17 @@ describe('PythonClientImpl', () => {
       await client.run(
         'return {"active": isActive}',
         z.object({ active: z.boolean() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
-      expect(request.body).toContain('import json, base64');
+      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 () => {
+    it("injects null bindings as Python variables", async () => {
       const mockExecutor = vi.fn().mockResolvedValue({ value: null });
       const client = new PythonClientImpl(createMockConfig(), mockExecutor);
 
@@ -103,17 +105,17 @@ describe('PythonClientImpl', () => {
       await client.run(
         'return {"value": nullValue}',
         z.object({ value: z.null() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
-      expect(request.body).toContain('import json, base64');
+      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 () => {
+    it("injects array bindings as Python variables", async () => {
       const mockExecutor = vi.fn().mockResolvedValue({ count: 3 });
       const client = new PythonClientImpl(createMockConfig(), mockExecutor);
 
@@ -121,81 +123,89 @@ describe('PythonClientImpl', () => {
       await client.run(
         'return {"count": len(items)}',
         z.object({ count: z.number() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
-      expect(request.body).toContain('import json, base64');
+      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' });
+    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 } };
+      const bindings = { user: { name: "John", age: 30 } };
       await client.run(
         'return {"name": user["name"]}',
         z.object({ name: z.string() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
-      expect(request.body).toContain('import json, base64');
+      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' });
+    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 };
+      const bindings = { userName: "Alice", userAge: 25 };
       await client.run(
         'return {"message": f"{userName} is {userAge} years old"}',
         z.object({ message: z.string() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
-      expect(request.body).toContain('import json, base64');
+      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"}');
+      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\"" });
+    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\"" };
+      const bindings = { text: 'It\'s a "test"' };
       await client.run(
         'return {"text": text}',
         z.object({ text: z.string() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
-      expect(request.body).toContain('import json, base64');
+      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' });
+    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' };
+      const bindings = { text: "line1\nline2\ttab" };
       await client.run(
         'return {"text": text}',
         z.object({ text: z.string() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
@@ -204,15 +214,17 @@ describe('PythonClientImpl', () => {
       expect(request.body).toContain("text = _bindings['text']");
     });
 
-    it('handles strings with backslashes', async () => {
-      const mockExecutor = vi.fn().mockResolvedValue({ path: 'C:\\Users\\test' });
+    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' };
+      const bindings = { path: "C:\\Users\\test" };
       await client.run(
         'return {"path": path}',
         z.object({ path: z.string() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
@@ -221,7 +233,7 @@ describe('PythonClientImpl', () => {
       expect(request.body).toContain("path = _bindings['path']");
     });
 
-    it('preserves code structure with blank line between preamble and user code', async () => {
+    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);
 
@@ -229,90 +241,96 @@ describe('PythonClientImpl', () => {
       await client.run(
         'result = number * 2\nreturn {"result": result}',
         z.object({ result: z.number() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
-      const lines = (request.body as string).split('\n');
+      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[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');
+      expect(lines[3]).toBe("");
+      expect(lines[4]).toBe("result = number * 2");
     });
   });
 
-  describe('validation', () => {
-    it('validates result against schema', async () => {
+  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() })
+        z.object({ result: z.number() }),
       );
 
       expect(result).toEqual({ result: 42 });
     });
 
-    it('throws CodeExecutionError when validation fails', async () => {
-      const mockExecutor = createMockExecutor({ result: 'not a number' });
+    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');
+          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'));
+    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');
+        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' });
+  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' } } };
+      const bindings = {
+        person: { first: "John", last: "Doe", address: { city: "NYC" } },
+      };
       await client.run(
-        'return {"name": f"{person[\'first\']} {person[\'last\']}"}',
+        "return {\"name\": f\"{person['first']} {person['last']}\"}",
         z.object({ name: z.string() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
-      expect(request.body).toContain('import json, base64');
+      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 () => {
+    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' }] };
+      const bindings = {
+        users: [
+          { id: 1, name: "Alice" },
+          { id: 2, name: "Bob" },
+        ],
+      };
       await client.run(
         'return {"count": len(users)}',
         z.object({ count: z.number() }),
-        bindings
+        bindings,
       );
 
       const request = mockExecutor.mock.calls[0][0];
-      expect(request.body).toContain('import json, base64');
+      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

@@ -4,13 +4,13 @@
  * 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';
+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.
@@ -48,7 +48,10 @@ export class PythonClientImpl implements PythonClient, IntegrationClientImpl {
    * @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 {
+  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 {
@@ -58,12 +61,16 @@ export class PythonClientImpl implements PythonClient, IntegrationClientImpl {
 
     // 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'];
+    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())`);
+    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)) {
@@ -71,7 +78,7 @@ export class PythonClientImpl implements PythonClient, IntegrationClientImpl {
     }
 
     // Combine binding preamble with user code
-    const fullCode = `${bindingLines.join('\n')}\n\n${code}`;
+    const fullCode = `${bindingLines.join("\n")}\n\n${code}`;
 
     return {
       body: fullCode,
@@ -81,7 +88,7 @@ export class PythonClientImpl implements PythonClient, IntegrationClientImpl {
   async run<T>(
     code: string,
     schema: z.ZodSchema<T>,
-    bindings?: Record<string, unknown>
+    bindings?: Record<string, unknown>,
   ): Promise<T> {
     // Build request with bindings injected as Python variables
     const request = this.buildRequest(code, bindings);
@@ -90,7 +97,7 @@ export class PythonClientImpl implements PythonClient, IntegrationClientImpl {
       // 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>
+        request as unknown as Record<string, unknown>,
       );
 
       // Validate result against schema
@@ -104,7 +111,7 @@ export class PythonClientImpl implements PythonClient, IntegrationClientImpl {
             bindings,
             result,
             zodError: parseResult.error,
-          }
+          },
         );
       }
 
@@ -114,14 +121,11 @@ export class PythonClientImpl implements PythonClient, IntegrationClientImpl {
         throw error;
       }
 
-      throw new CodeExecutionError(
-        'Python execution failed',
-        {
-          code,
-          bindings,
-          originalError: error,
-        }
-      );
+      throw new CodeExecutionError("Python execution failed", {
+        code,
+        bindings,
+        originalError: error,
+      });
     }
   }
 }

package/src/integrations/python/index.ts

@@ -2,5 +2,5 @@
  * Python code execution client.
  */
 
-export type { PythonClient } from './types.js';
-export { PythonClientImpl } from './client.js';
+export type { PythonClient } from "./types.js";
+export { PythonClientImpl } from "./client.js";

package/src/integrations/python/types.ts

@@ -2,8 +2,8 @@
  * Python code execution client types.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * Python code execution client.
@@ -14,9 +14,9 @@ import type { BaseIntegrationClient } from '../../types.js';
  *
  * @example
  * ```typescript
- * const python = ctx.python('Python Runtime');
- *
- * const result = await python.run(
+ * // Declare in api(): integrations: { runtime: python(INTEGRATION_ID) }
+ * // In run(), access via: ctx.integrations.runtime
+ * const result = await ctx.integrations.runtime.run(
  *   `
  *   import time
  *
@@ -68,6 +68,6 @@ export interface PythonClient extends BaseIntegrationClient {
   run<T>(
     code: string,
     schema: z.ZodSchema<T>,
-    bindings?: Record<string, unknown>
+    bindings?: Record<string, unknown>,
   ): Promise<T>;
 }