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

package/src/integrations/cohere/README.md

@@ -4,8 +4,8 @@ Interact with Cohere's APIs for text generation, embeddings, classification, and
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                        |
+| ----------------------------- | -------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Cohere API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Interact with Cohere's APIs for text generation, embeddings, classification, and
 ### Chat Completion
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, cohere } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_COHERE = "a1b2c3d4-5678-90ab-cdef-cohere000001";
@@ -25,7 +25,7 @@ const ChatResponseSchema = z.object({
     z.object({
       role: z.enum(["USER", "CHATBOT", "SYSTEM"]),
       message: z.string(),
-    })
+    }),
   ),
   finish_reason: z.string(),
   meta: z.object({
@@ -39,6 +39,9 @@ const ChatResponseSchema = z.object({
 
 export default api({
   name: "CohereExample",
+  integrations: {
+    cohere: cohere(PROD_COHERE),
+  },
   input: z.object({
     message: z.string(),
   }),
@@ -46,9 +49,7 @@ export default api({
     response: z.string(),
   }),
   async run(ctx, { message }) {
-    const cohere = ctx.cohere(PROD_COHERE);
-
-    const result = await cohere.apiRequest(
+    const result = await ctx.integrations.cohere.apiRequest(
       {
         method: "POST",
         path: "/v1/chat",
@@ -57,7 +58,7 @@ export default api({
           message: message,
         },
       },
-      { response: ChatResponseSchema }
+      { response: ChatResponseSchema },
     );
 
     return { response: result.text };
@@ -77,7 +78,7 @@ const EmbedResponseSchema = z.object({
   }),
 });
 
-const result = await cohere.apiRequest(
+const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
     path: "/v1/embed",
@@ -87,7 +88,7 @@ const result = await cohere.apiRequest(
       input_type: "search_document",
     },
   },
-  { response: EmbedResponseSchema }
+  { response: EmbedResponseSchema },
 );
 
 result.embeddings.forEach((embedding, i) => {
@@ -107,11 +108,11 @@ const ClassifyResponseSchema = z.object({
       prediction: z.string(),
       confidence: z.number(),
       labels: z.record(z.object({ confidence: z.number() })),
-    })
+    }),
   ),
 });
 
-const result = await cohere.apiRequest(
+const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
     path: "/v1/classify",
@@ -126,7 +127,7 @@ const result = await cohere.apiRequest(
       ],
     },
   },
-  { response: ClassifyResponseSchema }
+  { response: ClassifyResponseSchema },
 );
 
 result.classifications.forEach((c) => {
@@ -144,7 +145,7 @@ const RerankResponseSchema = z.object({
       index: z.number(),
       relevance_score: z.number(),
       document: z.object({ text: z.string() }).optional(),
-    })
+    }),
   ),
 });
 
@@ -155,7 +156,7 @@ const documents = [
   "Capital punishment has existed since ancient times.",
 ];
 
-const result = await cohere.apiRequest(
+const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
     path: "/v1/rerank",
@@ -167,7 +168,7 @@ const result = await cohere.apiRequest(
       return_documents: true,
     },
   },
-  { response: RerankResponseSchema }
+  { response: RerankResponseSchema },
 );
 
 result.results.forEach((r) => {
@@ -185,11 +186,11 @@ const GenerateResponseSchema = z.object({
       id: z.string(),
       text: z.string(),
       finish_reason: z.string(),
-    })
+    }),
   ),
 });
 
-const result = await cohere.apiRequest(
+const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
     path: "/v1/generate",
@@ -200,7 +201,7 @@ const result = await cohere.apiRequest(
       temperature: 0.7,
     },
   },
-  { response: GenerateResponseSchema }
+  { response: GenerateResponseSchema },
 );
 ```
 
@@ -214,7 +215,7 @@ await cohere.chat({ ... });
 await cohere.embed({ ... });
 
 // CORRECT - Use apiRequest
-await cohere.apiRequest(
+await ctx.integrations.cohere.apiRequest(
   { method: "POST", path: "/v1/chat", body: { ... } },
   { response: ChatResponseSchema }
 );
@@ -226,7 +227,7 @@ When creating embeddings, specify the correct `input_type`:
 
 ```typescript
 // For documents to be searched
