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

package/src/integrations/cosmosdb/types.ts

@@ -4,6 +4,7 @@
 
 import type { z } from "zod";
 import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
 
 /**
  * Options for CosmosDB SQL queries.
@@ -64,6 +65,7 @@ export interface CosmosDBClient extends BaseIntegrationClient {
     sql: string,
     schema: z.ZodSchema<T>,
     options?: CosmosDBQueryOptions,
+    metadata?: TraceMetadata,
   ): Promise<T>;
 
   /**
@@ -73,6 +75,7 @@ export interface CosmosDBClient extends BaseIntegrationClient {
    * @param id - The document ID
    * @param schema - Zod schema for validating the result
    * @param partitionKey - Optional partition key value
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The validated document
    */
   read<T>(
@@ -80,6 +83,7 @@ export interface CosmosDBClient extends BaseIntegrationClient {
     id: string,
     schema: z.ZodSchema<T>,
     partitionKey?: string,
+    metadata?: TraceMetadata,
   ): Promise<T>;
 
   /**
@@ -88,12 +92,14 @@ export interface CosmosDBClient extends BaseIntegrationClient {
    * @param containerId - The container to create in
    * @param body - The document to create (will be JSON-serialized)
    * @param partitionKey - Optional partition key value
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The raw result from CosmosDB
    */
   create(
     containerId: string,
     body: unknown,
     partitionKey?: string,
+    metadata?: TraceMetadata,
   ): Promise<unknown>;
 
   /**
@@ -102,12 +108,14 @@ export interface CosmosDBClient extends BaseIntegrationClient {
    * @param containerId - The container containing the document
    * @param body - The replacement document (will be JSON-serialized)
    * @param partitionKey - Optional partition key value
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The raw result from CosmosDB
    */
   replace(
     containerId: string,
     body: unknown,
     partitionKey?: string,
+    metadata?: TraceMetadata,
   ): Promise<unknown>;
 
   /**
@@ -116,12 +124,14 @@ export interface CosmosDBClient extends BaseIntegrationClient {
    * @param containerId - The container to upsert into
    * @param body - The document to upsert (will be JSON-serialized)
    * @param partitionKey - Optional partition key value
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The raw result from CosmosDB
    */
   upsert(
     containerId: string,
     body: unknown,
     partitionKey?: string,
+    metadata?: TraceMetadata,
   ): Promise<unknown>;
 
   /**
@@ -130,11 +140,13 @@ export interface CosmosDBClient extends BaseIntegrationClient {
    * @param containerId - The container containing the document
    * @param id - The document ID to delete
    * @param partitionKey - Optional partition key value
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The raw result from CosmosDB
    */
   deleteItem(
     containerId: string,
     id: string,
     partitionKey?: string,
+    metadata?: TraceMetadata,
   ): Promise<unknown>;
 }

package/src/integrations/couchbase/README.md

@@ -4,12 +4,12 @@ Interact with Couchbase databases with full type safety and runtime validation.
 
 ## Methods
 
-| Method                                | Description                                  |
-| ------------------------------------- | -------------------------------------------- |
-| `query(bucket, sql, schema, params?)` | Execute a SQL++ query with schema validation |
-| `insert(key, value, identifier)`      | Insert a document into a collection          |
-| `get(key, schema, identifier)`        | Get a document by key with schema validation |
-| `remove(key, identifier)`             | Remove a document by key                     |
+| Method                                           | Description                                  |
+| ------------------------------------------------ | -------------------------------------------- |
+| `query(bucket, sql, schema, params?, metadata?)` | Execute a SQL++ query with schema validation |
+| `insert(key, value, identifier, metadata?)`      | Insert a document into a collection          |
+| `get(key, schema, identifier, metadata?)`        | Get a document by key with schema validation |
+| `remove(key, identifier, metadata?)`             | Remove a document by key                     |
 
 ## Usage
 
