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

package/src/integrations/googledrive/README.md

@@ -4,8 +4,8 @@ Upload, download, and manage files in Google Drive.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                              |
+| ----------------------------- | -------------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Google Drive API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Upload, download, and manage files in Google Drive.
 ### List Files
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, googledrive } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_DRIVE = "a1b2c3d4-5678-90ab-cdef-gdrive000001";
@@ -28,12 +28,14 @@ const FileSchema = z.object({
   size: z.string().optional(),
   webViewLink: z.string().optional(),
   webContentLink: z.string().optional(),
-  owners: z.array(
-    z.object({
-      displayName: z.string(),
-      emailAddress: z.string(),
-    })
-  ).optional(),
+  owners: z
+    .array(
+      z.object({
+        displayName: z.string(),
+        emailAddress: z.string(),
+      }),
+    )
+    .optional(),
 });
 
 const ListFilesResponseSchema = z.object({
@@ -42,28 +44,31 @@ const ListFilesResponseSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    drive: googledrive(PROD_DRIVE),
+  },
   name: "GoogleDriveExample",
   input: z.object({
     folderId: z.string().optional(),
     pageSize: z.number().default(50),
   }),
   output: z.object({
-    files: z.array(z.object({
-      id: z.string(),
-      name: z.string(),
-      type: z.string(),
-    })),
+    files: z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        type: z.string(),
+      }),
+    ),
   }),
   async run(ctx, { folderId, pageSize }) {
-    const drive = ctx.googledrive(PROD_DRIVE);
-
     // Build query
     let query = "trashed = false";
     if (folderId) {
       query += ` and '${folderId}' in parents`;
     }
 
-    const result = await drive.apiRequest(
+    const result = await ctx.integrations.drive.apiRequest(
       {
         method: "GET",
         path: "/drive/v3/files",
@@ -74,7 +79,7 @@ export default api({
           orderBy: "modifiedTime desc",
         },
       },
-      { response: ListFilesResponseSchema }
+      { response: ListFilesResponseSchema },
     );
 
     return {
@@ -91,15 +96,16 @@ export default api({
 ### Get File Metadata
 
 ```typescript
-const file = await drive.apiRequest(
+const file = await ctx.integrations.drive.apiRequest(
   {
     method: "GET",
     path: `/drive/v3/files/${fileId}`,
     params: {
-      fields: "id,name,mimeType,size,createdTime,modifiedTime,parents,webViewLink,webContentLink,owners",
+      fields:
+        "id,name,mimeType,size,createdTime,modifiedTime,parents,webViewLink,webContentLink,owners",
     },
   },
-  { response: FileSchema }
+  { response: FileSchema },
 );
 
 console.log(`File: ${file.name} (${file.size} bytes)`);
@@ -111,7 +117,7 @@ console.log(`File: ${file.name} (${file.size} bytes)`);
 const DownloadResponseSchema = z.string(); // Raw content
 
 // For text files
-const content = await drive.apiRequest(
+const content = await ctx.integrations.drive.apiRequest(
   {
     method: "GET",
     path: `/drive/v3/files/${fileId}`,
@@ -119,13 +125,13 @@ const content = await drive.apiRequest(
       alt: "media",
     },
   },
-  { response: DownloadResponseSchema }
+  { response: DownloadResponseSchema },
 );
 
 // For Google Docs, export to a format
 const ExportResponseSchema = z.string();
 
-const docContent = await drive.apiRequest(
+const docContent = await ctx.integrations.drive.apiRequest(
   {
     method: "GET",
     path: `/drive/v3/files/${fileId}/export`,
@@ -133,14 +139,14 @@ const docContent = await drive.apiRequest(
       mimeType: "text/plain", // or application/pdf, text/html, etc.
     },
   },
-  { response: ExportResponseSchema }
+  { response: ExportResponseSchema },
 );
 ```
 
 ### Create a Folder
 
 ```typescript
-const folder = await drive.apiRequest(
+const folder = await ctx.integrations.drive.apiRequest(
   {
     method: "POST",
     path: "/drive/v3/files",
@@ -150,7 +156,7 @@ const folder = await drive.apiRequest(
       parents: [parentFolderId], // Optional: specify parent folder
     },
   },
-  { response: FileSchema }
+  { response: FileSchema },
 );
 
 console.log(`Created folder: ${folder.id}`);
@@ -160,7 +166,7 @@ console.log(`Created folder: ${folder.id}`);
 
 ```typescript
 // For simple uploads (< 5MB)
-const uploadedFile = await drive.apiRequest(
+const uploadedFile = await ctx.integrations.drive.apiRequest(
   {
     method: "POST",
     path: "/upload/drive/v3/files",
@@ -178,14 +184,14 @@ const uploadedFile = await drive.apiRequest(
       },
     },
   },
-  { response: FileSchema }
+  { response: FileSchema },
 );
 ```
 
 ### Update File Metadata
 
 ```typescript
-const updatedFile = await drive.apiRequest(
+const updatedFile = await ctx.integrations.drive.apiRequest(
   {
     method: "PATCH",
     path: `/drive/v3/files/${fileId}`,
@@ -194,14 +200,14 @@ const updatedFile = await drive.apiRequest(
       description: "Updated description",
     },
   },
-  { response: FileSchema }
+  { response: FileSchema },
 );
 ```
 
 ### Move File to Another Folder
 
 ```typescript
-const movedFile = await drive.apiRequest(
+const movedFile = await ctx.integrations.drive.apiRequest(
   {
     method: "PATCH",
     path: `/drive/v3/files/${fileId}`,
@@ -210,14 +216,14 @@ const movedFile = await drive.apiRequest(
       removeParents: oldFolderId,
     },
   },
-  { response: FileSchema }
+  { response: FileSchema },
 );
 ```
 
 ### Search Files
 
 ```typescript
-const result = await drive.apiRequest(
+const result = await ctx.integrations.drive.apiRequest(
   {
     method: "GET",
     path: "/drive/v3/files",
@@ -227,7 +233,7 @@ const result = await drive.apiRequest(
       fields: "files(id,name,mimeType,modifiedTime)",
     },
   },
-  { response: ListFilesResponseSchema }
+  { response: ListFilesResponseSchema },
 );
 ```
 
@@ -241,7 +247,7 @@ const PermissionSchema = z.object({
   emailAddress: z.string().optional(),
 });
 
-const permission = await drive.apiRequest(
+const permission = await ctx.integrations.drive.apiRequest(
   {
     method: "POST",
     path: `/drive/v3/files/${fileId}/permissions`,
@@ -254,7 +260,7 @@ const permission = await drive.apiRequest(
       sendNotificationEmail: true,
     },
   },
-  { response: PermissionSchema }
+  { response: PermissionSchema },
 );
 ```
 
@@ -262,7 +268,7 @@ const permission = await drive.apiRequest(
 
 ```typescript
 // Move to trash
-await drive.apiRequest(
+await ctx.integrations.drive.apiRequest(
   {
     method: "PATCH",
     path: `/drive/v3/files/${fileId}`,
@@ -270,16 +276,16 @@ await drive.apiRequest(
       trashed: true,
     },
   },
-  { response: FileSchema }
+  { response: FileSchema },
 );
 
 // Permanently delete
-await drive.apiRequest(
+await ctx.integrations.drive.apiRequest(
   {
     method: "DELETE",
     path: `/drive/v3/files/${fileId}`,
   },
-  { response: z.void() }
+  { response: z.void() },
 );
 ```
 
@@ -293,7 +299,7 @@ await drive.listFiles({ ... });
 await drive.uploadFile({ ... });
 
 // CORRECT - Use apiRequest
-await drive.apiRequest(
+await ctx.integrations.drive.apiRequest(
   { method: "GET", path: "/drive/v3/files", params: { ... } },
   { response: ListFilesResponseSchema }
 );
@@ -305,14 +311,14 @@ By default, only basic fields are returned. Use the `fields` parameter:
 
 ```typescript
 // WRONG - Missing fields, gets minimal data
-const file = await drive.apiRequest(
+const file = await ctx.integrations.drive.apiRequest(
   { method: "GET", path: `/drive/v3/files/${fileId}` },
-  { response: FileSchema }
+  { response: FileSchema },
 );
 // file.size, file.owners, etc. will be undefined
 
 // CORRECT - Specify needed fields
-const file = await drive.apiRequest(
+const file = await ctx.integrations.drive.apiRequest(
   {
     method: "GET",
     path: `/drive/v3/files/${fileId}`,
@@ -320,7 +326,7 @@ const file = await drive.apiRequest(
       fields: "id,name,mimeType,size,createdTime,modifiedTime,owners",
     },
   },
-  { response: FileSchema }
+  { response: FileSchema },
 );
 ```
 
@@ -344,7 +350,8 @@ const q = "trashed = false";
 const q = "'folder-id-here' in parents";
 
 // Combining conditions
-const q = "name contains 'report' and mimeType = 'application/pdf' and trashed = false";
+const q =
+  "name contains 'report' and mimeType = 'application/pdf' and trashed = false";
 
 // Date filtering
 const q = "modifiedTime > '2024-01-01T00:00:00'";
@@ -422,7 +429,7 @@ async function getAllFiles(drive: GoogleDriveClient, folderId: string) {
   let pageToken: string | undefined;
 
   while (true) {
-    const result = await drive.apiRequest(
+    const result = await ctx.integrations.drive.apiRequest(
       {
         method: "GET",
         path: "/drive/v3/files",
@@ -433,7 +440,7 @@ async function getAllFiles(drive: GoogleDriveClient, folderId: string) {
           ...(pageToken && { pageToken }),
         },
       },
-      { response: ListFilesResponseSchema }
+      { response: ListFilesResponseSchema },
     );
 
     allFiles.push(...result.files);
@@ -451,7 +458,7 @@ async function getAllFiles(drive: GoogleDriveClient, folderId: string) {
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await drive.apiRequest(
+  const result = await ctx.integrations.drive.apiRequest(
     { method: "GET", path: "/drive/v3/files", params: { ... } },
     { response: ListFilesResponseSchema }
   );

package/src/integrations/googledrive/client.ts

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

package/src/integrations/googledrive/index.ts

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

package/src/integrations/googledrive/types.ts

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

package/src/integrations/graphql/README.md

@@ -4,9 +4,9 @@ Execute GraphQL queries and mutations against configured GraphQL endpoints with
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
-| `query<T>(query, schema, variables?)` | Execute a GraphQL query with required schema validation |
+| Method                                      | Description                                                |
+| ------------------------------------------- | ---------------------------------------------------------- |
+| `query<T>(query, schema, variables?)`       | Execute a GraphQL query with required schema validation    |
 | `mutation<T>(mutation, schema, variables?)` | Execute a GraphQL mutation with required schema validation |
 
 ## Usage
@@ -14,7 +14,7 @@ Execute GraphQL queries and mutations against configured GraphQL endpoints with
 ### Basic Query
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, graphql } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_GRAPHQL = "a1b2c3d4-5678-90ab-cdef-graphql00001";
@@ -31,6 +31,9 @@ const GetUserResponseSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    graphql: graphql(PROD_GRAPHQL),
+  },
   name: "GraphQLExample",
   input: z.object({
     userId: z.string(),
@@ -43,9 +46,7 @@ export default api({
     }),
   }),
   async run(ctx, { userId }) {
-    const graphql = ctx.graphql(PROD_GRAPHQL);
-
-    const result = await graphql.query(
+    const result = await ctx.integrations.graphql.query(
       `query GetUser($id: ID!) {
         user(id: $id) {
           id
@@ -54,7 +55,7 @@ export default api({
         }
       }`,
       { response: GetUserResponseSchema },
-      { id: userId }
+      { id: userId },
     );
 
     // Access data through the data property
@@ -73,13 +74,13 @@ const ListUsersResponseSchema = z.object({
         id: z.string(),
         name: z.string(),
         role: z.enum(["admin", "user", "guest"]),
-      })
+      }),
     ),
     totalCount: z.number(),
   }),
 });
 
-const result = await graphql.query(
+const result = await ctx.integrations.graphql.query(
   `query ListUsers($limit: Int, $offset: Int) {
     users(limit: $limit, offset: $offset) {
       id
@@ -89,7 +90,7 @@ const result = await graphql.query(
     totalCount
   }`,
   { response: ListUsersResponseSchema },
-  { limit: 10, offset: 0 }
+  { limit: 10, offset: 0 },
 );
 
 console.log(`Found ${result.data.totalCount} users`);
@@ -125,7 +126,7 @@ const result = await graphql.mutation(
       name: "John Doe",
       email: "john@example.com",
     },
-  }
+  },
 );
 
 console.log(`Created user: ${result.data.createUser.id}`);
@@ -143,7 +144,7 @@ const UpdateOrderResponseSchema = z.object({
         z.object({
           productId: z.string(),
           quantity: z.number(),
-        })
+        }),
       ),
     }),
   }),
@@ -170,7 +171,7 @@ const result = await graphql.mutation(
         { productId: "prod-2", quantity: 1 },
       ],
     },
-  }
+  },
 );
 ```
 
@@ -182,12 +183,14 @@ const UserProfileResponseSchema = z.object({
     user: z.object({
       id: z.string(),
       name: z.string(),
-      bio: z.string().nullable(),           // Field can be null
-      avatar: z.string().optional(),         // Field may not be present
-      settings: z.object({
-        theme: z.string(),
-        notifications: z.boolean(),
-      }).nullable(),                         // Entire object can be null
+      bio: z.string().nullable(), // Field can be null
+      avatar: z.string().optional(), // Field may not be present
+      settings: z
+        .object({
+          theme: z.string(),
+          notifications: z.boolean(),
+        })
+        .nullable(), // Entire object can be null
     }),
   }),
 });
@@ -224,13 +227,15 @@ const schema = z.object({
 The result object includes the `data` wrapper, so you must access fields through it:
 
 ```typescript
