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

package/src/integrations/base/graphql-integration-client.ts

@@ -6,7 +6,7 @@
  */
 
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor } from "../registry.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import { z } from "zod";
 import { RestApiValidationError } from "../../errors.js";
 
@@ -38,14 +38,16 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
    * @param query - GraphQL query string
    * @param schema - Zod schema for full response validation (REQUIRED)
    * @param variables - Optional variables for the query
+   * @param metadata - Optional trace metadata for observability
    * @returns Validated query result
    */
   async query<TResponse>(
     query: string,
     schema: { response: z.ZodSchema<TResponse> },
     variables?: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ): Promise<TResponse> {
-    return this.executeGraphQL(query, schema, variables);
+    return this.executeGraphQL(query, schema, variables, metadata);
   }
 
   /**
@@ -54,14 +56,16 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
    * @param mutation - GraphQL mutation string
    * @param schema - Zod schema for full response validation (REQUIRED)
    * @param variables - Optional variables for the mutation
+   * @param metadata - Optional trace metadata for observability
    * @returns Validated mutation result
    */
   async mutation<TResponse>(
     mutation: string,
     schema: { response: z.ZodSchema<TResponse> },
     variables?: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ): Promise<TResponse> {
-    return this.executeGraphQL(mutation, schema, variables);
+    return this.executeGraphQL(mutation, schema, variables, metadata);
   }
 
   /**
@@ -74,6 +78,7 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
     queryString: string,
     schema: { response: z.ZodSchema<TResponse> },
     variables?: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ): Promise<TResponse> {
     // Build graphql.v1.Plugin proto message
     const request = {
@@ -91,7 +96,7 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
     };
 
     // Execute query through orchestrator
-    const response = await this.executeQuery(request);
+    const response = await this.executeQuery(request, undefined, metadata);
 
     // Return full GraphQL response without unwrapping
     // Users should access result.data themselves

package/src/integrations/base/rest-api-integration-client.ts

@@ -8,7 +8,11 @@ import type { PartialMessage } from "@bufbuild/protobuf";
 import type { Plugin as RestApiIntegrationPlugin } from "@superblocksteam/types/dist/src/plugins/restapiintegration/v1/plugin_pb";
 import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, StreamingQueryExecutor } from "../registry.js";
+import type {
+  QueryExecutor,
+  StreamingQueryExecutor,
+  TraceMetadata,
+} from "../registry.js";
 import type {
   ApiRequestOptions,
   ApiRequestSchema,
@@ -71,6 +75,7 @@ export abstract class RestApiIntegrationClient
     schema: ApiRequestSchema<TBody, TResponse> & {
       response: z.ZodSchema<TResponse>;
     },
+    metadata?: TraceMetadata,
   ): Promise<TResponse> {
     // Validate that body schema is provided if body is present
     if (options.body !== undefined) {
@@ -139,7 +144,11 @@ export abstract class RestApiIntegrationClient
     }
 
     // Execute the request
-    const result = await this.executeQuery(request as Record<string, unknown>);
+    const result = await this.executeQuery(
+      request as Record<string, unknown>,
+      undefined,
+      metadata,
+    );
 
     // Response schema is REQUIRED - always validate
     const responseParseResult = schema.response.safeParse(result);
@@ -165,6 +174,7 @@ export abstract class RestApiIntegrationClient
    *
    * @param options - Request configuration including method, path, params, and body
    * @param schema - Zod schemas for request body and chunk validation
+   * @param metadata - Optional trace metadata for observability (label, description)
    * @returns AsyncIterable yielding validated chunks
    *
    * @example
@@ -188,7 +198,8 @@ export abstract class RestApiIntegrationClient
    *       messages: [{ role: 'user', content: 'Hello!' }],
    *     },
    *   },
-   *   { chunk: ChunkSchema }
+   *   { chunk: ChunkSchema },
+   *   { label: 'openai.chatCompletions', description: 'Stream chat completion' }
    * );
    *
    * for await (const chunk of stream) {
@@ -199,6 +210,7 @@ export abstract class RestApiIntegrationClient
   async *streamApiRequest<TBody, TChunk>(
     options: ApiRequestOptions<TBody>,
     schema: StreamApiRequestSchema<TBody, TChunk>,
+    metadata?: TraceMetadata,
   ): AsyncIterable<TChunk> {
     // Validate that streaming is supported
     if (!this.executeStreamingQuery) {
@@ -278,6 +290,7 @@ export abstract class RestApiIntegrationClient
     // Execute the streaming request
     const stream = this.executeStreamingQuery(
       request as Record<string, unknown>,
+      metadata,
     );
 
     // Validate and yield each chunk

package/src/integrations/base/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+import type { TraceMetadata } from "../registry.js";
 
 /**
  * Options for making a generic REST API request.
@@ -63,6 +64,7 @@ export interface SupportsApiRequest {
    *
    * @param options - Request configuration including method, path, params, and body
    * @param schema - Zod schemas for request body and response validation (response schema REQUIRED)
+   * @param metadata - Optional trace metadata for observability (label, description)
    * @returns Validated response data
    *
    * @example
@@ -84,7 +86,8 @@ export interface SupportsApiRequest {
    *       text: z.string(),
    *     }),
    *     response: ResponseSchema,
-   *   }
+   *   },
+   *   { label: 'slack.postMessage', description: 'Post a message to #alerts' }
    * );
    * // result is typed as { ts: string; channel: string }
    * ```
@@ -94,6 +97,7 @@ export interface SupportsApiRequest {
     schema: ApiRequestSchema<TBody, TResponse> & {
       response: z.ZodSchema<TResponse>;
     },
+    metadata?: TraceMetadata,
   ): Promise<TResponse>;
 }
 
@@ -131,6 +135,7 @@ export interface SupportsStreamingApiRequest {
    *
    * @param options - Request configuration including method, path, params, and body
    * @param schema - Zod schemas for request body and chunk validation (chunk schema REQUIRED)
+   * @param metadata - Optional trace metadata for observability (label, description)
    * @returns AsyncIterable yielding validated chunks
    *
    * @example
@@ -154,7 +159,8 @@ export interface SupportsStreamingApiRequest {
    *       messages: [{ role: 'user', content: 'Hello!' }],
    *     },
    *   },
-   *   { chunk: ChunkSchema }
+   *   { chunk: ChunkSchema },
+   *   { label: 'openai.chatCompletions', description: 'Stream chat completion' }
    * );
    *
    * for await (const chunk of stream) {
@@ -165,5 +171,6 @@ export interface SupportsStreamingApiRequest {
   streamApiRequest<TBody, TChunk>(
     options: ApiRequestOptions<TBody>,
     schema: StreamApiRequestSchema<TBody, TChunk>,
+    metadata?: TraceMetadata,
   ): AsyncIterable<TChunk>;
 }

package/src/integrations/bigquery/README.md

@@ -4,10 +4,10 @@ Execute SQL queries against Google BigQuery with full type safety and runtime va
 
 ## Methods
 
-| Method                           | Description                                                |
-| -------------------------------- | ---------------------------------------------------------- |
-| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results |
-| `execute(sql, params?)`          | Execute a statement 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 and return affected row count          |
 
 ## Usage
 
@@ -110,6 +110,10 @@ const activity = await ctx.integrations.bigquery.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
 
 ### Backtick Table References

package/src/integrations/bigquery/client.ts

@@ -9,7 +9,7 @@ import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
 import type { Plugin as BigQueryPlugin } from "@superblocksteam/types/dist/src/plugins/bigquery/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 BigQueryClientImpl
     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 BigQueryClientImpl
   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/bigquery/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 BigQuery queries with type-safe validation.
@@ -45,6 +46,7 @@ export interface BigQueryClient extends BaseIntegrationClient {
     sql: string,
     schema: z.ZodSchema<T>,
     params?: unknown[],
+    metadata?: TraceMetadata,
   ): Promise<T[]>;
 
   /**
@@ -54,5 +56,9 @@ export interface BigQueryClient 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/bitbucket/README.md

@@ -4,9 +4,9 @@ Manage repositories, pull requests, and interact with Bitbucket's APIs.
 
 ## Methods
 
-| Method                        | Description                                           |
-| ----------------------------- | ----------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any Bitbucket API request with schema validation |
+| Method                                   | Description                                           |
+| ---------------------------------------- | ----------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Bitbucket API request with schema validation |
 
 ## Usage
 
@@ -285,6 +285,10 @@ const comment = await ctx.integrations.bitbucket.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/box/README.md

@@ -4,9 +4,9 @@ Upload, download, and manage files in Box.
 
 ## Methods
 
-| Method                        | Description                                     |
-| ----------------------------- | ----------------------------------------------- |
-| `apiRequest(options, schema)` | Make any Box API request with schema validation |
+| Method                                   | Description                                     |
+| ---------------------------------------- | ----------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Box API request with schema validation |
 
 ## Usage
 
@@ -385,6 +385,10 @@ const comment = await ctx.integrations.box.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/circleci/README.md

@@ -4,9 +4,9 @@ Trigger pipelines, manage jobs, and interact with CircleCI's CI/CD platform.
 
 ## Methods
 
-| Method                        | Description                                          |
-| ----------------------------- | ---------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any CircleCI API request with schema validation |
+| Method                                   | Description                                          |
+| ---------------------------------------- | ---------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any CircleCI API request with schema validation |
 
 ## Usage
 
@@ -280,6 +280,10 @@ result.items.forEach((artifact) => {
 });
 ```
 
+## 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/cockroachdb/README.md

@@ -4,10 +4,10 @@ Execute SQL queries and statements against CockroachDB databases with full type
 
 ## 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
 
@@ -84,6 +84,10 @@ const items = await ctx.integrations.db.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
 
 ### UUID Primary Keys

package/src/integrations/cockroachdb/client.ts

@@ -9,7 +9,7 @@ import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
 import type { Plugin as CockroachDBPlugin } from "@superblocksteam/types/dist/src/plugins/cockroachdb/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 CockroachDBClientImpl
     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 CockroachDBClientImpl
   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/cockroachdb/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 CockroachDB queries with type-safe validation.
@@ -45,6 +46,7 @@ export interface CockroachDBClient extends BaseIntegrationClient {
     sql: string,
     schema: z.ZodSchema<T>,
     params?: unknown[],
+    metadata?: TraceMetadata,
   ): Promise<T[]>;
 
   /**
@@ -54,5 +56,9 @@ export interface CockroachDBClient 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/cohere/README.md

@@ -4,9 +4,9 @@ Interact with Cohere's APIs for text generation, embeddings, classification, and
 
 ## Methods
 
-| Method                        | Description                                        |
-| ----------------------------- | -------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any Cohere API request with schema validation |
+| Method                                   | Description                                        |
+| ---------------------------------------- | -------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Cohere API request with schema validation |
 
 ## Usage
 
@@ -205,6 +205,10 @@ const result = await ctx.integrations.cohere.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/confluence/README.md

@@ -4,9 +4,9 @@ Create pages, manage content, and search in Confluence spaces.
 
 ## Methods
 
-| Method                        | Description                                            |
-| ----------------------------- | ------------------------------------------------------ |
-| `apiRequest(options, schema)` | Make any Confluence API request with schema validation |
+| Method                                   | Description                                            |
+| ---------------------------------------- | ------------------------------------------------------ |
+| `apiRequest(options, schema, metadata?)` | Make any Confluence API request with schema validation |
 
 ## Usage
 
@@ -292,6 +292,10 @@ const result = await ctx.integrations.confluence.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/cosmosdb/README.md

@@ -4,9 +4,9 @@ Interact with Azure CosmosDB with full type safety and runtime validation.
 
 ## Methods
 
-| Method                        | Description                                          |
-| ----------------------------- | ---------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any CosmosDB API request with schema validation |
+| Method                                   | Description                                          |
+| ---------------------------------------- | ---------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any CosmosDB API request with schema validation |
 
 ## Usage
 
@@ -158,6 +158,10 @@ await ctx.integrations.cosmosdb.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
 
 ### Partition Key Header

package/src/integrations/cosmosdb/client.ts

@@ -10,7 +10,7 @@ import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
 import type { Plugin as CosmosDBPlugin } from "@superblocksteam/types/dist/src/plugins/cosmosdb/v1/plugin_pb";
 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 { CosmosDBClient, CosmosDBQueryOptions } from "./types.js";
@@ -51,9 +51,14 @@ export class CosmosDBClientImpl
   private async exec(
     request: CosmosDBRequest,
     operation: string,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     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 RestApiValidationError ||
@@ -90,6 +95,7 @@ export class CosmosDBClientImpl
     sql: string,
     schema: z.ZodSchema<T>,
     options?: CosmosDBQueryOptions,
+    metadata?: TraceMetadata,
   ): Promise<T> {
     const request: CosmosDBRequest = {
       cosmosdbAction: {
@@ -108,7 +114,7 @@ export class CosmosDBClientImpl
       },
     };
 
-    const result = await this.exec(request, "query");
+    const result = await this.exec(request, "query", metadata);
     return this.validate(result, schema);
   }
 
@@ -117,6 +123,7 @@ export class CosmosDBClientImpl
     id: string,
     schema: z.ZodSchema<T>,
     partitionKey?: string,
+    metadata?: TraceMetadata,
   ): Promise<T> {
     const request: CosmosDBRequest = {
       cosmosdbAction: {
@@ -131,7 +138,7 @@ export class CosmosDBClientImpl
       },
     };
 
-    const result = await this.exec(request, "read");
+    const result = await this.exec(request, "read", metadata);
     return this.validate(result, schema);
   }
 
@@ -139,6 +146,7 @@ export class CosmosDBClientImpl
     containerId: string,
     body: unknown,
     partitionKey?: string,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request: CosmosDBRequest = {
       cosmosdbAction: {
@@ -156,13 +164,14 @@ export class CosmosDBClientImpl
       },
     };
 
-    return this.exec(request, "create");
+    return this.exec(request, "create", metadata);
   }
 
   async replace(
     containerId: string,
     body: unknown,
     partitionKey?: string,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request: CosmosDBRequest = {
       cosmosdbAction: {
@@ -180,13 +189,14 @@ export class CosmosDBClientImpl
       },
     };
 
-    return this.exec(request, "replace");
+    return this.exec(request, "replace", metadata);
   }
 
   async upsert(
     containerId: string,
     body: unknown,
     partitionKey?: string,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request: CosmosDBRequest = {
       cosmosdbAction: {
@@ -204,13 +214,14 @@ export class CosmosDBClientImpl
       },
     };
 
-    return this.exec(request, "upsert");
+    return this.exec(request, "upsert", metadata);
   }
 
   async deleteItem(
     containerId: string,
     id: string,
     partitionKey?: string,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request: CosmosDBRequest = {
       cosmosdbAction: {
@@ -225,6 +236,6 @@ export class CosmosDBClientImpl
       },
     };
 
-    return this.exec(request, "delete");
+    return this.exec(request, "delete", metadata);
   }
 }