@superblocksteam/sdk-api 2.0.96 → 2.0.97-next.0

package/src/integrations/python/types.ts

@@ -4,6 +4,7 @@
 
 import type { z } from "zod";
 import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
 
 /**
  * Python code execution client.
@@ -46,9 +47,25 @@ export interface PythonClient extends BaseIntegrationClient {
    * 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
+   * @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
@@ -69,5 +86,6 @@ export interface PythonClient extends BaseIntegrationClient {
     code: string,
     schema: z.ZodSchema<T>,
     bindings?: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ): Promise<T>;
 }

package/src/integrations/redis/README.md

@@ -4,9 +4,9 @@ Execute Redis commands with full type safety and runtime validation.
 
 ## Methods
 
-| Method                     | Description                 |
-| -------------------------- | --------------------------- |
-| `command(command, schema)` | Execute a raw Redis command |
+| Method                                | Description                 |
+| ------------------------------------- | --------------------------- |
+| `command(command, schema, metadata?)` | Execute a raw Redis command |
 
 ## Usage
 
@@ -142,6 +142,10 @@ await ctx.integrations.redis.command("EXPIRE mykey 3600", z.number());
 const ttl = await ctx.integrations.redis.command("TTL mykey", z.number());
 ```
 
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
 ## Common Pitfalls
 
 ### Quote String Values

package/src/integrations/redis/client.ts

@@ -12,7 +12,7 @@
 
 import type { z } from "zod";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor } from "../registry.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import { RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
 import type { RedisClient } from "./types.js";
@@ -81,9 +81,10 @@ export class RedisClientImpl implements RedisClient, IntegrationClientImpl {
   private async exec(
     request: Record<string, unknown>,
     operation: string,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     try {
-      return await this.executeQuery(request);
+      return await this.executeQuery(request, undefined, metadata);
     } catch (error) {
       if (
         error instanceof RestApiValidationError ||
@@ -96,9 +97,13 @@ export class RedisClientImpl implements RedisClient, IntegrationClientImpl {
     }
   }
 
-  async command<T>(command: string, schema: z.ZodSchema<T>): Promise<T> {
+  async command<T>(
+    command: string,
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T> {
     const request = buildRawRequest(command);
-    const result = await this.exec(request, "command");
+    const result = await this.exec(request, "command", metadata);
 
     const parseResult = schema.safeParse(result);
 
@@ -115,61 +120,79 @@ export class RedisClientImpl implements RedisClient, IntegrationClientImpl {
     return parseResult.data;
   }
 
-  async get(key: string): Promise<unknown> {
+  async get(key: string, metadata?: TraceMetadata): Promise<unknown> {
     const request = buildStructuredRequest("get", { key });
-    return this.exec(request, "get");
+    return this.exec(request, "get", metadata);
   }
 
   async set(
     key: string,
     value: string,
     expirationMs?: number,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const params: Record<string, unknown> = { key, value };
     if (expirationMs !== undefined) {
       params.expirationMs = expirationMs;
     }
     const request = buildStructuredRequest("set", params);
-    return this.exec(request, "set");
+    return this.exec(request, "set", metadata);
   }
 
-  async del(key: string): Promise<unknown> {
+  async del(key: string, metadata?: TraceMetadata): Promise<unknown> {
     const request = buildStructuredRequest("del", { key });
-    return this.exec(request, "del");
+    return this.exec(request, "del", metadata);
   }
 
-  async keys(pattern: string): Promise<unknown> {
+  async keys(pattern: string, metadata?: TraceMetadata): Promise<unknown> {
     const request = buildStructuredRequest("keys", { pattern });
-    return this.exec(request, "keys");
+    return this.exec(request, "keys", metadata);
   }
 
-  async hget(key: string, field: string): Promise<unknown> {
+  async hget(
+    key: string,
+    field: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
     const request = buildStructuredRequest("hget", { key, field });
-    return this.exec(request, "hget");
+    return this.exec(request, "hget", metadata);
   }
 
-  async hset(key: string, field: string, value: string): Promise<unknown> {
+  async hset(
+    key: string,
+    field: string,
+    value: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
     const request = buildStructuredRequest("hset", { key, field, value });
-    return this.exec(request, "hset");
+    return this.exec(request, "hset", metadata);
   }
 
-  async hgetall(key: string): Promise<unknown> {
+  async hgetall(key: string, metadata?: TraceMetadata): Promise<unknown> {
     const request = buildStructuredRequest("hgetall", { key });
-    return this.exec(request, "hgetall");
+    return this.exec(request, "hgetall", metadata);
   }
 
-  async hdel(key: string, field: string): Promise<unknown> {
+  async hdel(
+    key: string,
+    field: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
     const request = buildStructuredRequest("hdel", { key, field });
-    return this.exec(request, "hdel");
+    return this.exec(request, "hdel", metadata);
   }
 
-  async expire(key: string, seconds: number): Promise<unknown> {
+  async expire(
+    key: string,
+    seconds: number,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
     const request = buildStructuredRequest("expire", { key, seconds });
-    return this.exec(request, "expire");
+    return this.exec(request, "expire", metadata);
   }
 
-  async ttl(key: string): Promise<unknown> {
+  async ttl(key: string, metadata?: TraceMetadata): Promise<unknown> {
     const request = buildStructuredRequest("ttl", { key });
-    return this.exec(request, "ttl");
+    return this.exec(request, "ttl", metadata);
   }
 }

package/src/integrations/redis/types.ts

@@ -4,6 +4,7 @@
 
 import type { z } from "zod";
 import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
 
 /**
  * Redis client for executing commands.
@@ -46,15 +47,20 @@ export interface RedisClient extends BaseIntegrationClient {
    * @param schema - Zod schema for validating the result
    * @returns The validated result
    */
