@superblocksteam/sdk-api 2.0.101-next.5 → 2.0.101

package/src/integrations/smtp/README.md

@@ -1,220 +0,0 @@
-# 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/snowflakecortex/README.md

@@ -1,216 +0,0 @@
-# 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

@@ -1,233 +0,0 @@
-# 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)