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

package/src/integrations/intercom/client.ts

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

package/src/integrations/intercom/index.ts

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

package/src/integrations/intercom/types.ts

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

package/src/integrations/jira/README.md

@@ -4,8 +4,8 @@ Create issues, search projects, and manage work in Jira.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                      |
+| ----------------------------- | ------------------------------------------------ |
 | `apiRequest(options, schema)` | Make any Jira API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Create issues, search projects, and manage work in Jira.
 ### Create an Issue
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, jira } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_JIRA = "a1b2c3d4-5678-90ab-cdef-jira00000001";
@@ -22,11 +22,13 @@ const IssueSchema = z.object({
   id: z.string(),
   key: z.string(),
   self: z.string(),
-  fields: z.object({
-    summary: z.string(),
-    status: z.object({ name: z.string() }),
-    issuetype: z.object({ name: z.string() }),
-  }).passthrough(),
+  fields: z
+    .object({
+      summary: z.string(),
+      status: z.object({ name: z.string() }),
+      issuetype: z.object({ name: z.string() }),
+    })
+    .passthrough(),
 });
 
 const CreateIssueResponseSchema = z.object({
@@ -36,6 +38,9 @@ const CreateIssueResponseSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    jira: jira(PROD_JIRA),
+  },
   name: "JiraExample",
   input: z.object({
     projectKey: z.string(),
@@ -46,9 +51,7 @@ export default api({
     issueKey: z.string(),
   }),
   async run(ctx, { projectKey, summary, description }) {
-    const jira = ctx.jira(PROD_JIRA);
-
-    const result = await jira.apiRequest(
+    const result = await ctx.integrations.jira.apiRequest(
       {
         method: "POST",
         path: "/rest/api/3/issue",
@@ -70,7 +73,7 @@ export default api({
           },
         },
       },
-      { response: CreateIssueResponseSchema }
+      { response: CreateIssueResponseSchema },
     );
 
     return { issueKey: result.key };
@@ -88,7 +91,7 @@ const SearchResponseSchema = z.object({
   startAt: z.number(),
 });
 
-const result = await jira.apiRequest(
+const result = await ctx.integrations.jira.apiRequest(
   {
     method: "POST",
     path: "/rest/api/3/search",
@@ -98,7 +101,7 @@ const result = await jira.apiRequest(
       maxResults: 50,
     },
   },
-  { response: SearchResponseSchema }
+  { response: SearchResponseSchema },
 );
 
 result.issues.forEach((issue) => {
@@ -109,7 +112,7 @@ result.issues.forEach((issue) => {
 ### Get an Issue
 
 ```typescript
-const result = await jira.apiRequest(
+const result = await ctx.integrations.jira.apiRequest(
   {
     method: "GET",
     path: `/rest/api/3/issue/${issueKey}`,
@@ -117,14 +120,14 @@ const result = await jira.apiRequest(
       fields: "summary,status,assignee,description,priority,labels",
     },
   },
-  { response: IssueSchema }
+  { response: IssueSchema },
 );
 ```
 
 ### Update an Issue
 
 ```typescript
-await jira.apiRequest(
+await ctx.integrations.jira.apiRequest(
   {
     method: "PUT",
     path: `/rest/api/3/issue/${issueKey}`,
@@ -136,7 +139,7 @@ await jira.apiRequest(
       },
     },
   },
-  { response: z.object({}).optional() } // Returns empty on success
+  { response: z.object({}).optional() }, // Returns empty on success
 );
 ```
 
@@ -150,16 +153,16 @@ const TransitionsResponseSchema = z.object({
       id: z.string(),
       name: z.string(),
       to: z.object({ name: z.string() }),
-    })
+    }),
   ),
 });
 
-const transitions = await jira.apiRequest(
+const transitions = await ctx.integrations.jira.apiRequest(
   {
     method: "GET",
     path: `/rest/api/3/issue/${issueKey}/transitions`,
   },
-  { response: TransitionsResponseSchema }
+  { response: TransitionsResponseSchema },
 );
 
 // Find the transition you want
@@ -167,7 +170,7 @@ const doneTransition = transitions.transitions.find((t) => t.name === "Done");
 
 // Execute the transition
 if (doneTransition) {
-  await jira.apiRequest(
+  await ctx.integrations.jira.apiRequest(
     {
       method: "POST",
       path: `/rest/api/3/issue/${issueKey}/transitions`,
@@ -175,7 +178,7 @@ if (doneTransition) {
         transition: { id: doneTransition.id },
       },
     },
-    { response: z.object({}).optional() }
+    { response: z.object({}).optional() },
   );
 }
 ```
@@ -192,7 +195,7 @@ const CommentResponseSchema = z.object({
   }),
 });
 
-const result = await jira.apiRequest(
+const result = await ctx.integrations.jira.apiRequest(
   {
     method: "POST",
     path: `/rest/api/3/issue/${issueKey}/comment`,
@@ -209,14 +212,14 @@ const result = await jira.apiRequest(
       },
     },
   },
-  { response: CommentResponseSchema }
+  { response: CommentResponseSchema },
 );
 ```
 
 ### Assign an Issue
 
 ```typescript
-await jira.apiRequest(
+await ctx.integrations.jira.apiRequest(
   {
     method: "PUT",
     path: `/rest/api/3/issue/${issueKey}/assignee`,
@@ -224,7 +227,7 @@ await jira.apiRequest(
       accountId: "5b10a2844c20165700ede21g", // User account ID
     },
   },
-  { response: z.object({}).optional() }
+  { response: z.object({}).optional() },
 );
 ```
 
@@ -238,12 +241,12 @@ const ListProjectsResponseSchema = z.object({
       key: z.string(),
       name: z.string(),
       projectTypeKey: z.string(),
-    })
+    }),
   ),
   total: z.number(),
 });
 
-const result = await jira.apiRequest(
+const result = await ctx.integrations.jira.apiRequest(
   {
     method: "GET",
     path: "/rest/api/3/project/search",
@@ -252,7 +255,7 @@ const result = await jira.apiRequest(
       orderBy: "name",
     },
   },
-  { response: ListProjectsResponseSchema }
+  { response: ListProjectsResponseSchema },
 );
 ```
 
@@ -266,10 +269,10 @@ const AttachmentResponseSchema = z.array(
     id: z.string(),
     filename: z.string(),
     size: z.number(),
-  })
+  }),
 );
 
-const result = await jira.apiRequest(
+const result = await ctx.integrations.jira.apiRequest(
   {
     method: "POST",
     path: `/rest/api/3/issue/${issueKey}/attachments`,
@@ -278,7 +281,7 @@ const result = await jira.apiRequest(
     },
     body: fileContent, // Multipart form data
   },
-  { response: AttachmentResponseSchema }
+  { response: AttachmentResponseSchema },
 );
 ```
 
@@ -292,7 +295,7 @@ await jira.createIssue({ ... });
 await jira.searchIssues({ ... });
 
 // CORRECT - Use apiRequest
-await jira.apiRequest(
+await ctx.integrations.jira.apiRequest(
   { method: "POST", path: "/rest/api/3/issue", body: { fields: { ... } } },
   { response: CreateIssueResponseSchema }
 );
@@ -375,14 +378,14 @@ const jql = 'project = "PROJ"';
 const jql = 'project = "PROJ" AND status = "In Progress"';
 
 // Date queries
-const jql = 'created >= -7d';  // Last 7 days
-const jql = 'due <= 2024-12-31';
+const jql = "created >= -7d"; // Last 7 days
+const jql = "due <= 2024-12-31";
 
 // Text search
 const jql = 'text ~ "search term"';
 
 // Assignee
-const jql = 'assignee = currentUser()';
+const jql = "assignee = currentUser()";
 const jql = 'assignee = "john@example.com"';
 
 // Labels
@@ -415,9 +418,9 @@ Custom fields use IDs like `customfield_10001`:
 const body = {
   fields: {
     summary: "Issue summary",
-    customfield_10001: "Custom value",  // Text field
-    customfield_10002: { value: "Option A" },  // Select field
-    customfield_10003: [{ value: "A" }, { value: "B" }],  // Multi-select
+    customfield_10001: "Custom value", // Text field
+    customfield_10002: { value: "Option A" }, // Select field
+    customfield_10003: [{ value: "A" }, { value: "B" }], // Multi-select
   },
 };
 ```
@@ -433,13 +436,13 @@ async function getAllIssues(jira: JiraClient, jql: string) {
   const maxResults = 100;
 
   while (true) {
-    const result = await jira.apiRequest(
+    const result = await ctx.integrations.jira.apiRequest(
       {
         method: "POST",
         path: "/rest/api/3/search",
         body: { jql, startAt, maxResults },
       },
-      { response: SearchResponseSchema }
+      { response: SearchResponseSchema },
     );
 
     allIssues.push(...result.issues);
@@ -458,7 +461,7 @@ async function getAllIssues(jira: JiraClient, jql: string) {
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await jira.apiRequest(
+  const result = await ctx.integrations.jira.apiRequest(
     { method: "POST", path: "/rest/api/3/issue", body: { ... } },
     { response: CreateIssueResponseSchema }
   );

package/src/integrations/jira/client.ts

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

package/src/integrations/jira/index.ts

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

package/src/integrations/jira/types.ts

@@ -2,8 +2,8 @@
  * Jira 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";
 
 /**
  * Jira client for API interactions.
@@ -13,7 +13,8 @@ import type { SupportsApiRequest } from '../base/index.js';
  *
  * @example
  * ```typescript
- * const jira = ctx.jira('My Jira');
+ * // Declare in api(): integrations: { jira: jira(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.jira
  *
  * // Make API requests
  * const ResponseSchema = z.object({

package/src/integrations/kafka/README.md

@@ -4,29 +4,34 @@ Interact with Apache Kafka with full type safety and runtime validation.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                    | Description                         |
+| ------------------------- | ----------------------------------- |
 | `consume(schema, params)` | Consume messages from a Kafka topic |
-| `produce(schema, params)` | Produce messages to Kafka topics |
+| `produce(schema, params)` | Produce messages to Kafka topics    |
 
 ## Usage
 
 ### Consume Messages
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, kafka } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_KAFKA = "a1b2c3d4-5678-90ab-cdef-kafka0000001";
 
-const MessageSchema = z.array(z.object({
-  topic: z.string(),
-  partition: z.number(),
-  offset: z.number(),
-  value: z.unknown(),
-}));
+const MessageSchema = z.array(
+  z.object({
+    topic: z.string(),
+    partition: z.number(),
+    offset: z.number(),
+    value: z.unknown(),
+  }),
+);
 
 export default api({
+  integrations: {
+    kafka: kafka(PROD_KAFKA),
+  },
   name: "KafkaExample",
   input: z.object({
     topic: z.string(),
@@ -35,8 +40,6 @@ export default api({
     messages: MessageSchema,
   }),
   async run(ctx, { topic }) {
-    const kafka = ctx.kafka(PROD_KAFKA);
-
     const messages = await kafka.consume(MessageSchema, {
       topic: topic,
       from: "LATEST",
@@ -63,7 +66,7 @@ const messages = await kafka.consume(MessageSchema, {
 ```typescript
 const ProduceResultSchema = z.any();
 
-const result = await kafka.produce(ProduceResultSchema, {
+const result = await ctx.integrations.kafka.produce(ProduceResultSchema, {
   messages: JSON.stringify([
     { topic: "my-topic", value: { event: "purchase", amount: 99.99 } },
     { topic: "my-topic", value: { event: "signup", userId: "123" } },
@@ -74,7 +77,7 @@ const result = await kafka.produce(ProduceResultSchema, {
 ### Produce with Options
 
 ```typescript
-const result = await kafka.produce(ProduceResultSchema, {
+const result = await ctx.integrations.kafka.produce(ProduceResultSchema, {
   messages: JSON.stringify([
     { topic: "my-topic", key: "user-123", value: { data: "payload" } },
   ]),
@@ -87,32 +90,35 @@ const result = await kafka.produce(ProduceResultSchema, {
 
 ## Consume Parameters
 
-| Parameter | Type | Description |
-| --------- | ---- | ----------- |
-| `topic` | `string` | Topic to consume from |
-| `from` | `'BEGINNING' \| 'LATEST' \| 'SEEK'` | Where to start consuming from |
-| `groupId` | `string` | Consumer group ID |
-| `clientId` | `string` | Client ID |
-| `readUncommitted` | `boolean` | Whether to read uncommitted messages |
-| `seek` | `object` | Seek position for SEEK mode |
+| Parameter         | Type                                | Description                          |
+| ----------------- | ----------------------------------- | ------------------------------------ |
+| `topic`           | `string`                            | Topic to consume from                |
+| `from`            | `'BEGINNING' \| 'LATEST' \| 'SEEK'` | Where to start consuming from        |
+| `groupId`         | `string`                            | Consumer group ID                    |
+| `clientId`        | `string`                            | Client ID                            |
+| `readUncommitted` | `boolean`                           | Whether to read uncommitted messages |
+| `seek`            | `object`                            | Seek position for SEEK mode          |
 
 ## Produce Parameters
 
-| Parameter | Type | Description |
-| --------- | ---- | ----------- |
-| `messages` | `string` | JSON string array of messages |
-| `acks` | `'NONE' \| 'LEADER' \| 'ALL'` | Acknowledgment level |
-| `compression` | `'GZIP' \| 'SNAPPY' \| 'LZ4' \| 'ZSTD'` | Compression type |
-| `autoCreateTopic` | `boolean` | Auto-create topic if missing |
-| `transaction` | `boolean` | Use transactions |
-| `idempotent` | `boolean` | Enable idempotent delivery |
-| `clientId` | `string` | Client ID |
-| `timeout` | `number` | Timeout in milliseconds |
+| Parameter         | Type                                    | Description                   |
+| ----------------- | --------------------------------------- | ----------------------------- |
+| `messages`        | `string`                                | JSON string array of messages |
+| `acks`            | `'NONE' \| 'LEADER' \| 'ALL'`           | Acknowledgment level          |
+| `compression`     | `'GZIP' \| 'SNAPPY' \| 'LZ4' \| 'ZSTD'` | Compression type              |
+| `autoCreateTopic` | `boolean`                               | Auto-create topic if missing  |
+| `transaction`     | `boolean`                               | Use transactions              |
+| `idempotent`      | `boolean`                               | Enable idempotent delivery    |
+| `clientId`        | `string`                                | Client ID                     |
+| `timeout`         | `number`                                | Timeout in milliseconds       |
 
 ## Error Handling
 
 ```typescript
-import { RestApiValidationError, IntegrationError } from "@superblocksteam/sdk-api";
+import {
+  RestApiValidationError,
+  IntegrationError,
+} from "@superblocksteam/sdk-api";
 
 try {
   const messages = await kafka.consume(MessageSchema, {

package/src/integrations/kafka/client.ts

@@ -4,18 +4,22 @@
  * Constructs request objects matching the expected backend format.
  */
 
-import type { z } from 'zod';
-import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
-import type { QueryExecutor } from '../registry.js';
-import { RestApiValidationError } from '../../errors.js';
-import { IntegrationError } from '../../runtime/errors.js';
-import type { KafkaClient, KafkaConsumeParams, KafkaProduceParams } from './types.js';
+import type { z } from "zod";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor } from "../registry.js";
+import { RestApiValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import type {
+  KafkaClient,
+  KafkaConsumeParams,
+  KafkaProduceParams,
+} from "./types.js";
 
 /**
  * Consume request structure.
  */
 interface KafkaConsumeRequest {
-  operation: 'OPERATION_CONSUME';
+  operation: "OPERATION_CONSUME";
   consume: {
     topic: string;
     from: string;
@@ -34,7 +38,7 @@ interface KafkaConsumeRequest {
  * Produce request structure.
  */
 interface KafkaProduceRequest {
-  operation: 'OPERATION_PRODUCE';
+  operation: "OPERATION_PRODUCE";
   produce: {
     messages: string;
     acks?: string;
@@ -57,36 +61,36 @@ type KafkaRequest = KafkaConsumeRequest | KafkaProduceRequest;
  * Operation string values expected by the Kafka plugin.
  */
 const OPERATION = {
-  CONSUME: 'OPERATION_CONSUME',
-  PRODUCE: 'OPERATION_PRODUCE',
+  CONSUME: "OPERATION_CONSUME",
+  PRODUCE: "OPERATION_PRODUCE",
 } as const;
 
 /**
  * Consume from string values.
  */
 const CONSUME_FROM = {
-  BEGINNING: 'FROM_BEGINNING',
-  LATEST: 'FROM_LATEST',
-  SEEK: 'FROM_SEEK',
+  BEGINNING: "FROM_BEGINNING",
+  LATEST: "FROM_LATEST",
+  SEEK: "FROM_SEEK",
 } as const;
 
 /**
  * Acks string values.
  */
 const ACKS = {
-  NONE: 'ACKS_NONE',
-  LEADER: 'ACKS_LEADER',
-  ALL: 'ACKS_ALL',
+  NONE: "ACKS_NONE",
+  LEADER: "ACKS_LEADER",
+  ALL: "ACKS_ALL",
 } as const;
 
 /**
  * Compression string values.
  */
 const COMPRESSION = {
-  GZIP: 'COMPRESSION_GZIP',
-  SNAPPY: 'COMPRESSION_SNAPPY',
-  LZ4: 'COMPRESSION_LZ4',
-  ZSTD: 'COMPRESSION_ZSTD',
+  GZIP: "COMPRESSION_GZIP",
+  SNAPPY: "COMPRESSION_SNAPPY",
+  LZ4: "COMPRESSION_LZ4",
+  ZSTD: "COMPRESSION_ZSTD",
 } as const;
 
 /**
@@ -109,9 +113,7 @@ export class KafkaClientImpl implements KafkaClient, IntegrationClientImpl {
     return this.config.pluginId;
   }
 
-  private buildConsumeRequest(
-    params: KafkaConsumeParams,
-  ): KafkaConsumeRequest {
+  private buildConsumeRequest(params: KafkaConsumeParams): KafkaConsumeRequest {
     const request: KafkaConsumeRequest = {
       operation: OPERATION.CONSUME,
       consume: {
@@ -134,9 +136,7 @@ export class KafkaClientImpl implements KafkaClient, IntegrationClientImpl {
     return request;
   }
 
-  private buildProduceRequest(
-    params: KafkaProduceParams,
-  ): KafkaProduceRequest {
+  private buildProduceRequest(params: KafkaProduceParams): KafkaProduceRequest {
     const request: KafkaProduceRequest = {
       operation: OPERATION.PRODUCE,
       produce: {
@@ -144,7 +144,9 @@ export class KafkaClientImpl implements KafkaClient, IntegrationClientImpl {
         acks: params.acks ? ACKS[params.acks] : ACKS.ALL,
         clientId: params.clientId,
         timeout: params.timeout,
-        compression: params.compression ? COMPRESSION[params.compression] : undefined,
+        compression: params.compression
+          ? COMPRESSION[params.compression]
+          : undefined,
         transactionId: params.transactionId,
         autoCreateTopic: params.autoCreateTopic ?? false,
         idempotent: params.idempotent ?? false,
@@ -161,7 +163,9 @@ export class KafkaClientImpl implements KafkaClient, IntegrationClientImpl {
     operation: string,
   ): Promise<T> {
     try {
-      const result = await this.executeQuery(request as unknown as Record<string, unknown>);
+      const result = await this.executeQuery(
+        request as unknown as Record<string, unknown>,
+      );
 
       const parseResult = schema.safeParse(result);
 
@@ -193,7 +197,7 @@ export class KafkaClientImpl implements KafkaClient, IntegrationClientImpl {
     params: KafkaConsumeParams,
   ): Promise<T> {
     const request = this.buildConsumeRequest(params);
-    return this.executeAndValidate(request, schema, 'consume');
+    return this.executeAndValidate(request, schema, "consume");
   }
 
   async produce<T>(
@@ -201,6 +205,6 @@ export class KafkaClientImpl implements KafkaClient, IntegrationClientImpl {
     params: KafkaProduceParams,
   ): Promise<T> {
     const request = this.buildProduceRequest(params);
-    return this.executeAndValidate(request, schema, 'produce');
+    return this.executeAndValidate(request, schema, "produce");
   }
 }