@superblocksteam/sdk-api 2.0.101 → 2.0.102-next.0

package/src/integrations/smtp/README.md

@@ -0,0 +1,220 @@
+# SMTP Client
+
+Send emails via SMTP with support for HTML content, CC/BCC, reply-to, and attachments.
+
+## Methods
+
+| Method                     | Description            |
+| -------------------------- | ---------------------- |
+| `send(options, metadata?)` | Send an email via SMTP |
+
+## Usage
+
+### Send a Simple Email
+
+```typescript
+import { api, z, smtp } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const MAILER = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+export default api({
+  name: "SendEmail",
+  integrations: {
+    mailer: smtp(MAILER),
+  },
+  input: z.object({
+    to: z.string(),
+    subject: z.string(),
+    body: z.string(),
+  }),
+  output: z.object({ success: z.boolean() }),
+
+  async run(ctx, { to, subject, body }) {
+    await ctx.integrations.mailer.send({
+      from: "noreply@example.com",
+      to,
+      subject,
+      body,
+    });
+
+    return { success: true };
+  },
+});
+```
+
+### Send HTML Email
+
+```typescript
+await ctx.integrations.mailer.send({
+  from: "noreply@example.com",
+  to: "user@example.com",
+  subject: "Welcome!",
+  body: "<h1>Welcome!</h1><p>Thank you for signing up.</p>",
+});
+```
+
+### Send with CC and BCC
+
+```typescript
+await ctx.integrations.mailer.send({
+  from: "noreply@example.com",
+  to: "user@example.com",
+  subject: "Team Update",
+  body: "Hello team!",
+  cc: "manager@example.com,lead@example.com",
+  bcc: "archive@example.com",
+  replyTo: "support@example.com",
+});
+```
+
+### Send to Multiple Recipients
+
+Use comma-separated email addresses:
+
+```typescript
+await ctx.integrations.mailer.send({
+  from: "noreply@example.com",
+  to: "user1@example.com,user2@example.com,user3@example.com",
+  subject: "Announcement",
+  body: "<p>Important update for the team.</p>",
+});
+```
+
+### Send with Attachments
+
+Attachments are passed as a JSON string containing an array of objects with `content` (base64-encoded), `name` (filename), and `type` (MIME type):
+
+```typescript
+const attachments = JSON.stringify([
+  {
+    content: base64EncodedPdf, // Base64-encoded file content
+    name: "report.pdf",
+    type: "application/pdf",
+  },
+  {
+    content: base64EncodedCsv,
+    name: "data.csv",
+    type: "text/csv",
+  },
+]);
+
+await ctx.integrations.mailer.send({
+  from: "reports@example.com",
+  to: "user@example.com",
+  subject: "Your Report",
+  body: "<p>Please find the attached report.</p>",
+  attachments,
+});
+```
+
+## Trace Metadata
+
+The `send` method accepts an optional `metadata` parameter as the last argument for diagnostics labeling:
+
+```typescript
+await ctx.integrations.mailer.send(
+  {
+    from: "noreply@example.com",
+    to: "user@example.com",
+    subject: "Welcome",
+    body: "Hello!",
+  },
+  { label: "Send welcome email" },
+);
+```
+
+When `includeDiagnostics` is enabled, `label` and `description` appear in the trace view. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Send Options Reference
+
+| Option        | Type     | Required | Description                                   |
+| ------------- | -------- | -------- | --------------------------------------------- |
+| `from`        | `string` | Yes      | Sender email address                          |
+| `to`          | `string` | Yes      | Recipient(s), comma-separated for multiple    |
+| `subject`     | `string` | Yes      | Email subject line                            |
+| `body`        | `string` | Yes      | Email body (HTML or plain text)               |
+| `cc`          | `string` | No       | CC recipient(s), comma-separated              |
+| `bcc`         | `string` | No       | BCC recipient(s), comma-separated             |
+| `replyTo`     | `string` | No       | Reply-to email address                        |
+| `attachments` | `string` | No       | JSON array of `{content, name, type}` objects |
+
+## Common Pitfalls
+
+### Use the `send` Method, Not `apiRequest`
+
+Unlike most integrations, SMTP has a dedicated `send()` method:
+
+```typescript
+// WRONG - apiRequest does not exist on SmtpClient
+await ctx.integrations.mailer.apiRequest({ ... });
+
+// CORRECT - Use send()
+await ctx.integrations.mailer.send({
+  from: "noreply@example.com",
+  to: "user@example.com",
+  subject: "Hello",
+  body: "World",
+});
+```
+
+### Attachments Must Be a JSON String
+
+```typescript
+// WRONG - Passing an array directly
+await ctx.integrations.mailer.send({
+  from: "noreply@example.com",
+  to: "user@example.com",
+  subject: "Report",
+  body: "See attached",
+  attachments: [{ content: "...", name: "file.pdf", type: "application/pdf" }],
+});
+
+// CORRECT - JSON.stringify the array
+await ctx.integrations.mailer.send({
+  from: "noreply@example.com",
+  to: "user@example.com",
+  subject: "Report",
+  body: "See attached",
+  attachments: JSON.stringify([
+    { content: "...", name: "file.pdf", type: "application/pdf" },
+  ]),
+});
+```
+
+### Multiple Recipients Use Comma Separation
+
+```typescript
+// WRONG - Array of recipients
+await ctx.integrations.mailer.send({
+  to: ["user1@example.com", "user2@example.com"],
+  // ...
+});
+
+// CORRECT - Comma-separated string
+await ctx.integrations.mailer.send({
+  to: "user1@example.com,user2@example.com",
+  // ...
+});
+```
+
+## Error Handling
+
+```typescript
+import { IntegrationError } from "@superblocksteam/sdk-api";
+
+try {
+  await ctx.integrations.mailer.send({
+    from: "noreply@example.com",
+    to: "user@example.com",
+    subject: "Test",
+    body: "Hello",
+  });
+} catch (error) {
+  if (error instanceof IntegrationError) {
+    console.error(
+      `SMTP error in ${error.integrationName}.${error.method}: ${error.message}`,
+    );
+  }
+}
+```