-const result = await graphql.query(
+const result = await ctx.integrations.graphql.query(
   `query { user(id: "123") { name } }`,
-  { response: ResponseSchema }
+  {
+    response: ResponseSchema,
+  },
 );
 
 // WRONG - Direct access
-console.log(result.user.name);  // undefined or error
+console.log(result.user.name); // undefined or error
 
 // CORRECT - Access through data
 console.log(result.data.user.name);
@@ -242,16 +247,16 @@ Both `query()` and `mutation()` require a schema for validation:
 
 ```typescript
 // WRONG - Missing schema
-const result = await graphql.query(
+const result = await ctx.integrations.graphql.query(
   `query { users { id } }`,
-  { id: "123" }  // This looks like variables, not schema
+  { id: "123" }, // This looks like variables, not schema
 );
 
 // CORRECT - Schema is required
-const result = await graphql.query(
+const result = await ctx.integrations.graphql.query(
   `query GetUser($id: ID!) { user(id: $id) { id } }`,
-  { response: ResponseSchema },  // Schema is required
-  { id: "123" }                   // Variables are optional third parameter
+  { response: ResponseSchema }, // Schema is required
+  { id: "123" }, // Variables are optional third parameter
 );
 ```
 
@@ -268,22 +273,28 @@ const ResponseSchema = z.object({
         name: z.string(),
       }),
     })