@@ -97,6 +97,10 @@ await ctx.integrations.cb.remove("user::123", {
 });
 ```
 
+## 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

package/src/integrations/couchbase/client.ts

@@ -10,7 +10,7 @@ import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
 import type { Plugin as CouchbasePlugin } from "@superblocksteam/types/dist/src/plugins/couchbase/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, RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
 import { describeType } from "../utils.js";
@@ -52,6 +52,7 @@ export class CouchbaseClientImpl
     sql: string,
     schema: z.ZodSchema<T>,
     params?: unknown[],
+    metadata?: TraceMetadata,
   ): Promise<T[]> {
     const hasParams = params && params.length > 0;
     const request: CouchbaseRequest = {
@@ -68,6 +69,8 @@ export class CouchbaseClientImpl
     try {
       const result = await this.executeQuery(
         request as Record<string, unknown>,
+        undefined,
+        metadata,
       );
 
       if (!Array.isArray(result)) {
@@ -114,6 +117,7 @@ export class CouchbaseClientImpl
     key: string,
     value: unknown,
     identifier: CouchbaseIdentifier,
+    metadata?: TraceMetadata,
   ): Promise<void> {
     const request: CouchbaseRequest = {
       bucketName: identifier.bucket,
@@ -131,7 +135,11 @@ export class CouchbaseClientImpl
     };
 
     try {
-      await this.executeQuery(request as Record<string, unknown>);
+      await this.executeQuery(
+        request as Record<string, unknown>,
+        undefined,
+        metadata,
+      );
     } catch (error) {
       if (error instanceof IntegrationError) {
         throw error;
@@ -145,6 +153,7 @@ export class CouchbaseClientImpl
     key: string,
     schema: z.ZodSchema<T>,
     identifier: CouchbaseIdentifier,
+    metadata?: TraceMetadata,
   ): Promise<T> {
     const request: CouchbaseRequest = {
       bucketName: identifier.bucket,
@@ -163,6 +172,8 @@ export class CouchbaseClientImpl
     try {
       const result = await this.executeQuery(
         request as Record<string, unknown>,
+        undefined,
+        metadata,
       );
 
       const parseResult = schema.safeParse(result);
@@ -190,7 +201,11 @@ export class CouchbaseClientImpl
     }
   }
 
-  async remove(key: string, identifier: CouchbaseIdentifier): Promise<void> {
+  async remove(
+    key: string,
+    identifier: CouchbaseIdentifier,
+    metadata?: TraceMetadata,
+  ): Promise<void> {
     const request: CouchbaseRequest = {
       bucketName: identifier.bucket,
       couchbaseAction: {
@@ -206,7 +221,11 @@ export class CouchbaseClientImpl
     };
 
     try {
-      await this.executeQuery(request as Record<string, unknown>);
+      await this.executeQuery(
+        request as Record<string, unknown>,
+        undefined,
+        metadata,
+      );
     } catch (error) {
       if (error instanceof IntegrationError) {
         throw error;

package/src/integrations/couchbase/types.ts

@@ -4,6 +4,7 @@
 
 import type { z } from "zod";
 import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
 
 /**
  * Parameters for identifying a Couchbase document location.
@@ -75,6 +76,7 @@ export interface CouchbaseClient extends BaseIntegrationClient {
     sql: string,
     schema: z.ZodSchema<T>,
     params?: unknown[],
+    metadata?: TraceMetadata,
   ): Promise<T[]>;
 
   /**
@@ -83,11 +85,13 @@ export interface CouchbaseClient extends BaseIntegrationClient {
    * @param key - The document key
    * @param value - The document value (will be JSON-serialized)
    * @param identifier - The bucket, scope, and collection to insert into
+   * @param metadata - Optional trace metadata for diagnostics
    */
   insert(
     key: string,
     value: unknown,
     identifier: CouchbaseIdentifier,
+    metadata?: TraceMetadata,
   ): Promise<void>;
 
   /**
@@ -96,12 +100,14 @@ export interface CouchbaseClient extends BaseIntegrationClient {
    * @param key - The document key
    * @param schema - Zod schema for validating the result
    * @param identifier - The bucket, scope, and collection to get from
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The validated document
    */
   get<T>(
     key: string,
     schema: z.ZodSchema<T>,
     identifier: CouchbaseIdentifier,
+    metadata?: TraceMetadata,
   ): Promise<T>;
 
   /**
@@ -109,6 +115,11 @@ export interface CouchbaseClient extends BaseIntegrationClient {
    *
    * @param key - The document key
    * @param identifier - The bucket, scope, and collection to remove from
+   * @param metadata - Optional trace metadata for diagnostics
    */
-  remove(key: string, identifier: CouchbaseIdentifier): Promise<void>;
+  remove(
+    key: string,
+    identifier: CouchbaseIdentifier,
+    metadata?: TraceMetadata,
+  ): Promise<void>;
 }

package/src/integrations/databricks/README.md

@@ -4,10 +4,10 @@ Execute SQL queries against Databricks SQL warehouses with full type safety and
 
 ## 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
 
@@ -94,6 +94,10 @@ const analytics = await ctx.integrations.databricks.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/LONG Values Returned as Strings

package/src/integrations/databricks/client.ts

@@ -9,7 +9,7 @@ import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
 import type { Plugin as DatabricksPlugin } from "@superblocksteam/types/dist/src/plugins/databricks/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";
@@ -66,11 +66,12 @@ export class DatabricksClientImpl
     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(
@@ -118,11 +119,12 @@ export class DatabricksClientImpl
   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/databricks/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 Databricks queries with type-safe validation.
@@ -45,6 +46,7 @@ export interface DatabricksClient extends BaseIntegrationClient {
     sql: string,
     schema: z.ZodSchema<T>,
     params?: unknown[],
+    metadata?: TraceMetadata,
   ): Promise<T[]>;
 
   /**
@@ -54,5 +56,9 @@ export interface DatabricksClient 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/datadog/README.md

@@ -4,9 +4,9 @@ Query metrics, manage monitors, and interact with Datadog's monitoring and obser
 
 ## Methods
 
-| Method                        | Description                                         |
-| ----------------------------- | --------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any Datadog API request with schema validation |
+| Method                                   | Description                                         |
+| ---------------------------------------- | --------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Datadog API request with schema validation |
 
 ## Usage
 
@@ -311,6 +311,10 @@ result.data.forEach((log) => {
 });
 ```
 
