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

package/src/integrations/smtp/client.ts

@@ -8,7 +8,7 @@
 import type { PartialMessage } from "@bufbuild/protobuf";
 import type { Plugin as SmtpPlugin } from "@superblocksteam/types/dist/src/plugins/smtp/v1/plugin_pb";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor } from "../registry.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import { IntegrationError } from "../../runtime/errors.js";
 import type { SmtpClient, SmtpSendOptions } from "./types.js";
 
@@ -40,7 +40,10 @@ export class SmtpClientImpl implements SmtpClient, IntegrationClientImpl {
     return this.config.pluginId;
   }
 
-  async send(options: SmtpSendOptions): Promise<unknown> {
+  async send(
+    options: SmtpSendOptions,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
     const request: SmtpRequest = {
       from: options.from,
       to: options.to,
@@ -53,7 +56,11 @@ export class SmtpClientImpl implements SmtpClient, IntegrationClientImpl {
     };
 
     try {
-      return await this.executeQuery(request as Record<string, unknown>);
+      return await this.executeQuery(
+        request as Record<string, unknown>,
+        undefined,
+        metadata,
+      );
     } catch (error) {
       if (error instanceof IntegrationError) {
         throw error;

package/src/integrations/smtp/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
 
 /**
  * Options for sending an email via SMTP.
@@ -60,5 +61,5 @@ export interface SmtpClient extends BaseIntegrationClient {
    * @param options - Email send options
    * @returns The raw result from the SMTP plugin
    */
-  send(options: SmtpSendOptions): Promise<unknown>;
+  send(options: SmtpSendOptions, metadata?: TraceMetadata): Promise<unknown>;
 }

package/src/integrations/snowflake/README.md

@@ -4,10 +4,10 @@ Execute SQL queries and statements against Snowflake data warehouses with full t
 
 ## 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
 
@@ -143,6 +143,10 @@ const events = await ctx.integrations.snowflake.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
 
 ### Uppercase Column Names by Default

package/src/integrations/snowflake/client.ts

@@ -9,7 +9,7 @@ import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
 import type { Plugin as SnowflakePlugin } from "@superblocksteam/types/dist/src/plugins/snowflake/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 SnowflakeClientImpl
     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);
 
       // Validate result structure
       if (!Array.isArray(result)) {
@@ -118,11 +119,12 @@ export class SnowflakeClientImpl
   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);
 
       // Extract row count from result
       // Snowflake returns execution metadata in the result

package/src/integrations/snowflake/types.ts

@@ -6,6 +6,7 @@
 
 import type { z } from "zod";
 import type { BaseIntegrationClient } from "../../types";
+import type { TraceMetadata } from "../registry.js";
 
 /**
  * Client for executing Snowflake queries with type-safe validation.
@@ -60,6 +61,7 @@ export interface SnowflakeClient extends BaseIntegrationClient {
     sql: string,
     schema: z.ZodSchema<T>,
     params?: unknown[],
+    metadata?: TraceMetadata,
   ): Promise<T[]>;
 
   /**
@@ -78,5 +80,9 @@ export interface SnowflakeClient extends BaseIntegrationClient {
    * console.log(`Updated ${result.rowCount} rows`);
    * ```
    */
-  execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }>;
+  execute(
+    sql: string,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<{ rowCount: number }>;
 }

package/src/integrations/snowflakepostgres/types.ts

@@ -7,6 +7,7 @@
 
 import type { z } from "zod";
 import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
 
 /**
  * Snowflake Postgres client for SQL query and execute operations.
@@ -42,6 +43,7 @@ export interface SnowflakePostgresClient extends BaseIntegrationClient {
     sql: string,
     schema: z.ZodSchema<T>,
     params?: unknown[],
+    metadata?: TraceMetadata,
   ): Promise<T[]>;
 
   /**
@@ -51,5 +53,9 @@ export interface SnowflakePostgresClient extends BaseIntegrationClient {
    * @param params - Optional query parameters for server-side binding
    * @returns The affected row count
    */
-  execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }>;
+  execute(
+    sql: string,
+    params?: unknown[],
+    metadata?: TraceMetadata,
+  ): Promise<{ rowCount: number }>;
 }

package/src/integrations/stabilityai/README.md

@@ -4,9 +4,9 @@ Generate, edit, and upscale images using Stability AI's image generation models.
 
 ## Methods
 
