@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/s3/README.md

@@ -0,0 +1,127 @@
+# S3 Client
+
+Interact with Amazon S3 buckets with full type safety and runtime validation.
+
+## Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `listBuckets(schema)` | List all buckets |
+| `listObjects(bucket, schema, options?)` | List objects in a bucket |
+| `getObject(bucket, path, schema, options?)` | Get an object |
+| `deleteObject(bucket, path)` | Delete an object |
+| `uploadObject(bucket, path, body)` | Upload a single object |
+| `uploadMultipleObjects(bucket, fileObjects)` | Upload multiple objects |
+| `generatePresignedUrl(bucket, path, schema)` | Generate a presigned URL |
+
+## Usage
+
+### List Objects in a Bucket
+
+```typescript
+import { api, z, s3 } from "@superblocksteam/sdk-api";
+
+export default api({
+  integrations: {
+    storage: s3("Production S3"),
+  },
+  input: z.object({
+    bucket: z.string(),
+    prefix: z.string().optional(),
+  }),
+  output: z.object({
+    files: z.array(z.object({
+      Key: z.string(),
+      Size: z.number(),
+    })),
+  }),
+  async run(ctx, { bucket, prefix }) {
+    const files = await ctx.integrations.storage.listObjects(
+      bucket,
+      z.array(z.object({ Key: z.string(), Size: z.number() })),
+      prefix ? { prefix } : undefined,
+    );
+
+    return { files };
+  },
+});
+```
+
+### Get Object Content
+
+```typescript
+// For text files
+const content = await ctx.integrations.storage.getObject(
+  "my-bucket",
+  "data/file.txt",
+  z.string(),
+);
+
+// For JSON files
+const data = await ctx.integrations.storage.getObject(
+  "my-bucket",
+  "data/config.json",
+  z.object({ name: z.string(), value: z.number() }),
+);
+```
+
+### Upload Object
+
+```typescript
+await ctx.integrations.storage.uploadObject(
+  "my-bucket",
+  "uploads/file.txt",
+  "File content here",
+);
+```
+
+### Delete Object
+
+```typescript
+await ctx.integrations.storage.deleteObject(
+  "my-bucket",
+  "uploads/file.txt",
+);
+```
+
+### List Buckets
+
+```typescript
+const buckets = await ctx.integrations.storage.listBuckets(
+  z.array(z.object({ Name: z.string(), CreationDate: z.string() })),
+);
+```
+
+### Generate Presigned URL
+
+```typescript
+const url = await ctx.integrations.storage.generatePresignedUrl(
+  "my-bucket",
+  "private/document.pdf",
+  z.string(),
+);
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError, IntegrationError } from "@superblocksteam/sdk-api";
+
+try {
+  const content = await ctx.integrations.storage.getObject(
+    "my-bucket",
+    "file.txt",
+    z.string(),
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  } else if (error instanceof IntegrationError) {
+    console.error("S3 error:", error.message);
+  }
+}
+```
+
+## API Reference
+
+- [Amazon S3 Documentation](https://docs.aws.amazon.com/s3/)

package/src/integrations/s3/client.ts

@@ -0,0 +1,199 @@
+/**
+ * S3 client implementation.
+ *
+ * Uses the native S3 plugin type from @superblocksteam/types.
+ */
+
+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 { RestApiValidationError } from '../../errors.js';
+import { IntegrationError } from '../../runtime/errors.js';
+import type {
+  S3Client,
+  S3Action,
+  S3ListObjectsOptions,
+  S3GetObjectOptions,
+} from './types.js';
+
+/**
+ * Internal implementation of S3Client.
+ */
+export class S3ClientImpl implements S3Client, IntegrationClientImpl {
+  readonly config: IntegrationConfig;
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  get name(): string {
+    return this.config.name;
+  }
+
+  get pluginId(): string {
+    return this.config.pluginId;
+  }
+
+  /**
+   * Builds an S3 plugin request and executes it.
+   */
+  private async execute(
+    action: S3Action,
+    request: PartialMessage<S3Plugin>,
+  ): Promise<unknown> {
+    const fullRequest: PartialMessage<S3Plugin> = {
+      ...request,
+      action,
+    };
+
+    return this.executeQuery(fullRequest as Record<string, unknown>);
+  }
+
+  /**
+   * Validates a result against a Zod schema.
+   */
+  private validate<T>(
+    result: unknown,
+    schema: z.ZodSchema<T>,
+    operation: string,
+  ): T {
+    const parseResult = schema.safeParse(result);
+
+    if (!parseResult.success) {
+      throw new RestApiValidationError(
+        `Result validation failed: ${parseResult.error.message}`,
+        {
+          zodError: parseResult.error,
+          data: result,
+        },
+      );
+    }
+
+    return parseResult.data;
+  }
+
+  /**
+   * Wraps an operation with standard error handling.
+   */
+  private async withErrorHandling<T>(
+    operation: string,
+    fn: () => Promise<T>,
+  ): Promise<T> {
+    try {
+      return await fn();
+    } catch (error) {
+      if (
+        error instanceof RestApiValidationError ||
+        error instanceof IntegrationError
+      ) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, operation, error);
+    }
+  }
+
+  async listBuckets<T>(schema: z.ZodSchema<T>): Promise<T> {
+    return this.withErrorHandling('listBuckets', async () => {
+      const result = await this.execute('LIST_BUCKETS', {});
+      return this.validate(result, schema, 'listBuckets');
+    });
+  }
+
+  async listObjects<T>(
+    bucket: string,
+    schema: z.ZodSchema<T>,
+    options?: S3ListObjectsOptions,
+  ): Promise<T> {
+    return this.withErrorHandling('listObjects', async () => {
+      const request: PartialMessage<S3Plugin> = {
+        resource: bucket,
+      };
+
+      if (options?.prefix || options?.delimiter) {
+        request.listFilesConfig = {
+          prefix: options.prefix,
+          delimiter: options.delimiter,
+        };
+      }
+
+      const result = await this.execute('LIST_BUCKET_OBJECTS', request);
+      return this.validate(result, schema, 'listObjects');
+    });
+  }
+
+  async getObject<T>(
+    bucket: string,
+    path: string,
+    schema: z.ZodSchema<T>,
+    options?: S3GetObjectOptions,
+  ): Promise<T> {
+    return this.withErrorHandling('getObject', async () => {
+      const request: PartialMessage<S3Plugin> = {
+        resource: bucket,
+        path,
+      };
+
+      if (options?.responseType) {
+        request.responseType = options.responseType;
+      }
+
+      const result = await this.execute('GET_OBJECT', request);
+      return this.validate(result, schema, 'getObject');
+    });
+  }
+
+  async deleteObject(bucket: string, path: string): Promise<void> {
+    return this.withErrorHandling('deleteObject', async () => {
+      await this.execute('DELETE_OBJECT', {
+        resource: bucket,
+        path,
+      });
+    });
+  }
+
+  async uploadObject(
+    bucket: string,
+    path: string,
+    body: string,
+  ): Promise<void> {
+    return this.withErrorHandling('uploadObject', async () => {
+      await this.execute('UPLOAD_OBJECT', {
+        resource: bucket,
+        path,
+        body,
+      });
+    });
+  }
+
+  async uploadMultipleObjects(
+    bucket: string,
+    fileObjects: string,
+  ): Promise<void> {
+    return this.withErrorHandling('uploadMultipleObjects', async () => {
+      await this.execute('UPLOAD_MULTIPLE_OBJECTS', {
+        resource: bucket,
+        fileObjects,
+      });
+    });
+  }
+
+  async generatePresignedUrl<T>(
+    bucket: string,
+    path: string,
+    schema: z.ZodSchema<T>,
+  ): Promise<T> {
+    return this.withErrorHandling('generatePresignedUrl', async () => {
+      const result = await this.execute('GENERATE_PRESIGNED_URL', {
+        resource: bucket,
+        path,
+      });
+      return this.validate(result, schema, 'generatePresignedUrl');
+    });
+  }
+
+}