+## 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/dropbox/README.md

@@ -4,9 +4,9 @@ Upload, download, and manage files in Dropbox.
 
 ## Methods
 
-| Method                        | Description                                         |
-| ----------------------------- | --------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any Dropbox API request with schema validation |
+| Method                                   | Description                                         |
+| ---------------------------------------- | --------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Dropbox API request with schema validation |
 
 ## Usage
 
@@ -316,6 +316,10 @@ const result = await ctx.integrations.dropbox.apiRequest(
 console.log(`Share URL: ${result.url}`);
 ```
 
+## 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/dynamodb/README.md

@@ -4,19 +4,19 @@ Execute operations against Amazon DynamoDB with full type safety and runtime val
 
 ## Methods
 
-| Method                                               | Description                  |
-| ---------------------------------------------------- | ---------------------------- |
-| `query(statement, schema, params?)`                  | Execute a PartiQL statement  |
-| `getItem(table, key, schema)`                        | Get an item by key           |
-| `putItem(table, item)`                               | Insert or replace an item    |
-| `updateItem(table, key, expr, values, names?)`       | Update an existing item      |
-| `deleteItem(table, key)`                             | Delete an item by key        |
-| `scan(table, schema, filter?, values?, names?)`      | Scan a table                 |
-| `queryTable(table, keyExpr, values, schema, names?)` | Query by key condition       |
-| `batchWriteItem(requestItems)`                       | Batch write multiple items   |
-| `listTables(schema)`                                 | List all tables              |
-| `describeTable(table, schema)`                       | Describe a table's structure |
-| `deleteTable(table)`                                 | Delete a table               |
+| Method                                                          | Description                  |
+| --------------------------------------------------------------- | ---------------------------- |
+| `query(statement, schema, params?, metadata?)`                  | Execute a PartiQL statement  |
+| `getItem(table, key, schema, metadata?)`                        | Get an item by key           |
+| `putItem(table, item, metadata?)`                               | Insert or replace an item    |
+| `updateItem(table, key, expr, values, names?, metadata?)`       | Update an existing item      |
+| `deleteItem(table, key, metadata?)`                             | Delete an item by key        |
+| `scan(table, schema, filter?, values?, names?, metadata?)`      | Scan a table                 |
+| `queryTable(table, keyExpr, values, schema, names?, metadata?)` | Query by key condition       |
+| `batchWriteItem(requestItems, metadata?)`                       | Batch write multiple items   |
+| `listTables(schema, metadata?)`                                 | List all tables              |
+| `describeTable(table, schema, metadata?)`                       | Describe a table's structure |
+| `deleteTable(table, metadata?)`                                 | Delete a table               |
 
 ## DynamoDB AttributeValue Format
 
@@ -205,6 +205,10 @@ const description = await ctx.integrations.dynamodb.describeTable(
 await ctx.integrations.dynamodb.deleteTable("temp-table");
 ```
 
+## 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
 
 ### Use Parameterized PartiQL Queries

package/src/integrations/dynamodb/client.ts

@@ -8,7 +8,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 { DynamoDBClient, DynamoDBAttributeValue } from "./types.js";
@@ -86,9 +86,10 @@ export class DynamoDBClientImpl
   private async executeWithErrorHandling(
     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 ||
@@ -105,6 +106,7 @@ export class DynamoDBClientImpl
     statement: string,
     schema: z.ZodSchema<T>,
     params?: DynamoDBAttributeValue[],
+    metadata?: TraceMetadata,
   ): Promise<T> {
     const body: Record<string, unknown> = { Statement: statement };
 
@@ -113,7 +115,11 @@ export class DynamoDBClientImpl
     }
 
     const request = this.buildRequest("executeStatement", body);
-    const result = await this.executeWithErrorHandling(request, "query");
+    const result = await this.executeWithErrorHandling(
+      request,
+      "query",
+      metadata,
+    );
     return this.validateResult(result, schema, "query");
   }
 
