@superblocksteam/sdk-api 0.0.6 → 0.0.8

package/src/integrations/circleci/README.md

@@ -51,7 +51,7 @@ export default api({
     const result = await ctx.integrations.circleci.apiRequest(
       {
         method: "POST",
-        path: `/api/v2/project/${projectSlug}/pipeline`,
+        path: `/project/${projectSlug}/pipeline`,
         body: {
           branch: branch,
           parameters: {
@@ -73,7 +73,7 @@ export default api({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/pipeline/${pipelineId}`,
+    path: `/pipeline/${pipelineId}`,
   },
   { response: PipelineSchema },
 );
@@ -102,7 +102,7 @@ const ListWorkflowsResponseSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/pipeline/${pipelineId}/workflow`,
+    path: `/pipeline/${pipelineId}/workflow`,
   },
   { response: ListWorkflowsResponseSchema },
 );
@@ -133,7 +133,7 @@ const ListJobsResponseSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/workflow/${workflowId}/job`,
+    path: `/workflow/${workflowId}/job`,
   },
   { response: ListJobsResponseSchema },
 );
@@ -162,7 +162,7 @@ const JobDetailSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/project/${projectSlug}/job/${jobNumber}`,
+    path: `/project/${projectSlug}/job/${jobNumber}`,
   },
   { response: JobDetailSchema },
 );
@@ -178,7 +178,7 @@ const RetryResponseSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "POST",
-    path: `/api/v2/workflow/${workflowId}/rerun`,
+    path: `/workflow/${workflowId}/rerun`,
     body: {
       from_failed: true, // Only rerun failed jobs
     },
@@ -199,7 +199,7 @@ const CancelResponseSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "POST",
-    path: `/api/v2/workflow/${workflowId}/cancel`,
+    path: `/workflow/${workflowId}/cancel`,
   },
   { response: CancelResponseSchema },
 );
@@ -216,7 +216,7 @@ const ListPipelinesResponseSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/project/${projectSlug}/pipeline`,
+    path: `/project/${projectSlug}/pipeline`,
     params: {
       branch: "main",
       "page-token": undefined, // For pagination
@@ -247,7 +247,7 @@ const ProjectSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/project/${projectSlug}`,
+    path: `/project/${projectSlug}`,
   },
   { response: ProjectSchema },
 );
@@ -270,7 +270,7 @@ const ListArtifactsResponseSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/project/${projectSlug}/${jobNumber}/artifacts`,
+    path: `/project/${projectSlug}/${jobNumber}/artifacts`,
   },
   { response: ListArtifactsResponseSchema },
 );
@@ -295,7 +295,7 @@ await circleci.getWorkflow({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.circleci.apiRequest(
-  { method: "POST", path: `/api/v2/project/${slug}/pipeline`, body: { ... } },
+  { method: "POST", path: `/project/${slug}/pipeline`, body: { ... } },
   { response: PipelineSchema }
 );
 ```
@@ -317,13 +317,13 @@ const slug = "gl/my-group/my-repo";
 
 ### API Version in Path
 
-Always include `/api/v2/`:
+The base URL already includes `/api/v2`, so do not repeat it in paths:
 
 ```typescript
-// WRONG
+// CORRECT - No version prefix (base URL already has /api/v2)
 const path = `/project/${slug}/pipeline`;
 
-// CORRECT
+// WRONG - Duplicates version from base URL
 const path = `/api/v2/project/${slug}/pipeline`;
 ```
 
