@superblocksteam/sdk-api 2.0.93 → 2.0.94-next.1

package/src/integrations/zendesk/README.md

@@ -4,8 +4,8 @@ Create tickets, manage users, and interact with Zendesk's customer support platf
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                         |
+| ----------------------------- | --------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Zendesk API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Create tickets, manage users, and interact with Zendesk's customer support platf
 ### Create a Ticket
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, zendesk } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_ZENDESK = "a1b2c3d4-5678-90ab-cdef-zendesk00001";
@@ -37,6 +37,9 @@ const CreateTicketResponseSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    zendesk: zendesk(PROD_ZENDESK),
+  },
   name: "ZendeskExample",
   input: z.object({
     subject: z.string(),
@@ -47,9 +50,7 @@ export default api({
     ticketId: z.number(),
   }),
   async run(ctx, { subject, description, requesterEmail }) {
-    const zendesk = ctx.zendesk(PROD_ZENDESK);
-
-    const result = await zendesk.apiRequest(
+    const result = await ctx.integrations.zendesk.apiRequest(
       {
         method: "POST",
         path: "/api/v2/tickets.json",
@@ -63,7 +64,7 @@ export default api({
           },
         },
       },
-      { response: CreateTicketResponseSchema }
+      { response: CreateTicketResponseSchema },
     );
 
     return { ticketId: result.ticket.id };
@@ -78,12 +79,12 @@ const GetTicketResponseSchema = z.object({
   ticket: TicketSchema,
 });
 
-const result = await zendesk.apiRequest(
+const result = await ctx.integrations.zendesk.apiRequest(
   {
     method: "GET",
     path: `/api/v2/tickets/${ticketId}.json`,
   },
-  { response: GetTicketResponseSchema }
+  { response: GetTicketResponseSchema },
 );
 
 console.log(`Ticket #${result.ticket.id}: ${result.ticket.subject}`);
@@ -99,17 +100,17 @@ const SearchResponseSchema = z.object({
   previous_page: z.string().nullable(),
 });
 
-const result = await zendesk.apiRequest(
+const result = await ctx.integrations.zendesk.apiRequest(
   {
     method: "GET",
     path: "/api/v2/search.json",
     params: {
-      query: 'type:ticket status:open priority:high',
+      query: "type:ticket status:open priority:high",
       sort_by: "created_at",
       sort_order: "desc",
     },
   },
-  { response: SearchResponseSchema }
+  { response: SearchResponseSchema },
 );
 
 result.results.forEach((ticket) => {
@@ -120,7 +121,7 @@ result.results.forEach((ticket) => {
 ### Update a Ticket
 
 ```typescript
-await zendesk.apiRequest(
+await ctx.integrations.zendesk.apiRequest(
   {
     method: "PUT",
     path: `/api/v2/tickets/${ticketId}.json`,
@@ -136,14 +137,14 @@ await zendesk.apiRequest(
       },
     },
   },
-  { response: GetTicketResponseSchema }
+  { response: GetTicketResponseSchema },
 );
 ```
 
 ### Add a Comment
 
 ```typescript
-await zendesk.apiRequest(
+await ctx.integrations.zendesk.apiRequest(
   {
     method: "PUT",
     path: `/api/v2/tickets/${ticketId}.json`,
@@ -156,7 +157,7 @@ await zendesk.apiRequest(
       },
     },
   },
-  { response: GetTicketResponseSchema }
+  { response: GetTicketResponseSchema },
 );
 ```
 
@@ -177,7 +178,7 @@ const CreateUserResponseSchema = z.object({
   user: UserSchema,
 });
 
-const result = await zendesk.apiRequest(
+const result = await ctx.integrations.zendesk.apiRequest(
   {
     method: "POST",
     path: "/api/v2/users.json",
@@ -190,7 +191,7 @@ const result = await zendesk.apiRequest(
       },
     },
   },
-  { response: CreateUserResponseSchema }
+  { response: CreateUserResponseSchema },
 );
 ```
 
@@ -203,7 +204,7 @@ const ListTicketsResponseSchema = z.object({
   count: z.number(),
 });
 
-const result = await zendesk.apiRequest(
+const result = await ctx.integrations.zendesk.apiRequest(
   {
     method: "GET",
     path: `/api/v2/users/${userId}/tickets/requested.json`,
@@ -212,7 +213,7 @@ const result = await zendesk.apiRequest(
       sort_order: "desc",
     },
   },
-  { response: ListTicketsResponseSchema }
+  { response: ListTicketsResponseSchema },
 );
 ```
 
@@ -232,12 +233,12 @@ const ListCommentsResponseSchema = z.object({
   next_page: z.string().nullable(),
 });
 
-const result = await zendesk.apiRequest(
+const result = await ctx.integrations.zendesk.apiRequest(
   {
     method: "GET",
     path: `/api/v2/tickets/${ticketId}/comments.json`,
   },
-  { response: ListCommentsResponseSchema }
+  { response: ListCommentsResponseSchema },
 );
 
 result.comments.forEach((comment) => {
@@ -256,7 +257,7 @@ const BulkUpdateResponseSchema = z.object({
   }),
 });
 
-const result = await zendesk.apiRequest(
+const result = await ctx.integrations.zendesk.apiRequest(
   {
     method: "PUT",
     path: "/api/v2/tickets/update_many.json",
@@ -270,7 +271,7 @@ const result = await zendesk.apiRequest(
       },
     },
   },
-  { response: BulkUpdateResponseSchema }
+  { response: BulkUpdateResponseSchema },
 );
 ```
 
@@ -284,7 +285,7 @@ await zendesk.createTicket({ ... });
 await zendesk.searchTickets({ ... });
 
 // CORRECT - Use apiRequest
-await zendesk.apiRequest(
+await ctx.integrations.zendesk.apiRequest(
   { method: "POST", path: "/api/v2/tickets.json", body: { ticket: { ... } } },
   { response: CreateTicketResponseSchema }
 );
@@ -389,13 +390,13 @@ async function getAllTickets(zendesk: ZendeskClient) {
   let page = 1;
 
   while (true) {
-    const result = await zendesk.apiRequest(
+    const result = await ctx.integrations.zendesk.apiRequest(
       {
         method: "GET",
         path: "/api/v2/tickets.json",
         params: { page, per_page: 100 },
       },
-      { response: ListTicketsResponseSchema }
+      { response: ListTicketsResponseSchema },
     );
 
     allTickets.push(...result.tickets);
@@ -422,7 +423,7 @@ Zendesk has rate limits (varies by plan):
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await zendesk.apiRequest(
+  const result = await ctx.integrations.zendesk.apiRequest(
     { method: "POST", path: "/api/v2/tickets.json", body: { ... } },
     { response: CreateTicketResponseSchema }
   );

package/src/integrations/zendesk/client.ts

@@ -5,8 +5,8 @@
  * Zendesk integrations use the REST API Integration plugin under the hood.
  */
 
-import { RestApiIntegrationClient } from '../base/index.js';
-import type { ZendeskClient } from './types.js';
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { ZendeskClient } from "./types.js";
 
 /**
  * Internal implementation of ZendeskClient.
@@ -16,6 +16,8 @@ import type { ZendeskClient } from './types.js';
  * Zendesk API calls. At runtime, the orchestrator handles authentication
  * and API request execution.
  */
-export class ZendeskClientImpl extends RestApiIntegrationClient implements ZendeskClient {
+export class ZendeskClientImpl
+  extends RestApiIntegrationClient
+  implements ZendeskClient {
   // Inherits: name, pluginId, config, executeQuery, apiRequest()
 }

package/src/integrations/zendesk/index.ts

@@ -1,2 +1,2 @@
-export { ZendeskClientImpl } from './client.js';
-export type { ZendeskClient } from './types.js';
+export { ZendeskClientImpl } from "./client.js";
+export type { ZendeskClient } from "./types.js";

package/src/integrations/zendesk/types.ts

@@ -2,8 +2,8 @@
  * Zendesk client types.
  */
 
-import type { BaseIntegrationClient } from '../../types.js';
-import type { SupportsApiRequest } from '../base/index.js';
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
 
 /**
  * Zendesk client for API interactions.
@@ -13,7 +13,8 @@ import type { SupportsApiRequest } from '../base/index.js';
  *
  * @example
  * ```typescript
- * const zendesk = ctx.zendesk('My Zendesk');
+ * // Declare in api(): integrations: { zendesk: zendesk(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.zendesk
  *
  * // Make API requests
  * const ResponseSchema = z.object({
@@ -29,6 +30,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  * );
  * ```
  */
-export interface ZendeskClient extends BaseIntegrationClient, SupportsApiRequest {
+export interface ZendeskClient
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
 }

package/src/integrations/zoom/README.md

@@ -4,8 +4,8 @@ Create meetings, manage users, and interact with Zoom's video conferencing platf
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                      |
+| ----------------------------- | ------------------------------------------------ |
 | `apiRequest(options, schema)` | Make any Zoom API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Create meetings, manage users, and interact with Zoom's video conferencing platf
 ### Create a Meeting
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, zoom } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_ZOOM = "a1b2c3d4-5678-90ab-cdef-zoom00000001";
@@ -34,6 +34,9 @@ const MeetingSchema = z.object({
 
 export default api({
   name: "ZoomExample",
+  integrations: {
+    zoom: zoom(PROD_ZOOM),
+  },
   input: z.object({
     topic: z.string(),
     startTime: z.string(),
@@ -44,9 +47,7 @@ export default api({
     joinUrl: z.string(),
   }),
   async run(ctx, { topic, startTime, duration }) {
-    const zoom = ctx.zoom(PROD_ZOOM);
-
-    const result = await zoom.apiRequest(
+    const result = await ctx.integrations.zoom.apiRequest(
       {
         method: "POST",
         path: "/v2/users/me/meetings",
@@ -65,7 +66,7 @@ export default api({
           },
         },
       },
-      { response: MeetingSchema }
+      { response: MeetingSchema },
     );
 
     return { meetingId: result.id, joinUrl: result.join_url };
@@ -91,11 +92,11 @@ const ListMeetingsResponseSchema = z.object({
       duration: z.number(),
       timezone: z.string(),
       join_url: z.string(),
-    })
+    }),
   ),
 });
 
-const result = await zoom.apiRequest(
+const result = await ctx.integrations.zoom.apiRequest(
   {
     method: "GET",
     path: "/v2/users/me/meetings",
@@ -104,7 +105,7 @@ const result = await zoom.apiRequest(
       page_size: 30,
     },
   },
-  { response: ListMeetingsResponseSchema }
+  { response: ListMeetingsResponseSchema },
 );
 
 result.meetings.forEach((meeting) => {
@@ -133,19 +134,19 @@ const MeetingDetailSchema = z.object({
   }),
 });
 
-const result = await zoom.apiRequest(
+const result = await ctx.integrations.zoom.apiRequest(
   {
     method: "GET",
     path: `/v2/meetings/${meetingId}`,
   },
-  { response: MeetingDetailSchema }
+  { response: MeetingDetailSchema },
 );
 ```
 
 ### Update a Meeting
 
 ```typescript
-await zoom.apiRequest(
+await ctx.integrations.zoom.apiRequest(
   {
     method: "PATCH",
     path: `/v2/meetings/${meetingId}`,
@@ -157,14 +158,14 @@ await zoom.apiRequest(
       },
     },
   },
-  { response: z.object({}).optional() } // Returns 204 No Content
+  { response: z.object({}).optional() }, // Returns 204 No Content
 );
 ```
 
 ### Delete a Meeting
 
 ```typescript
-await zoom.apiRequest(
+await ctx.integrations.zoom.apiRequest(
   {
     method: "DELETE",
     path: `/v2/meetings/${meetingId}`,
@@ -172,7 +173,7 @@ await zoom.apiRequest(
       schedule_for_reminder: true,
     },
   },
-  { response: z.object({}).optional() }
+  { response: z.object({}).optional() },
 );
 ```
 
@@ -192,7 +193,7 @@ const WebinarSchema = z.object({
   registration_url: z.string().optional(),
 });
 
-const result = await zoom.apiRequest(
+const result = await ctx.integrations.zoom.apiRequest(
   {
     method: "POST",
     path: "/v2/users/me/webinars",
@@ -211,7 +212,7 @@ const result = await zoom.apiRequest(
       },
     },
   },
-  { response: WebinarSchema }
+  { response: WebinarSchema },
 );
 ```
 
@@ -230,12 +231,12 @@ const UserSchema = z.object({
   dept: z.string().optional(),
 });
 
-const result = await zoom.apiRequest(
+const result = await ctx.integrations.zoom.apiRequest(
   {
     method: "GET",
     path: "/v2/users/me",
   },
-  { response: UserSchema }
+  { response: UserSchema },
 );
 
 console.log(`User: ${result.first_name} ${result.last_name}`);
@@ -257,11 +258,11 @@ const ListUsersResponseSchema = z.object({
       email: z.string(),
       type: z.number(),
       status: z.string(),
-    })
+    }),
   ),
 });
 
-const result = await zoom.apiRequest(
+const result = await ctx.integrations.zoom.apiRequest(
   {
     method: "GET",
     path: "/v2/users",
@@ -270,7 +271,7 @@ const result = await zoom.apiRequest(
       page_size: 30,
     },
   },
-  { response: ListUsersResponseSchema }
+  { response: ListUsersResponseSchema },
 );
 ```
 
@@ -285,7 +286,7 @@ const RegistrantSchema = z.object({
   start_time: z.string(),
 });
 
-const result = await zoom.apiRequest(
+const result = await ctx.integrations.zoom.apiRequest(
   {
     method: "POST",
     path: `/v2/meetings/${meetingId}/registrants`,
@@ -293,12 +294,10 @@ const result = await zoom.apiRequest(
       email: "attendee@example.com",
       first_name: "John",
       last_name: "Doe",
-      custom_questions: [
-        { title: "Company", value: "Acme Corp" },
-      ],
+      custom_questions: [{ title: "Company", value: "Acme Corp" }],
     },
   },
-  { response: RegistrantSchema }
+  { response: RegistrantSchema },
 );
 ```
 
@@ -312,7 +311,7 @@ await zoom.createMeeting({ ... });
 await zoom.listMeetings();
 
 // CORRECT - Use apiRequest
-await zoom.apiRequest(
+await ctx.integrations.zoom.apiRequest(
   { method: "POST", path: "/v2/users/me/meetings", body: { ... } },
   { response: MeetingSchema }
 );
@@ -323,17 +322,17 @@ await zoom.apiRequest(
 ```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
+  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
+  WEBINAR: 5, // Scheduled webinar
+  RECURRING_NO_TIME: 6, // Recurring webinar no fixed time
+  RECURRING_FIXED: 9, // Recurring webinar fixed time
 };
 ```
 
@@ -355,7 +354,7 @@ Zoom uses ISO 8601 format:
 
 ```typescript
 const body = {
-  start_time: "2024-12-15T14:00:00Z",  // UTC
+  start_time: "2024-12-15T14:00:00Z", // UTC
   // Or with timezone
   start_time: "2024-12-15T14:00:00",
   timezone: "America/New_York",
@@ -368,7 +367,7 @@ Many operations return empty responses:
 
 ```typescript
 // PATCH and DELETE often return 204 No Content
-await zoom.apiRequest(
+await ctx.integrations.zoom.apiRequest(
   { method: "PATCH", path: `/v2/meetings/${id}`, body: { ... } },
   { response: z.object({}).optional() }  // Handle empty response
 );
@@ -409,7 +408,7 @@ async function getAllMeetings(zoom: ZoomClient) {
   let pageNumber = 1;
 
   while (true) {
-    const result = await zoom.apiRequest(
+    const result = await ctx.integrations.zoom.apiRequest(
       {
         method: "GET",
         path: "/v2/users/me/meetings",
@@ -418,7 +417,7 @@ async function getAllMeetings(zoom: ZoomClient) {
           page_number: pageNumber,
         },
       },
-      { response: ListMeetingsResponseSchema }
+      { response: ListMeetingsResponseSchema },
     );
 
     allMeetings.push(...result.meetings);
@@ -437,7 +436,7 @@ async function getAllMeetings(zoom: ZoomClient) {
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await zoom.apiRequest(
+  const result = await ctx.integrations.zoom.apiRequest(
     { method: "POST", path: "/v2/users/me/meetings", body: { ... } },
     { response: MeetingSchema }
   );

package/src/integrations/zoom/client.ts

@@ -5,8 +5,8 @@
  * Zoom integrations use the REST API Integration plugin under the hood.
  */
 
-import { RestApiIntegrationClient } from '../base/index.js';
-import type { ZoomClient } from './types.js';
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { ZoomClient } from "./types.js";
 
 /**
  * Internal implementation of ZoomClient.
@@ -16,6 +16,8 @@ import type { ZoomClient } from './types.js';
  * Zoom API calls. At runtime, the orchestrator handles authentication
  * and API request execution.
  */
-export class ZoomClientImpl extends RestApiIntegrationClient implements ZoomClient {
+export class ZoomClientImpl
+  extends RestApiIntegrationClient
+  implements ZoomClient {
   // Inherits: name, pluginId, config, executeQuery, apiRequest()
 }

package/src/integrations/zoom/index.ts

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

package/src/integrations/zoom/types.ts

@@ -2,8 +2,8 @@
  * Zoom client types.
  */
 
-import type { BaseIntegrationClient } from '../../types.js';
-import type { SupportsApiRequest } from '../base/index.js';
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
 
 /**
  * Zoom client for API interactions.
@@ -13,14 +13,15 @@ import type { SupportsApiRequest } from '../base/index.js';
  *
  * @example
  * ```typescript
- * const zoom = ctx.zoom('My Zoom');
+ * // 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 zoom.apiRequest(
+ * const result = await ctx.integrations.zoom.apiRequest(
  *   {
  *     method: 'GET',
  *     path: '/users',

package/src/runtime/context.ts

@@ -5,11 +5,19 @@
  * 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 } from '../integrations/registry.js';
-import { createDefaultLogger } from './logger.js';
+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 } from "../integrations/registry.js";
+import { createDefaultLogger } from "./logger.js";
 
 /**
  * Options for creating an API execution context.
@@ -35,7 +43,7 @@ export interface CreateContextOptions {
   executeQuery: (
     integrationId: string,
     request: Record<string, unknown>,
-    bindings?: Record<string, unknown>
+    bindings?: Record<string, unknown>,
   ) => Promise<unknown>;
 
   /** Execution ID for logging correlation */
@@ -82,8 +90,15 @@ export interface CreateContextOptions {
 export function createApiContext(
   options: CreateContextOptions,
 ): ApiContext<Record<string, AnyIntegrationRef>> {
-  const { integrations, integrationDeclarations, executeQuery, executionId, env, user, logger } =
-    options;
+  const {
+    integrations,
+    integrationDeclarations,
+    executeQuery,
+    executionId,
+    env,
+    user,
+    logger,
+  } = options;
 
   // Cache for created integration clients
   const clientCache = new Map<string, IntegrationClientImpl>();
@@ -111,7 +126,7 @@ export function createApiContext(
     // Create executor bound to this integration
     const boundExecutor: QueryExecutor = (
       request: Record<string, unknown>,
-      bindings?: Record<string, unknown>
+      bindings?: Record<string, unknown>,
     ) => executeQuery(id, request, bindings);
 
     // Create config for client - use pre-loaded config or create synthetic one
@@ -148,7 +163,7 @@ export function createApiContext(
   return {
     integrations: integrationsObject as ApiContext<
       Record<string, AnyIntegrationRef>
-    >['integrations'],
+    >["integrations"],
     log,
     env: Object.freeze({ ...env }),
     user,