@superblocksteam/sdk-api 0.0.4

package/dist/integrations/postgres/index.js

@@ -0,0 +1,5 @@
+/**
+ * PostgreSQL integration module.
+ */
+export { PostgresClientImpl } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/integrations/postgres/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/integrations/postgres/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/integrations/postgres/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * PostgreSQL client types.
+ */
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+/**
+ * PostgreSQL client for database operations.
+ *
+ * Provides typed methods for executing SQL queries and statements
+ * against a PostgreSQL database.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * // Declare in api(): integrations: { db: postgres(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.db
+ *
+ * // Query with runtime validation
+ * const UserSchema = z.object({
+ *   id: z.string(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ * });
+ *
+ * const users = await ctx.integrations.db.query(
+ *   'SELECT * FROM users WHERE status = $1',
+ *   UserSchema,
+ *   ['active']
+ * );
+ * // Type is automatically inferred: Array<{ id: string; name: string; email: string }>
+ *
+ * // Execute a statement (no validation needed)
+ * const result = await ctx.integrations.db.execute(
+ *   'UPDATE users SET last_login = NOW() WHERE id = $1',
+ *   [userId]
+ * );
+ * console.log(`Updated ${result.rowCount} rows`);
+ * ```
+ */
+export interface PostgresClient extends BaseIntegrationClient {
+    /**
+     * Execute a SQL query and return validated typed results.
+     *
+     * Type parameter T is automatically inferred from the schema.
+     * All query results are validated at runtime against the provided Zod schema.
+     *
+     * Use parameterized queries with $1, $2, etc. placeholders
+     * to prevent SQL injection.
+     *
+     * @param sql - The SQL query to execute
+     * @param schema - Zod schema for runtime validation (REQUIRED)
+     * @param params - Optional array of parameter values
+     * @returns Array of validated result rows
+     * @throws {QueryValidationError} If any row fails schema validation
+     *
+     * @example
+     * ```typescript
+     * import { z } from 'zod';
+     *
+     * const UserSchema = z.object({
+     *   id: z.number(),
+     *   email: z.string().email(),
+     * });
+     *
+     * const users = await ctx.integrations.db.query(
+     *   'SELECT * FROM users WHERE email = $1',
+     *   UserSchema,
+     *   ['user@example.com']
+     * );
+     * // Type is automatically z.infer<typeof UserSchema>[]
+     * ```
+     */
+    query<T>(sql: string, schema: z.ZodSchema<T>, params?: unknown[], metadata?: TraceMetadata): Promise<T[]>;
+    /**
+     * Execute a SQL statement (INSERT, UPDATE, DELETE) and return affected row count.
+     *
+     * Use this method when you don't need the returned data, only the count
+     * of affected rows.
+     *
+     * @param sql - The SQL statement to execute
+     * @param params - Optional array of parameter values
+     * @returns Object with the count of affected rows
+     *
+     * @example
+     * ```typescript
+     * const result = await ctx.integrations.db.execute(
+     *   'DELETE FROM sessions WHERE expires_at < NOW()'
+     * );
+     * console.log(`Deleted ${result.rowCount} expired sessions`);
+     * ```
+     */
+    execute(sql: string, params?: unknown[], metadata?: TraceMetadata): Promise<{
+        rowCount: number;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/integrations/postgres/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/integrations/postgres/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,cAAe,SAAQ,qBAAqB;IAC3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,KAAK,CAAC,CAAC,EACL,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACtB,MAAM,CAAC,EAAE,OAAO,EAAE,EAClB,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEhB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CACL,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,EAClB,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClC"}

package/dist/integrations/postgres/types.js

@@ -0,0 +1,5 @@
+/**
+ * PostgreSQL client types.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/integrations/postgres/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/integrations/postgres/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/integrations/python/client.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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";
+/**
+ * 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 declare class PythonClientImpl implements PythonClient, IntegrationClientImpl {
+    readonly name: string;
+    readonly pluginId: string;
+    readonly config: IntegrationConfig;
+    private readonly executeQuery;
+    constructor(config: IntegrationConfig, executeQuery: QueryExecutor);
+    /**
+     * 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;
+    run<T>(code: string, schema: z.ZodSchema<T>, bindings?: Record<string, unknown>, metadata?: TraceMetadata): Promise<T>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/integrations/python/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/integrations/python/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,6DAA6D,CAAC;AAC1G,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;AAEzD;;;;;GAKG;AACH,qBAAa,gBAAiB,YAAW,YAAY,EAAE,qBAAqB;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAEnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;gBAEjC,MAAM,EAAE,iBAAiB,EAAE,YAAY,EAAE,aAAa;IAOlE;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY;IAqCd,GAAG,CAAC,CAAC,EACT,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,CAAC,CAAC;CAyCd"}

package/dist/integrations/python/client.js

@@ -0,0 +1,89 @@
+/**
+ * Python client implementation.
+ *
+ * Executes Python code via the orchestrator with type-safe bindings.
+ */
+import { CodeExecutionError } from "../../errors.js";
+/**
+ * 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 {
+    name;
+    pluginId;
+    config;
+    executeQuery;
+    constructor(config, executeQuery) {
+        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
+     */
+    buildRequest(code, bindings) {
+        // 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 = ["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(code, schema, bindings, metadata) {
+        // 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, 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,
+            });
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/integrations/python/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/integrations/python/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAQrD;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IAClB,IAAI,CAAS;IACb,QAAQ,CAAS;IACjB,MAAM,CAAoB;IAElB,YAAY,CAAgB;IAE7C,YAAY,MAAyB,EAAE,YAA2B;QAChE,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IAED;;;;;;;;;OASG;IACK,YAAY,CAClB,IAAY,EACZ,QAAkC;QAElC,6CAA6C;QAC7C,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,OAAO;gBACL,IAAI,EAAE,IAAI;aACX,CAAC;QACJ,CAAC;QAED,oFAAoF;QACpF,qIAAqI;QACrI,MAAM,YAAY,GAAa,CAAC,qBAAqB,CAAC,CAAC;QAEvD,sFAAsF;QACtF,0EAA0E;QAC1E,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAChE,QAAQ,CACT,CAAC;QACF,YAAY,CAAC,IAAI,CACf,4CAA4C,WAAW,cAAc,CACtE,CAAC;QAEF,2CAA2C;QAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxC,YAAY,CAAC,IAAI,CAAC,GAAG,GAAG,iBAAiB,GAAG,IAAI,CAAC,CAAC;QACpD,CAAC;QAED,0CAA0C;QAC1C,MAAM,QAAQ,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;QAEzD,OAAO;YACL,IAAI,EAAE,QAAQ;SACf,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,GAAG,CACP,IAAY,EACZ,MAAsB,EACtB,QAAkC,EAClC,QAAwB;QAExB,2DAA2D;QAC3D,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAElD,IAAI,CAAC;YACH,iDAAiD;YACjD,sEAAsE;YACtE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CACpC,OAA6C,EAC7C,SAAS,EACT,QAAQ,CACT,CAAC;YAEF,iCAAiC;YACjC,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAE7C,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;gBACzB,MAAM,IAAI,kBAAkB,CAC1B,8CAA8C,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,EACzE;oBACE,IAAI;oBACJ,QAAQ;oBACR,MAAM;oBACN,QAAQ,EAAE,WAAW,CAAC,KAAK;iBAC5B,CACF,CAAC;YACJ,CAAC;YAED,OAAO,WAAW,CAAC,IAAI,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,kBAAkB,EAAE,CAAC;gBACxC,MAAM,KAAK,CAAC;YACd,CAAC;YAED,MAAM,IAAI,kBAAkB,CAAC,yBAAyB,EAAE;gBACtD,IAAI;gBACJ,QAAQ;gBACR,aAAa,EAAE,KAAK;aACrB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF"}

package/dist/integrations/python/client.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for Python client binding injection.
+ */
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/integrations/python/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../../../src/integrations/python/client.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/integrations/python/client.test.js

@@ -0,0 +1,214 @@
+/**
+ * Tests for Python client binding injection.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+import { PythonClientImpl } from "./client.js";
+/** Helper to compute expected base64-encoded json.loads preamble. */
+function expectedBindingsLine(bindings) {
+    const b64 = Buffer.from(JSON.stringify(bindings)).toString("base64");
+    return `_bindings = json.loads(base64.b64decode('${b64}').decode())`;
+}
+describe("PythonClientImpl", () => {
+    const createMockConfig = () => ({
+        id: "test-python-id",
+        name: "Test Python",
+        pluginId: "python",
+        configuration: {},
+    });
+    const createMockExecutor = (mockResult) => {
+        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.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']");
+        });
+    });
+});
+//# sourceMappingURL=client.test.js.map

package/dist/integrations/python/client.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.js","sourceRoot":"","sources":["../../../src/integrations/python/client.test.ts"],"names":[],"mappings":"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"}

package/dist/integrations/python/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Python code execution client.
+ */
+export type { PythonClient } from "./types.js";
+export { PythonClientImpl } from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/integrations/python/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/integrations/python/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/integrations/python/index.js

@@ -0,0 +1,5 @@
+/**
+ * Python code execution client.
+ */
+export { PythonClientImpl } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/integrations/python/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/integrations/python/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/integrations/python/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/integrations/python/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/integrations/python/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,YAAa,SAAQ,qBAAqB;IACzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,GAAG,CAAC,CAAC,EACH,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,CAAC,CAAC,CAAC;CACf"}

package/dist/integrations/python/types.js

@@ -0,0 +1,5 @@
+/**
+ * Python code execution client types.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/integrations/python/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/integrations/python/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}