package/src/integrations/smtp/client.ts

@@ -6,10 +6,12 @@
  */
 
 import type { PartialMessage } from "@bufbuild/protobuf";
+
 import type { Plugin as SmtpPlugin } from "@superblocksteam/types/dist/src/plugins/smtp/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type { SmtpClient, SmtpSendOptions } from "./types.js";
 
 /**

package/src/integrations/snowflake/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 SnowflakePlugin } from "@superblocksteam/types/dist/src/plugins/snowflake/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 { SnowflakeClient } from "./types.js";
 

package/src/integrations/snowflake/types.ts

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

package/src/integrations/snowflakecortex/README.md

@@ -0,0 +1,216 @@
+# Snowflake Cortex Client
+
+Interact with Snowflake Cortex AI/ML inference endpoints for text generation, embeddings, and other AI capabilities.
+
+## Methods
+
+| Method                                         | Description                                                  |
+| ---------------------------------------------- | ------------------------------------------------------------ |
+| `apiRequest(options, schema, metadata?)`       | Make any Snowflake Cortex API request with schema validation |
+| `streamApiRequest(options, schema, metadata?)` | Stream responses with real-time chunk validation             |
+
+## Usage
+
+### Text Completion
+
+```typescript
+import { api, z, snowflakeCortex } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const CORTEX = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+const CompletionResponseSchema = z
+  .object({
+    choices: z
+      .array(
+        z
+          .object({
+            message: z
+              .object({
+                content: z.string().optional(),
+              })
+              .passthrough()
+              .optional(),
+          })
+          .passthrough(),
+      )
+      .optional(),
+  })
+  .passthrough();
+
+export default api({
+  name: "CortexCompletion",
+  integrations: {
+    cortex: snowflakeCortex(CORTEX),
+  },
+  input: z.object({
+    prompt: z.string(),
+  }),
+  output: z.object({
+    response: z.string(),
+  }),
+  async run(ctx, { prompt }) {
+    const result = await ctx.integrations.cortex.apiRequest(
+      {
+        method: "POST",
+        path: "/api/v2/cortex/inference:complete",
+        body: {
+          model: "llama3.1-8b",
+          messages: [{ role: "user", content: prompt }],
+          stream: false,
+        },
+      },
+      {
+        body: z.object({
+          model: z.string(),
+          messages: z.array(
+            z.object({ role: z.string(), content: z.string() }),
+          ),
+          stream: z.boolean(),
+        }),
+        response: CompletionResponseSchema,
+      },
+    );
+
+    return {
+      response: result.choices?.[0]?.message?.content ?? "",
+    };
+  },
+});
+```
+
+### Streaming Completion
+
+```typescript
+import { streamingApi, z, snowflakeCortex } from "@superblocksteam/sdk-api";
+
+const CORTEX = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+const StreamChunkSchema = z.object({
+  choices: z.array(
+    z.object({
+      delta: z.object({
+        content: z.string().optional(),
+      }),
+    }),
+  ),
+});
+
+export default streamingApi({
+  integrations: {
+    cortex: snowflakeCortex(CORTEX),
+  },
+  input: z.object({ prompt: z.string() }),
+  chunk: z.object({ type: z.literal("text"), text: z.string() }),
+
+  async *run(ctx, { prompt }) {
+    const stream = ctx.integrations.cortex.streamApiRequest(
+      {
+        method: "POST",
+        path: "/api/v2/cortex/inference:complete",
+        body: {
+          model: "mistral-large2",
+          stream: true,
+          messages: [{ role: "user", content: prompt }],
+        },
+      },
+      { chunk: StreamChunkSchema },
+    );
+
+    for await (const chunk of stream) {
+      const content = chunk.choices[0]?.delta?.content;
+      if (content) {
+        yield { type: "text" as const, text: content };
+      }
+    }
+  },
+});
+```
+
+### Text Embedding
+
+```typescript
+const EmbeddingResponseSchema = z.object({
+  data: z.array(
+    z.object({
+      embedding: z.array(z.number()),
+    }),
+  ),
+});
+
+const embeddings = await ctx.integrations.cortex.apiRequest(
+  {
+    method: "POST",
+    path: "/api/v2/cortex/inference:embed",
+    body: {
+      model: "e5-base-v2",
+      input: ["Hello world", "How are you?"],
+    },
+  },
+  { response: EmbeddingResponseSchema },
+);
+```
+
+## 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
+
+The Snowflake Cortex client only provides `apiRequest()` and `streamApiRequest()`. There are no SDK-specific methods:
+
+```typescript
+// WRONG - These methods do not exist
+await cortex.complete({ ... });
+await cortex.embed({ ... });
+
+// CORRECT - Use apiRequest for all operations
+await ctx.integrations.cortex.apiRequest(
+  { method: "POST", path: "/api/v2/cortex/inference:complete", body: { ... } },
+  { response: ResponseSchema }
+);
+```
+
+### Response Schema is Required
+
+You must always provide a schema object with at least a `response` schema. The `body` schema is optional but recommended for request validation:
+
+```typescript
+// WRONG - Missing schema object entirely
+const result = await ctx.integrations.cortex.apiRequest({
+  method: "POST",
+  path: "/api/v2/cortex/inference:complete",
+  body: { ... },
+});
+
+// CORRECT - Include at least a response schema
+const result = await ctx.integrations.cortex.apiRequest(
+  { method: "POST", path: "/api/v2/cortex/inference:complete", body: { ... } },
+  { response: CompletionResponseSchema }
+);
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.cortex.apiRequest(
+    { method: "POST", path: "/api/v2/cortex/inference:complete", body: { ... } },
+    { response: CompletionResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+    console.error("Actual response:", error.details.data);
+  }
+}
+```
+
+## API Reference
+
+- [Snowflake Cortex Documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/overview)
+- [Cortex LLM Functions](https://docs.snowflake.com/en/user-guide/snowflake-cortex/llm-functions)

package/src/integrations/snowflakepostgres/README.md

@@ -0,0 +1,233 @@
+# Snowflake Postgres Client
+
+Execute SQL queries and statements against Snowflake databases using the PostgreSQL wire protocol, with full type safety and runtime validation.
+
+Snowflake Postgres uses the same API contract as the PostgreSQL integration. If you are familiar with the Postgres client, this works identically.
+
+## 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, snowflakePostgres } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const SNOWFLAKE_PG = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+const SalesSchema = z.object({
+  region: z.string(),
+  total_revenue: z.string(), // NUMERIC returned as string
+  order_count: z.coerce.number(),
+});
+
+export default api({
+  name: "GetSalesByRegion",
+  integrations: {
+    db: snowflakePostgres(SNOWFLAKE_PG),
+  },
+  input: z.object({
+    region: z.string(),
+  }),
+  output: z.object({
+    sales: z.array(SalesSchema),
+  }),
+  async run(ctx, { region }) {
+    const sales = await ctx.integrations.db.query(
+      "SELECT region, total_revenue, order_count FROM sales_summary WHERE region = $1",
+      SalesSchema,
+      [region],
+    );
+
+    return { sales };
+  },
+});
+```
+
+### Executing INSERT, UPDATE, DELETE Statements
+
+```typescript
+import { api, z, snowflakePostgres } from "@superblocksteam/sdk-api";
+
+const SNOWFLAKE_PG = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+export default api({
+  name: "ManageRecords",
+  integrations: {
+    db: snowflakePostgres(SNOWFLAKE_PG),
+  },
+  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 = CURRENT_TIMESTAMP() WHERE email = $1",
+      [email],
+    );
+    console.log(`Updated ${updateResult.rowCount} rows`);
+
+    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 < CURRENT_TIMESTAMP()",
+  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
+
+### 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)),
+});
+```
+
+### Aggregate Functions (COUNT, SUM) Return Strings
+
+Use `z.coerce.number()` to convert:
+
+```typescript
+const StatsSchema = z.object({
+  total_orders: z.coerce.number(),
+  total_revenue: z.coerce.number(),
+});
+```
+
+### 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);
+  }
+}
+```
+
+## API Reference
+
+- [Snowflake SQL Reference](https://docs.snowflake.com/en/sql-reference)
+- [Snowflake Data Types](https://docs.snowflake.com/en/sql-reference/data-types)