@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/cockroachdb/client.ts

@@ -0,0 +1,135 @@
+/**
+ * CockroachDB integration client implementation.
+ *
+ * Executes CockroachDB queries through the Superblocks orchestrator with
+ * runtime validation using Zod schemas.
+ */
+
+import type { z } from 'zod';
+import type { PartialMessage } from '@bufbuild/protobuf';
+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 } from '../registry.js';
+import { QueryValidationError } from '../../errors.js';
+import { IntegrationError } from '../../runtime/errors.js';
+import { describeType } from '../utils.js';
+import type { CockroachDBClient } from './types.js';
+
+/**
+ * Internal implementation of the CockroachDB client.
+ */
+export class CockroachDBClientImpl
+  implements CockroachDBClient, IntegrationClientImpl
+{
+  readonly config: IntegrationConfig;
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  get name(): string {
+    return this.config.name;
+  }
+
+  get pluginId(): string {
+    return this.config.pluginId;
+  }
+
+  /**
+   * Builds a CockroachDB request object from SQL and parameters.
+   *
+   * When params are provided, the SQL body is sent with placeholders intact
+   * (e.g. $1, $2) and the parameter values are passed via the `parameters`
+   * field as a JSON-stringified array for server-side binding.
+   *
+   * @param sql - The SQL query with optional $1, $2 placeholders
+   * @param params - Optional array of parameter values for server-side binding
+   * @returns The plugin request object
+   */
+  private buildRequest(
+    sql: string,
+    params?: unknown[],
+  ): PartialMessage<CockroachDBPlugin> {
+    const hasParams = params && params.length > 0;
+
+    return {
+      body: sql,
+      parameters: hasParams ? JSON.stringify(params) : undefined,
+    };
+  }
+
+  async query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+  ): Promise<T[]> {
+    const request = this.buildRequest(sql, params);
+
+    try {
+      const result = await this.executeQuery(request);
+
+      if (!Array.isArray(result)) {
+        throw new IntegrationError(
+          this.config.name,
+          'query',
+          `Expected array result from CockroachDB query, got: ${describeType(result)}`,
+        );
+      }
+
+      const validated: T[] = [];
+      for (let i = 0; i < result.length; i++) {
+        const row = result[i];
+        const parseResult = schema.safeParse(row);
+
+        if (!parseResult.success) {
+          throw new QueryValidationError(
+            `Row ${i} validation failed: ${parseResult.error.message}`,
+            {
+              rowIndex: i,
+              errors: parseResult.error.errors.map((err) => ({
+                path: err.path,
+                message: err.message,
+              })),
+              row,
+            },
+          );
+        }
+
+        validated.push(parseResult.data);
+      }
+
+      return validated;
+    } catch (error) {
+      if (
+        error instanceof QueryValidationError ||
+        error instanceof IntegrationError
+      ) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, 'query', error);
+    }
+  }
+
+  async execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }> {
+    const request = this.buildRequest(sql, params);
+
+    try {
+      const result = await this.executeQuery(request);
+
+      if (
+        typeof result === 'object' &&
+        result !== null &&
+        'rowCount' in result
+      ) {
+        return { rowCount: Number(result.rowCount) || 0 };
+      }
+
+      return { rowCount: 0 };
+    } catch (error) {
+      throw new IntegrationError(this.config.name, 'execute', error);
+    }
+  }
+}

package/src/integrations/cockroachdb/index.ts

@@ -0,0 +1,8 @@
+/**
+ * CockroachDB integration client.
+ *
+ * @module
+ */
+
+export type { CockroachDBClient } from './types.js';
+export { CockroachDBClientImpl } from './client.js';

package/src/integrations/cockroachdb/types.ts

@@ -0,0 +1,53 @@
+/**
+ * CockroachDB integration client types.
+ *
+ * Provides typed methods for executing CockroachDB queries with runtime validation.
+ */
+
+import type { z } from 'zod';
+import type { BaseIntegrationClient } from '../../types.js';
+
+/**
+ * Client for executing CockroachDB queries with type-safe validation.
+ *
+ * @example
+ * ```typescript
+ * const cockroachdb = ctx.cockroachdb('Production CockroachDB');
+ *
+ * // Query with validation
+ * const UserSchema = z.object({
+ *   id: z.string(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ * });
+ *
+ * const users = await cockroachdb.query(
+ *   'SELECT * FROM users WHERE status = $1',
+ *   UserSchema,
+ *   ['active']
+ * );
+ * ```
+ */
+export interface CockroachDBClient 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 schema - Zod schema to validate the query results
+   * @param params - Optional query parameters
+   * @returns Promise resolving to validated query results
+   *
+   * @throws {QueryValidationError} If results don't match schema
+   * @throws {IntegrationError} If query execution fails
+   */
+  query<T>(sql: string, schema: z.ZodSchema<T>, params?: unknown[]): Promise<T[]>;
+
+  /**
+   * Execute a SQL statement (INSERT, UPDATE, DELETE) without output validation.
+   *
+   * @param sql - The SQL statement to execute
+   * @param params - Optional parameters for prepared statements
+   * @returns Promise resolving to execution result with row count
+   */
+  execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }>;
+}