-  command<T>(command: string, schema: z.ZodSchema<T>): Promise<T>;
+  command<T>(
+    command: string,
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T>;
 
   /**
    * Get the value of a key.
    *
    * @param key - The key to get
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The value, or null if the key does not exist
    */
-  get(key: string): Promise<unknown>;
+  get(key: string, metadata?: TraceMetadata): Promise<unknown>;
 
   /**
    * Set the value of a key.
@@ -62,34 +68,43 @@ export interface RedisClient extends BaseIntegrationClient {
    * @param key - The key to set
    * @param value - The value to set
    * @param expirationMs - Optional expiration time in milliseconds
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The result (typically "OK")
    */
-  set(key: string, value: string, expirationMs?: number): Promise<unknown>;
+  set(
+    key: string,
+    value: string,
+    expirationMs?: number,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
 
   /**
    * Delete a key.
    *
    * @param key - The key to delete
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The number of keys removed
    */
-  del(key: string): Promise<unknown>;
+  del(key: string, metadata?: TraceMetadata): Promise<unknown>;
 
   /**
    * Find all keys matching a pattern.
    *
    * @param pattern - The glob-style pattern to match (e.g., "user:*")
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns Array of matching keys
    */
-  keys(pattern: string): Promise<unknown>;
+  keys(pattern: string, metadata?: TraceMetadata): Promise<unknown>;
 
   /**
    * Get the value of a hash field.
    *
    * @param key - The hash key
    * @param field - The field name
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The field value, or null if the field does not exist
    */
-  hget(key: string, field: string): Promise<unknown>;
+  hget(key: string, field: string, metadata?: TraceMetadata): Promise<unknown>;
 
   /**
    * Set the value of a hash field.
@@ -97,41 +112,55 @@ export interface RedisClient extends BaseIntegrationClient {
    * @param key - The hash key
    * @param field - The field name
    * @param value - The value to set
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The number of fields that were added
    */
-  hset(key: string, field: string, value: string): Promise<unknown>;
+  hset(
+    key: string,
+    field: string,
+    value: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
 
   /**
    * Get all fields and values of a hash.
    *
    * @param key - The hash key
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns Object with all field-value pairs
    */
-  hgetall(key: string): Promise<unknown>;
+  hgetall(key: string, metadata?: TraceMetadata): Promise<unknown>;
 
   /**
    * Delete a hash field.
    *
    * @param key - The hash key
    * @param field - The field to delete
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The number of fields that were removed
    */
-  hdel(key: string, field: string): Promise<unknown>;
+  hdel(key: string, field: string, metadata?: TraceMetadata): Promise<unknown>;
 
   /**
    * Set expiration on a key.
    *
    * @param key - The key to set expiration on
    * @param seconds - Time to live in seconds
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns 1 if timeout was set, 0 if key does not exist
    */
-  expire(key: string, seconds: number): Promise<unknown>;
+  expire(
+    key: string,
+    seconds: number,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
 
   /**
    * Get the remaining time to live of a key.
    *
    * @param key - The key to check
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns TTL in seconds, -2 if key does not exist, -1 if no expiration
    */
-  ttl(key: string): Promise<unknown>;
+  ttl(key: string, metadata?: TraceMetadata): Promise<unknown>;
 }

package/src/integrations/redshift/README.md

@@ -4,10 +4,10 @@ Execute SQL queries and statements against Amazon Redshift data warehouses with
 
 ## Methods
 
-| Method                           | Description                                                                |
-| -------------------------------- | -------------------------------------------------------------------------- |
-| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results                 |
-| `execute(sql, params?)`          | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
+| Method                                      | Description                                                                |
+| ------------------------------------------- | -------------------------------------------------------------------------- |
+| `query<T>(sql, schema, params?, metadata?)` | Execute a SELECT query and return validated, typed results                 |
+| `execute(sql, params?, metadata?)`          | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
 
 ## Usage
 
@@ -94,6 +94,10 @@ const analytics = await ctx.integrations.redshift.query(
 );
 ```
 
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
 ## Common Pitfalls
 
 ### BIGINT Values Returned as Strings

package/src/integrations/redshift/client.ts

@@ -9,7 +9,7 @@ import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
 import type { Plugin as RedshiftPlugin } from "@superblocksteam/types/dist/src/plugins/redshift/v1/plugin_pb";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor } from "../registry.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
 import { describeType } from "../utils.js";
@@ -64,11 +64,12 @@ export class RedshiftClientImpl
     sql: string,
     schema: z.ZodSchema<T>,
     params?: unknown[],
+    metadata?: TraceMetadata,
   ): Promise<T[]> {
     const request = this.buildRequest(sql, params);
 
     try {
-      const result = await this.executeQuery(request);
+      const result = await this.executeQuery(request, undefined, metadata);
 
       if (!Array.isArray(result)) {
         throw new IntegrationError(
@@ -116,11 +117,12 @@ export class RedshiftClientImpl
   async execute(
     sql: string,
     params?: unknown[],
+    metadata?: TraceMetadata,
   ): Promise<{ rowCount: number }> {
     const request = this.buildRequest(sql, params);
 
     try {
-      const result = await this.executeQuery(request);
+      const result = await this.executeQuery(request, undefined, metadata);
 
       if (
         typeof result === "object" &&

package/src/integrations/redshift/types.ts

@@ -6,6 +6,7 @@
 
 import type { z } from "zod";
 import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
 
 /**
  * Client for executing Redshift queries with type-safe validation.
@@ -45,6 +46,7 @@ export interface RedshiftClient extends BaseIntegrationClient {
     sql: string,
     schema: z.ZodSchema<T>,
     params?: unknown[],
+    metadata?: TraceMetadata,
   ): Promise<T[]>;
 
   /**
@@ -54,5 +56,9 @@ export interface RedshiftClient extends BaseIntegrationClient {
    * @param params - Optional parameters for prepared statements
    * @returns Promise resolving to execution result with row count
    */
-  execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }>;
+  execute(
+    sql: string,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<{ rowCount: number }>;
 }

package/src/integrations/registry.ts

@@ -155,6 +155,24 @@ export const SUPPORTED_PLUGINS = {
 export type SupportedPluginId =
   (typeof SUPPORTED_PLUGINS)[keyof typeof SUPPORTED_PLUGINS];
 
+/**
+ * Optional metadata attached to an integration call for diagnostics.
+ *
+ * When `includeDiagnostics` is enabled, the `label` and `description`
+ * are captured alongside the standard timing/input/output data and
+ * surfaced in the Trace View UI.
+ *
+ * **Security:** Do not include secrets, passwords, access tokens, or other
+ * sensitive/PII data in trace metadata, as it may be stored in logs or trace
+ * payloads and visible to others with access to diagnostics.
+ */
+export interface TraceMetadata {
+  /** Short human-readable label for this call (e.g., "Fetch active users"). */
+  label?: string;
+  /** Longer description of what this call does and why. */
+  description?: string;
+}
+
 /**
  * Type for the query executor function provided by the orchestrator.
  *
@@ -166,11 +184,13 @@ export type SupportedPluginId =
  *
  * @param request - Plugin-specific request object matching the proto schema
  * @param bindings - Optional bindings data for binding resolution (e.g., Python/JavaScript bindings)
+ * @param metadata - Optional trace metadata (label, description) for diagnostics
  * @returns Promise resolving to the operation result
  */
 export type QueryExecutor = (
   request: Record<string, unknown>,
   bindings?: Record<string, unknown>,
+  metadata?: TraceMetadata,
 ) => Promise<unknown>;
 
 /**
@@ -180,10 +200,12 @@ export type QueryExecutor = (
  * Used for streaming operations like LLM token streaming.
  *
  * @param request - Plugin-specific request object matching the proto schema
+ * @param metadata - Optional trace metadata (label, description) for diagnostics
  * @returns AsyncIterable yielding raw chunks from the stream
  */
 export type StreamingQueryExecutor = (
   request: Record<string, unknown>,
+  metadata?: TraceMetadata,
 ) => AsyncIterable<unknown>;
 
 /**

package/src/integrations/s3/README.md

@@ -4,15 +4,15 @@ Interact with Amazon S3 buckets with full type safety and runtime validation.
 
 ## Methods
 
-| Method                                       | Description              |
-| -------------------------------------------- | ------------------------ |
-| `listBuckets(schema)`                        | List all buckets         |
-| `listObjects(bucket, schema, options?)`      | List objects in a bucket |
-| `getObject(bucket, path, schema, options?)`  | Get an object            |
-| `deleteObject(bucket, path)`                 | Delete an object         |
-| `uploadObject(bucket, path, body)`           | Upload a single object   |
-| `uploadMultipleObjects(bucket, fileObjects)` | Upload multiple objects  |
-| `generatePresignedUrl(bucket, path, schema)` | Generate a presigned URL |
+| Method                                                  | Description              |
+| ------------------------------------------------------- | ------------------------ |
+| `listBuckets(schema, metadata?)`                        | List all buckets         |
+| `listObjects(bucket, schema, options?, metadata?)`      | List objects in a bucket |
+| `getObject(bucket, path, schema, options?, metadata?)`  | Get an object            |
+| `deleteObject(bucket, path, metadata?)`                 | Delete an object         |
+| `uploadObject(bucket, path, body, metadata?)`           | Upload a single object   |
+| `uploadMultipleObjects(bucket, fileObjects, metadata?)` | Upload multiple objects  |
+| `generatePresignedUrl(bucket, path, schema, metadata?)` | Generate a presigned URL |
 
 ## Usage
 
@@ -104,6 +104,10 @@ const url = await ctx.integrations.storage.generatePresignedUrl(
 );
 ```
 
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
 ## Error Handling
 
 ```typescript