@superblocksteam/sdk-api 0.0.5 → 0.0.7

package/src/integrations/slack/types.ts

@@ -1,50 +1,163 @@
 /**
  * Slack client types.
+ *
+ * Defines the SlackResponse<T> discriminated union that wraps every
+ * Slack API call, plus the SlackClient interface consumers interact with.
  */
 
+import { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
-import type { SupportsApiRequest } from "../base/index.js";
+import type { ApiRequestOptions, TraceMetadata } from "../base/types.js";
 
 /**
- * Slack client for API interactions.
+ * Zod schema for Slack API error responses.
+ *
+ * Slack returns errors as HTTP 200 with `{ ok: false, error: "..." }`.
+ * For `missing_scope` errors, `needed` and `provided` list the
+ * required vs current OAuth scopes.
+ */
+export const SlackErrorSchema = z.object({
+  ok: z.literal(false),
+  error: z.string(),
+  needed: z.string().optional(),
+  provided: z.string().optional(),
+});
+
+/** Slack API error response, derived from {@link SlackErrorSchema}. */
+export type SlackErrorResponse = z.infer<typeof SlackErrorSchema>;
+
+/**
+ * Zod schema for Slack success envelopes.
+ *
+ * Success responses from Slack include `{ ok: true, ...payload }`.
+ * Callers provide schemas for the payload fields only; the SDK validates
+ * this envelope separately and injects `ok: true` in the returned type.
+ */
+export const SlackSuccessEnvelopeSchema = z.object({
+  ok: z.literal(true),
+});
+
+/**
+ * Enforce that caller-provided success schemas do not define `ok`.
  *
- * Provides generic API request method for interacting with Slack's API.
- * Use apiRequest() to make calls to any Slack API endpoint.
+ * The `ok` field belongs to the Slack envelope and is injected by the SDK.
+ */
+type SlackSuccessSchemaHasExplicitOkKey<TSchema extends z.AnyZodObject> =
+  TSchema extends z.ZodObject<
+    infer TShape,
+    z.UnknownKeysParam,
+    z.ZodTypeAny,
+    unknown,
+    unknown
+  >
+    ? "ok" extends keyof TShape
+      ? true
+      : false
+    : false;
+
+export type SlackSuccessSchema<TSchema extends z.AnyZodObject> =
+  SlackSuccessSchemaHasExplicitOkKey<TSchema> extends true ? never : TSchema;
+
+/**
+ * Schema configuration for Slack API requests.
+ *
+ * Response schema must be an object payload schema (without `ok`).
+ */
+export interface SlackApiRequestSchema<
+  TBody,
+  TResponseSchema extends z.AnyZodObject,
+> {
+  body?: z.ZodSchema<TBody>;
+  response: SlackSuccessSchema<TResponseSchema>;
+}
+
+/** Slack success response shape with injected discriminant. */
+export type SlackSuccessResponse<T extends Record<string, unknown>> = T & {
+  readonly ok: true;
+};
+
+/**
+ * Discriminated union of a Slack success response and error response.
+ *
+ * On success (`ok: true`), the type is `T & { ok: true }` — the
+ * validated schema output intersected with a literal `true` discriminant.
+ * On failure (`ok: false`), the type is {@link SlackErrorResponse}.
+ *
+ * Use the `ok` field as a discriminant for type narrowing:
  *
  * @example
  * ```typescript
- * // Declare in api(): integrations: { slack: slack(INTEGRATION_ID) }
- * // In run(), access via: ctx.integrations.slack
- * await ctx.integrations.slack.apiRequest(
- *   {
- *     method: 'POST',
- *     path: '/chat.postMessage',
- *     body: {
- *       channel: '#alerts',
- *       text: 'Deployment completed!',
- *     },
- *   },
- *   { response: PostMessageResponseSchema }
+ * const result = await ctx.integrations.slack.apiRequest(
+ *   { method: "GET", path: "/conversations.list", params: { limit: 100 } },
+ *   { response: ListChannelsSchema },
  * );
  *
- * // List channels
- * const ListChannelsResponseSchema = z.object({
- *   channels: z.array(z.object({
- *     id: z.string(),
- *     name: z.string(),
- *   })),
- * });
+ * if (!result.ok) {
+ *   // TypeScript narrows to SlackErrorResponse
+ *   console.error(`Slack error: ${result.error}`);
+ *   return;
+ * }
  *
+ * // TypeScript narrows to T & { ok: true }
+ * result.channels.forEach(ch => console.log(ch.name));
+ * ```
+ */
+export type SlackResponse<T extends Record<string, unknown>> =
+  | SlackSuccessResponse<T>
+  | SlackErrorResponse;
+
+/**
+ * Slack client for API interactions.
+ *
+ * Returns {@link SlackResponse}<T> from `apiRequest` — a discriminated
+ * union that encapsulates both Slack success and error responses. This
+ * avoids confusing Zod validation errors when Slack returns `ok: false`
+ * (which is an HTTP 200 with no success-specific fields).
+ *
+ * Note: SlackClient intentionally does not extend `SupportsApiRequest`.
+ * `SupportsApiRequest.apiRequest` returns `Promise<TResponse>`, while
+ * Slack returns `Promise<SlackResponse<T>>` by design.
+ *
+ * @example
+ * ```typescript
  * const result = await ctx.integrations.slack.apiRequest(
  *   {
- *     method: 'GET',
- *     path: '/conversations.list',
- *     params: { limit: 100 },
+ *     method: "POST",
+ *     path: "/chat.postMessage",
+ *     body: { channel: "#alerts", text: "Deployed!" },
  *   },
- *   { response: ListChannelsResponseSchema }
+ *   { response: PostMessageResponseSchema },
  * );
+ *
+ * if (!result.ok) {
+ *   throw new Error(`Slack API error: ${result.error}`);
+ * }
+ *
+ * console.log(`Message sent: ${result.ts}`);
  * ```
  */
-export interface SlackClient extends BaseIntegrationClient, SupportsApiRequest {
-  // apiRequest() method inherited from SupportsApiRequest
+export interface SlackClient extends BaseIntegrationClient {
+  /**
+   * Execute a Slack API request with type-safe response handling.
+   *
+   * Returns a {@link SlackResponse}<TResponse> discriminated union:
+   * - On success: the Zod-validated payload with injected `ok: true`
+   * - On failure: a {@link SlackErrorResponse} with `ok: false` and the Slack error code
+   *
+   * Body validation still throws {@link RestApiValidationError} if the
+   * request body fails its Zod schema.
+   *
+   * @param options - Request configuration (method, path, params, body, headers)
+   * @param schema - Zod schemas for body and response validation (response REQUIRED)
+   *   - `response` must be `z.object(...)`
+   *   - `response` should define payload fields only (MUST NOT define `ok`)
+   * @param metadata - Optional trace metadata for observability
+   * @returns Discriminated union — check `result.ok` before accessing fields
+   */
+  apiRequest<TBody, TResponseSchema extends z.AnyZodObject>(
+    options: ApiRequestOptions<TBody>,
+    schema: SlackApiRequestSchema<TBody, TResponseSchema>,
+    metadata?: TraceMetadata,
+  ): Promise<SlackResponse<z.output<TResponseSchema>>>;
 }

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/smtp/docs.manifest.json

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

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";
 
@@ -41,10 +43,10 @@ export class SnowflakeClientImpl
    * Builds a Snowflake 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`
+   * (e.g. ?) 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 sql - The SQL query with optional ? placeholders
    * @param params - Optional array of parameter values for server-side binding
    * @returns The plugin request object
    */

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

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

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,167 @@
+# 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 |
+
+## 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 ?? "",
+    };
+  },
+});
+```
+
+### 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()`. There are no other specialized 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/snowflakecortex/client.ts

@@ -11,12 +11,11 @@ import type { SnowflakeCortexClient } from "./types.js";
 /**
  * Internal implementation of SnowflakeCortexClient.
  *
- * Extends RestApiIntegrationClient to inherit generic apiRequest() and
- * streamApiRequest() methods.
+ * Extends RestApiIntegrationClient to inherit generic apiRequest() method.
  */
 export class SnowflakeCortexClientImpl
   extends RestApiIntegrationClient
   implements SnowflakeCortexClient {
-  // Inherits: name, pluginId, config, executeQuery, createParam(), apiRequest(), streamApiRequest()
+  // Inherits: name, pluginId, config, executeQuery, createParam(), apiRequest()
   // Can add Snowflake Cortex-specific methods here in the future if needed
 }

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

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