package/src/integrations/cohere/README.md

@@ -0,0 +1,313 @@
+# Cohere Client
+
+Interact with Cohere's APIs for text generation, embeddings, classification, and semantic search.
+
+## Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `apiRequest(options, schema)` | Make any Cohere API request with schema validation |
+
+## Usage
+
+### Chat Completion
+
+```typescript
+import { api, z } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_COHERE = "a1b2c3d4-5678-90ab-cdef-cohere000001";
+
+const ChatResponseSchema = z.object({
+  text: z.string(),
+  generation_id: z.string(),
+  chat_history: z.array(
+    z.object({
+      role: z.enum(["USER", "CHATBOT", "SYSTEM"]),
+      message: z.string(),
+    })
+  ),
+  finish_reason: z.string(),
+  meta: z.object({
+    api_version: z.object({ version: z.string() }),
+    billed_units: z.object({
+      input_tokens: z.number(),
+      output_tokens: z.number(),
+    }),
+  }),
+});
+
+export default api({
+  name: "CohereExample",
+  input: z.object({
+    message: z.string(),
+  }),
+  output: z.object({
+    response: z.string(),
+  }),
+  async run(ctx, { message }) {
+    const cohere = ctx.cohere(PROD_COHERE);
+
+    const result = await cohere.apiRequest(
+      {
+        method: "POST",
+        path: "/v1/chat",
+        body: {
+          model: "command-r-plus",
+          message: message,
+        },
+      },
+      { response: ChatResponseSchema }
+    );
+
+    return { response: result.text };
+  },
+});
+```
+
+### Generate Embeddings
+
+```typescript
+const EmbedResponseSchema = z.object({
+  id: z.string(),
+  embeddings: z.array(z.array(z.number())),
+  texts: z.array(z.string()),
+  meta: z.object({
+    api_version: z.object({ version: z.string() }),
+  }),
+});
+
+const result = await cohere.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/embed",
+    body: {
+      model: "embed-english-v3.0",
+      texts: ["Hello world", "How are you?"],
+      input_type: "search_document",
+    },
+  },
+  { response: EmbedResponseSchema }
+);
+
+result.embeddings.forEach((embedding, i) => {
+  console.log(`Text ${i}: ${embedding.length} dimensions`);
+});
+```
+
+### Text Classification
+
+```typescript
+const ClassifyResponseSchema = z.object({
+  id: z.string(),
+  classifications: z.array(
+    z.object({
+      id: z.string(),
+      input: z.string(),
+      prediction: z.string(),
+      confidence: z.number(),
+      labels: z.record(z.object({ confidence: z.number() })),
+    })
+  ),
+});
+
+const result = await cohere.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/classify",
+    body: {
+      model: "embed-english-v3.0",
+      inputs: ["This product is amazing!", "Terrible experience, never again"],
+      examples: [
+        { text: "I love this!", label: "positive" },
+        { text: "Great product", label: "positive" },
+        { text: "This is awful", label: "negative" },
+        { text: "Worst purchase ever", label: "negative" },
+      ],
+    },
+  },
+  { response: ClassifyResponseSchema }
+);
+
+result.classifications.forEach((c) => {
+  console.log(`"${c.input}" -> ${c.prediction} (${c.confidence})`);
+});
+```
+
+### Rerank Documents
+
+```typescript
+const RerankResponseSchema = z.object({
+  id: z.string(),
+  results: z.array(
+    z.object({
+      index: z.number(),
+      relevance_score: z.number(),
+      document: z.object({ text: z.string() }).optional(),
+    })
+  ),
+});
+
+const documents = [
+  "Carson City is the capital of Nevada.",
+  "The Commonwealth of the Northern Mariana Islands is a US territory.",
+  "Washington, D.C. is the capital of the United States.",
+  "Capital punishment has existed since ancient times.",
+];
+
+const result = await cohere.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/rerank",
+    body: {
+      model: "rerank-english-v3.0",
+      query: "What is the capital of the United States?",
+      documents: documents,
+      top_n: 3,
+      return_documents: true,
+    },
+  },
+  { response: RerankResponseSchema }
+);
+
+result.results.forEach((r) => {
+  console.log(`Score: ${r.relevance_score}, Doc: ${r.document?.text}`);
+});
+```
+
+### Generate Text (Legacy)
+
+```typescript
+const GenerateResponseSchema = z.object({
+  id: z.string(),
+  generations: z.array(
+    z.object({
+      id: z.string(),
+      text: z.string(),
+      finish_reason: z.string(),
+    })
+  ),
+});
+
+const result = await cohere.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/generate",
+    body: {
+      model: "command",
+      prompt: "Write a creative story about",
+      max_tokens: 200,
+      temperature: 0.7,
+    },
+  },
+  { response: GenerateResponseSchema }
+);
+```
+
+## Common Pitfalls
+
+### No Specialized Methods
+
+```typescript
+// WRONG - These methods do not exist
+await cohere.chat({ ... });
+await cohere.embed({ ... });
+
+// CORRECT - Use apiRequest
+await cohere.apiRequest(
+  { method: "POST", path: "/v1/chat", body: { ... } },
+  { response: ChatResponseSchema }
+);
+```
+
+### Embedding Input Types
+
+When creating embeddings, specify the correct `input_type`:
+
+```typescript
+// For documents to be searched
+const docEmbeddings = await cohere.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/embed",
+    body: {
+      texts: documents,
+      input_type: "search_document", // For documents
+    },
+  },
+  { response: EmbedResponseSchema }
+);
+
+// For search queries
+const queryEmbedding = await cohere.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/embed",
+    body: {
+      texts: [query],
+      input_type: "search_query", // For queries
+    },
+  },
+  { response: EmbedResponseSchema }
+);
+```
+
+### Classification Requires Examples
+
+The classify endpoint requires labeled examples:
+
+```typescript
+// WRONG - No examples
+const result = await cohere.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/classify",
+    body: {
+      inputs: ["Great product!"],
+      // Missing examples!
+    },
+  },
+  { response: ClassifyResponseSchema }
+);
+
+// CORRECT - Include examples
+const result = await cohere.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/classify",
+    body: {
+      inputs: ["Great product!"],
+      examples: [
+        { text: "I love this!", label: "positive" },
+        { text: "Terrible", label: "negative" },
+      ],
+    },
+  },
+  { response: ClassifyResponseSchema }
+);
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await cohere.apiRequest(
+    { method: "POST", path: "/v1/chat", body: { ... } },
+    { response: ChatResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Cohere API Reference](https://docs.cohere.com/reference/about)
+- [Chat](https://docs.cohere.com/reference/chat)
+- [Embed](https://docs.cohere.com/reference/embed)
+- [Classify](https://docs.cohere.com/reference/classify)
+- [Rerank](https://docs.cohere.com/reference/rerank)

package/src/integrations/cohere/client.ts

@@ -0,0 +1,21 @@
+/**
+ * Cohere client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * Cohere integrations use the REST API Integration plugin under the hood.
+ */
+
+import { RestApiIntegrationClient } from '../base/index.js';
+import type { CohereClient } from './types.js';
+
+/**
+ * Internal implementation of CohereClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * Cohere API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export class CohereClientImpl extends RestApiIntegrationClient implements CohereClient {
+  // Inherits: name, pluginId, config, executeQuery, apiRequest()
+}

package/src/integrations/cohere/index.ts

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

package/src/integrations/cohere/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Cohere client types.
+ */
+
+import type { BaseIntegrationClient } from '../../types.js';
+import type { SupportsApiRequest } from '../base/index.js';
+
+/**
+ * Cohere client for API interactions.
+ *
+ * Provides generic API request method for interacting with Cohere's API.
+ * Use apiRequest() to make calls to any Cohere API endpoint.
+ *
+ * @example
+ * ```typescript
+ * const cohere = ctx.cohere('My Cohere');
+ *
+ * // Make API requests
+ * const ResponseSchema = z.object({
+ *   // Define your response schema
+ * });
+ *
+ * const result = await cohere.apiRequest(
+ *   {
+ *     method: 'POST',
+ *     path: '/generate',
+ *   },
+ *   { response: ResponseSchema }
+ * );
+ * ```
+ */
+export interface CohereClient extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}