@superblocksteam/sdk-api 0.0.5 → 0.0.7

package/src/integrations/lakebase/README.md

@@ -0,0 +1,242 @@
+# Lakebase Client
+
+Execute SQL queries and statements against Lakebase databases with full type safety and runtime validation.
+
+## Methods
+
+| Method                                      | Description                                                                |
+| ------------------------------------------- | -------------------------------------------------------------------------- |
+| `query<T>(sql, schema, params?, metadata?)` | Execute a SELECT query and return validated, typed results                 |
+| `execute(sql, params?, metadata?)`          | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
+
+## Usage
+
+### Basic Query with Schema Validation
+
+```typescript
+import { api, z, lakebase } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const LAKEBASE_DB = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string(),
+  created_at: z.string(),
+});
+
+export default api({
+  name: "GetUsers",
+  integrations: {
+    db: lakebase(LAKEBASE_DB),
+  },
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: z.array(UserSchema),
+  }),
+  async run(ctx, { status }) {
+    const users = await ctx.integrations.db.query(
+      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      UserSchema,
+      [status],
+    );
+
+    return { users };
+  },
+});
+```
+
+### Executing INSERT, UPDATE, DELETE Statements
+
+```typescript
+import { api, z, lakebase } from "@superblocksteam/sdk-api";
+
+const LAKEBASE_DB = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+export default api({
+  name: "ManageUsers",
+  integrations: {
+    db: lakebase(LAKEBASE_DB),
+  },
+  input: z.object({
+    name: z.string(),
+    email: z.string(),
+  }),
+  output: z.object({ success: z.boolean() }),
+
+  async run(ctx, { name, email }) {
+    // INSERT
+    await ctx.integrations.db.execute(
+      "INSERT INTO users (name, email) VALUES ($1, $2)",
+      [name, email],
+    );
+
+    // UPDATE
+    const updateResult = await ctx.integrations.db.execute(
+      "UPDATE users SET last_login = NOW() WHERE email = $1",
+      [email],
+    );
+    console.log(`Updated ${updateResult.rowCount} rows`);
+
+    // DELETE
+    const deleteResult = await ctx.integrations.db.execute(
+      "DELETE FROM sessions WHERE expires_at < NOW()",
+    );
+    console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
+
+    return { success: true };
+  },
+});
+```
+
+### Query with JOIN
+
+```typescript
+const OrderSchema = z.object({
+  order_id: z.string(),
+  customer_name: z.string(),
+  total: z.string(), // NUMERIC as string
+});
+
+const orders = await ctx.integrations.db.query(
+  `SELECT o.id as order_id, c.name as customer_name, o.total
+   FROM orders o
+   JOIN customers c ON o.customer_id = c.id
+   WHERE o.status = $1`,
+  OrderSchema,
+  ["pending"],
+);
+```
+
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling:
+
+```typescript
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE status = $1",
+  UserSchema,
+  ["active"],
+  { label: "Fetch active users" },
+);
+
+await ctx.integrations.db.execute(
+  "DELETE FROM sessions WHERE expires_at < NOW()",
+  undefined, // no params
+  { label: "Clean expired sessions" },
+);
+```
+
+When `includeDiagnostics` is enabled, `label` and `description` appear in the trace view. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Common Pitfalls
+
+### Uses `$1` Placeholders (PostgreSQL-Style)
+
+Lakebase uses `$1, $2, ...` for parameter placeholders, following PostgreSQL conventions:
+
+```typescript
+// WRONG - Question-mark placeholders
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE name = ? AND status = ?",
+  UserSchema,
+  [name, status],
+);
+
+// CORRECT - Use $1, $2, ... placeholders
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE name = $1 AND status = $2",
+  UserSchema,
+  [name, status],
+);
+```
+
+### Schema Parameter is Required
+
+The `query()` method requires a Zod schema for runtime validation:
+
+```typescript
+// WRONG - Missing schema parameter
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users",
+  [
+    /* params */
+  ], // This is wrong - params are 3rd argument
+);
+
+// CORRECT - Schema is the second parameter
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE id = $1",
+  UserSchema, // Schema is required
+  [userId], // Params are optional, third argument
+);
+```
+
+### Use Parameterized Queries to Prevent SQL Injection
+
+Always use `$1, $2, ...` placeholders instead of string interpolation:
+
+```typescript
+// WRONG - SQL injection vulnerability
+const users = await ctx.integrations.db.query(
+  `SELECT * FROM users WHERE name = '${userName}'`, // DANGEROUS!
+  UserSchema,
+);
+
+// CORRECT - Use parameterized queries
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users WHERE name = $1",
+  UserSchema,
+  [userName], // Safe - value is escaped
+);
+```
+
+### NUMERIC/DECIMAL Values Returned as Strings
+
+Large `NUMERIC` and `DECIMAL` columns are returned as strings to preserve precision:
+
+```typescript
+// WRONG - May lose precision
+const schema = z.object({ price: z.number() });
+
+// CORRECT - Keep as string or transform
+const schema = z.object({
+  price: z.string().transform((val) => parseFloat(val)),
+});
+```
+
+### Handling NULL Values
+
+```typescript
+// WRONG - Will fail if column contains NULL
+const schema = z.object({ bio: z.string() });
+
+// CORRECT - Mark nullable columns
+const schema = z.object({ bio: z.string().nullable() });
+```
+
+## Error Handling
+
+### QueryValidationError
+
+Thrown when query results fail schema validation:
+
+```typescript
+import { QueryValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const users = await ctx.integrations.db.query(
+    "SELECT * FROM users",
+    UserSchema,
+  );
+} catch (error) {
+  if (error instanceof QueryValidationError) {
+    console.error("Row index:", error.details.rowIndex);
+    console.error("Validation errors:", error.details.errors);
+    console.error("Actual row data:", error.details.row);
+  }
+}
+```