-const docEmbeddings = await cohere.apiRequest(
+const docEmbeddings = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
     path: "/v1/embed",
@@ -235,11 +236,11 @@ const docEmbeddings = await cohere.apiRequest(
       input_type: "search_document", // For documents
     },
   },
-  { response: EmbedResponseSchema }
+  { response: EmbedResponseSchema },
 );
 
 // For search queries
-const queryEmbedding = await cohere.apiRequest(
+const queryEmbedding = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
     path: "/v1/embed",
@@ -248,7 +249,7 @@ const queryEmbedding = await cohere.apiRequest(
       input_type: "search_query", // For queries
     },
   },
-  { response: EmbedResponseSchema }
+  { response: EmbedResponseSchema },
 );
 ```
 
@@ -258,7 +259,7 @@ The classify endpoint requires labeled examples:
 
 ```typescript
 // WRONG - No examples
-const result = await cohere.apiRequest(
+const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
     path: "/v1/classify",
@@ -267,11 +268,11 @@ const result = await cohere.apiRequest(
       // Missing examples!
     },
   },
-  { response: ClassifyResponseSchema }
+  { response: ClassifyResponseSchema },
 );
 
 // CORRECT - Include examples
-const result = await cohere.apiRequest(
+const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
     path: "/v1/classify",
@@ -283,7 +284,7 @@ const result = await cohere.apiRequest(
       ],
     },
   },
-  { response: ClassifyResponseSchema }
+  { response: ClassifyResponseSchema },
 );
 ```
 
@@ -293,7 +294,7 @@ const result = await cohere.apiRequest(
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await cohere.apiRequest(
+  const result = await ctx.integrations.cohere.apiRequest(
     { method: "POST", path: "/v1/chat", body: { ... } },
     { response: ChatResponseSchema }
   );

package/src/integrations/cohere/client.ts

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

package/src/integrations/cohere/index.ts

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

package/src/integrations/cohere/types.ts

@@ -2,8 +2,8 @@
  * Cohere 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";
 
 /**
  * Cohere client for API interactions.
@@ -13,14 +13,9 @@ import type { SupportsApiRequest } from '../base/index.js';
  *
  * @example
  * ```typescript