-| Method                        | Description                                              |
-| ----------------------------- | -------------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any Stability AI API request with schema validation |
+| Method                                   | Description                                              |
+| ---------------------------------------- | -------------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Stability AI API request with schema validation |
 
 ## Usage
 
@@ -228,6 +228,10 @@ result.engines.forEach((engine) => {
 });
 ```
 
+## 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
 
 ### No Specialized Methods

package/src/integrations/stripe/README.md

@@ -4,9 +4,9 @@ Process payments, manage customers, and interact with Stripe's payment platform.
 
 ## Methods
 
-| Method                        | Description                                        |
-| ----------------------------- | -------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any Stripe API request with schema validation |
+| Method                                   | Description                                        |
+| ---------------------------------------- | -------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Stripe API request with schema validation |
 
 ## Usage
 
@@ -295,6 +295,10 @@ await ctx.integrations.stripe.apiRequest(
 );
 ```
 
+## 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
 
 ### No Specialized Methods

package/src/integrations/superblocks-ocr/README.md

@@ -4,9 +4,9 @@ Extract text from images using the Superblocks OCR service with full type safety
 
 ## Methods
 
-| Method                        | Description                                     |
-| ----------------------------- | ----------------------------------------------- |
-| `apiRequest(options, schema)` | Make any OCR API request with schema validation |
+| Method                                   | Description                                     |
+| ---------------------------------------- | ----------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any OCR API request with schema validation |
 
 ## Usage
 
@@ -133,6 +133,10 @@ const result = await ctx.integrations.ocr.apiRequest(
 );
 ```
 
+## 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
 
 ### Image Format

package/src/integrations/twilio/README.md

@@ -4,9 +4,9 @@ Send SMS messages, make calls, and interact with Twilio's communication APIs.
 
 ## Methods
 
-| Method                        | Description                                        |
-| ----------------------------- | -------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any Twilio API request with schema validation |
+| Method                                   | Description                                        |
+| ---------------------------------------- | -------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Twilio API request with schema validation |
 
 ## Usage
 
@@ -207,6 +207,10 @@ console.log(`Message status: ${result.status}`);
 // Statuses: queued, sending, sent, delivered, undelivered, failed
 ```
 
+## 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
 
 ### No Specialized Methods

package/src/integrations/zendesk/README.md

@@ -4,9 +4,9 @@ Create tickets, manage users, and interact with Zendesk's customer support platf
 
 ## Methods
 
-| Method                        | Description                                         |
-| ----------------------------- | --------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any Zendesk API request with schema validation |
+| Method                                   | Description                                         |
+| ---------------------------------------- | --------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Zendesk API request with schema validation |
 
 ## Usage
 
@@ -275,6 +275,10 @@ const result = await ctx.integrations.zendesk.apiRequest(
 );
 ```
 
+## 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
 
 ### No Specialized Methods

package/src/integrations/zoom/README.md

@@ -4,9 +4,9 @@ Create meetings, manage users, and interact with Zoom's video conferencing platf
 
 ## Methods
 
-| Method                        | Description                                      |
-| ----------------------------- | ------------------------------------------------ |
-| `apiRequest(options, schema)` | Make any Zoom API request with schema validation |
+| Method                                   | Description                                      |
+| ---------------------------------------- | ------------------------------------------------ |
+| `apiRequest(options, schema, metadata?)` | Make any Zoom API request with schema validation |
 
 ## Usage
 
@@ -301,6 +301,10 @@ const result = await ctx.integrations.zoom.apiRequest(
 );
 ```
 
+## 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
 
 ### No Specialized Methods

package/src/runtime/context.ts

@@ -16,7 +16,11 @@ import type {
   IntegrationClientImpl,
 } from "../integrations/types.js";
 import type { IntegrationDeclaration } from "../integrations/declarations.js";
-import { createClient, type QueryExecutor } from "../integrations/registry.js";
+import {
+  createClient,
+  type QueryExecutor,
+  type TraceMetadata,
+} from "../integrations/registry.js";
 import { createDefaultLogger } from "./logger.js";
 
 /**
@@ -44,6 +48,7 @@ export interface CreateContextOptions {
     integrationId: string,
     request: Record<string, unknown>,
     bindings?: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ) => Promise<unknown>;
 
   /** Execution ID for logging correlation */