package/src/integrations/lakebase/client.ts

@@ -5,15 +5,17 @@
  * Supports server-side parameterized SQL queries via the `parameters` field.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as LakebasePlugin } from "@superblocksteam/types/dist/src/plugins/lakebase/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
-import type { LakebaseClient } from "./types.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 { LakebaseClient } from "./types.js";
 
 /**
  * Lakebase request type derived from proto definition.

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

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

package/src/integrations/lakebase/types.ts

@@ -6,6 +6,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 
@@ -18,14 +19,14 @@ import type { TraceMetadata } from "../registry.js";
  *
  * // Parameterized query
  * const users = await lb.query(
- *   'SELECT * FROM users WHERE status = ?',
+ *   'SELECT * FROM users WHERE status = $1',
  *   UserSchema,
  *   ['active'],
  * );
  *
  * // Execute a mutation
  * const result = await lb.execute(
- *   'INSERT INTO users (name, email) VALUES (?, ?)',
+ *   'INSERT INTO users (name, email) VALUES ($1, $2)',
  *   ['Alice', 'alice@example.com'],
  * );
  * ```
@@ -34,7 +35,7 @@ export interface LakebaseClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and return validated rows.
    *
-   * @param sql - SQL query string with `?` placeholders for parameters
+   * @param sql - SQL query string with `$1`, `$2` placeholders for parameters
    * @param schema - Zod schema for validating each result row
    * @param params - Optional query parameters for server-side binding
    * @returns Array of validated rows
@@ -49,7 +50,7 @@ export interface LakebaseClient extends BaseIntegrationClient {
   /**
    * Execute a SQL statement (INSERT, UPDATE, DELETE).
    *
-   * @param sql - SQL statement with `?` placeholders for parameters
+   * @param sql - SQL statement with `$1`, `$2` placeholders for parameters
    * @param params - Optional query parameters for server-side binding
    * @returns The affected row count
    */

package/src/integrations/launchdarkly/README.md

