@superblocksteam/sdk-api 0.0.5 → 0.0.7

package/src/integrations/fireworks/README.md

@@ -10,7 +10,9 @@ Interact with Fireworks AI's fast inference platform for LLM chat completions an
 
 ## Usage
 
-### Chat Completion
+### Step 1: List Available Models
+
+Model availability varies by account. Before making requests, validate which models are deployed on your account:
 
 ```typescript
 import { api, z, fireworks } from "@superblocksteam/sdk-api";
@@ -18,6 +20,30 @@ import { api, z, fireworks } from "@superblocksteam/sdk-api";
 // Integration ID from the integrations panel
 const PROD_FIREWORKS = "a1b2c3d4-5678-90ab-cdef-fireworks001";
 
+const ModelsResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      id: z.string(),
+      object: z.string(),
+    }),
+  ),
+});
+
+const models = await ctx.integrations.fireworks.apiRequest(
+  {
+    method: "GET",
+    path: "/v1/models",
+  },
+  { response: ModelsResponseSchema },
+);
+
+// Use a model ID from the response in subsequent requests
+const availableModelId = models.data[0]?.id;
+```
+
+### Chat Completion
+
+```typescript
 const ChatCompletionResponseSchema = z.object({
   id: z.string(),
   object: z.string(),
@@ -55,7 +81,7 @@ export default api({
     const result = await ctx.integrations.fireworks.apiRequest(
       {
         method: "POST",
-        path: "/inference/v1/chat/completions",
+        path: "/v1/chat/completions",
         body: {
           model: "accounts/fireworks/models/llama-v3p1-70b-instruct",
           messages: [{ role: "user", content: prompt }],
@@ -76,7 +102,7 @@ export default api({
 const llama70b = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/llama-v3p1-70b-instruct",
       messages: [{ role: "user", content: "Complex task..." }],
@@ -89,7 +115,7 @@ const llama70b = await ctx.integrations.fireworks.apiRequest(
 const llama8b = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/llama-v3p1-8b-instruct",
       messages: [{ role: "user", content: "Simple task..." }],
@@ -102,7 +128,7 @@ const llama8b = await ctx.integrations.fireworks.apiRequest(
 const mixtral = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/mixtral-8x7b-instruct",
       messages: [{ role: "user", content: "..." }],
@@ -115,7 +141,7 @@ const mixtral = await ctx.integrations.fireworks.apiRequest(
 const qwen = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/qwen2p5-coder-32b-instruct",
       messages: [{ role: "user", content: "Write code..." }],
@@ -147,7 +173,7 @@ const EmbeddingsResponseSchema = z.object({
 const result = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/embeddings",
+    path: "/v1/embeddings",
     body: {
       model: "accounts/fireworks/models/nomic-embed-text-v1.5",
       input: ["Hello world", "How are you?"],
@@ -188,7 +214,7 @@ const FunctionCallResponseSchema = z.object({
 const result = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/firefunction-v2",
       messages: [{ role: "user", content: "What's the weather in Paris?" }],
@@ -220,7 +246,7 @@ const result = await ctx.integrations.fireworks.apiRequest(
 const result = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/llama-v3p1-70b-instruct",
       messages: [{ role: "user", content: "List 3 colors in JSON format" }],
@@ -239,7 +265,7 @@ const data = JSON.parse(result.choices[0]?.message.content ?? "{}");
 const result = await ctx.integrations.fireworks.apiRequest(
   {
     method: "POST",
-    path: "/inference/v1/chat/completions",
+    path: "/v1/chat/completions",
     body: {
       model: "accounts/fireworks/models/llama-v3p1-70b-instruct",
       messages: [{ role: "user", content: "Generate user data" }],
@@ -276,7 +302,7 @@ await fireworks.complete({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.fireworks.apiRequest(
-  { method: "POST", path: "/inference/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
 ```
