@superblocksteam/sdk-api 0.0.4

package/src/integrations/salesforce/types.ts

@@ -0,0 +1,193 @@
+/**
+ * Salesforce client types.
+ */
+
+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.
+ */
+export type SalesforceCrudAction =
+  | "CRUD_ACTION_CREATE"
+  | "CRUD_ACTION_UPDATE"
+  | "CRUD_ACTION_DELETE"
+  | "CRUD_ACTION_READ";
+
+/**
+ * Salesforce bulk action identifiers matching proto BulkAction enum.
+ */
+export type SalesforceBulkAction =
+  | "BULK_ACTION_CREATE"
+  | "BULK_ACTION_UPDATE"
+  | "BULK_ACTION_DELETE"
+  | "BULK_ACTION_UPSERT";
+
+/**
+ * Salesforce client for SOQL queries, CRUD, and bulk operations.
+ *
+ * Provides methods for querying, creating, updating, and deleting
+ * Salesforce objects with schema validation.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { sf: salesforce(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.sf
+ *
+ * // SOQL query
+ * const accounts = await ctx.integrations.sf.query(
+ *   'SELECT Id, Name FROM Account LIMIT 10',
+ *   z.object({ Id: z.string(), Name: z.string() })
+ * );
+ *
+ * // Create a record
+ * await ctx.integrations.sf.create('Account', { Name: 'Acme Corp', Industry: 'Tech' });
+ *
+ * // Read a record
+ * const account = await ctx.integrations.sf.read('Account', '001xx000003DGb2AAG',
+ *   z.object({ Id: z.string(), Name: z.string() })
+ * );
+ *
+ * // Update a record
+ * await ctx.integrations.sf.update('Account', '001xx000003DGb2AAG', { Name: 'New Name' });
+ *
+ * // Delete a record
+ * await ctx.integrations.sf.remove('Account', '001xx000003DGb2AAG');
+ *
+ * // Bulk upsert
+ * await ctx.integrations.sf.bulkUpsert('Account', [{ Name: 'A' }, { Name: 'B' }], 'ExternalId__c');
+ * ```
+ */
+export interface SalesforceClient extends BaseIntegrationClient {
+  /**
+   * Execute a SOQL query and validate the results.
+   *
+   * @param soql - The SOQL query string
+   * @param schema - Zod schema for validating each row in the result
+   * @returns Array of validated records
+   */
+  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>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown>;
+
+  /**
+   * Read a single Salesforce object by ID.
+   *
+   * @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>;
+
+  /**
+   * Update a Salesforce object by ID.
+   *
+   * @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>;
+
+  /**
+   * Delete a Salesforce object by ID.
+   *
+   * @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,
+    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>;
+
+  /**
+   * Bulk update multiple Salesforce objects.
+   *
+   * @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>;
+
+  /**
+   * Bulk delete multiple Salesforce objects.
+   *
+   * @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>;
+
+  /**
+   * Bulk upsert (create or update) multiple Salesforce objects.
+   *
+   * @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

@@ -0,0 +1,492 @@
+# Segment Client
+
+Track events, identify users, and interact with Segment's customer data platform.
+
+## Methods
+
+| Method                                   | Description                                         |
+| ---------------------------------------- | --------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Segment API request with schema validation |
+
+## Usage
+
+### Track an Event
+
+```typescript
+import { api, z, segment } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_SEGMENT = "a1b2c3d4-5678-90ab-cdef-segment00001";
+
+const TrackResponseSchema = z.object({
+  success: z.boolean(),
+});
+
+export default api({
+  integrations: {
+    segment: segment(PROD_SEGMENT),
+  },
+  name: "SegmentExample",
+  input: z.object({
+    userId: z.string(),
+    event: z.string(),
+    properties: z.record(z.unknown()),
+  }),
+  output: z.object({
+    success: z.boolean(),
+  }),
+  async run(ctx, { userId, event, properties }) {
+    const result = await ctx.integrations.segment.apiRequest(
+      {
+        method: "POST",
+        path: "/v1/track",
+        body: {
+          userId: userId,
+          event: event,
+          properties: properties,
+          timestamp: new Date().toISOString(),
+          context: {
+            library: {
+              name: "superblocks-sdk",
+              version: "1.0.0",
+            },
+          },
+        },
+      },
+      { response: TrackResponseSchema },
+    );
+
+    return { success: result.success };
+  },
+});
+```
+
+### Identify a User
+
+```typescript
+const IdentifyResponseSchema = z.object({
+  success: z.boolean(),
+});
+
+const result = await ctx.integrations.segment.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/identify",
+    body: {
+      userId: "user_123",
+      traits: {
+        email: "john@example.com",
+        name: "John Doe",
+        plan: "enterprise",
+        createdAt: "2024-01-15T10:00:00Z",
+        company: {
+          id: "company_456",
+          name: "Acme Corp",
+          industry: "Technology",
+        },
+      },
+      context: {
+        ip: "192.168.1.1",
+        userAgent: "Mozilla/5.0...",
+      },
+    },
+  },
+  { response: IdentifyResponseSchema },
+);
+
+console.log(`User identified: ${result.success}`);
+```
+
+### Create an Alias
+
+```typescript
+const AliasResponseSchema = z.object({
+  success: z.boolean(),
+});
+
+// Link anonymous user to known user
+const result = await ctx.integrations.segment.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/alias",
+    body: {
+      previousId: "anonymous_abc123",
+      userId: "user_123",
+    },
+  },
+  { response: AliasResponseSchema },
+);
+```
+
+### Track Page View
+
+```typescript
+const PageResponseSchema = z.object({
+  success: z.boolean(),
+});
+
+const result = await ctx.integrations.segment.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/page",
+    body: {
+      userId: "user_123",
+      name: "Home",
+      category: "Marketing",
+      properties: {
+        title: "Welcome to Acme",
+        url: "https://example.com/",
+        path: "/",
+        referrer: "https://google.com/",
+      },
+    },
+  },
+  { response: PageResponseSchema },
+);
+```
+
+### Group Users
+
+```typescript
+const GroupResponseSchema = z.object({
+  success: z.boolean(),
+});
+
+const result = await ctx.integrations.segment.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/group",
+    body: {
+      userId: "user_123",
+      groupId: "company_456",
+      traits: {
+        name: "Acme Corp",
+        industry: "Technology",
+        employees: 250,
+        plan: "enterprise",
+        website: "https://acme.com",
+      },
+    },
+  },
+  { response: GroupResponseSchema },
+);
+```
+
+### Batch Multiple Events
+
+```typescript
+const BatchResponseSchema = z.object({
+  success: z.boolean(),
+});
+
+const result = await ctx.integrations.segment.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/batch",
+    body: {
+      batch: [
+        {
+          type: "identify",
+          userId: "user_123",
+          traits: { email: "john@example.com" },
+        },
+        {
+          type: "track",
+          userId: "user_123",
+          event: "Signed Up",
+          properties: { plan: "free" },
+        },
+        {
+          type: "track",
+          userId: "user_123",
+          event: "Onboarding Started",
+          properties: { step: 1 },
+        },
+      ],
+      context: {
+        library: { name: "superblocks-sdk" },
+      },
+    },
+  },
+  { response: BatchResponseSchema },
+);
+```
+
+### Track Screen View (Mobile)
+
+```typescript
+const ScreenResponseSchema = z.object({
+  success: z.boolean(),
+});
+
+const result = await ctx.integrations.segment.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/screen",
+    body: {
+      userId: "user_123",
+      name: "Dashboard",
+      properties: {
+        section: "Overview",
+        loaded_at: new Date().toISOString(),
+      },
+      context: {
+        device: {
+          type: "ios",
+          model: "iPhone 15",
+          manufacturer: "Apple",
+        },
+        app: {
+          name: "MyApp",
+          version: "2.1.0",
+          build: "145",
+        },
+      },
+    },
+  },
+  { response: ScreenResponseSchema },
+);
+```
+
+## 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
+
+```typescript
+// WRONG - These methods do not exist
+await segment.track({ ... });
+await segment.identify({ ... });
+
+// CORRECT - Use apiRequest
+await ctx.integrations.segment.apiRequest(
+  { method: "POST", path: "/v1/track", body: { ... } },
+  { response: TrackResponseSchema }
+);
+```
+
+### userId vs anonymousId
+
+At least one ID is required:
+
+```typescript
+// WRONG - No user identifier
+const body = {
+  event: "Button Clicked",
+  properties: { buttonName: "Submit" },
+};
+
+// CORRECT - With userId
+const body = {
+  userId: "user_123",
+  event: "Button Clicked",
+  properties: { buttonName: "Submit" },
+};
+
+// CORRECT - With anonymousId (for unknown users)
+const body = {
+  anonymousId: "anon_abc123",
+  event: "Button Clicked",
+  properties: { buttonName: "Submit" },
+};
+
+// Can include both
+const body = {
+  userId: "user_123",
+  anonymousId: "anon_abc123", // Links them together
+  event: "Button Clicked",
+  properties: { buttonName: "Submit" },
+};
+```
+
+### Event Naming Conventions
+
+Use consistent, descriptive event names:
+
+```typescript
+// WRONG - Inconsistent naming
+await track({ event: "click_button" });
+await track({ event: "SignUp" });
+await track({ event: "order-completed" });
+
+// CORRECT - Object Action format (recommended)
+await track({ event: "Button Clicked" });
+await track({ event: "Account Created" });
+await track({ event: "Order Completed" });
+
+// Use past tense for actions
+// Good: "Product Added", "Form Submitted", "Page Viewed"
+// Avoid: "Add Product", "Submit Form", "View Page"
+```
+
+### Reserved Property Names
+
+Some property names have special meaning:
+
+```typescript
+const body = {
+  userId: "user_123",
+  event: "Order Completed",
+  properties: {
+    // Reserved Segment properties (use these correctly)
+    revenue: 99.99, // Total revenue (number)
+    currency: "USD", // ISO 4217 code
+    value: 99.99, // Generic value (number)
+    orderId: "order_789", // Unique order ID
+
+    // Custom properties
+    products: [...],
+    coupon: "SAVE20",
+  },
+};
+```
+
+### Timestamp Format
+
+Use ISO 8601 format:
+
+```typescript
+// WRONG - Unix timestamp
+const body = {
+  timestamp: Date.now(),
+};
+
+// WRONG - Other formats
+const body = {
+  timestamp: "01/15/2024",
+};
+
+// CORRECT - ISO 8601
+const body = {
+  timestamp: new Date().toISOString(), // "2024-01-15T10:30:00.000Z"
+};
+
+// Or specific timestamp
+const body = {
+  timestamp: "2024-01-15T10:30:00Z",
+};
+```
+
+### Traits vs Properties
+
+`traits` for identify, `properties` for track:
+
+```typescript
+// identify uses "traits"
+const identifyBody = {
+  userId: "user_123",
+  traits: {
+    email: "john@example.com",
+    name: "John Doe",
+  },
+};
+
+// track uses "properties"
+const trackBody = {
+  userId: "user_123",
+  event: "Order Completed",
+  properties: {
+    orderId: "order_789",
+    total: 99.99,
+  },
+};
+```
+
+### Batch Size Limits
+
+Batch endpoint has limits:
+
+```typescript
+// Maximum 500KB per request
+// Maximum 100 events recommended per batch
+
+const events = [...]; // Large array
+
+// Split into chunks
+const chunkSize = 100;
+for (let i = 0; i < events.length; i += chunkSize) {
+  const batch = events.slice(i, i + chunkSize);
+  await ctx.integrations.segment.apiRequest(
+    {
+      method: "POST",
+      path: "/v1/batch",
+      body: { batch },
+    },
+    { response: BatchResponseSchema }
+  );
+}
+```
+
+### Context Object
+
+Include context for richer data:
+
+```typescript
+const body = {
+  userId: "user_123",
+  event: "Order Completed",
+  properties: { ... },
+  context: {
+    // Library info
+    library: {
+      name: "superblocks-sdk",
+      version: "1.0.0",
+    },
+    // User's IP (for geo)
+    ip: "192.168.1.1",
+    // User agent (for device info)
+    userAgent: "Mozilla/5.0...",
+    // Locale
+    locale: "en-US",
+    // Timezone
+    timezone: "America/New_York",
+    // Campaign info
+    campaign: {
+      source: "google",
+      medium: "cpc",
+      name: "spring_sale",
+    },
+  },
+};
+```
+
+### Response Always Returns Success
+
+Segment's Tracking API always returns `{success: true}` for valid requests:
+
+```typescript
+// The API returns 200 OK with {success: true} even if:
+// - User doesn't exist
+// - Event is malformed but syntactically valid
+// - Destinations fail
+
+// Actual delivery errors appear in Segment's debugger
+// or destination logs, not in the API response
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.segment.apiRequest(
+    { method: "POST", path: "/v1/track", body: { ... } },
+    { response: TrackResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Segment HTTP Tracking API](https://segment.com/docs/connections/sources/catalog/libraries/server/http-api/)
+- [Track Spec](https://segment.com/docs/connections/spec/track/)
+- [Identify Spec](https://segment.com/docs/connections/spec/identify/)
+- [Common Fields](https://segment.com/docs/connections/spec/common/)

package/src/integrations/segment/client.ts

@@ -0,0 +1,23 @@
+/**
+ * Segment client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * Segment integrations use the REST API Integration plugin under the hood.
+ */
+
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { SegmentClient } from "./types.js";
+
+/**
+ * Internal implementation of SegmentClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * Segment API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export class SegmentClientImpl
+  extends RestApiIntegrationClient
+  implements SegmentClient {
+  // Inherits: name, pluginId, config, executeQuery, apiRequest()
+}

package/src/integrations/segment/index.ts

@@ -0,0 +1,2 @@
+export { SegmentClientImpl } from "./client.js";
+export type { SegmentClient } from "./types.js";