@@ -13,7 +13,7 @@ Manage feature flags, get flag evaluations, and interact with LaunchDarkly's fea
 ### Get Feature Flag
 
 ```typescript
-import { api, z, launchdarkly } from "@superblocksteam/sdk-api";
+import { api, z, launchDarkly } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_LAUNCHDARKLY = "a1b2c3d4-5678-90ab-cdef-launchda0001";
@@ -44,7 +44,7 @@ const FlagSchema = z.object({
 
 export default api({
   integrations: {
-    launchdarkly: launchdarkly(PROD_LAUNCHDARKLY),
+    launchdarkly: launchDarkly(PROD_LAUNCHDARKLY),
   },
   name: "LaunchDarklyExample",
   input: z.object({

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

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

package/src/integrations/mariadb/README.md

@@ -39,7 +39,7 @@ export default api({
   }),
   async run(ctx, { status }) {
     const users = await ctx.integrations.mariadb.query(
-      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      "SELECT id, name, email, created_at FROM users WHERE status = ?",
       UserSchema,
       [status],
     );
@@ -54,13 +54,13 @@ export default api({
 ```typescript
 // INSERT
 await ctx.integrations.mariadb.execute(
-  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  "INSERT INTO users (name, email) VALUES (?, ?)",
   ["John Doe", "john@example.com"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.mariadb.execute(
-  "UPDATE users SET last_login = NOW() WHERE id = $1",
+  "UPDATE users SET last_login = NOW() WHERE id = ?",
   [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);

package/src/integrations/mariadb/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 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 type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { MariaDBClient } from "./types.js";
 

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

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

package/src/integrations/mariadb/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 users = await mariadb.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = ?',
  *   UserSchema,
  *   ['active']
  * );
@@ -34,7 +35,7 @@ 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 sql - SQL query string (use ? placeholders for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results

package/src/integrations/mistral/README.md

@@ -10,7 +10,9 @@ Interact with Mistral AI's APIs for chat completions, embeddings, and code gener
 
 ## Usage
 
-### Chat Completion
+### Step 1: List Available Models
+
+Model availability varies by account and API plan. Before making requests, validate which models you can access:
 
 ```typescript
 import { api, z, mistral } from "@superblocksteam/sdk-api";
@@ -18,6 +20,30 @@ import { api, z, mistral } from "@superblocksteam/sdk-api";
 // Integration ID from the integrations panel
 const PROD_MISTRAL = "a1b2c3d4-5678-90ab-cdef-mistral00001";
 
+const ModelsResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      id: z.string(),
+      object: z.string(),
+    }),
+  ),
+});
+
+const models = await ctx.integrations.mistral.apiRequest(
+  {
+    method: "GET",
+    path: "/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.mistral.apiRequest(
       {
         method: "POST",
-        path: "/v1/chat/completions",
+        path: "/chat/completions",
         body: {
           model: "mistral-large-latest",
           messages: [{ role: "user", content: prompt }],
@@ -76,7 +102,7 @@ export default api({
 const large = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [{ role: "user", content: "Complex analysis..." }],
@@ -89,7 +115,7 @@ const large = await ctx.integrations.mistral.apiRequest(
 const medium = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-medium-latest",
       messages: [{ role: "user", content: "General task..." }],
@@ -102,7 +128,7 @@ const medium = await ctx.integrations.mistral.apiRequest(
 const small = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-small-latest",
       messages: [{ role: "user", content: "Simple task..." }],
@@ -115,7 +141,7 @@ const small = await ctx.integrations.mistral.apiRequest(
 const codestral = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "codestral-latest",
       messages: [{ role: "user", content: "Write a function to..." }],
@@ -148,7 +174,7 @@ const EmbeddingsResponseSchema = z.object({
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/embeddings",
+    path: "/embeddings",
     body: {
       model: "mistral-embed",
       input: ["Hello world", "Bonjour le monde"],
@@ -193,7 +219,7 @@ const FunctionCallResponseSchema = z.object({
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [{ role: "user", content: "What's the weather in London?" }],
@@ -227,7 +253,7 @@ const result = await ctx.integrations.mistral.apiRequest(
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [
@@ -260,7 +286,7 @@ await mistral.embed({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.mistral.apiRequest(
-  { method: "POST", path: "/v1/chat/completions", body: { ... } },
+  { method: "POST", path: "/chat/completions", body: { ... } },
   { response: ChatCompletionResponseSchema }
 );
 ```
@@ -288,7 +314,7 @@ Mistral has a safe mode for content moderation:
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [{ role: "user", content: "..." }],
@@ -307,7 +333,7 @@ Mistral supports system messages:
 const result = await ctx.integrations.mistral.apiRequest(
   {
     method: "POST",
-    path: "/v1/chat/completions",
+    path: "/chat/completions",
     body: {
       model: "mistral-large-latest",
       messages: [
@@ -327,7 +353,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.mistral.apiRequest(
-    { method: "POST", path: "/v1/chat/completions", body: { ... } },
+    { method: "POST", path: "/chat/completions", body: { ... } },
     { response: ChatCompletionResponseSchema }
   );
 } catch (error) {

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

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