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

package/src/integrations/segment/README.md

@@ -4,8 +4,8 @@ Track events, identify users, and interact with Segment's customer data platform
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                         |
+| ----------------------------- | --------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Segment API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Track events, identify users, and interact with Segment's customer data platform
 ### Track an Event
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, segment } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_SEGMENT = "a1b2c3d4-5678-90ab-cdef-segment00001";
@@ -23,6 +23,9 @@ const TrackResponseSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    segment: segment(PROD_SEGMENT),
+  },
   name: "SegmentExample",
   input: z.object({
     userId: z.string(),
@@ -33,9 +36,7 @@ export default api({
     success: z.boolean(),
   }),
   async run(ctx, { userId, event, properties }) {
-    const segment = ctx.segment(PROD_SEGMENT);
-
-    const result = await segment.apiRequest(
+    const result = await ctx.integrations.segment.apiRequest(
       {
         method: "POST",
         path: "/v1/track",
@@ -52,7 +53,7 @@ export default api({
           },
         },
       },
-      { response: TrackResponseSchema }
+      { response: TrackResponseSchema },
     );
 
     return { success: result.success };
@@ -67,7 +68,7 @@ const IdentifyResponseSchema = z.object({
   success: z.boolean(),
 });
 
-const result = await segment.apiRequest(
+const result = await ctx.integrations.segment.apiRequest(
   {
     method: "POST",
     path: "/v1/identify",
@@ -90,7 +91,7 @@ const result = await segment.apiRequest(
       },
     },
   },
-  { response: IdentifyResponseSchema }
+  { response: IdentifyResponseSchema },
 );
 
 console.log(`User identified: ${result.success}`);
@@ -104,7 +105,7 @@ const AliasResponseSchema = z.object({
 });
 
 // Link anonymous user to known user
-const result = await segment.apiRequest(
+const result = await ctx.integrations.segment.apiRequest(
   {
     method: "POST",
     path: "/v1/alias",
@@ -113,7 +114,7 @@ const result = await segment.apiRequest(
       userId: "user_123",
     },
   },
-  { response: AliasResponseSchema }
+  { response: AliasResponseSchema },
 );
 ```
 
@@ -124,7 +125,7 @@ const PageResponseSchema = z.object({
   success: z.boolean(),
 });
 
-const result = await segment.apiRequest(
+const result = await ctx.integrations.segment.apiRequest(
   {
     method: "POST",
     path: "/v1/page",
@@ -140,7 +141,7 @@ const result = await segment.apiRequest(
       },
     },
   },
-  { response: PageResponseSchema }
+  { response: PageResponseSchema },
 );
 ```
 
@@ -151,7 +152,7 @@ const GroupResponseSchema = z.object({
   success: z.boolean(),
 });
 
-const result = await segment.apiRequest(
+const result = await ctx.integrations.segment.apiRequest(
   {
     method: "POST",
     path: "/v1/group",
@@ -167,7 +168,7 @@ const result = await segment.apiRequest(
       },
     },
   },
-  { response: GroupResponseSchema }
+  { response: GroupResponseSchema },
 );
 ```
 
@@ -178,7 +179,7 @@ const BatchResponseSchema = z.object({
   success: z.boolean(),
 });
 
-const result = await segment.apiRequest(
+const result = await ctx.integrations.segment.apiRequest(
   {
     method: "POST",
     path: "/v1/batch",
@@ -207,7 +208,7 @@ const result = await segment.apiRequest(
       },
     },
   },
-  { response: BatchResponseSchema }
+  { response: BatchResponseSchema },
 );
 ```
 
@@ -218,7 +219,7 @@ const ScreenResponseSchema = z.object({
   success: z.boolean(),
 });
 
-const result = await segment.apiRequest(
+const result = await ctx.integrations.segment.apiRequest(
   {
     method: "POST",
     path: "/v1/screen",
@@ -243,7 +244,7 @@ const result = await segment.apiRequest(
       },
     },
   },
-  { response: ScreenResponseSchema }
+  { response: ScreenResponseSchema },
 );
 ```
 
@@ -257,7 +258,7 @@ await segment.track({ ... });
 await segment.identify({ ... });
 
 // CORRECT - Use apiRequest
-await segment.apiRequest(
+await ctx.integrations.segment.apiRequest(
   { method: "POST", path: "/v1/track", body: { ... } },
   { response: TrackResponseSchema }
 );
@@ -404,7 +405,7 @@ const events = [...]; // Large array
 const chunkSize = 100;
 for (let i = 0; i < events.length; i += chunkSize) {
   const batch = events.slice(i, i + chunkSize);
-  await segment.apiRequest(
+  await ctx.integrations.segment.apiRequest(
     {
       method: "POST",
       path: "/v1/batch",
@@ -468,7 +469,7 @@ Segment's Tracking API always returns `{success: true}` for valid requests:
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await segment.apiRequest(
+  const result = await ctx.integrations.segment.apiRequest(
     { method: "POST", path: "/v1/track", body: { ... } },
     { response: TrackResponseSchema }
   );

package/src/integrations/segment/client.ts

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

package/src/integrations/segment/index.ts

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

package/src/integrations/segment/types.ts

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

package/src/integrations/sendgrid/README.md

@@ -4,8 +4,8 @@ Send transactional emails, manage contacts, and interact with SendGrid's email A
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                          |
+| ----------------------------- | ---------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any SendGrid API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Send transactional emails, manage contacts, and interact with SendGrid's email A
 ### Send a Simple Email
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, sendgrid } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_SENDGRID = "a1b2c3d4-5678-90ab-cdef-sendgrid0001";
@@ -22,6 +22,9 @@ const PROD_SENDGRID = "a1b2c3d4-5678-90ab-cdef-sendgrid0001";
 const SendEmailResponseSchema = z.object({}).optional();
 
 export default api({
+  integrations: {
+    sendgrid: sendgrid(PROD_SENDGRID),
+  },
   name: "SendGridExample",
   input: z.object({
     to: z.string().email(),
@@ -32,9 +35,7 @@ export default api({
     success: z.boolean(),
   }),
   async run(ctx, { to, subject, body }) {
-    const sendgrid = ctx.sendgrid(PROD_SENDGRID);
-
-    await sendgrid.apiRequest(
+    await ctx.integrations.sendgrid.apiRequest(
       {
         method: "POST",
         path: "/v3/mail/send",
@@ -54,7 +55,7 @@ export default api({
           ],
         },
       },
-      { response: SendEmailResponseSchema }
+      { response: SendEmailResponseSchema },
     );
 
     return { success: true };
@@ -65,7 +66,7 @@ export default api({
 ### Send HTML Email
 
 ```typescript
-await sendgrid.apiRequest(
+await ctx.integrations.sendgrid.apiRequest(
   {
     method: "POST",
     path: "/v3/mail/send",
@@ -89,14 +90,14 @@ await sendgrid.apiRequest(
       ],
     },
   },
-  { response: SendEmailResponseSchema }
+  { response: SendEmailResponseSchema },
 );
 ```
 
 ### Send with Template
 
 ```typescript
-await sendgrid.apiRequest(
+await ctx.integrations.sendgrid.apiRequest(
   {
     method: "POST",
     path: "/v3/mail/send",
@@ -115,14 +116,14 @@ await sendgrid.apiRequest(
       template_id: "d-abc123def456", // Your template ID
     },
   },
-  { response: SendEmailResponseSchema }
+  { response: SendEmailResponseSchema },
 );
 ```
 
 ### Send to Multiple Recipients
 
 ```typescript
-await sendgrid.apiRequest(
+await ctx.integrations.sendgrid.apiRequest(
   {
     method: "POST",
     path: "/v3/mail/send",
@@ -142,14 +143,14 @@ await sendgrid.apiRequest(
       content: [{ type: "text/plain", value: "Hello team!" }],
     },
   },
-  { response: SendEmailResponseSchema }
+  { response: SendEmailResponseSchema },
 );
 ```
 
 ### Send with Attachments
 
 ```typescript
-await sendgrid.apiRequest(
+await ctx.integrations.sendgrid.apiRequest(
   {
     method: "POST",
     path: "/v3/mail/send",
@@ -168,7 +169,7 @@ await sendgrid.apiRequest(
       ],
     },
   },
-  { response: SendEmailResponseSchema }
+  { response: SendEmailResponseSchema },
 );
 ```
 
@@ -179,7 +180,7 @@ const AddContactResponseSchema = z.object({
   job_id: z.string(),
 });
 
-const result = await sendgrid.apiRequest(
+const result = await ctx.integrations.sendgrid.apiRequest(
   {
     method: "PUT",
     path: "/v3/marketing/contacts",
@@ -197,7 +198,7 @@ const result = await sendgrid.apiRequest(
       ],
     },
   },
-  { response: AddContactResponseSchema }
+  { response: AddContactResponseSchema },
 );
 ```
 
@@ -217,12 +218,12 @@ const StatsResponseSchema = z.array(
           bounces: z.number(),
           spam_reports: z.number(),
         }),
-      })
+      }),
     ),
-  })
+  }),
 );
 