-    .nullable(),  // data can be null if errors occur
+    .nullable(), // data can be null if errors occur
   errors: z
     .array(
       z.object({
         message: z.string(),
-        locations: z.array(z.object({
-          line: z.number(),
-          column: z.number(),
-        })).optional(),
+        locations: z
+          .array(
+            z.object({
+              line: z.number(),
+              column: z.number(),
+            }),
+          )
+          .optional(),
         path: z.array(z.union([z.string(), z.number()])).optional(),
-      })
+      }),
     )
     .optional(),
 });
 
-const result = await graphql.query(query, { response: ResponseSchema });
+const result = await ctx.integrations.graphql.query(query, {
+  response: ResponseSchema,
+});
 
 if (result.errors && result.errors.length > 0) {
   console.error("GraphQL errors:", result.errors);
@@ -302,10 +313,18 @@ Ensure variable values match the expected GraphQL types:
 // GraphQL schema expects: query GetUser($id: ID!)
 
 // WRONG - Number instead of string
-const result = await graphql.query(query, { response: schema }, { id: 123 });
+const result = await ctx.integrations.graphql.query(
+  query,
+  { response: schema },
+  { id: 123 },
+);
 
 // CORRECT - ID type expects string
-const result = await graphql.query(query, { response: schema }, { id: "123" });
+const result = await ctx.integrations.graphql.query(
+  query,
+  { response: schema },
+  { id: "123" },
+);
 ```
 
 ### Handling Unions and Interfaces
@@ -327,12 +346,12 @@ const SearchResultSchema = z.object({
           id: z.string(),
           title: z.string(),
         }),
-      ])
+      ]),
     ),
   }),
 });
 
-const result = await graphql.query(
+const result = await ctx.integrations.graphql.query(
   `query Search($term: String!) {
     search(term: $term) {
       __typename
@@ -347,7 +366,7 @@ const result = await graphql.query(
     }
   }`,
   { response: SearchResultSchema },
-  { term: "john" }
+  { term: "john" },
 );
 
 result.data.search.forEach((item) => {
@@ -369,7 +388,9 @@ Thrown when the GraphQL response fails schema validation:
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await graphql.query(query, { response: schema });
+  const result = await ctx.integrations.graphql.query(query, {
+    response: schema,
+  });
 } catch (error) {
   if (error instanceof RestApiValidationError) {
     console.error("Validation failed:", error.message);

package/src/integrations/graphql/client.ts

@@ -5,8 +5,8 @@
  * GraphQL integrations use the GraphQL Integration plugin under the hood.
  */
 
-import { GraphQLIntegrationClient } from '../base/graphql-integration-client.js';
-import type { GraphQLClient } from './types.js';
+import { GraphQLIntegrationClient } from "../base/graphql-integration-client.js";
+import type { GraphQLClient } from "./types.js";
 
 /**
  * Internal implementation of GraphQLClient.
@@ -16,6 +16,8 @@ import type { GraphQLClient } from './types.js';
  * GraphQL operations. At runtime, the orchestrator handles authentication
  * and GraphQL request execution.
  */
-export class GraphQLClientImpl extends GraphQLIntegrationClient implements GraphQLClient {
+export class GraphQLClientImpl
+  extends GraphQLIntegrationClient
+  implements GraphQLClient {
   // Inherits: name, pluginId, config, executeQuery, query(), mutation()
 }

package/src/integrations/graphql/index.ts

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