@superblocksteam/sdk-api 0.0.4

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

@@ -0,0 +1,340 @@
+/**
+ * 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}' },
+        undefined,
+        undefined,
+      );
+    });
+
+    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,134 @@
+/**
+ * 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, TraceMetadata } 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>,
+    metadata?: TraceMetadata,
+  ): 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>,
+        undefined,
+        metadata,
+      );
+
+      // 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,91 @@
+/**
+ * Python code execution client types.
+ */
+
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.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
+ * // Declare in api(): integrations: { runtime: python(INTEGRATION_ID) }
+ * // In run(), access via: ctx.integrations.runtime
+ * const result = await ctx.integrations.runtime.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.
+   *
+   * **Important:** The parameter order is `(code, schema, bindings?, metadata?)`.
+   * Because `bindings` is `Record<string, unknown>`, it is structurally
+   * compatible with `TraceMetadata`. Take care not to pass a metadata object
+   * as the third argument -- if you only need metadata and no bindings, pass
+   * `undefined` for `bindings` explicitly:
+   *
+   * ```typescript
+   * // Correct: skip bindings, pass metadata
+   * await python.run(code, schema, undefined, { label: "my label" });
+   *
+   * // Wrong: metadata is accidentally treated as bindings
+   * await python.run(code, schema, { label: "my label" });
+   * ```
+   *
+   * @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.
+   *   Do not pass `TraceMetadata` here; use the `metadata` parameter instead.
+   * @param metadata - Optional trace metadata for diagnostics labeling
+   * @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>,
+    metadata?: TraceMetadata,
+  ): Promise<T>;
+}