-const stats = await sendgrid.apiRequest(
+const stats = await ctx.integrations.sendgrid.apiRequest(
   {
     method: "GET",
     path: "/v3/stats",
@@ -232,12 +233,14 @@ const stats = await sendgrid.apiRequest(
       aggregated_by: "day",
     },
   },
-  { response: StatsResponseSchema }
+  { response: StatsResponseSchema },
 );
 
 stats.forEach((day) => {
   const metrics = day.stats[0]?.metrics;
-  console.log(`${day.date}: ${metrics?.delivered} delivered, ${metrics?.opens} opens`);
+  console.log(
+    `${day.date}: ${metrics?.delivered} delivered, ${metrics?.opens} opens`,
+  );
 });
 ```
 
@@ -251,7 +254,7 @@ await sendgrid.sendEmail({ ... });
 await sendgrid.send({ ... });
 
 // CORRECT - Use apiRequest
-await sendgrid.apiRequest(
+await ctx.integrations.sendgrid.apiRequest(
   { method: "POST", path: "/v3/mail/send", body: { ... } },
   { response: SendEmailResponseSchema }
 );
@@ -343,7 +346,7 @@ SendGrid has rate limits based on your plan. For bulk sending, consider:
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  await sendgrid.apiRequest(
+  await ctx.integrations.sendgrid.apiRequest(
     { method: "POST", path: "/v3/mail/send", body: { ... } },
     { response: SendEmailResponseSchema }
   );

package/src/integrations/sendgrid/client.ts

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

package/src/integrations/sendgrid/index.ts

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

package/src/integrations/sendgrid/types.ts

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