@@ -127,7 +132,8 @@ export function createApiContext(
     const boundExecutor: QueryExecutor = (
       request: Record<string, unknown>,
       bindings?: Record<string, unknown>,
-    ) => executeQuery(id, request, bindings);
+      metadata?: TraceMetadata,
+    ) => executeQuery(id, request, bindings, metadata);
 
     // Create config for client - use pre-loaded config or create synthetic one
     const clientConfig: IntegrationConfig = config ?? {

package/src/runtime/execute.ts

@@ -7,6 +7,7 @@
 
 import type { CompiledApi } from "../api/definition.js";
 import { isStreamingApi, type CompiledStreamingApi } from "../api/streaming.js";
+import type { TraceMetadata } from "../integrations/registry.js";
 import type { IntegrationConfig } from "../integrations/types.js";
 import type { ApiUser } from "../types.js";
 import { executeApi, type ExecuteApiResponse } from "./executor.js";
@@ -48,6 +49,7 @@ export interface UnifiedExecuteApiRequest {
     integrationId: string,
     request: Record<string, unknown>,
     bindings?: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ) => Promise<unknown>;
 
   /**
@@ -56,11 +58,13 @@ export interface UnifiedExecuteApiRequest {
    *
    * @param integrationId - The integration ID
    * @param request - Plugin-specific request object
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns AsyncIterable yielding raw chunks
    */
   executeStreamingQuery?: (
     integrationId: string,
     request: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ) => AsyncIterable<unknown>;
 }
 

package/src/runtime/executor.ts

@@ -7,6 +7,7 @@
 
 import type { CompiledApi } from "../api/definition.js";
 import { getIntegrationDeclarations } from "../integrations/declarations.js";
+import type { TraceMetadata } from "../integrations/registry.js";
 import type { IntegrationConfig } from "../integrations/types.js";
 import type { ApiUser } from "../types.js";
 import { createApiContext } from "./context.js";
@@ -58,6 +59,7 @@ export interface ExecuteApiRequest {
     integrationId: string,
     request: Record<string, unknown>,
     bindings?: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ) => Promise<unknown>;
 }
 

package/src/runtime/streaming-context.ts

@@ -20,6 +20,7 @@ import {
   createClient,
   type QueryExecutor,
   type StreamingQueryExecutor,
+  type TraceMetadata,
 } from "../integrations/registry.js";
 import { createDefaultLogger } from "./logger.js";
 
@@ -42,6 +43,7 @@ export interface CreateStreamingContextOptions {
     integrationId: string,
     request: Record<string, unknown>,
     bindings?: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ) => Promise<unknown>;
 
   /**
@@ -51,6 +53,7 @@ export interface CreateStreamingContextOptions {
   executeStreamingQuery?: (
     integrationId: string,
     request: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ) => AsyncIterable<unknown>;
 
   /** Execution ID for logging correlation */
@@ -111,13 +114,14 @@ export function createStreamingApiContext(
     const boundExecutor: QueryExecutor = (
       request: Record<string, unknown>,
       bindings?: Record<string, unknown>,
-    ) => executeQuery(id, request, bindings);
+      metadata?: TraceMetadata,
+    ) => executeQuery(id, request, bindings, metadata);
 
     // Create streaming executor if provided
     const boundStreamingExecutor: StreamingQueryExecutor | undefined =
       executeStreamingQuery
-        ? (request: Record<string, unknown>) =>
-            executeStreamingQuery(id, request)
+        ? (request: Record<string, unknown>, metadata?: TraceMetadata) =>
+            executeStreamingQuery(id, request, metadata)
         : undefined;
 
     const clientConfig: IntegrationConfig = config ?? {

package/src/runtime/streaming-executor.ts

@@ -7,6 +7,7 @@
 
 import type { CompiledStreamingApi } from "../api/streaming.js";
 import { getIntegrationDeclarations } from "../integrations/declarations.js";
+import type { TraceMetadata } from "../integrations/registry.js";
 import type { IntegrationConfig } from "../integrations/types.js";
 import type { ApiUser } from "../types.js";
 import {
@@ -52,6 +53,7 @@ export interface ExecuteStreamingApiRequest {
     integrationId: string,
     request: Record<string, unknown>,
     bindings?: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ) => Promise<unknown>;
 
   /**
@@ -59,11 +61,13 @@ export interface ExecuteStreamingApiRequest {
    *
    * @param integrationId - The integration ID
    * @param request - Plugin-specific request object
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns AsyncIterable yielding raw chunks
    */
   executeStreamingQuery?: (
     integrationId: string,
     request: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ) => AsyncIterable<unknown>;
 }