package/src/integrations/s3/index.ts

@@ -0,0 +1,13 @@
+/**
+ * S3 integration client.
+ *
+ * @module
+ */
+
+export type {
+  S3Client,
+  S3Action,
+  S3ListObjectsOptions,
+  S3GetObjectOptions,
+} from './types.js';
+export { S3ClientImpl } from './client.js';

package/src/integrations/s3/types.ts

@@ -0,0 +1,151 @@
+/**
+ * S3 client types.
+ */
+
+import type { z } from 'zod';
+import type { BaseIntegrationClient } from '../../types.js';
+
+/**
+ * S3 action types (used internally by the client).
+ */
+export type S3Action =
+  | 'LIST_OBJECTS'
+  | 'LIST_BUCKET_OBJECTS'
+  | 'GET_OBJECT'
+  | 'DELETE_OBJECT'
+  | 'UPLOAD_OBJECT'
+  | 'LIST_BUCKETS'
+  | 'UPLOAD_MULTIPLE_OBJECTS'
+  | 'GENERATE_PRESIGNED_URL';
+
+/**
+ * Options for listing objects in a bucket.
+ */
+export interface S3ListObjectsOptions {
+  /** Prefix filter for listing */
+  prefix?: string;
+  /** Delimiter for listing (e.g., '/' for directory-like grouping) */
+  delimiter?: string;
+}
+
+/**
+ * Options for getting an object.
+ */
+export interface S3GetObjectOptions {
+  /** Response type (e.g., 'text', 'binary', 'json') */
+  responseType?: string;
+}
+
+/**
+ * S3 client for storage operations.
+ *
+ * Provides per-operation methods for common S3 tasks with schema validation.
+ *
+ * @example
+ * ```typescript
+ * const s3 = ctx.integrations.storage;
+ *
+ * // List buckets
+ * const buckets = await s3.listBuckets(z.array(z.object({ Name: z.string() })));
+ *
+ * // List objects in a bucket
+ * const files = await s3.listObjects('my-bucket', z.array(z.object({
+ *   Key: z.string(),
+ *   Size: z.number(),
+ * })), { prefix: 'uploads/' });
+ *
+ * // Get an object
+ * const content = await s3.getObject('my-bucket', 'data/file.txt', z.string());
+ *
+ * // Upload an object
+ * await s3.uploadObject('my-bucket', 'data/file.txt', 'Hello, World!');
+ *
+ * // Delete an object
+ * await s3.deleteObject('my-bucket', 'data/file.txt');
+ *
+ * // Generate a presigned URL
+ * const url = await s3.generatePresignedUrl('my-bucket', 'data/file.txt', z.string());
+ * ```
+ */
+export interface S3Client extends BaseIntegrationClient {
+  /**
+   * List all S3 buckets.
+   *
+   * @param schema - Zod schema for validating the result
+   * @returns The validated bucket list
+   */
+  listBuckets<T>(schema: z.ZodSchema<T>): Promise<T>;
+
+  /**
+   * List objects in a bucket.
+   *
+   * @param bucket - Bucket name
+   * @param schema - Zod schema for validating the result
+   * @param options - Optional prefix and delimiter filters
+   * @returns The validated object list
+   */
+  listObjects<T>(
+    bucket: string,
+    schema: z.ZodSchema<T>,
+    options?: S3ListObjectsOptions,
+  ): Promise<T>;
+
+  /**
+   * Get an object from a bucket.
+   *
+   * @param bucket - Bucket name
+   * @param path - Object key/path
+   * @param schema - Zod schema for validating the result
+   * @param options - Optional response type
+   * @returns The validated object content
+   */
+  getObject<T>(
+    bucket: string,
+    path: string,
+    schema: z.ZodSchema<T>,
+    options?: S3GetObjectOptions,
+  ): Promise<T>;
+
+  /**
+   * Delete an object from a bucket.
+   *
+   * @param bucket - Bucket name
+   * @param path - Object key/path
+   */
+  deleteObject(bucket: string, path: string): Promise<void>;
+
+  /**
+   * Upload an object to a bucket.
+   *
+   * @param bucket - Bucket name
+   * @param path - Object key/path
+   * @param body - File content (base64 or text)
+   */
+  uploadObject(bucket: string, path: string, body: string): Promise<void>;
+
+  /**
+   * Upload multiple objects to a bucket.
+   *
+   * @param bucket - Bucket name
+   * @param fileObjects - Serialized file objects
+   */
+  uploadMultipleObjects(
+    bucket: string,
+    fileObjects: string,
+  ): Promise<void>;
+
+  /**
+   * Generate a presigned URL for an object.
+   *
+   * @param bucket - Bucket name
+   * @param path - Object key/path
+   * @param schema - Zod schema for validating the result
+   * @returns The validated presigned URL
+   */
+  generatePresignedUrl<T>(
+    bucket: string,
+    path: string,
+    schema: z.ZodSchema<T>,
+  ): Promise<T>;
+
+}