@@ -406,7 +406,7 @@ async function getAllPipelines(circleci: CircleCIClient, projectSlug: string) {
     const result = await ctx.integrations.circleci.apiRequest(
       {
         method: "GET",
-        path: `/api/v2/project/${projectSlug}/pipeline`,
+        path: `/project/${projectSlug}/pipeline`,
         params: pageToken ? { "page-token": pageToken } : {},
       },
       { response: ListPipelinesResponseSchema },
@@ -429,7 +429,7 @@ When rerunning workflows:
 await ctx.integrations.circleci.apiRequest(
   {
     method: "POST",
-    path: `/api/v2/workflow/${workflowId}/rerun`,
+    path: `/workflow/${workflowId}/rerun`,
     body: {
       from_failed: false, // Rerun everything
     },
@@ -441,7 +441,7 @@ await ctx.integrations.circleci.apiRequest(
 await ctx.integrations.circleci.apiRequest(
   {
     method: "POST",
-    path: `/api/v2/workflow/${workflowId}/rerun`,
+    path: `/workflow/${workflowId}/rerun`,
     body: {
       from_failed: true, // Only failed jobs
     },
@@ -457,7 +457,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.circleci.apiRequest(
-    { method: "POST", path: `/api/v2/project/${slug}/pipeline`, body: { ... } },
+    { method: "POST", path: `/project/${slug}/pipeline`, body: { ... } },
     { response: PipelineSchema }
   );
 } catch (error) {

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

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

package/src/integrations/cockroachdb/client.ts

@@ -5,13 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as CockroachDBPlugin } from "@superblocksteam/types/dist/src/plugins/cockroachdb/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { CockroachDBClient } from "./types.js";
 

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

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

package/src/integrations/cockroachdb/types.ts

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

package/src/integrations/cohere/README.md

@@ -52,7 +52,7 @@ export default api({
     const result = await ctx.integrations.cohere.apiRequest(
       {
         method: "POST",
-        path: "/v1/chat",
+        path: "/chat",
         body: {
           model: "command-r-plus",
           message: message,
@@ -81,7 +81,7 @@ const EmbedResponseSchema = z.object({
 const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/embed",
+    path: "/embed",
     body: {
       model: "embed-english-v3.0",
       texts: ["Hello world", "How are you?"],
@@ -115,7 +115,7 @@ const ClassifyResponseSchema = z.object({
 const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/classify",
+    path: "/classify",
     body: {
       model: "embed-english-v3.0",
       inputs: ["This product is amazing!", "Terrible experience, never again"],
@@ -159,7 +159,7 @@ const documents = [
 const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/rerank",
+    path: "/rerank",
     body: {
       model: "rerank-english-v3.0",
       query: "What is the capital of the United States?",
@@ -193,7 +193,7 @@ const GenerateResponseSchema = z.object({
 const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/generate",
+    path: "/generate",
     body: {
       model: "command",
       prompt: "Write a creative story about",
@@ -220,7 +220,7 @@ await cohere.embed({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.cohere.apiRequest(
-  { method: "POST", path: "/v1/chat", body: { ... } },
+  { method: "POST", path: "/chat", body: { ... } },
   { response: ChatResponseSchema }
 );
 ```
@@ -234,7 +234,7 @@ When creating embeddings, specify the correct `input_type`:
 const docEmbeddings = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/embed",
+    path: "/embed",
     body: {
       texts: documents,
       input_type: "search_document", // For documents
@@ -247,7 +247,7 @@ const docEmbeddings = await ctx.integrations.cohere.apiRequest(
 const queryEmbedding = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/embed",
+    path: "/embed",
     body: {
       texts: [query],
       input_type: "search_query", // For queries
@@ -266,7 +266,7 @@ The classify endpoint requires labeled examples:
 const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/classify",
+    path: "/classify",
     body: {
       inputs: ["Great product!"],
       // Missing examples!
@@ -279,7 +279,7 @@ const result = await ctx.integrations.cohere.apiRequest(
 const result = await ctx.integrations.cohere.apiRequest(
   {
     method: "POST",
-    path: "/v1/classify",
+    path: "/classify",
     body: {
       inputs: ["Great product!"],
       examples: [
@@ -299,7 +299,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.cohere.apiRequest(
-    { method: "POST", path: "/v1/chat", body: { ... } },
+    { method: "POST", path: "/chat", body: { ... } },
     { response: ChatResponseSchema }
   );
 } catch (error) {

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

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

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

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

package/src/integrations/cosmosdb/client.test.ts

@@ -7,8 +7,9 @@
 
 import { describe, it, expect, vi } from "vitest";
 import { z } from "zod";
-import { CosmosDBClientImpl } from "./client.js";
+
 import type { IntegrationConfig } from "../types.js";
+import { CosmosDBClientImpl } from "./client.js";
 
 /** Minimal integration config for testing. */
 const TEST_CONFIG: IntegrationConfig = {

package/src/integrations/cosmosdb/client.ts

@@ -6,13 +6,15 @@
  * upsert, delete) against CosmosDB containers.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as CosmosDBPlugin } from "@superblocksteam/types/dist/src/plugins/cosmosdb/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 { CosmosDBClient, CosmosDBQueryOptions } from "./types.js";
 
 /**

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

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

package/src/integrations/cosmosdb/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/databricks/README.md

@@ -38,7 +38,7 @@ export default api({
   }),
   async run(ctx, { date }) {
     const data = await ctx.integrations.databricks.query(
-      "SELECT id, value, timestamp FROM data WHERE date = $1",
+      "SELECT id, value, timestamp FROM data WHERE date = :PARAM_1",
       DataSchema,
       [date],
     );
@@ -48,25 +48,29 @@ export default api({
 });
 ```
 
+The SDK accepts Databricks parameters as a positional `params` array, but the
+SQL text should use `:PARAM_1`, `:PARAM_2`, and so on. The first array value
+binds to `:PARAM_1`, the second binds to `:PARAM_2`, and so forth.
+
 ### Executing INSERT, UPDATE, DELETE Statements
 
 ```typescript
 // INSERT
 await ctx.integrations.databricks.execute(
-  "INSERT INTO metrics (name, value) VALUES ($1, $2)",
+  "INSERT INTO metrics (name, value) VALUES (:PARAM_1, :PARAM_2)",
   ["cpu_usage", "75.5"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.databricks.execute(
-  "UPDATE metrics SET value = $1 WHERE name = $2",
+  "UPDATE metrics SET value = :PARAM_1 WHERE name = :PARAM_2",
   ["80.0", "cpu_usage"],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);
 
 // DELETE
 const deleteResult = await ctx.integrations.databricks.execute(
-  "DELETE FROM metrics WHERE timestamp < $1",
+  "DELETE FROM metrics WHERE timestamp < :PARAM_1",
   ["2024-01-01"],
 );
 console.log(`Deleted ${deleteResult.rowCount} rows`);
@@ -100,6 +104,27 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Parameter Placeholders Must Match the SDK Contract
+
+Pass parameter values as an array, but write the SQL with `:PARAM_n`
+placeholders:
+
+```typescript
+// WRONG - Positional question marks are not the placeholder syntax this SDK emits
+await ctx.integrations.databricks.query(
+  "SELECT * FROM data WHERE date = ?",
+  DataSchema,
+  ["2024-01-01"],
+);
+
+// CORRECT - Use Databricks placeholders with positional params
+await ctx.integrations.databricks.query(
+  "SELECT * FROM data WHERE date = :PARAM_1",
+  DataSchema,
+  ["2024-01-01"],
+);
+```
+
 ### BIGINT/LONG Values Returned as Strings
 
 ```typescript

package/src/integrations/databricks/client.ts

@@ -5,13 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as DatabricksPlugin } from "@superblocksteam/types/dist/src/plugins/databricks/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { DatabricksClient } from "./types.js";
 

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

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

package/src/integrations/databricks/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 
@@ -24,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const data = await databricks.query(
- *   'SELECT * FROM data WHERE date = $1',
+ *   'SELECT * FROM data WHERE date = :PARAM_1',
  *   DataSchema,
  *   ['2024-01-01']
  * );
@@ -34,9 +35,9 @@ export interface DatabricksClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use :PARAM_1, :PARAM_2, etc. for parameters)
    * @param schema - Zod schema to validate the query results
-   * @param params - Optional query parameters
+   * @param params - Optional query parameters, bound positionally so the first value maps to :PARAM_1
    * @returns Promise resolving to validated query results
    *
    * @throws {QueryValidationError} If results don't match schema

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

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

package/src/integrations/declarations.test.ts

@@ -1,4 +1,5 @@
 import { describe, expectTypeOf, it } from "vitest";
+
 import {
   mysql,
   openai,