@superblocksteam/sdk-api 0.0.4

package/src/integrations/salesforce/README.md

@@ -0,0 +1,241 @@
+# 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, 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
+
+### SOQL Query
+
+```typescript
+import { api, z, salesforce } 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({
+  integrations: {
+    salesforce: salesforce(PROD_SALESFORCE),
+  },
+  name: "SalesforceExample",
+  input: z.object({}),
+  output: z.object({
+    accounts: z.array(AccountSchema),
+  }),
+  async run(ctx) {
+    const accounts = await ctx.integrations.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 ctx.integrations.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 ctx.integrations.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",
+);
+```
+
+## 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
+
+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 ctx.integrations.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/)

package/src/integrations/salesforce/client.ts

@@ -0,0 +1,296 @@
+/**
+ * Salesforce integration client implementation.
+ *
+ * Executes Salesforce operations through the Superblocks orchestrator
+ * including SOQL queries, single-object CRUD, and bulk operations.
+ */
+
+import type { z } from "zod";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.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";
+import type { SalesforceClient } from "./types.js";
+
+/**
+ * SOQL action string value expected by the backend.
+ */
+const SOQL_ACTION_SOQL = "SOQL_ACTION_SOQL";
+
+/**
+ * CRUD action string values matching proto CrudAction enum.
+ */
+const CRUD_ACTION = {
+  CREATE: "CRUD_ACTION_CREATE",
+  UPDATE: "CRUD_ACTION_UPDATE",
+  DELETE: "CRUD_ACTION_DELETE",
+  READ: "CRUD_ACTION_READ",
+} as const;
+
+/**
+ * Bulk action string values matching proto BulkAction enum.
+ */
+const BULK_ACTION = {
+  CREATE: "BULK_ACTION_CREATE",
+  UPDATE: "BULK_ACTION_UPDATE",
+  DELETE: "BULK_ACTION_DELETE",
+  UPSERT: "BULK_ACTION_UPSERT",
+} as const;
+
+/**
+ * Internal implementation of the Salesforce client.
+ */
+export class SalesforceClientImpl
+  implements SalesforceClient, 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;
+  }
+
+  /**
+   * Execute a request and wrap errors.
+   */
+  private async exec(
+    request: Record<string, unknown>,
+    operation: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    try {
+      return await this.executeQuery(request, undefined, metadata);
+    } catch (error) {
+      if (
+        error instanceof QueryValidationError ||
+        error instanceof RestApiValidationError ||
+        error instanceof IntegrationError
+      ) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, operation, error);
+    }
+  }
+
+  /**
+   * Build a CRUD request object.
+   */
+  private buildCrudRequest(
+    action: string,
+    resourceType: string,
+    options?: { resourceId?: string; resourceBody?: string },
+  ): Record<string, unknown> {
+    const crud: Record<string, unknown> = {
+      action,
+      resourceType,
+    };
+
+    if (options?.resourceId) {
+      crud.resourceId = options.resourceId;
+    }
+
+    if (options?.resourceBody) {
+      crud.resourceBody = options.resourceBody;
+    }
+
+    return { crud };
+  }
+
+  /**
+   * Build a bulk request object.
+   */
+  private buildBulkRequest(
+    action: string,
+    resourceType: string,
+    records: Array<Record<string, unknown>>,
+    externalId?: string,
+  ): Record<string, unknown> {
+    const bulk: Record<string, unknown> = {
+      action,
+      resourceType,
+      resourceBody: JSON.stringify(records),
+    };
+
+    if (externalId) {
+      bulk.externalId = externalId;
+    }
+
+    return { bulk };
+  }
+
+  async query<T>(
+    soql: string,
+    schema: z.ZodSchema<T>,
+    metadata?: TraceMetadata,
+  ): Promise<T[]> {
+    const request = {
+      soql: {
+        action: SOQL_ACTION_SOQL,
+        sqlBody: soql,
+      },
+    };
+
+    const result = await this.exec(
+      request as unknown as Record<string, unknown>,
+      "query",
+      metadata,
+    );
+
+    if (!Array.isArray(result)) {
+      throw new IntegrationError(
+        this.config.name,
+        "query",
+        `Expected array result from Salesforce query, got: ${describeType(result)}`,
+      );
+    }
+
+    const validated: T[] = [];
+    for (let i = 0; i < result.length; i++) {
+      const row = result[i];
+      const parseResult = schema.safeParse(row);
+
+      if (!parseResult.success) {
+        throw new QueryValidationError(
+          `Row ${i} validation failed: ${parseResult.error.message}`,
+          {
+            rowIndex: i,
+            errors: parseResult.error.errors.map((err) => ({
+              path: err.path,
+              message: err.message,
+            })),
+            row,
+          },
+        );
+      }
+
+      validated.push(parseResult.data);
+    }
+
+    return validated;
+  }
+
+  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", 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", metadata);
+
+    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;
+  }
+
+  async update(
+    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", metadata);
+  }
+
+  async remove(
+    resourceType: string,
+    resourceId: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = this.buildCrudRequest(CRUD_ACTION.DELETE, resourceType, {
+      resourceId,
+    });
+    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", 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", 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", metadata);
+  }
+
+  async bulkUpsert(
+    resourceType: string,
+    records: Array<Record<string, unknown>>,
+    externalId: string,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request = this.buildBulkRequest(
+      BULK_ACTION.UPSERT,
+      resourceType,
+      records,
+      externalId,
+    );
+    return this.exec(request, "bulkUpsert", metadata);
+  }
+}

package/src/integrations/salesforce/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Salesforce integration client.
+ *
+ * @module
+ */
+
+export type {
+  SalesforceClient,
+  SalesforceCrudAction,
+  SalesforceBulkAction,
+} from "./types.js";
+export { SalesforceClientImpl } from "./client.js";