@superblocksteam/sdk-api 0.0.4

package/src/integrations/mariadb/client.ts

@@ -0,0 +1,138 @@
+/**
+ * MariaDB integration client implementation.
+ *
+ * Executes MariaDB 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 MariaDBPlugin } from "@superblocksteam/types/dist/src/plugins/mariadb/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 { describeType } from "../utils.js";
+import type { MariaDBClient } from "./types.js";
+
+/**
+ * Internal implementation of the MariaDB client.
+ */
+export class MariaDBClientImpl implements MariaDBClient, 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 MariaDB request object from SQL and parameters.
+   *
+   * When params are provided, the SQL body is sent with placeholders intact
+   * 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 ? placeholders
+   * @param params - Optional array of parameter values for server-side binding
+   * @returns The plugin request object
+   */
+  private buildRequest(
+    sql: string,
+    params?: unknown[],
+  ): PartialMessage<MariaDBPlugin> {
+    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[],
+    metadata?: TraceMetadata,
+  ): Promise<T[]> {
+    const request = this.buildRequest(sql, params);
+
+    try {
+      const result = await this.executeQuery(request, undefined, metadata);
+
+      if (!Array.isArray(result)) {
+        throw new IntegrationError(
+          this.config.name,
+          "query",
+          `Expected array result from MariaDB 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[],
+    metadata?: TraceMetadata,
+  ): Promise<{ rowCount: number }> {
+    const request = this.buildRequest(sql, params);
+
+    try {
+      const result = await this.executeQuery(request, undefined, metadata);
+
+      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/mariadb/index.ts

@@ -0,0 +1,8 @@
+/**
+ * MariaDB integration client.
+ *
+ * @module
+ */
+
+export type { MariaDBClient } from "./types.js";
+export { MariaDBClientImpl } from "./client.js";

package/src/integrations/mariadb/types.ts

@@ -0,0 +1,64 @@
+/**
+ * MariaDB integration client types.
+ *
+ * Provides typed methods for executing MariaDB queries with runtime validation.
+ */
+
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+
+/**
+ * Client for executing MariaDB queries with type-safe validation.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { mariadb: mariadb(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.mariadb
+ *
+ * // Query with validation
+ * const UserSchema = z.object({
+ *   id: z.number(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ * });
+ *
+ * const users = await mariadb.query(
+ *   'SELECT * FROM users WHERE status = $1',
+ *   UserSchema,
+ *   ['active']
+ * );
+ * ```
+ */
+export interface MariaDBClient 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[],
+    metadata?: TraceMetadata,
+  ): 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[],
+    metadata?: TraceMetadata,
+  ): Promise<{ rowCount: number }>;
+}

package/src/integrations/mistral/README.md

@@ -0,0 +1,345 @@
+# Mistral Client
+
+Interact with Mistral AI's APIs for chat completions, embeddings, and code generation.
+
+## Methods
+
+| Method                                   | Description                                         |
+| ---------------------------------------- | --------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Mistral API request with schema validation |
+
+## Usage
+
+### Chat Completion
+
+```typescript
+import { api, z, mistral } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_MISTRAL = "a1b2c3d4-5678-90ab-cdef-mistral00001";
+
+const ChatCompletionResponseSchema = z.object({
+  id: z.string(),
+  object: z.string(),
+  created: z.number(),
+  model: z.string(),
+  choices: z.array(
+    z.object({
+      index: z.number(),
+      message: z.object({
+        role: z.string(),
+        content: z.string(),
+      }),
+      finish_reason: z.string(),
+    }),
+  ),
+  usage: z.object({
+    prompt_tokens: z.number(),
+    completion_tokens: z.number(),
+    total_tokens: z.number(),
+  }),
+});
+
+export default api({
+  integrations: {
+    mistral: mistral(PROD_MISTRAL),
+  },
+  name: "MistralExample",
+  input: z.object({
+    prompt: z.string(),
+  }),
+  output: z.object({
+    response: z.string(),
+  }),
+  async run(ctx, { prompt }) {
+    const result = await ctx.integrations.mistral.apiRequest(
+      {
+        method: "POST",
+        path: "/v1/chat/completions",
+        body: {
+          model: "mistral-large-latest",
+          messages: [{ role: "user", content: prompt }],
+        },
+      },
+      { response: ChatCompletionResponseSchema },
+    );
+
+    return { response: result.choices[0]?.message.content ?? "" };
+  },
+});
+```
+
+### Using Different Models
+
+```typescript
+// Mistral Large - Most capable
+const large = await ctx.integrations.mistral.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/chat/completions",
+    body: {
+      model: "mistral-large-latest",
+      messages: [{ role: "user", content: "Complex analysis..." }],
+    },
+  },
+  { response: ChatCompletionResponseSchema },
+);
+
+// Mistral Medium - Balanced
+const medium = await ctx.integrations.mistral.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/chat/completions",
+    body: {
+      model: "mistral-medium-latest",
+      messages: [{ role: "user", content: "General task..." }],
+    },
+  },
+  { response: ChatCompletionResponseSchema },
+);
+
+// Mistral Small - Fast and efficient
+const small = await ctx.integrations.mistral.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/chat/completions",
+    body: {
+      model: "mistral-small-latest",
+      messages: [{ role: "user", content: "Simple task..." }],
+    },
+  },
+  { response: ChatCompletionResponseSchema },
+);
+
+// Codestral - Optimized for code
+const codestral = await ctx.integrations.mistral.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/chat/completions",
+    body: {
+      model: "codestral-latest",
+      messages: [{ role: "user", content: "Write a function to..." }],
+    },
+  },
+  { response: ChatCompletionResponseSchema },
+);
+```
+
+### Generate Embeddings
+
+```typescript
+const EmbeddingsResponseSchema = z.object({
+  id: z.string(),
+  object: z.string(),
+  data: z.array(
+    z.object({
+      object: z.string(),
+      embedding: z.array(z.number()),
+      index: z.number(),
+    }),
+  ),
+  model: z.string(),
+  usage: z.object({
+    prompt_tokens: z.number(),
+    total_tokens: z.number(),
+  }),
+});
+
+const result = await ctx.integrations.mistral.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/embeddings",
+    body: {
+      model: "mistral-embed",
+      input: ["Hello world", "Bonjour le monde"],
+    },
+  },
+  { response: EmbeddingsResponseSchema },
+);
+
+result.data.forEach((item, i) => {
+  console.log(`Text ${i}: ${item.embedding.length} dimensions`);
+});
+```
+
+### Function Calling
+
+```typescript
+const FunctionCallResponseSchema = z.object({
+  id: z.string(),
+  choices: z.array(
+    z.object({
+      message: z.object({
+        role: z.string(),
+        content: z.string().nullable(),
+        tool_calls: z
+          .array(
+            z.object({
+              id: z.string(),
+              type: z.literal("function"),
+              function: z.object({
+                name: z.string(),
+                arguments: z.string(),
+              }),
+            }),
+          )
+          .optional(),
+      }),
+      finish_reason: z.string(),
+    }),
+  ),
+});
+
+const result = await ctx.integrations.mistral.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/chat/completions",
+    body: {
+      model: "mistral-large-latest",
+      messages: [{ role: "user", content: "What's the weather in London?" }],
+      tools: [
+        {
+          type: "function",
+          function: {
+            name: "get_weather",
+            description: "Get weather for a location",
+            parameters: {
+              type: "object",
+              properties: {
+                location: { type: "string" },
+                unit: { type: "string", enum: ["celsius", "fahrenheit"] },
+              },
+              required: ["location"],
+            },
+          },
+        },
+      ],
+      tool_choice: "auto",
+    },
+  },
+  { response: FunctionCallResponseSchema },
+);
+```
+
+### JSON Mode
+
+```typescript
+const result = await ctx.integrations.mistral.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/chat/completions",
+    body: {
+      model: "mistral-large-latest",
+      messages: [
+        {
+          role: "user",
+          content: "List 3 countries with capitals in JSON format",
+        },
+      ],
+      response_format: { type: "json_object" },
+    },
+  },
+  { response: ChatCompletionResponseSchema },
+);
+
+const data = JSON.parse(result.choices[0]?.message.content ?? "{}");
+```
+
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Common Pitfalls
+
+### No Specialized Methods
+
+```typescript
+// WRONG - These methods do not exist
+await mistral.chat({ ... });
+await mistral.embed({ ... });
+
+// CORRECT - Use apiRequest
+await ctx.integrations.mistral.apiRequest(
+  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { response: ChatCompletionResponseSchema }
+);
+```
+
+### Model Names Use "latest" Suffix
+
+Mistral models typically use a `-latest` suffix for the current version:
+
+```typescript
+// Common model names
+const models = [
+  "mistral-large-latest",
+  "mistral-medium-latest",
+  "mistral-small-latest",
+  "codestral-latest",
+  "mistral-embed",
+];
+```
+
+### Safe Mode
+
+Mistral has a safe mode for content moderation:
+
+```typescript
+const result = await ctx.integrations.mistral.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/chat/completions",
+    body: {
+      model: "mistral-large-latest",
+      messages: [{ role: "user", content: "..." }],
+      safe_prompt: true, // Enable safety guardrails
+    },
+  },
+  { response: ChatCompletionResponseSchema },
+);
+```
+
+### System Prompts
+
+Mistral supports system messages:
+
+```typescript
+const result = await ctx.integrations.mistral.apiRequest(
+  {
+    method: "POST",
+    path: "/v1/chat/completions",
+    body: {
+      model: "mistral-large-latest",
+      messages: [
+        { role: "system", content: "You are a helpful coding assistant." },
+        { role: "user", content: "Write a Python function..." },
+      ],
+    },
+  },
+  { response: ChatCompletionResponseSchema },
+);
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.mistral.apiRequest(
+    { method: "POST", path: "/v1/chat/completions", body: { ... } },
+    { response: ChatCompletionResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Mistral API Documentation](https://docs.mistral.ai/)
+- [Chat Completions](https://docs.mistral.ai/api/#operation/createChatCompletion)
+- [Embeddings](https://docs.mistral.ai/api/#operation/createEmbedding)
+- [Models](https://docs.mistral.ai/getting-started/models/)

package/src/integrations/mistral/client.ts

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

package/src/integrations/mistral/index.ts

@@ -0,0 +1,2 @@
+export { MistralClientImpl } from "./client.js";
+export type { MistralClient } from "./types.js";

package/src/integrations/mistral/types.ts

@@ -0,0 +1,36 @@
+/**
+ * Mistral client types.
+ */
+
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
+
+/**
+ * Mistral client for API interactions.
+ *
+ * Provides generic API request method for interacting with Mistral's API.
+ * Use apiRequest() to make calls to any Mistral API endpoint.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { mistral: mistral(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.mistral
+ *
+ * // Make API requests
+ * const ResponseSchema = z.object({
+ *   // Define your response schema
+ * });
+ *
+ * const result = await mistral.apiRequest(
+ *   {
+ *     method: 'POST',
+ *     path: '/chat/completions',
+ *   },
+ *   { response: ResponseSchema }
+ * );
+ * ```
+ */
+export interface MistralClient
+  extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}