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

package/src/integrations/github/README.md

@@ -4,8 +4,8 @@ Manage repositories, issues, pull requests, and interact with GitHub's APIs.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                        |
+| ----------------------------- | -------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any GitHub API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Manage repositories, issues, pull requests, and interact with GitHub's APIs.
 ### Create an Issue
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, github } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_GITHUB = "a1b2c3d4-5678-90ab-cdef-github000001";
@@ -34,6 +34,9 @@ const IssueSchema = z.object({
 
 export default api({
   name: "GitHubExample",
+  integrations: {
+    repo: github(PROD_GITHUB),
+  },
   input: z.object({
     owner: z.string(),
     repo: z.string(),
@@ -45,9 +48,7 @@ export default api({
     url: z.string(),
   }),
   async run(ctx, { owner, repo, title, body }) {
-    const github = ctx.github(PROD_GITHUB);
-
-    const result = await github.apiRequest(
+    const result = await ctx.integrations.repo.apiRequest(
       {
         method: "POST",
         path: `/repos/${owner}/${repo}/issues`,
@@ -57,7 +58,7 @@ export default api({
           labels: ["bug"],
         },
       },
-      { response: IssueSchema }
+      { response: IssueSchema },
     );
 
     return { issueNumber: result.number, url: result.html_url };
@@ -70,7 +71,7 @@ export default api({
 ```typescript
 const ListIssuesSchema = z.array(IssueSchema);
 
-const issues = await github.apiRequest(
+const issues = await ctx.integrations.repo.apiRequest(
   {
     method: "GET",
     path: `/repos/${owner}/${repo}/issues`,
@@ -82,7 +83,7 @@ const issues = await github.apiRequest(
       per_page: 30,
     },
   },
-  { response: ListIssuesSchema }
+  { response: ListIssuesSchema },
 );
 
 issues.forEach((issue) => {
@@ -107,12 +108,12 @@ const RepositorySchema = z.object({
   }),
 });
 
-const repo = await github.apiRequest(
+const repo = await ctx.integrations.repo.apiRequest(
   {
     method: "GET",
     path: `/repos/${owner}/${repo}`,
   },
-  { response: RepositorySchema }
+  { response: RepositorySchema },
 );
 
 console.log(`${repo.full_name}: ${repo.stargazers_count} stars`);
@@ -132,7 +133,7 @@ const PullRequestSchema = z.object({
   mergeable: z.boolean().nullable(),
 });
 
-const pr = await github.apiRequest(
+const pr = await ctx.integrations.repo.apiRequest(
   {
     method: "POST",
     path: `/repos/${owner}/${repo}/pulls`,
@@ -143,7 +144,7 @@ const pr = await github.apiRequest(
       base: "main",
     },
   },
-  { response: PullRequestSchema }
+  { response: PullRequestSchema },
 );
 
 console.log(`Created PR #${pr.number}: ${pr.html_url}`);
@@ -158,7 +159,7 @@ const MergeResponseSchema = z.object({
   message: z.string(),
 });
 
-const result = await github.apiRequest(
+const result = await ctx.integrations.repo.apiRequest(
   {
     method: "PUT",
     path: `/repos/${owner}/${repo}/pulls/${prNumber}/merge`,
@@ -167,7 +168,7 @@ const result = await github.apiRequest(
       merge_method: "squash", // merge, squash, or rebase
     },
   },
-  { response: MergeResponseSchema }
+  { response: MergeResponseSchema },
 );
 
 if (result.merged) {
@@ -190,7 +191,7 @@ const CommitSchema = z.object({
   html_url: z.string(),
 });
 
-const commits = await github.apiRequest(
+const commits = await ctx.integrations.repo.apiRequest(
   {
     method: "GET",
     path: `/repos/${owner}/${repo}/commits`,
@@ -199,11 +200,13 @@ const commits = await github.apiRequest(
       per_page: 10,
     },
   },
-  { response: z.array(CommitSchema) }
+  { response: z.array(CommitSchema) },
 );
 
 commits.forEach((commit) => {
-  console.log(`${commit.sha.slice(0, 7)}: ${commit.commit.message.split('\n')[0]}`);
+  console.log(
+    `${commit.sha.slice(0, 7)}: ${commit.commit.message.split("\n")[0]}`,
+  );
 });
 ```
 
@@ -218,7 +221,7 @@ const FileContentSchema = z.object({
   encoding: z.string(),
 });
 
-const file = await github.apiRequest(
+const file = await ctx.integrations.repo.apiRequest(
   {
     method: "GET",
     path: `/repos/${owner}/${repo}/contents/README.md`,
@@ -226,7 +229,7 @@ const file = await github.apiRequest(
       ref: "main",
     },
   },
-  { response: FileContentSchema }
+  { response: FileContentSchema },
 );
 
 const content = Buffer.from(file.content, "base64").toString("utf-8");
@@ -245,7 +248,7 @@ const CreateFileSchema = z.object({
   }),
 });
 
-const result = await github.apiRequest(
+const result = await ctx.integrations.repo.apiRequest(
   {
     method: "PUT",
     path: `/repos/${owner}/${repo}/contents/docs/new-file.md`,
@@ -257,14 +260,14 @@ const result = await github.apiRequest(
       // sha: existingFileSha,
     },
   },
-  { response: CreateFileSchema }
+  { response: CreateFileSchema },
 );
 ```
 
 ### Trigger a Workflow
 
 ```typescript
-await github.apiRequest(
+await ctx.integrations.repo.apiRequest(
   {
     method: "POST",
     path: `/repos/${owner}/${repo}/actions/workflows/${workflowId}/dispatches`,
@@ -276,7 +279,7 @@ await github.apiRequest(
       },
     },
   },
-  { response: z.object({}).optional() } // Returns 204 No Content
+  { response: z.object({}).optional() }, // Returns 204 No Content
 );
 ```
 
@@ -290,7 +293,7 @@ await github.createIssue({ ... });
 await github.getPullRequest({ ... });
 
 // CORRECT - Use apiRequest
-await github.apiRequest(
+await ctx.integrations.repo.apiRequest(
   { method: "POST", path: `/repos/${owner}/${repo}/issues`, body: { ... } },
   { response: IssueSchema }
 );
@@ -310,9 +313,9 @@ const RateLimitSchema = z.object({
   }),
 });
 
-const limits = await github.apiRequest(
+const limits = await ctx.integrations.repo.apiRequest(
   { method: "GET", path: "/rate_limit" },
-  { response: RateLimitSchema }
+  { response: RateLimitSchema },
 );
 
 console.log(`${limits.rate.remaining}/${limits.rate.limit} requests remaining`);
@@ -335,13 +338,13 @@ async function getAllIssues(github: GitHubClient, owner: string, repo: string) {
   let page = 1;
 
   while (true) {
-    const issues = await github.apiRequest(
+    const issues = await ctx.integrations.repo.apiRequest(
       {
         method: "GET",
         path: `/repos/${owner}/${repo}/issues`,
         params: { per_page: 100, page },
       },
-      { response: z.array(IssueSchema) }
+      { response: z.array(IssueSchema) },
     );
 
     allIssues.push(...issues);
@@ -359,7 +362,7 @@ Some features require special Accept headers:
 
 ```typescript
 // For draft PRs
-const result = await github.apiRequest(
+const result = await ctx.integrations.repo.apiRequest(
   {
     method: "POST",
     path: `/repos/${owner}/${repo}/pulls`,
@@ -373,7 +376,7 @@ const result = await github.apiRequest(
       Accept: "application/vnd.github.v3+json",
     },
   },
-  { response: PullRequestSchema }
+  { response: PullRequestSchema },
 );
 ```
 
@@ -383,9 +386,12 @@ Some endpoints return 204 No Content:
 
 ```typescript
 // DELETE requests typically return empty
-await github.apiRequest(
-  { method: "DELETE", path: `/repos/${owner}/${repo}/issues/${number}/labels/${label}` },
-  { response: z.object({}).optional() }
+await ctx.integrations.repo.apiRequest(
+  {
+    method: "DELETE",
+    path: `/repos/${owner}/${repo}/issues/${number}/labels/${label}`,
+  },
+  { response: z.object({}).optional() },
 );
 ```
 
@@ -417,7 +423,7 @@ const encoded = Buffer.from("file content").toString("base64");
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await github.apiRequest(
+  const result = await ctx.integrations.repo.apiRequest(
     { method: "POST", path: `/repos/${owner}/${repo}/issues`, body: { ... } },
     { response: IssueSchema }
   );

package/src/integrations/github/client.ts

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

package/src/integrations/github/index.ts

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

package/src/integrations/github/types.ts

@@ -2,8 +2,8 @@
  * GitHub 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";
 
 /**
  * GitHub client for repository and project management.
@@ -15,7 +15,8 @@ import type { SupportsApiRequest } from '../base/index.js';
  * ```typescript
  * import { z } from 'zod';
  *
- * const github = ctx.integration('Production GitHub');
+ * // Declare in api(): integrations: { repo: github(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.repo
  *
  * // Define schemas
  * const RepositorySchema = z.object({
@@ -28,7 +29,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  * });
  *
  * // Get a repository
- * const repo = await github.apiRequest(
+ * const repo = await ctx.integrations.repo.apiRequest(
  *   {
  *     method: 'GET',
  *     path: '/repos/owner/repo',
@@ -48,7 +49,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  *   title: z.string(),
  * });
  *
- * const issue = await github.apiRequest(
+ * const issue = await ctx.integrations.repo.apiRequest(
  *   {
  *     method: 'POST',
  *     path: '/repos/owner/repo/issues',
@@ -64,6 +65,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  * );
  * ```
  */
-export interface GitHubClient extends BaseIntegrationClient, SupportsApiRequest {
+export interface GitHubClient
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
 }

package/src/integrations/googleanalytics/README.md

@@ -4,8 +4,8 @@ Run reports, get real-time data, and interact with Google Analytics 4 properties
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                                  |
+| ----------------------------- | ------------------------------------------------------------ |
 | `apiRequest(options, schema)` | Make any Google Analytics API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Run reports, get real-time data, and interact with Google Analytics 4 properties
 ### Run a Report
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, googleanalytics } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_GA4 = "a1b2c3d4-5678-90ab-cdef-ga4000000001";
@@ -22,12 +22,12 @@ const ReportRowSchema = z.object({
   dimensionValues: z.array(
     z.object({
       value: z.string(),
-    })
+    }),
   ),
   metricValues: z.array(
     z.object({
       value: z.string(),
-    })
+    }),
   ),
 });
 
@@ -36,13 +36,18 @@ const ReportResponseSchema = z.object({
   metricHeaders: z.array(z.object({ name: z.string(), type: z.string() })),
   rows: z.array(ReportRowSchema).optional(),
   rowCount: z.number().optional(),
-  metadata: z.object({
-    currencyCode: z.string().optional(),
-    timeZone: z.string().optional(),
-  }).optional(),
+  metadata: z
+    .object({
+      currencyCode: z.string().optional(),
+      timeZone: z.string().optional(),
+    })
+    .optional(),
 });
 
 export default api({
+  integrations: {
+    ga: googleanalytics(PROD_GA4),
+  },
   name: "GoogleAnalyticsExample",
   input: z.object({
     propertyId: z.string(),
@@ -54,13 +59,11 @@ export default api({
       z.object({
         pagePath: z.string(),
         views: z.number(),
-      })
+      }),
     ),
   }),
   async run(ctx, { propertyId, startDate, endDate }) {
-    const ga = ctx.googleanalytics(PROD_GA4);
-
-    const result = await ga.apiRequest(
+    const result = await ctx.integrations.ga.apiRequest(
       {
         method: "POST",
         path: `/v1beta/properties/${propertyId}:runReport`,
@@ -82,7 +85,7 @@ export default api({
           ],
         },
       },
-      { response: ReportResponseSchema }
+      { response: ReportResponseSchema },
     );
 
     return {
@@ -105,7 +108,7 @@ const RealTimeResponseSchema = z.object({
   rowCount: z.number().optional(),
 });
 
-const result = await ga.apiRequest(
+const result = await ctx.integrations.ga.apiRequest(
   {
     method: "POST",
     path: `/v1beta/properties/${propertyId}:runRealtimeReport`,
@@ -115,11 +118,13 @@ const result = await ga.apiRequest(
       limit: 10,
     },
   },
-  { response: RealTimeResponseSchema }
+  { response: RealTimeResponseSchema },
 );
 
 result.rows?.forEach((row) => {
-  console.log(`${row.dimensionValues[0].value}: ${row.metricValues[0].value} active users`);
+  console.log(
+    `${row.dimensionValues[0].value}: ${row.metricValues[0].value} active users`,
+  );
 });
 ```
 
@@ -130,7 +135,7 @@ const BatchReportResponseSchema = z.object({
   reports: z.array(ReportResponseSchema),
 });
 
-const result = await ga.apiRequest(
+const result = await ctx.integrations.ga.apiRequest(
   {
     method: "POST",
     path: `/v1beta/properties/${propertyId}:batchRunReports`,
@@ -149,7 +154,7 @@ const result = await ga.apiRequest(
       ],
     },
   },
-  { response: BatchReportResponseSchema }
+  { response: BatchReportResponseSchema },
 );
 
 // Access individual reports
@@ -160,7 +165,7 @@ const browserReport = result.reports[1];
 ### Get User Metrics with Segments
 
 ```typescript
-const result = await ga.apiRequest(
+const result = await ctx.integrations.ga.apiRequest(
   {
     method: "POST",
     path: `/v1beta/properties/${propertyId}:runReport`,
@@ -187,7 +192,7 @@ const result = await ga.apiRequest(
       orderBys: [{ dimension: { dimensionName: "date" } }],
     },
   },
-  { response: ReportResponseSchema }
+  { response: ReportResponseSchema },
 );
 ```
 
@@ -198,13 +203,15 @@ const AccountSummarySchema = z.object({
   name: z.string(),
   account: z.string(),
   displayName: z.string(),
-  propertySummaries: z.array(
-    z.object({
-      property: z.string(),
-      displayName: z.string(),
-      propertyType: z.string(),
-    })
-  ).optional(),
+  propertySummaries: z
+    .array(
+      z.object({
+        property: z.string(),
+        displayName: z.string(),
+        propertyType: z.string(),
+      }),
+    )
+    .optional(),
 });
 
 const ListAccountSummariesSchema = z.object({
@@ -212,7 +219,7 @@ const ListAccountSummariesSchema = z.object({
   nextPageToken: z.string().optional(),
 });
 
-const result = await ga.apiRequest(
+const result = await ctx.integrations.ga.apiRequest(
   {
     method: "GET",
     path: "/v1beta/accountSummaries",
@@ -220,7 +227,7 @@ const result = await ga.apiRequest(
       pageSize: 50,
     },
   },
-  { response: ListAccountSummariesSchema }
+  { response: ListAccountSummariesSchema },
 );
 
 result.accountSummaries?.forEach((account) => {
@@ -241,7 +248,7 @@ await ga.runReport({ ... });
 await ga.getRealtimeData();
 
 // CORRECT - Use apiRequest
-await ga.apiRequest(
+await ctx.integrations.ga.apiRequest(
   { method: "POST", path: `/v1beta/properties/${propertyId}:runReport`, body: { ... } },
   { response: ReportResponseSchema }
 );
@@ -358,14 +365,18 @@ Large reports may be sampled:
 ```typescript
 const ReportResponseSchema = z.object({
   rows: z.array(ReportRowSchema).optional(),
-  metadata: z.object({
-    samplingMetadatas: z.array(
-      z.object({
-        samplesReadCount: z.string(),
-        samplingSpaceSize: z.string(),
-      })
-    ).optional(),
-  }).optional(),
+  metadata: z
+    .object({
+      samplingMetadatas: z
+        .array(
+          z.object({
+            samplesReadCount: z.string(),
+            samplingSpaceSize: z.string(),
+          }),
+        )
+        .optional(),
+    })
+    .optional(),
 });
 
 // Check if data was sampled
@@ -380,7 +391,7 @@ if (result.metadata?.samplingMetadatas) {
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await ga.apiRequest(
+  const result = await ctx.integrations.ga.apiRequest(
     { method: "POST", path: `/v1beta/properties/${propertyId}:runReport`, body: { ... } },
     { response: ReportResponseSchema }
   );

package/src/integrations/googleanalytics/client.ts

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

package/src/integrations/googleanalytics/index.ts

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

package/src/integrations/googleanalytics/types.ts

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