@@ -121,24 +127,30 @@ export class DynamoDBClientImpl
     table: string,
     key: Record<string, DynamoDBAttributeValue>,
     schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
   ): Promise<T> {
     const request = this.buildRequest("getItem", {
       TableName: table,
       Key: key,
     });
-    const result = await this.executeWithErrorHandling(request, "getItem");
+    const result = await this.executeWithErrorHandling(
+      request,
+      "getItem",
+      metadata,
+    );
     return this.validateResult(result, schema, "getItem");
   }
 
   async putItem(
     table: string,
     item: Record<string, DynamoDBAttributeValue>,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request = this.buildRequest("putItem", {
       TableName: table,
       Item: item,
     });
-    return this.executeWithErrorHandling(request, "putItem");
+    return this.executeWithErrorHandling(request, "putItem", metadata);
   }
 
   async updateItem(
@@ -147,6 +159,7 @@ export class DynamoDBClientImpl
     updateExpression: string,
     expressionAttributeValues: Record<string, DynamoDBAttributeValue>,
     expressionAttributeNames?: Record<string, string>,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const params: Record<string, unknown> = {
       TableName: table,
@@ -160,18 +173,19 @@ export class DynamoDBClientImpl
     }
 
     const request = this.buildRequest("updateItem", params);
-    return this.executeWithErrorHandling(request, "updateItem");
+    return this.executeWithErrorHandling(request, "updateItem", metadata);
   }
 
   async deleteItem(
     table: string,
     key: Record<string, DynamoDBAttributeValue>,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request = this.buildRequest("deleteItem", {
       TableName: table,
       Key: key,
     });
-    return this.executeWithErrorHandling(request, "deleteItem");
+    return this.executeWithErrorHandling(request, "deleteItem", metadata);
   }
 
   async scan<T>(
@@ -180,6 +194,7 @@ export class DynamoDBClientImpl
     filterExpression?: string,
     expressionAttributeValues?: Record<string, DynamoDBAttributeValue>,
     expressionAttributeNames?: Record<string, string>,
+    metadata?: TraceMetadata,
   ): Promise<T> {
     const params: Record<string, unknown> = { TableName: table };
 
@@ -196,7 +211,11 @@ export class DynamoDBClientImpl
     }
 
     const request = this.buildRequest("scan", params);
-    const result = await this.executeWithErrorHandling(request, "scan");
+    const result = await this.executeWithErrorHandling(
+      request,
+      "scan",
+      metadata,
+    );
     return this.validateResult(result, schema, "scan");
   }
 
@@ -206,6 +225,7 @@ export class DynamoDBClientImpl
     expressionAttributeValues: Record<string, DynamoDBAttributeValue>,
     schema: z.ZodSchema<T>,
     expressionAttributeNames?: Record<string, string>,
+    metadata?: TraceMetadata,
   ): Promise<T> {
     const params: Record<string, unknown> = {
       TableName: table,
@@ -218,40 +238,57 @@ export class DynamoDBClientImpl
     }
 
     const request = this.buildRequest("query", params);
-    const result = await this.executeWithErrorHandling(request, "queryTable");
+    const result = await this.executeWithErrorHandling(
+      request,
+      "queryTable",
+      metadata,
+    );
     return this.validateResult(result, schema, "queryTable");
   }
 
   async batchWriteItem(
     requestItems: Record<string, Array<Record<string, unknown>>>,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request = this.buildRequest("batchWriteItem", {
       RequestItems: requestItems,
     });
-    return this.executeWithErrorHandling(request, "batchWriteItem");
+    return this.executeWithErrorHandling(request, "batchWriteItem", metadata);
   }
 
-  async listTables<T>(schema: z.ZodSchema<T>): Promise<T> {
+  async listTables<T>(
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T> {
     const request = this.buildRequest("listTables", {});
-    const result = await this.executeWithErrorHandling(request, "listTables");
+    const result = await this.executeWithErrorHandling(
+      request,
+      "listTables",
+      metadata,
+    );
     return this.validateResult(result, schema, "listTables");
   }
 
-  async describeTable<T>(table: string, schema: z.ZodSchema<T>): Promise<T> {
+  async describeTable<T>(
+    table: string,
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T> {
     const request = this.buildRequest("describeTable", {
       TableName: table,
     });
     const result = await this.executeWithErrorHandling(
       request,
       "describeTable",
+      metadata,
     );
     return this.validateResult(result, schema, "describeTable");
   }
 
-  async deleteTable(table: string): Promise<unknown> {
+  async deleteTable(table: string, metadata?: TraceMetadata): Promise<unknown> {
     const request = this.buildRequest("deleteTable", {
       TableName: table,
     });
-    return this.executeWithErrorHandling(request, "deleteTable");
+    return this.executeWithErrorHandling(request, "deleteTable", metadata);
   }
 }