- * const cohere = ctx.cohere('My Cohere');
- *
- * // Make API requests
- * const ResponseSchema = z.object({
- *   // Define your response schema
- * });
- *
- * const result = await cohere.apiRequest(
+ * // Declare in api(): integrations: { cohere: cohere(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.cohere
+ * const result = await ctx.integrations.cohere.apiRequest(
  *   {
  *     method: 'POST',
  *     path: '/generate',
@@ -29,6 +24,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  * );
  * ```
  */
-export interface CohereClient extends BaseIntegrationClient, SupportsApiRequest {
+export interface CohereClient
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
 }

package/src/integrations/confluence/README.md

@@ -4,8 +4,8 @@ Create pages, manage content, and search in Confluence spaces.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                            |
+| ----------------------------- | ------------------------------------------------------ |
 | `apiRequest(options, schema)` | Make any Confluence API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Create pages, manage content, and search in Confluence spaces.
 ### Create a Page
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, confluence } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_CONFLUENCE = "a1b2c3d4-5678-90ab-cdef-confluen0001";
@@ -31,6 +31,9 @@ const PageSchema = z.object({
 
 export default api({
   name: "ConfluenceExample",
+  integrations: {
+    confluence: confluence(PROD_CONFLUENCE),
+  },
   input: z.object({
     spaceKey: z.string(),
     title: z.string(),
@@ -41,9 +44,7 @@ export default api({
     url: z.string(),
   }),
   async run(ctx, { spaceKey, title, content }) {
-    const confluence = ctx.confluence(PROD_CONFLUENCE);
-
-    const result = await confluence.apiRequest(
+    const result = await ctx.integrations.confluence.apiRequest(
       {
         method: "POST",
         path: "/wiki/api/v2/pages",
@@ -57,7 +58,7 @@ export default api({
           },
         },
       },
-      { response: PageSchema }
+      { response: PageSchema },
     );
 
     return { pageId: result.id, url: result._links.webui };
@@ -72,19 +73,23 @@ const PageDetailSchema = z.object({
   id: z.string(),
   title: z.string(),
   status: z.string(),
-  body: z.object({
-    storage: z.object({
-      value: z.string(),
-      representation: z.string(),
-    }).optional(),
-  }).optional(),
+  body: z
+    .object({
+      storage: z
+        .object({
+          value: z.string(),
+          representation: z.string(),
+        })
+        .optional(),
+    })
+    .optional(),
   version: z.object({
     number: z.number(),
     createdAt: z.string(),
   }),
 });
 
-const result = await confluence.apiRequest(
+const result = await ctx.integrations.confluence.apiRequest(
   {
     method: "GET",
     path: `/wiki/api/v2/pages/${pageId}`,
@@ -92,7 +97,7 @@ const result = await confluence.apiRequest(
       "body-format": "storage",
     },
   },
-  { response: PageDetailSchema }
+  { response: PageDetailSchema },
 );
 
 console.log(`Page: ${result.title} (v${result.version.number})`);
@@ -102,13 +107,13 @@ console.log(`Page: ${result.title} (v${result.version.number})`);
 
 ```typescript
 // First, get current version
-const page = await confluence.apiRequest(
+const page = await ctx.integrations.confluence.apiRequest(
   { method: "GET", path: `/wiki/api/v2/pages/${pageId}` },
-  { response: PageDetailSchema }
+  { response: PageDetailSchema },
 );
 
 // Then update with incremented version
-await confluence.apiRequest(
+await ctx.integrations.confluence.apiRequest(
   {
     method: "PUT",
     path: `/wiki/api/v2/pages/${pageId}`,
@@ -126,7 +131,7 @@ await confluence.apiRequest(
       },
     },
   },
-  { response: PageSchema }
+  { response: PageSchema },
 );
 ```
 
@@ -142,7 +147,7 @@ const SearchResponseSchema = z.object({
         title: z.string(),
       }),
       excerpt: z.string().optional(),
-    })
+    }),
   ),
   totalSize: z.number(),
   _links: z.object({
@@ -150,7 +155,7 @@ const SearchResponseSchema = z.object({
   }),
 });
 
-const result = await confluence.apiRequest(
+const result = await ctx.integrations.confluence.apiRequest(
   {
     method: "GET",
     path: "/wiki/rest/api/search",
@@ -159,7 +164,7 @@ const result = await confluence.apiRequest(
       limit: 25,
     },
   },
-  { response: SearchResponseSchema }
+  { response: SearchResponseSchema },
 );
 
 result.results.forEach((r) => {
@@ -176,14 +181,14 @@ const ListPagesResponseSchema = z.object({
       id: z.string(),
       title: z.string(),
       status: z.string(),
-    })
+    }),
   ),
   _links: z.object({
     next: z.string().optional(),
   }),
 });
 
-const result = await confluence.apiRequest(
+const result = await ctx.integrations.confluence.apiRequest(
   {
     method: "GET",
     path: `/wiki/api/v2/spaces/${spaceId}/pages`,
@@ -192,14 +197,14 @@ const result = await confluence.apiRequest(
       status: "current",
     },
   },
-  { response: ListPagesResponseSchema }
+  { response: ListPagesResponseSchema },
 );
 ```
 
 ### Create a Child Page
 
 ```typescript
-const result = await confluence.apiRequest(
+const result = await ctx.integrations.confluence.apiRequest(
   {
     method: "POST",
     path: "/wiki/api/v2/pages",
@@ -214,7 +219,7 @@ const result = await confluence.apiRequest(
       },
     },
   },
-  { response: PageSchema }
+  { response: PageSchema },
 );
 ```
 
@@ -230,7 +235,7 @@ const CommentSchema = z.object({
   }),
 });
 
-const result = await confluence.apiRequest(
+const result = await ctx.integrations.confluence.apiRequest(
   {
     method: "POST",
     path: `/wiki/api/v2/pages/${pageId}/footer-comments`,
@@ -241,7 +246,7 @@ const result = await confluence.apiRequest(
       },
     },
   },
-  { response: CommentSchema }
+  { response: CommentSchema },
 );
 ```
 
@@ -256,12 +261,12 @@ const SpaceSchema = z.object({
   status: z.string(),
 });
 
-const result = await confluence.apiRequest(
+const result = await ctx.integrations.confluence.apiRequest(
   {
     method: "GET",
     path: `/wiki/api/v2/spaces/${spaceId}`,
   },
-  { response: SpaceSchema }
+  { response: SpaceSchema },
 );
 ```
 
@@ -273,20 +278,17 @@ const LabelSchema = z.object({
     z.object({
       id: z.string(),
       name: z.string(),
-    })
+    }),
   ),
 });
 