@@ -301,18 +327,18 @@ const body = {
 
 ### API Path
 
-Fireworks uses `/inference/v1/` prefix:
+The integration's base URL already includes `https://api.fireworks.ai/inference`, so paths should start with `/v1/`:
 
 ```typescript
-// WRONG - Missing inference prefix
+// WRONG - Duplicates the /inference prefix (base URL already includes it)
 await ctx.integrations.fireworks.apiRequest(
-  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/inference/v1/chat/completions", body: { ... } },
   { response: schema }
 );
 
-// CORRECT - Include inference prefix
+// CORRECT - Start with /v1/ (the integration prepends /inference automatically)
 await ctx.integrations.fireworks.apiRequest(
-  { method: "POST", path: "/inference/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
   { response: schema }
 );
 ```
@@ -347,7 +373,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.fireworks.apiRequest(
-    { method: "POST", path: "/inference/v1/chat/completions", body: { ... } },
+    { method: "POST", path: "/v1/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   );
 } catch (error) {

package/src/integrations/fireworks/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "fireworks",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/front/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "front",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/gcs/client.ts

@@ -4,13 +4,15 @@
  * Uses the native GCS plugin type from @superblocksteam/types.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as GCSPlugin } from "@superblocksteam/types/dist/src/plugins/gcs/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type {
   GCSClient,
   GCSAction,

package/src/integrations/gcs/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "gcs",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/gcs/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 

package/src/integrations/gemini/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "gemini",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/github/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "github",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/googleanalytics/README.md

@@ -13,7 +13,7 @@ Run reports, get real-time data, and interact with Google Analytics 4 properties
 ### Run a Report
 
 ```typescript
-import { api, z, googleanalytics } 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";
@@ -46,7 +46,7 @@ const ReportResponseSchema = z.object({
 
 export default api({
   integrations: {
-    ga: googleanalytics(PROD_GA4),
+    ga: googleAnalytics(PROD_GA4),
   },
   name: "GoogleAnalyticsExample",
   input: z.object({

package/src/integrations/googleanalytics/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "googleanalytics",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/googledrive/README.md

@@ -13,7 +13,7 @@ Upload, download, and manage files in Google Drive.
 ### List Files
 
 ```typescript
-import { api, z, googledrive } from "@superblocksteam/sdk-api";
+import { api, z, googleDrive } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_DRIVE = "a1b2c3d4-5678-90ab-cdef-gdrive000001";
@@ -45,7 +45,7 @@ const ListFilesResponseSchema = z.object({
 
 export default api({
   integrations: {
-    drive: googledrive(PROD_DRIVE),
+    drive: googleDrive(PROD_DRIVE),
   },
   name: "GoogleDriveExample",
   input: z.object({
@@ -71,7 +71,7 @@ export default api({
     const result = await ctx.integrations.drive.apiRequest(
       {
         method: "GET",
-        path: "/drive/v3/files",
+        path: "/files",
         params: {
           q: query,
           pageSize: pageSize,
@@ -99,7 +99,7 @@ export default api({
 const file = await ctx.integrations.drive.apiRequest(
   {
     method: "GET",
-    path: `/drive/v3/files/${fileId}`,
+    path: `/files/${fileId}`,
     params: {
       fields:
         "id,name,mimeType,size,createdTime,modifiedTime,parents,webViewLink,webContentLink,owners",
@@ -120,7 +120,7 @@ const DownloadResponseSchema = z.string(); // Raw content
 const content = await ctx.integrations.drive.apiRequest(
   {
     method: "GET",
-    path: `/drive/v3/files/${fileId}`,
+    path: `/files/${fileId}`,
     params: {
       alt: "media",
     },
@@ -134,7 +134,7 @@ const ExportResponseSchema = z.string();
 const docContent = await ctx.integrations.drive.apiRequest(
   {
     method: "GET",
-    path: `/drive/v3/files/${fileId}/export`,
+    path: `/files/${fileId}/export`,
     params: {
       mimeType: "text/plain", // or application/pdf, text/html, etc.
     },
@@ -149,7 +149,7 @@ const docContent = await ctx.integrations.drive.apiRequest(
 const folder = await ctx.integrations.drive.apiRequest(
   {
     method: "POST",
-    path: "/drive/v3/files",
+    path: "/files",
     body: {
       name: "New Folder",
       mimeType: "application/vnd.google-apps.folder",
@@ -194,7 +194,7 @@ const uploadedFile = await ctx.integrations.drive.apiRequest(
 const updatedFile = await ctx.integrations.drive.apiRequest(
   {
     method: "PATCH",
-    path: `/drive/v3/files/${fileId}`,
+    path: `/files/${fileId}`,
     body: {
       name: "Renamed File.txt",
       description: "Updated description",
@@ -210,7 +210,7 @@ const updatedFile = await ctx.integrations.drive.apiRequest(
 const movedFile = await ctx.integrations.drive.apiRequest(
   {
     method: "PATCH",
-    path: `/drive/v3/files/${fileId}`,
+    path: `/files/${fileId}`,
     params: {
       addParents: newFolderId,
       removeParents: oldFolderId,
@@ -226,7 +226,7 @@ const movedFile = await ctx.integrations.drive.apiRequest(
 const result = await ctx.integrations.drive.apiRequest(
   {
     method: "GET",
-    path: "/drive/v3/files",
+    path: "/files",
     params: {
       q: "name contains 'report' and mimeType = 'application/pdf' and trashed = false",
       pageSize: 25,
@@ -250,7 +250,7 @@ const PermissionSchema = z.object({
 const permission = await ctx.integrations.drive.apiRequest(
   {
     method: "POST",
-    path: `/drive/v3/files/${fileId}/permissions`,
+    path: `/files/${fileId}/permissions`,
     body: {
       type: "user", // user, group, domain, anyone
       role: "reader", // reader, writer, commenter, owner
@@ -271,7 +271,7 @@ const permission = await ctx.integrations.drive.apiRequest(
 await ctx.integrations.drive.apiRequest(
   {
     method: "PATCH",
-    path: `/drive/v3/files/${fileId}`,
+    path: `/files/${fileId}`,
     body: {
       trashed: true,
     },
@@ -283,7 +283,7 @@ await ctx.integrations.drive.apiRequest(
 await ctx.integrations.drive.apiRequest(
   {
     method: "DELETE",
-    path: `/drive/v3/files/${fileId}`,
+    path: `/files/${fileId}`,
   },
   { response: z.void() },
 );
@@ -304,7 +304,7 @@ await drive.uploadFile({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.drive.apiRequest(
-  { method: "GET", path: "/drive/v3/files", params: { ... } },
+  { method: "GET", path: "/files", params: { ... } },
   { response: ListFilesResponseSchema }
 );
 ```
@@ -316,7 +316,7 @@ By default, only basic fields are returned. Use the `fields` parameter:
 ```typescript
 // WRONG - Missing fields, gets minimal data
 const file = await ctx.integrations.drive.apiRequest(
-  { method: "GET", path: `/drive/v3/files/${fileId}` },
+  { method: "GET", path: `/files/${fileId}` },
   { response: FileSchema },
 );
 // file.size, file.owners, etc. will be undefined
@@ -325,7 +325,7 @@ const file = await ctx.integrations.drive.apiRequest(
 const file = await ctx.integrations.drive.apiRequest(
   {
     method: "GET",
-    path: `/drive/v3/files/${fileId}`,
+    path: `/files/${fileId}`,
     params: {
       fields: "id,name,mimeType,size,createdTime,modifiedTime,owners",
     },
@@ -367,10 +367,10 @@ Google Docs, Sheets, etc. must be exported, not downloaded directly:
 
 ```typescript
 // Regular files - use alt=media
-const path = `/drive/v3/files/${fileId}?alt=media`;
+const path = `/files/${fileId}?alt=media`;
 
 // Google Docs - use export endpoint
-const path = `/drive/v3/files/${fileId}/export?mimeType=text/plain`;
+const path = `/files/${fileId}/export?mimeType=text/plain`;
 
 // Export formats for Google Docs
 // Documents: text/plain, text/html, application/pdf, application/vnd.oasis.opendocument.text
@@ -396,14 +396,17 @@ const sizeMB = sizeBytes / (1024 * 1024);
 
 ### Upload Path vs Regular Path
 
-File uploads use a different base path:
+The base URL already includes `/drive/v3`, so regular API paths omit this prefix. However, uploads use a different URL root (`/upload/drive/v3/...` instead of `/drive/v3/...`) and require the full path:
 
 ```typescript
-// Regular API calls
-const path = "/drive/v3/files";
+// Regular API calls (base URL already has /drive/v3)
+const path = "/files";
 
-// Upload calls
+// Upload calls use a different URL root — include the full path
 const path = "/upload/drive/v3/files";
+
+// WRONG - Duplicates base URL prefix for regular calls
+const path = "/drive/v3/files";
 ```
 
 ### Folder MIME Type
@@ -436,7 +439,7 @@ async function getAllFiles(drive: GoogleDriveClient, folderId: string) {
     const result = await ctx.integrations.drive.apiRequest(
       {
         method: "GET",
-        path: "/drive/v3/files",
+        path: "/files",
         params: {
           q: `'${folderId}' in parents and trashed = false`,
           pageSize: 100,
@@ -463,7 +466,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.drive.apiRequest(
-    { method: "GET", path: "/drive/v3/files", params: { ... } },
+    { method: "GET", path: "/files", params: { ... } },
     { response: ListFilesResponseSchema }
   );
 } catch (error) {

package/src/integrations/googledrive/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "googledrive",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/googledrive/types.ts

@@ -24,7 +24,7 @@ import type { SupportsApiRequest } from "../base/index.js";
  * const result = await googleDrive.apiRequest(
  *   {
  *     method: 'GET',
- *     path: '/drive/v3/files',
+ *     path: '/files',
  *   },
  *   { response: ResponseSchema }
  * );

package/src/integrations/graphql/README.md

@@ -112,7 +112,7 @@ const CreateUserResponseSchema = z.object({
   }),
 });
 
-const result = await graphql.mutation(
+const result = await ctx.integrations.graphql.mutation(
   `mutation CreateUser($input: CreateUserInput!) {
     createUser(input: $input) {
       id
@@ -150,7 +150,7 @@ const UpdateOrderResponseSchema = z.object({
   }),
 });
 
-const result = await graphql.mutation(
+const result = await ctx.integrations.graphql.mutation(
   `mutation UpdateOrder($id: ID!, $input: UpdateOrderInput!) {
     updateOrder(id: $id, input: $input) {
       id