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

package/src/integrations/mysql/README.md

@@ -4,17 +4,17 @@ Execute SQL queries and statements against MySQL databases with full type safety
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
-| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results |
-| `execute(sql, params?)` | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
+| Method                           | Description                                                                |
+| -------------------------------- | -------------------------------------------------------------------------- |
+| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results                 |
+| `execute(sql, params?)`          | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
 
 ## Usage
 
 ### Basic Query with Schema Validation
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, mysql } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_MYSQL = "a1b2c3d4-5678-90ab-cdef-mysql0000001";
@@ -27,6 +27,9 @@ const UserSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    mysql: mysql(PROD_MYSQL),
+  },
   name: "MySQLExample",
   input: z.object({
     status: z.string(),
@@ -35,12 +38,10 @@ export default api({
     users: z.array(UserSchema),
   }),
   async run(ctx, { status }) {
-    const mysql = ctx.mysql(PROD_MYSQL);
-
-    const users = await mysql.query(
+    const users = await ctx.integrations.mysql.query(
       "SELECT id, name, email, created_at FROM users WHERE status = $1",
       UserSchema,
-      [status]
+      [status],
     );
 
     return { users };
@@ -51,24 +52,22 @@ export default api({
 ### Executing INSERT, UPDATE, DELETE Statements
 
 ```typescript
-const mysql = ctx.mysql(PROD_MYSQL);
-
 // INSERT
-await mysql.execute(
+await ctx.integrations.mysql.execute(
   "INSERT INTO users (name, email) VALUES ($1, $2)",
-  ["John Doe", "john@example.com"]
+  ["John Doe", "john@example.com"],
 );
 
 // UPDATE
-const updateResult = await mysql.execute(
+const updateResult = await ctx.integrations.mysql.execute(
   "UPDATE users SET last_login = NOW() WHERE id = $1",
-  [userId]
+  [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);
 
 // DELETE
-const deleteResult = await mysql.execute(
-  "DELETE FROM sessions WHERE expires_at < NOW()"
+const deleteResult = await ctx.integrations.mysql.execute(
+  "DELETE FROM sessions WHERE expires_at < NOW()",
 );
 console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
 ```
@@ -83,7 +82,7 @@ const OrderWithCustomerSchema = z.object({
   customer_email: z.string().email(),
 });
 
-const orders = await mysql.query(
+const orders = await ctx.integrations.mysql.query(
   `SELECT
     o.id as order_id,
     o.total as order_total,
@@ -93,7 +92,7 @@ const orders = await mysql.query(
   JOIN customers c ON o.customer_id = c.id
   WHERE o.status = $1`,
   OrderWithCustomerSchema,
-  ["pending"]
+  ["pending"],
 );
 ```
 
@@ -124,10 +123,13 @@ const schema = z.object({
 
 ```typescript
 // WRONG - Missing schema
-const users = await mysql.query("SELECT * FROM users");
+const users = await ctx.integrations.mysql.query("SELECT * FROM users");
 
 // CORRECT - Schema is required
-const users = await mysql.query("SELECT * FROM users", UserSchema);
+const users = await ctx.integrations.mysql.query(
+  "SELECT * FROM users",
+  UserSchema,
+);
 ```
 
 ### NULL Handling
@@ -145,7 +147,10 @@ const schema = z.object({
 import { QueryValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const users = await mysql.query("SELECT * FROM users", UserSchema);
+  const users = await ctx.integrations.mysql.query(
+    "SELECT * FROM users",
+    UserSchema,
+  );
 } catch (error) {
   if (error instanceof QueryValidationError) {
     console.error("Row index:", error.details.rowIndex);

package/src/integrations/mysql/client.ts

@@ -5,15 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from 'zod';
-import type { PartialMessage } from '@bufbuild/protobuf';
-import type { Plugin as MySQLPlugin } from '@superblocksteam/types/dist/src/plugins/mysql/v1/plugin_pb';
-import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
-import type { QueryExecutor } from '../registry.js';
-import { QueryValidationError } from '../../errors.js';
-import { IntegrationError } from '../../runtime/errors.js';
-import { describeType } from '../utils.js';
-import type { MySQLClient } from './types.js';
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+import type { Plugin as MySQLPlugin } from "@superblocksteam/types/dist/src/plugins/mysql/v1/plugin_pb";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor } from "../registry.js";
+import { QueryValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import { describeType } from "../utils.js";
+import type { MySQLClient } from "./types.js";
 
 /**
  * Internal implementation of the MySQL client.
@@ -71,7 +71,7 @@ export class MySQLClientImpl implements MySQLClient, IntegrationClientImpl {
       if (!Array.isArray(result)) {
         throw new IntegrationError(
           this.config.name,
-          'query',
+          "query",
           `Expected array result from MySQL query, got: ${describeType(result)}`,
         );
       }
@@ -107,27 +107,30 @@ export class MySQLClientImpl implements MySQLClient, IntegrationClientImpl {
         throw error;
       }
 
-      throw new IntegrationError(this.config.name, 'query', error);
+      throw new IntegrationError(this.config.name, "query", error);
     }
   }
 
-  async execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }> {
+  async execute(
+    sql: string,
+    params?: unknown[],
+  ): Promise<{ rowCount: number }> {
     const request = this.buildRequest(sql, params);
 
     try {
       const result = await this.executeQuery(request);
 
       if (
-        typeof result === 'object' &&
+        typeof result === "object" &&
         result !== null &&
-        'rowCount' in result
+        "rowCount" in result
       ) {
         return { rowCount: Number(result.rowCount) || 0 };
       }
 
       return { rowCount: 0 };
     } catch (error) {
-      throw new IntegrationError(this.config.name, 'execute', error);
+      throw new IntegrationError(this.config.name, "execute", error);
     }
   }
 }

package/src/integrations/mysql/index.ts

@@ -4,5 +4,5 @@
  * @module
  */
 
-export type { MySQLClient } from './types.js';
-export { MySQLClientImpl } from './client.js';
+export type { MySQLClient } from "./types.js";
+export { MySQLClientImpl } from "./client.js";

package/src/integrations/mysql/types.ts

@@ -4,15 +4,16 @@
  * Provides typed methods for executing MySQL queries with runtime validation.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * Client for executing MySQL queries with type-safe validation.
  *
  * @example
  * ```typescript
- * const mysql = ctx.mysql('Production MySQL');
+ * // Declare in api(): integrations: { mysql: mysql(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.mysql
  *
  * // Query with validation
  * const UserSchema = z.object({
@@ -55,7 +56,11 @@ export interface MySQLClient extends BaseIntegrationClient {
    * );
    * ```
    */
-  query<T>(sql: string, schema: z.ZodSchema<T>, params?: unknown[]): Promise<T[]>;
+  query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+  ): Promise<T[]>;
 
   /**
    * Execute a SQL statement (INSERT, UPDATE, DELETE) without output validation.

package/src/integrations/notion/README.md

@@ -4,8 +4,8 @@ Query databases, create pages, and manage content in Notion workspaces.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                        |
+| ----------------------------- | -------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Notion API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Query databases, create pages, and manage content in Notion workspaces.
 ### Query a Database
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, notion } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_NOTION = "a1b2c3d4-5678-90ab-cdef-notion000001";
@@ -37,6 +37,9 @@ const QueryDatabaseResponseSchema = z.object({
 
 export default api({
   name: "NotionExample",
+  integrations: {
+    notion: notion(PROD_NOTION),
+  },
   input: z.object({
     databaseId: z.string(),
     status: z.string(),
@@ -45,9 +48,7 @@ export default api({
     pages: z.array(z.object({ id: z.string(), url: z.string() })),
   }),
   async run(ctx, { databaseId, status }) {
-    const notion = ctx.notion(PROD_NOTION);
-
-    const result = await notion.apiRequest(
+    const result = await ctx.integrations.notion.apiRequest(
       {
         method: "POST",
         path: `/v1/databases/${databaseId}/query`,
@@ -60,7 +61,7 @@ export default api({
           },
         },
       },
-      { response: QueryDatabaseResponseSchema }
+      { response: QueryDatabaseResponseSchema },
     );
 
     return {
@@ -82,7 +83,7 @@ const CreatePageResponseSchema = z.object({
   url: z.string(),
 });
 
-const result = await notion.apiRequest(
+const result = await ctx.integrations.notion.apiRequest(
   {
     method: "POST",
     path: "/v1/pages",
@@ -108,7 +109,7 @@ const result = await notion.apiRequest(
       },
     },
   },
-  { response: CreatePageResponseSchema }
+  { response: CreatePageResponseSchema },
 );
 
 console.log(`Created page: ${result.url}`);
@@ -117,7 +118,7 @@ console.log(`Created page: ${result.url}`);
 ### Update Page Properties
 
 ```typescript
-const result = await notion.apiRequest(
+const result = await ctx.integrations.notion.apiRequest(
   {
     method: "PATCH",
     path: `/v1/pages/${pageId}`,
@@ -132,19 +133,19 @@ const result = await notion.apiRequest(
       },
     },
   },
-  { response: PageSchema }
+  { response: PageSchema },
 );
 ```
 
 ### Get a Page
 
 ```typescript
-const result = await notion.apiRequest(
+const result = await ctx.integrations.notion.apiRequest(
   {
     method: "GET",
     path: `/v1/pages/${pageId}`,
   },
-  { response: PageSchema }
+  { response: PageSchema },
 );
 
 console.log(`Page: ${result.id}, Archived: ${result.archived}`);
@@ -158,7 +159,7 @@ const AppendBlocksResponseSchema = z.object({
   results: z.array(z.object({ id: z.string(), type: z.string() })),
 });
 
-const result = await notion.apiRequest(
+const result = await ctx.integrations.notion.apiRequest(
   {
     method: "PATCH",
     path: `/v1/blocks/${pageId}/children`,
@@ -175,7 +176,9 @@ const result = await notion.apiRequest(
           object: "block",
           type: "paragraph",
           paragraph: {
-            rich_text: [{ type: "text", text: { content: "Paragraph content here." } }],
+            rich_text: [
+              { type: "text", text: { content: "Paragraph content here." } },
+            ],
           },
         },
         {
@@ -188,7 +191,7 @@ const result = await notion.apiRequest(
       ],
     },
   },
-  { response: AppendBlocksResponseSchema }
+  { response: AppendBlocksResponseSchema },
 );
 ```
 
@@ -201,12 +204,12 @@ const SearchResponseSchema = z.object({
     z.object({
       object: z.enum(["page", "database"]),
       id: z.string(),
-    })
+    }),
   ),
   has_more: z.boolean(),
 });
 
-const result = await notion.apiRequest(
+const result = await ctx.integrations.notion.apiRequest(
   {
     method: "POST",
     path: "/v1/search",
@@ -216,7 +219,7 @@ const result = await notion.apiRequest(
       sort: { direction: "descending", timestamp: "last_edited_time" },
     },
   },
-  { response: SearchResponseSchema }
+  { response: SearchResponseSchema },
 );
 ```
 
@@ -232,16 +235,16 @@ const DatabaseResponseSchema = z.object({
       id: z.string(),
       name: z.string(),
       type: z.string(),
-    })
+    }),
   ),
 });
 
-const result = await notion.apiRequest(
+const result = await ctx.integrations.notion.apiRequest(
   {
     method: "GET",
     path: `/v1/databases/${databaseId}`,
   },
-  { response: DatabaseResponseSchema }
+  { response: DatabaseResponseSchema },
 );
 
 console.log("Properties:", Object.keys(result.properties));
@@ -257,7 +260,7 @@ await notion.queryDatabase({ ... });
 await notion.createPage({ ... });
 
 // CORRECT - Use apiRequest
-await notion.apiRequest(
+await ctx.integrations.notion.apiRequest(
   { method: "POST", path: `/v1/databases/${id}/query`, body: { ... } },
   { response: QueryDatabaseResponseSchema }
 );
@@ -270,13 +273,13 @@ Notion uses property IDs internally but displays names in the UI. When filtering
 ```typescript
 // Use property NAME (as shown in Notion UI)
 const filter = {
-  property: "Status",  // Display name
+  property: "Status", // Display name
   select: { equals: "Done" },
 };
 
 // NOT the property ID
 const wrongFilter = {
-  property: "abc123",  // ID won't work in filters
+  property: "abc123", // ID won't work in filters
   select: { equals: "Done" },
 };
 ```
@@ -385,7 +388,7 @@ async function getAllPages(notion: NotionClient, databaseId: string) {
   let cursor: string | undefined;
 
   do {
-    const result = await notion.apiRequest(
+    const result = await ctx.integrations.notion.apiRequest(
       {
         method: "POST",
         path: `/v1/databases/${databaseId}/query`,
@@ -394,7 +397,7 @@ async function getAllPages(notion: NotionClient, databaseId: string) {
           page_size: 100,
         },
       },
-      { response: QueryDatabaseResponseSchema }
+      { response: QueryDatabaseResponseSchema },
     );
 
     allPages.push(...result.results);
@@ -411,7 +414,7 @@ async function getAllPages(notion: NotionClient, databaseId: string) {
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await notion.apiRequest(
+  const result = await ctx.integrations.notion.apiRequest(
     { method: "POST", path: `/v1/databases/${id}/query`, body: { ... } },
     { response: QueryDatabaseResponseSchema }
   );

package/src/integrations/notion/client.ts

@@ -5,8 +5,8 @@
  * Notion integrations use the REST API Integration plugin under the hood.
  */
 
-import { RestApiIntegrationClient } from '../base/index.js';
-import type { NotionClient } from './types.js';
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { NotionClient } from "./types.js";
 
 /**
  * Internal implementation of NotionClient.
@@ -16,7 +16,9 @@ import type { NotionClient } from './types.js';
  * Notion API calls. At runtime, the orchestrator handles authentication
  * and API request execution.
  */
-export class NotionClientImpl extends RestApiIntegrationClient implements NotionClient {
+export class NotionClientImpl
+  extends RestApiIntegrationClient
+  implements NotionClient {
   // Inherits: name, pluginId, config, executeQuery, createParam(), apiRequest()
   // Can add Notion-specific methods here in the future if needed
 }

package/src/integrations/notion/index.ts

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

package/src/integrations/notion/types.ts

@@ -2,8 +2,8 @@
  * Notion 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";
 
 /**
  * Notion client for workspace and database interactions.
@@ -15,7 +15,8 @@ import type { SupportsApiRequest } from '../base/index.js';
  * ```typescript
  * import { z } from 'zod';
  *
- * const notion = ctx.integration('Production Notion');
+ * // Declare in api(): integrations: { notion: notion(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.notion
  *
  * // Define schemas
  * const PageSchema = z.object({
@@ -25,7 +26,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  * });
  *
  * // Get a page
- * const page = await notion.apiRequest(
+ * const page = await ctx.integrations.notion.apiRequest(
  *   {
  *     method: 'GET',
  *     path: '/v1/pages/page-id',
@@ -48,7 +49,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  *   has_more: z.boolean(),
  * });
  *
- * const results = await notion.apiRequest(
+ * const results = await ctx.integrations.notion.apiRequest(
  *   {
  *     method: 'POST',
  *     path: '/v1/databases/database-id/query',
@@ -66,6 +67,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  * );
  * ```
  */
-export interface NotionClient extends BaseIntegrationClient, SupportsApiRequest {
+export interface NotionClient
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
 }