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

package/src/integrations/s3/client.ts

@@ -8,7 +8,7 @@ import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
 import type { Plugin as S3Plugin } from "@superblocksteam/types/dist/src/plugins/s3/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 {
@@ -44,13 +44,18 @@ export class S3ClientImpl implements S3Client, IntegrationClientImpl {
   private async execute(
     action: S3Action,
     request: PartialMessage<S3Plugin>,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const fullRequest: PartialMessage<S3Plugin> = {
       ...request,
       action,
     };
 
-    return this.executeQuery(fullRequest as Record<string, unknown>);
+    return this.executeQuery(
+      fullRequest as Record<string, unknown>,
+      undefined,
+      metadata,
+    );
   }
 
   /**
@@ -97,9 +102,12 @@ export class S3ClientImpl implements S3Client, IntegrationClientImpl {
     }
   }
 
-  async listBuckets<T>(schema: z.ZodSchema<T>): Promise<T> {
+  async listBuckets<T>(
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T> {
     return this.withErrorHandling("listBuckets", async () => {
-      const result = await this.execute("LIST_BUCKETS", {});
+      const result = await this.execute("LIST_BUCKETS", {}, metadata);
       return this.validate(result, schema, "listBuckets");
     });
   }
@@ -108,6 +116,7 @@ export class S3ClientImpl implements S3Client, IntegrationClientImpl {
     bucket: string,
     schema: z.ZodSchema<T>,
     options?: S3ListObjectsOptions,
+    metadata?: TraceMetadata,
   ): Promise<T> {
     return this.withErrorHandling("listObjects", async () => {
       const request: PartialMessage<S3Plugin> = {
@@ -121,7 +130,11 @@ export class S3ClientImpl implements S3Client, IntegrationClientImpl {
         };
       }
 
-      const result = await this.execute("LIST_BUCKET_OBJECTS", request);
+      const result = await this.execute(
+        "LIST_BUCKET_OBJECTS",
+        request,
+        metadata,
+      );
       return this.validate(result, schema, "listObjects");
     });
   }
@@ -131,6 +144,7 @@ export class S3ClientImpl implements S3Client, IntegrationClientImpl {
     path: string,
     schema: z.ZodSchema<T>,
     options?: S3GetObjectOptions,
+    metadata?: TraceMetadata,
   ): Promise<T> {
     return this.withErrorHandling("getObject", async () => {
       const request: PartialMessage<S3Plugin> = {
@@ -142,17 +156,25 @@ export class S3ClientImpl implements S3Client, IntegrationClientImpl {
         request.responseType = options.responseType;
       }
 
-      const result = await this.execute("GET_OBJECT", request);
+      const result = await this.execute("GET_OBJECT", request, metadata);
       return this.validate(result, schema, "getObject");
     });
   }
 
-  async deleteObject(bucket: string, path: string): Promise<void> {
+  async deleteObject(
+    bucket: string,
+    path: string,
+    metadata?: TraceMetadata,
+  ): Promise<void> {
     return this.withErrorHandling("deleteObject", async () => {
-      await this.execute("DELETE_OBJECT", {
-        resource: bucket,
-        path,
-      });
+      await this.execute(
+        "DELETE_OBJECT",
+        {
+          resource: bucket,
+          path,
+        },
+        metadata,
+      );
     });
   }
 
@@ -160,25 +182,35 @@ export class S3ClientImpl implements S3Client, IntegrationClientImpl {
     bucket: string,
     path: string,
     body: string,
+    metadata?: TraceMetadata,
   ): Promise<void> {
     return this.withErrorHandling("uploadObject", async () => {
-      await this.execute("UPLOAD_OBJECT", {
-        resource: bucket,
-        path,
-        body,
-      });
+      await this.execute(
+        "UPLOAD_OBJECT",
+        {
+          resource: bucket,
+          path,
+          body,
+        },
+        metadata,
+      );
     });
   }
 
   async uploadMultipleObjects(
     bucket: string,
     fileObjects: string,
+    metadata?: TraceMetadata,
   ): Promise<void> {
     return this.withErrorHandling("uploadMultipleObjects", async () => {
-      await this.execute("UPLOAD_MULTIPLE_OBJECTS", {
-        resource: bucket,
-        fileObjects,
-      });
+      await this.execute(
+        "UPLOAD_MULTIPLE_OBJECTS",
+        {
+          resource: bucket,
+          fileObjects,
+        },
+        metadata,
+      );
     });
   }
 
@@ -186,12 +218,17 @@ export class S3ClientImpl implements S3Client, IntegrationClientImpl {
     bucket: string,
     path: string,
     schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
   ): Promise<T> {
     return this.withErrorHandling("generatePresignedUrl", async () => {
-      const result = await this.execute("GENERATE_PRESIGNED_URL", {
-        resource: bucket,
-        path,
-      });
+      const result = await this.execute(
+        "GENERATE_PRESIGNED_URL",
+        {
+          resource: bucket,
+          path,
+        },
+        metadata,
+      );
       return this.validate(result, schema, "generatePresignedUrl");
     });
   }

package/src/integrations/s3/types.ts

@@ -4,6 +4,7 @@
 
 import type { z } from "zod";
 import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
 
 /**
  * S3 action types (used internally by the client).
@@ -74,7 +75,7 @@ export interface S3Client extends BaseIntegrationClient {
    * @param schema - Zod schema for validating the result
    * @returns The validated bucket list
    */
-  listBuckets<T>(schema: z.ZodSchema<T>): Promise<T>;
+  listBuckets<T>(schema: z.ZodSchema<T>, metadata?: TraceMetadata): Promise<T>;
 
   /**
    * List objects in a bucket.
@@ -82,12 +83,14 @@ export interface S3Client extends BaseIntegrationClient {
    * @param bucket - Bucket name
    * @param schema - Zod schema for validating the result
    * @param options - Optional prefix and delimiter filters
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The validated object list
    */
   listObjects<T>(
     bucket: string,
     schema: z.ZodSchema<T>,
     options?: S3ListObjectsOptions,
+    metadata?: TraceMetadata,
   ): Promise<T>;
 
   /**
@@ -97,6 +100,7 @@ export interface S3Client extends BaseIntegrationClient {
    * @param path - Object key/path
    * @param schema - Zod schema for validating the result
    * @param options - Optional response type
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The validated object content
    */
   getObject<T>(
@@ -104,6 +108,7 @@ export interface S3Client extends BaseIntegrationClient {
     path: string,
     schema: z.ZodSchema<T>,
     options?: S3GetObjectOptions,
+    metadata?: TraceMetadata,
   ): Promise<T>;
 
   /**
@@ -111,8 +116,13 @@ export interface S3Client extends BaseIntegrationClient {
    *
    * @param bucket - Bucket name
    * @param path - Object key/path
+   * @param metadata - Optional trace metadata for diagnostics
    */
-  deleteObject(bucket: string, path: string): Promise<void>;
+  deleteObject(
+    bucket: string,
+    path: string,
+    metadata?: TraceMetadata,
+  ): Promise<void>;
 
   /**
    * Upload an object to a bucket.
@@ -120,16 +130,27 @@ export interface S3Client extends BaseIntegrationClient {
    * @param bucket - Bucket name
    * @param path - Object key/path
    * @param body - File content (base64 or text)
+   * @param metadata - Optional trace metadata for diagnostics
    */
-  uploadObject(bucket: string, path: string, body: string): Promise<void>;
+  uploadObject(
+    bucket: string,
+    path: string,
+    body: string,
+    metadata?: TraceMetadata,
+  ): Promise<void>;
 
   /**
    * Upload multiple objects to a bucket.
    *
    * @param bucket - Bucket name
    * @param fileObjects - Serialized file objects
+   * @param metadata - Optional trace metadata for diagnostics
    */
-  uploadMultipleObjects(bucket: string, fileObjects: string): Promise<void>;
+  uploadMultipleObjects(
+    bucket: string,
+    fileObjects: string,
+    metadata?: TraceMetadata,
+  ): Promise<void>;
 
   /**
    * Generate a presigned URL for an object.
@@ -137,11 +158,13 @@ export interface S3Client extends BaseIntegrationClient {
    * @param bucket - Bucket name
    * @param path - Object key/path
    * @param schema - Zod schema for validating the result
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The validated presigned URL
    */
   generatePresignedUrl<T>(
     bucket: string,
     path: string,
     schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
   ): Promise<T>;
 }

package/src/integrations/salesforce/README.md

@@ -4,17 +4,17 @@ Execute SOQL queries, CRUD operations, and bulk operations against Salesforce wi
 
 ## Methods
 
-| Method                                          | Description                                         |
-| ----------------------------------------------- | --------------------------------------------------- |
-| `query(soql, schema)`                           | Execute a SOQL query with per-row schema validation |
-| `create(resourceType, body)`                    | Create a new Salesforce object                      |
-| `read(resourceType, resourceId, schema)`        | Read a single object by ID                          |
-| `update(resourceType, resourceId, body)`        | Update an existing object                           |
-| `remove(resourceType, resourceId)`              | Delete an object by ID                              |
-| `bulkCreate(resourceType, records)`             | Bulk create multiple objects                        |
-| `bulkUpdate(resourceType, records)`             | Bulk update multiple objects                        |
-| `bulkDelete(resourceType, records)`             | Bulk delete multiple objects                        |
-| `bulkUpsert(resourceType, records, externalId)` | Bulk upsert with external ID matching               |
+| Method                                                     | Description                                         |
+| ---------------------------------------------------------- | --------------------------------------------------- |
+| `query(soql, schema, metadata?)`                           | Execute a SOQL query with per-row schema validation |
+| `create(resourceType, body, metadata?)`                    | Create a new Salesforce object                      |
+| `read(resourceType, resourceId, schema, metadata?)`        | Read a single object by ID                          |
+| `update(resourceType, resourceId, body, metadata?)`        | Update an existing object                           |
+| `remove(resourceType, resourceId, metadata?)`              | Delete an object by ID                              |
+| `bulkCreate(resourceType, records, metadata?)`             | Bulk create multiple objects                        |
+| `bulkUpdate(resourceType, records, metadata?)`             | Bulk update multiple objects                        |
+| `bulkDelete(resourceType, records, metadata?)`             | Bulk delete multiple objects                        |
+| `bulkUpsert(resourceType, records, externalId, metadata?)` | Bulk upsert with external ID matching               |
 
 ## Usage
 
@@ -154,6 +154,10 @@ await salesforce.bulkUpsert(
 );
 ```
 
+## 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
 
 ### Schema Must Match Salesforce Field Names

package/src/integrations/salesforce/client.ts

@@ -7,7 +7,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 { QueryValidationError, RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
 import { describeType } from "../utils.js";
@@ -66,9 +66,10 @@ export class SalesforceClientImpl
   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 QueryValidationError ||
@@ -128,7 +129,11 @@ export class SalesforceClientImpl
     return { bulk };
   }
 
-  async query<T>(soql: string, schema: z.ZodSchema<T>): Promise<T[]> {
+  async query<T>(
+    soql: string,
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T[]> {
     const request = {
       soql: {
         action: SOQL_ACTION_SOQL,
@@ -139,6 +144,7 @@ export class SalesforceClientImpl
     const result = await this.exec(
       request as unknown as Record<string, unknown>,
       "query",
+      metadata,
     );
 
     if (!Array.isArray(result)) {
@@ -177,22 +183,24 @@ export class SalesforceClientImpl
   async create(
     resourceType: string,
     body: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request = this.buildCrudRequest(CRUD_ACTION.CREATE, resourceType, {
       resourceBody: JSON.stringify(body),
     });
-    return this.exec(request, "create");
+    return this.exec(request, "create", metadata);
   }
 
   async read<T>(
     resourceType: string,
     resourceId: string,
     schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
   ): Promise<T> {
     const request = this.buildCrudRequest(CRUD_ACTION.READ, resourceType, {
       resourceId,
     });
-    const result = await this.exec(request, "read");
+    const result = await this.exec(request, "read", metadata);
 
     const parseResult = schema.safeParse(result);
     if (!parseResult.success) {
@@ -212,61 +220,70 @@ export class SalesforceClientImpl
     resourceType: string,
     resourceId: string,
     body: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request = this.buildCrudRequest(CRUD_ACTION.UPDATE, resourceType, {
       resourceId,
       resourceBody: JSON.stringify(body),
     });
-    return this.exec(request, "update");
+    return this.exec(request, "update", metadata);
   }
 
-  async remove(resourceType: string, resourceId: string): Promise<unknown> {
+  async remove(
+    resourceType: string,
+    resourceId: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
     const request = this.buildCrudRequest(CRUD_ACTION.DELETE, resourceType, {
       resourceId,
     });
-    return this.exec(request, "remove");
+    return this.exec(request, "remove", metadata);
   }
 
   async bulkCreate(
     resourceType: string,
     records: Array<Record<string, unknown>>,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request = this.buildBulkRequest(
       BULK_ACTION.CREATE,
       resourceType,
       records,
     );
-    return this.exec(request, "bulkCreate");
+    return this.exec(request, "bulkCreate", metadata);
   }
 
   async bulkUpdate(
     resourceType: string,
     records: Array<Record<string, unknown>>,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request = this.buildBulkRequest(
       BULK_ACTION.UPDATE,
       resourceType,
       records,
     );
-    return this.exec(request, "bulkUpdate");
+    return this.exec(request, "bulkUpdate", metadata);
   }
 
   async bulkDelete(
     resourceType: string,
     records: Array<Record<string, unknown>>,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request = this.buildBulkRequest(
       BULK_ACTION.DELETE,
       resourceType,
       records,
     );
-    return this.exec(request, "bulkDelete");
+    return this.exec(request, "bulkDelete", metadata);
   }
 
   async bulkUpsert(
     resourceType: string,
     records: Array<Record<string, unknown>>,
     externalId: string,
+    metadata?: TraceMetadata,
   ): Promise<unknown> {
     const request = this.buildBulkRequest(
       BULK_ACTION.UPSERT,
@@ -274,6 +291,6 @@ export class SalesforceClientImpl
       records,
       externalId,
     );
-    return this.exec(request, "bulkUpsert");
+    return this.exec(request, "bulkUpsert", metadata);
   }
 }

package/src/integrations/salesforce/types.ts

@@ -4,6 +4,7 @@
 
 import type { z } from "zod";
 import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
 
 /**
  * Salesforce CRUD action identifiers matching proto CrudAction enum.
@@ -66,16 +67,25 @@ export interface SalesforceClient extends BaseIntegrationClient {
    * @param schema - Zod schema for validating each row in the result
    * @returns Array of validated records
    */
-  query<T>(soql: string, schema: z.ZodSchema<T>): Promise<T[]>;
+  query<T>(
+    soql: string,
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T[]>;
 
   /**
    * Create a new Salesforce object.
    *
    * @param resourceType - Salesforce object type (e.g., 'Account', 'Contact')
    * @param body - Object fields as key-value pairs
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The raw result from Salesforce
    */
-  create(resourceType: string, body: Record<string, unknown>): Promise<unknown>;
+  create(
+    resourceType: string,
+    body: Record<string, unknown>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
 
   /**
    * Read a single Salesforce object by ID.
@@ -83,12 +93,14 @@ export interface SalesforceClient extends BaseIntegrationClient {
    * @param resourceType - Salesforce object type (e.g., 'Account', 'Contact')
    * @param resourceId - The record ID
    * @param schema - Zod schema for validating the result
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The validated record
    */
   read<T>(
     resourceType: string,
     resourceId: string,
     schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
   ): Promise<T>;
 
   /**
@@ -97,12 +109,14 @@ export interface SalesforceClient extends BaseIntegrationClient {
    * @param resourceType - Salesforce object type (e.g., 'Account', 'Contact')
    * @param resourceId - The record ID
    * @param body - Fields to update as key-value pairs
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The raw result from Salesforce
    */
   update(
     resourceType: string,
     resourceId: string,
     body: Record<string, unknown>,
+    metadata?: TraceMetadata,
   ): Promise<unknown>;
 
   /**
@@ -110,20 +124,27 @@ export interface SalesforceClient extends BaseIntegrationClient {
    *
    * @param resourceType - Salesforce object type (e.g., 'Account', 'Contact')
    * @param resourceId - The record ID
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The raw result from Salesforce
    */
-  remove(resourceType: string, resourceId: string): Promise<unknown>;
+  remove(
+    resourceType: string,
+    resourceId: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
 
   /**
    * Bulk create multiple Salesforce objects.
    *
    * @param resourceType - Salesforce object type
    * @param records - Array of objects to create
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The raw result from Salesforce
    */
   bulkCreate(
     resourceType: string,
     records: Array<Record<string, unknown>>,
+    metadata?: TraceMetadata,
   ): Promise<unknown>;
 
   /**
@@ -131,11 +152,13 @@ export interface SalesforceClient extends BaseIntegrationClient {
    *
    * @param resourceType - Salesforce object type
    * @param records - Array of objects to update (must include Id field)
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The raw result from Salesforce
    */
   bulkUpdate(
     resourceType: string,
     records: Array<Record<string, unknown>>,
+    metadata?: TraceMetadata,
   ): Promise<unknown>;
 
   /**
@@ -143,11 +166,13 @@ export interface SalesforceClient extends BaseIntegrationClient {
    *
    * @param resourceType - Salesforce object type
    * @param records - Array of objects to delete (must include Id field)
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The raw result from Salesforce
    */
   bulkDelete(
     resourceType: string,
     records: Array<Record<string, unknown>>,
+    metadata?: TraceMetadata,
   ): Promise<unknown>;
 
   /**
@@ -156,11 +181,13 @@ export interface SalesforceClient extends BaseIntegrationClient {
    * @param resourceType - Salesforce object type
    * @param records - Array of objects to upsert
    * @param externalId - External ID field name used for matching
+   * @param metadata - Optional trace metadata for diagnostics
    * @returns The raw result from Salesforce
    */
   bulkUpsert(
     resourceType: string,
     records: Array<Record<string, unknown>>,
     externalId: string,
+    metadata?: TraceMetadata,
   ): Promise<unknown>;
 }

package/src/integrations/segment/README.md

@@ -4,9 +4,9 @@ Track events, identify users, and interact with Segment's customer data platform
 
 ## Methods
 
-| Method                        | Description                                         |
-| ----------------------------- | --------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any Segment API request with schema validation |
+| Method                                   | Description                                         |
+| ---------------------------------------- | --------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Segment API request with schema validation |
 
 ## Usage
 
@@ -248,6 +248,10 @@ const result = await ctx.integrations.segment.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/sendgrid/README.md

@@ -4,9 +4,9 @@ Send transactional emails, manage contacts, and interact with SendGrid's email A
 
 ## Methods
 
-| Method                        | Description                                          |
-| ----------------------------- | ---------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any SendGrid API request with schema validation |
+| Method                                   | Description                                          |
+| ---------------------------------------- | ---------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any SendGrid API request with schema validation |
 
 ## Usage
 
@@ -244,6 +244,10 @@ stats.forEach((day) => {
 });
 ```
 
+## 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/slack/README.md

@@ -4,9 +4,9 @@ Send messages, manage channels, and interact with Slack workspaces.
 
 ## Methods
 
-| Method                        | Description                                       |
-| ----------------------------- | ------------------------------------------------- |
-| `apiRequest(options, schema)` | Make any Slack API request with schema validation |
+| Method                                   | Description                                       |
+| ---------------------------------------- | ------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Slack API request with schema validation |
 
 ## Usage
 
@@ -241,6 +241,10 @@ const result = await ctx.integrations.slack.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