@superblocksteam/sdk-api 0.0.6 → 0.0.8

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

@@ -1,340 +0,0 @@
-/**
- * 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

@@ -1,134 +0,0 @@
-/**
- * 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

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

package/src/integrations/python/types.ts

@@ -1,91 +0,0 @@
-/**
- * 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>;
-}