-const result = await confluence.apiRequest(
+const result = await ctx.integrations.confluence.apiRequest(
   {
     method: "POST",
     path: `/wiki/rest/api/content/${pageId}/label`,
-    body: [
-      { name: "documentation" },
-      { name: "api" },
-    ],
+    body: [{ name: "documentation" }, { name: "api" }],
   },
-  { response: LabelSchema }
+  { response: LabelSchema },
 );
 ```
 
@@ -300,7 +302,7 @@ await confluence.createPage({ ... });
 await confluence.search({ ... });
 
 // CORRECT - Use apiRequest
-await confluence.apiRequest(
+await ctx.integrations.confluence.apiRequest(
   { method: "POST", path: "/wiki/api/v2/pages", body: { ... } },
   { response: PageSchema }
 );
@@ -398,13 +400,14 @@ const cql = 'lastModified >= "2024-01-01"';
 const cql = 'label = "documentation"';
 
 // Creator filter
-const cql = 'creator = currentUser()';
+const cql = "creator = currentUser()";
 
 // Ancestor (pages under a specific parent)
-const cql = 'ancestor = 123456';
+const cql = "ancestor = 123456";
 
 // Combine conditions
-const cql = 'type=page AND space="PROJ" AND label="api" ORDER BY lastModified DESC';
+const cql =
+  'type=page AND space="PROJ" AND label="api" ORDER BY lastModified DESC';
 ```
 
 ### Pagination
@@ -417,7 +420,7 @@ async function getAllPages(confluence: ConfluenceClient, spaceId: string) {
   let cursor: string | undefined;
 
   while (true) {
-    const result = await confluence.apiRequest(
+    const result = await ctx.integrations.confluence.apiRequest(
       {
         method: "GET",
         path: `/wiki/api/v2/spaces/${spaceId}/pages`,
@@ -426,14 +429,15 @@ async function getAllPages(confluence: ConfluenceClient, spaceId: string) {
           ...(cursor && { cursor }),
         },
       },
-      { response: ListPagesResponseSchema }
+      { response: ListPagesResponseSchema },
     );
 
     allPages.push(...result.results);
 
     if (!result._links.next) break;
     // Extract cursor from next link
-    cursor = new URL(result._links.next).searchParams.get("cursor") ?? undefined;
+    cursor =
+      new URL(result._links.next).searchParams.get("cursor") ?? undefined;
   }
 
   return allPages;
@@ -446,7 +450,7 @@ async function getAllPages(confluence: ConfluenceClient, spaceId: string) {
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await confluence.apiRequest(
+  const result = await ctx.integrations.confluence.apiRequest(
     { method: "POST", path: "/wiki/api/v2/pages", body: { ... } },
     { response: PageSchema }
   );

package/src/integrations/confluence/client.ts

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

package/src/integrations/confluence/index.ts

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

package/src/integrations/confluence/types.ts

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