@superblocksteam/sdk-api 0.0.4

package/src/integrations/zoom/README.md

@@ -0,0 +1,459 @@
+# Zoom Client
+
+Create meetings, manage users, and interact with Zoom's video conferencing platform.
+
+## Methods
+
+| Method                                   | Description                                      |
+| ---------------------------------------- | ------------------------------------------------ |
+| `apiRequest(options, schema, metadata?)` | Make any Zoom API request with schema validation |
+
+## Usage
+
+### Create a Meeting
+
+```typescript
+import { api, z, zoom } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_ZOOM = "a1b2c3d4-5678-90ab-cdef-zoom00000001";
+
+const MeetingSchema = z.object({
+  id: z.number(),
+  uuid: z.string(),
+  host_id: z.string(),
+  topic: z.string(),
+  type: z.number(),
+  status: z.string().optional(),
+  start_time: z.string(),
+  duration: z.number(),
+  timezone: z.string(),
+  join_url: z.string(),
+  password: z.string().optional(),
+});
+
+export default api({
+  name: "ZoomExample",
+  integrations: {
+    zoom: zoom(PROD_ZOOM),
+  },
+  input: z.object({
+    topic: z.string(),
+    startTime: z.string(),
+    duration: z.number(),
+  }),
+  output: z.object({
+    meetingId: z.number(),
+    joinUrl: z.string(),
+  }),
+  async run(ctx, { topic, startTime, duration }) {
+    const result = await ctx.integrations.zoom.apiRequest(
+      {
+        method: "POST",
+        path: "/v2/users/me/meetings",
+        body: {
+          topic: topic,
+          type: 2, // Scheduled meeting
+          start_time: startTime,
+          duration: duration,
+          timezone: "America/New_York",
+          settings: {
+            host_video: true,
+            participant_video: true,
+            join_before_host: false,
+            mute_upon_entry: true,
+            waiting_room: true,
+          },
+        },
+      },
+      { response: MeetingSchema },
+    );
+
+    return { meetingId: result.id, joinUrl: result.join_url };
+  },
+});
+```
+
+### List Meetings
+
+```typescript
+const ListMeetingsResponseSchema = z.object({
+  page_count: z.number(),
+  page_number: z.number(),
+  page_size: z.number(),
+  total_records: z.number(),
+  meetings: z.array(
+    z.object({
+      id: z.number(),
+      uuid: z.string(),
+      topic: z.string(),
+      type: z.number(),
+      start_time: z.string(),
+      duration: z.number(),
+      timezone: z.string(),
+      join_url: z.string(),
+    }),
+  ),
+});
+
+const result = await ctx.integrations.zoom.apiRequest(
+  {
+    method: "GET",
+    path: "/v2/users/me/meetings",
+    params: {
+      type: "scheduled", // upcoming, live, scheduled
+      page_size: 30,
+    },
+  },
+  { response: ListMeetingsResponseSchema },
+);
+
+result.meetings.forEach((meeting) => {
+  console.log(`${meeting.topic} - ${meeting.start_time}`);
+});
+```
+
+### Get Meeting Details
+
+```typescript
+const MeetingDetailSchema = z.object({
+  id: z.number(),
+  uuid: z.string(),
+  topic: z.string(),
+  type: z.number(),
+  status: z.string(),
+  start_time: z.string(),
+  duration: z.number(),
+  timezone: z.string(),
+  join_url: z.string(),
+  password: z.string().optional(),
+  settings: z.object({
+    host_video: z.boolean(),
+    participant_video: z.boolean(),
+    waiting_room: z.boolean(),
+  }),
+});
+
+const result = await ctx.integrations.zoom.apiRequest(
+  {
+    method: "GET",
+    path: `/v2/meetings/${meetingId}`,
+  },
+  { response: MeetingDetailSchema },
+);
+```
+
+### Update a Meeting
+
+```typescript
+await ctx.integrations.zoom.apiRequest(
+  {
+    method: "PATCH",
+    path: `/v2/meetings/${meetingId}`,
+    body: {
+      topic: "Updated Meeting Topic",
+      duration: 60,
+      settings: {
+        waiting_room: false,
+      },
+    },
+  },
+  { response: z.object({}).optional() }, // Returns 204 No Content
+);
+```
+
+### Delete a Meeting
+
+```typescript
+await ctx.integrations.zoom.apiRequest(
+  {
+    method: "DELETE",
+    path: `/v2/meetings/${meetingId}`,
+    params: {
+      schedule_for_reminder: true,
+    },
+  },
+  { response: z.object({}).optional() },
+);
+```
+
+### Create a Webinar
+
+```typescript
+const WebinarSchema = z.object({
+  id: z.number(),
+  uuid: z.string(),
+  host_id: z.string(),
+  topic: z.string(),
+  type: z.number(),
+  start_time: z.string(),
+  duration: z.number(),
+  timezone: z.string(),
+  join_url: z.string(),
+  registration_url: z.string().optional(),
+});
+
+const result = await ctx.integrations.zoom.apiRequest(
+  {
+    method: "POST",
+    path: "/v2/users/me/webinars",
+    body: {
+      topic: "Product Launch Webinar",
+      type: 5, // Scheduled webinar
+      start_time: "2024-12-15T14:00:00Z",
+      duration: 90,
+      timezone: "America/New_York",
+      settings: {
+        approval_type: 0, // Auto approve
+        registration_type: 1, // Register once
+        audio: "both",
+        panelists_video: true,
+        practice_session: true,
+      },
+    },
+  },
+  { response: WebinarSchema },
+);
+```
+
+### Get User
+
+```typescript
+const UserSchema = z.object({
+  id: z.string(),
+  first_name: z.string(),
+  last_name: z.string(),
+  email: z.string(),
+  type: z.number(), // 1=Basic, 2=Licensed, 3=On-prem
+  status: z.string(),
+  pmi: z.number(), // Personal Meeting ID
+  timezone: z.string(),
+  dept: z.string().optional(),
+});
+
+const result = await ctx.integrations.zoom.apiRequest(
+  {
+    method: "GET",
+    path: "/v2/users/me",
+  },
+  { response: UserSchema },
+);
+
+console.log(`User: ${result.first_name} ${result.last_name}`);
+```
+
+### List Users
+
+```typescript
+const ListUsersResponseSchema = z.object({
+  page_count: z.number(),
+  page_number: z.number(),
+  page_size: z.number(),
+  total_records: z.number(),
+  users: z.array(
+    z.object({
+      id: z.string(),
+      first_name: z.string(),
+      last_name: z.string(),
+      email: z.string(),
+      type: z.number(),
+      status: z.string(),
+    }),
+  ),
+});
+
+const result = await ctx.integrations.zoom.apiRequest(
+  {
+    method: "GET",
+    path: "/v2/users",
+    params: {
+      status: "active",
+      page_size: 30,
+    },
+  },
+  { response: ListUsersResponseSchema },
+);
+```
+
+### Add Meeting Registrant
+
+```typescript
+const RegistrantSchema = z.object({
+  id: z.string(),
+  registrant_id: z.string(),
+  join_url: z.string(),
+  topic: z.string(),
+  start_time: z.string(),
+});
+
+const result = await ctx.integrations.zoom.apiRequest(
+  {
+    method: "POST",
+    path: `/v2/meetings/${meetingId}/registrants`,
+    body: {
+      email: "attendee@example.com",
+      first_name: "John",
+      last_name: "Doe",
+      custom_questions: [{ title: "Company", value: "Acme Corp" }],
+    },
+  },
+  { response: RegistrantSchema },
+);
+```
+
+## 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 zoom.createMeeting({ ... });
+await zoom.listMeetings();
+
+// CORRECT - Use apiRequest
+await ctx.integrations.zoom.apiRequest(
+  { method: "POST", path: "/v2/users/me/meetings", body: { ... } },
+  { response: MeetingSchema }
+);
+```
+
+### Meeting Types
+
+```typescript
+// Meeting types
+const MEETING_TYPES = {
+  INSTANT: 1, // Instant meeting
+  SCHEDULED: 2, // Scheduled meeting
+  RECURRING_NO_TIME: 3, // Recurring with no fixed time
+  RECURRING_FIXED: 8, // Recurring with fixed time
+};
+
+// Webinar types
+const WEBINAR_TYPES = {
+  WEBINAR: 5, // Scheduled webinar
+  RECURRING_NO_TIME: 6, // Recurring webinar no fixed time
+  RECURRING_FIXED: 9, // Recurring webinar fixed time
+};
+```
+
+### User ID "me"
+
+Use "me" for the authenticated user:
+
+```typescript
+// Current user's meetings
+const path = "/v2/users/me/meetings";
+
+// Specific user's meetings (requires admin scope)
+const path = `/v2/users/${userId}/meetings`;
+```
+
+### Date/Time Format
+
+Zoom uses ISO 8601 format:
+
+```typescript
+const body = {
+  start_time: "2024-12-15T14:00:00Z", // UTC
+  // Or with timezone
+  start_time: "2024-12-15T14:00:00",
+  timezone: "America/New_York",
+};
+```
+
+### Empty Response on Success
+
+Many operations return empty responses:
+
+```typescript
+// PATCH and DELETE often return 204 No Content
+await ctx.integrations.zoom.apiRequest(
+  { method: "PATCH", path: `/v2/meetings/${id}`, body: { ... } },
+  { response: z.object({}).optional() }  // Handle empty response
+);
+```
+
+### Scopes Required
+
+Different endpoints require different OAuth scopes:
+
+```typescript
+// Meetings
+// meeting:read, meeting:write, meeting:read:admin, meeting:write:admin
+
+// Users
+// user:read, user:write, user:read:admin, user:write:admin
+
+// Webinars
+// webinar:read, webinar:write
+```
+
+### Rate Limits
+
+Zoom has rate limits (varies by endpoint):
+
+```typescript
+// Most endpoints: 10 requests/second
+// Heavy endpoints (e.g., reports): Lower limits
+// Check X-RateLimit-* headers
+```
+
+### Pagination
+
+Large result sets require pagination:
+
+```typescript
+async function getAllMeetings(zoom: ZoomClient) {
+  const allMeetings: Meeting[] = [];
+  let pageNumber = 1;
+
+  while (true) {
+    const result = await ctx.integrations.zoom.apiRequest(
+      {
+        method: "GET",
+        path: "/v2/users/me/meetings",
+        params: {
+          page_size: 300,
+          page_number: pageNumber,
+        },
+      },
+      { response: ListMeetingsResponseSchema },
+    );
+
+    allMeetings.push(...result.meetings);
+
+    if (pageNumber >= result.page_count) break;
+    pageNumber++;
+  }
+
+  return allMeetings;
+}
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.zoom.apiRequest(
+    { method: "POST", path: "/v2/users/me/meetings", body: { ... } },
+    { response: MeetingSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Zoom API Documentation](https://developers.zoom.us/docs/api/)
+- [Meetings](https://developers.zoom.us/docs/api/rest/reference/zoom-api/methods/#tag/Meetings)
+- [Users](https://developers.zoom.us/docs/api/rest/reference/zoom-api/methods/#tag/Users)
+- [Webinars](https://developers.zoom.us/docs/api/rest/reference/zoom-api/methods/#tag/Webinars)

package/src/integrations/zoom/client.ts

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

package/src/integrations/zoom/index.ts

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

package/src/integrations/zoom/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Zoom client types.
+ */
+
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
+
+/**
+ * Zoom client for API interactions.
+ *
+ * Provides generic API request method for interacting with Zoom's API.
+ * Use apiRequest() to make calls to any Zoom API endpoint.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { zoom: zoom(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.zoom
+ *
+ * // Make API requests
+ * const ResponseSchema = z.object({
+ *   // Define your response schema
+ * });
+ *
+ * const result = await ctx.integrations.zoom.apiRequest(
+ *   {
+ *     method: 'GET',
+ *     path: '/users',
+ *   },
+ *   { response: ResponseSchema }
+ * );
+ * ```
+ */
+export interface ZoomClient extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}

package/src/runtime/context.ts

@@ -0,0 +1,177 @@
+/**
+ * API execution context factory.
+ *
+ * Creates the context object that is passed to user API functions,
+ * providing access to integrations, logging, and environment.
+ */
+
+import type {
+  ApiContext,
+  ApiUser,
+  Logger,
+  AnyIntegrationRef,
+} from "../types.js";
+import type {
+  IntegrationConfig,
+  IntegrationClientImpl,
+} from "../integrations/types.js";
+import type { IntegrationDeclaration } from "../integrations/declarations.js";
+import {
+  createClient,
+  type QueryExecutor,
+  type TraceMetadata,
+} from "../integrations/registry.js";
+import { createDefaultLogger } from "./logger.js";
+
+/**
+ * Options for creating an API execution context.
+ */
+export interface CreateContextOptions {
+  /** Available integration configurations keyed by id */
+  integrations: Map<string, IntegrationConfig>;
+
+  /**
+   * Declared integrations from the API config.
+   *
+   * These are the integrations specified in the `integrations` field of the API config.
+   * The context will only expose these declared integrations via `ctx.integrations`.
+   */
+  integrationDeclarations: IntegrationDeclaration[];
+
+  /**
+   * Function to execute integration operations.
+   *
+   * For language plugins (Python, JavaScript), pass the bindings parameter
+   * to the API execution request as `input` field for binding resolution.
+   */
+  executeQuery: (
+    integrationId: string,
+    request: Record<string, unknown>,
+    bindings?: Record<string, unknown>,
+    metadata?: TraceMetadata,
+  ) => Promise<unknown>;
+
+  /** Execution ID for logging correlation */
+  executionId: string;
+
+  /** Environment variables */
+  env: Record<string, string>;
+
+  /** User information from JWT */
+  user: ApiUser;
+
+  /** Optional custom logger */
+  logger?: Logger;
+}
+
+/**
+ * Creates an API execution context.
+ *
+ * The context provides user code with access to:
+ * - Integration clients (built from declarations)
+ * - Logging utilities
+ * - Environment variables
+ *
+ * @param options - Context creation options
+ * @returns The API context for user code execution
+ *
+ * @example
+ * ```typescript
+ * const ctx = createApiContext({
+ *   integrations: new Map([
+ *     ['int_1', { id: 'int_1', name: 'Production Postgres', pluginId: 'postgres', configuration: {} }],
+ *   ]),
+ *   integrationDeclarations: [
+ *     { key: 'db', pluginId: 'postgres', id: 'int_1' },
+ *   ],
+ *   executeQuery: orchestratorExecutor,
+ *   executionId: 'exec_abc',
+ *   env: { NODE_ENV: 'production' },
+ * });
+ *
+ * // User code can access: ctx.integrations.db (typed as PostgresClient)
+ * ```
+ */
+export function createApiContext(
+  options: CreateContextOptions,
+): ApiContext<Record<string, AnyIntegrationRef>> {
+  const {
+    integrations,
+    integrationDeclarations,
+    executeQuery,
+    executionId,
+    env,
+    user,
+    logger,
+  } = options;
+
+  // Cache for created integration clients
+  const clientCache = new Map<string, IntegrationClientImpl>();
+
+  // Create logger
+  const log = logger ?? createDefaultLogger(executionId);
+
+  /**
+   * Gets or creates a typed integration client by id and plugin ID.
+   *
+   * Supports two modes:
+   * 1. Pre-loaded configs: Integration configs are provided upfront (orchestrator use)
+   * 2. Lazy resolution: Configs are empty, executeQuery handles ID resolution (library use)
+   */
+  function getTypedClient(id: string, pluginId: string): IntegrationClientImpl {
+    // Check cache first
+    const cached = clientCache.get(id);
+    if (cached) {
+      return cached;
+    }
+
+    // Look up integration config (may be undefined for lazy resolution)
+    const config = integrations.get(id);
+
+    // Create executor bound to this integration
+    const boundExecutor: QueryExecutor = (
+      request: Record<string, unknown>,
+      bindings?: Record<string, unknown>,
+      metadata?: TraceMetadata,
+    ) => executeQuery(id, request, bindings, metadata);
+
+    // Create config for client - use pre-loaded config or create synthetic one
+    const clientConfig: IntegrationConfig = config ?? {
+      id,
+      name: id, // Use ID as name placeholder for lazy resolution
+      pluginId,
+      configuration: {},
+    };
+
+    // Create and cache the client
+    const client = createClient({
+      config: clientConfig,
+      executeQuery: boundExecutor,
+    });
+
+    clientCache.set(id, client);
+    return client;
+  }
+
+  // Build the integrations object from declarations
+  // Each key maps to a lazily-created typed client
+  const integrationsObject: Record<string, IntegrationClientImpl> = {};
+
+  for (const declaration of integrationDeclarations) {
+    // Use Object.defineProperty to create a getter that lazily creates the client
+    Object.defineProperty(integrationsObject, declaration.key, {
+      get: () => getTypedClient(declaration.id, declaration.pluginId),
+      enumerable: true,
+      configurable: false,
+    });
+  }
+
+  return {
+    integrations: integrationsObject as ApiContext<
+      Record<string, AnyIntegrationRef>
+    >["integrations"],
+    log,
+    env: Object.freeze({ ...env }),
+    user,
+  };
+}