package/src/integrations/salesforce/README.md

@@ -0,0 +1,232 @@
+# Salesforce Client
+
+Execute SOQL queries, CRUD operations, and bulk operations against Salesforce with full type safety and runtime validation.
+
+## 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 |
+
+## Usage
+
+### SOQL Query
+
+```typescript
+import { api, z } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_SALESFORCE = "a1b2c3d4-5678-90ab-cdef-salesfor0001";
+
+const AccountSchema = z.object({
+  Id: z.string(),
+  Name: z.string(),
+  Industry: z.string().nullable(),
+});
+
+export default api({
+  name: "SalesforceExample",
+  input: z.object({}),
+  output: z.object({
+    accounts: z.array(AccountSchema),
+  }),
+  async run(ctx) {
+    const salesforce = ctx.salesforce(PROD_SALESFORCE);
+
+    const accounts = await salesforce.query(
+      "SELECT Id, Name, Industry FROM Account LIMIT 10",
+      AccountSchema
+    );
+
+    return { accounts };
+  },
+});
+```
+
+### Query with Relationships
+
+```typescript
+const OpportunitySchema = z.object({
+  Id: z.string(),
+  Name: z.string(),
+  Amount: z.number().nullable(),
+  Account: z.object({
+    Name: z.string(),
+  }).nullable(),
+});
+
+const opportunities = await salesforce.query(
+  `SELECT Id, Name, Amount, Account.Name
+   FROM Opportunity
+   WHERE StageName = 'Closed Won'`,
+  OpportunitySchema
+);
+```
+
+### Create a Record
+
+```typescript
+await salesforce.create("Account", {
+  Name: "Acme Corp",
+  Industry: "Technology",
+  Website: "https://acme.example.com",
+});
+```
+
+### Read a Record by ID
+
+```typescript
+const account = await salesforce.read(
+  "Account",
+  "001xx000003DGb2AAG",
+  z.object({
+    Id: z.string(),
+    Name: z.string(),
+    Industry: z.string().nullable(),
+  })
+);
+```
+
+### Update a Record
+
+```typescript
+await salesforce.update("Account", "001xx000003DGb2AAG", {
+  Name: "Acme Corp (Updated)",
+  Industry: "Software",
+});
+```
+
+### Delete a Record
+
+```typescript
+await salesforce.remove("Account", "001xx000003DGb2AAG");
+```
+
+### Bulk Create
+
+```typescript
+await salesforce.bulkCreate("Contact", [
+  { FirstName: "Alice", LastName: "Smith", Email: "alice@example.com" },
+  { FirstName: "Bob", LastName: "Jones", Email: "bob@example.com" },
+  { FirstName: "Charlie", LastName: "Lee", Email: "charlie@example.com" },
+]);
+```
+
+### Bulk Update
+
+```typescript
+await salesforce.bulkUpdate("Contact", [
+  { Id: "003xx000004TmiQAAS", Email: "alice-new@example.com" },
+  { Id: "003xx000004TmiRAAS", Email: "bob-new@example.com" },
+]);
+```
+
+### Bulk Delete
+
+```typescript
+await salesforce.bulkDelete("Contact", [
+  { Id: "003xx000004TmiQAAS" },
+  { Id: "003xx000004TmiRAAS" },
+]);
+```
+
+### Bulk Upsert
+
+```typescript
+await salesforce.bulkUpsert(
+  "Account",
+  [
+    { ExternalId__c: "EXT-001", Name: "Acme Corp", Industry: "Tech" },
+    { ExternalId__c: "EXT-002", Name: "Globex Inc", Industry: "Finance" },
+  ],
+  "ExternalId__c"
+);
+```
+
+## Common Pitfalls
+
+### Schema Must Match Salesforce Field Names
+
+Use the exact API field names from Salesforce (case-sensitive):
+
+```typescript
+// CORRECT - Matches Salesforce API field names
+const Schema = z.object({
+  Id: z.string(),
+  FirstName: z.string(),
+  LastName: z.string(),
+});
+
+// WRONG - Using different casing
+const Schema = z.object({
+  id: z.string(),
+  firstName: z.string(),
+  lastName: z.string(),
+});
+```
+
+### Nullable Fields
+
+Many Salesforce fields can be null. Use `.nullable()`:
+
+```typescript
+const Schema = z.object({
+  Id: z.string(),
+  Email: z.string().nullable(),
+  Phone: z.string().nullable(),
+});
+```
+
+### Bulk Records Require Id for Updates/Deletes
+
+Bulk update and delete records must include the `Id` field:
+
+```typescript
+// CORRECT
+await salesforce.bulkUpdate("Contact", [
+  { Id: "003xx000004TmiQAAS", Email: "new@example.com" },
+]);
+
+// WRONG - Missing Id field
+await salesforce.bulkUpdate("Contact", [
+  { Email: "new@example.com" },
+]);
+```
+
+## Error Handling
+
+```typescript
+import { QueryValidationError, RestApiValidationError, IntegrationError } from "@superblocksteam/sdk-api";
+
+try {
+  const accounts = await salesforce.query(
+    "SELECT Id, Name FROM Account",
+    AccountSchema
+  );
+} catch (error) {
+  if (error instanceof QueryValidationError) {
+    // Per-row validation failure from query()
+    console.error("Row validation failed:", error.details);
+  } else if (error instanceof RestApiValidationError) {
+    // Validation failure from read()
+    console.error("Validation failed:", error.details.zodError);
+  } else if (error instanceof IntegrationError) {
+    // Salesforce API error
+    console.error("Salesforce error:", error.message);
+  }
+}
+```
+
+## API Reference
+
+- [SOQL Reference](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/)
+- [Salesforce Object Reference](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/)
+- [Bulk API 2.0](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/)