@superblocksteam/sdk-api 0.0.4

package/src/integrations/slack/README.md

@@ -0,0 +1,400 @@
+# Slack Client
+
+Send messages, manage channels, and interact with Slack workspaces.
+
+## Methods
+
+| Method                                   | Description                                       |
+| ---------------------------------------- | ------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Slack API request with schema validation |
+
+## Usage
+
+### Post a Message
+
+```typescript
+import { api, z, slack } from "@superblocksteam/sdk-api";
+
+const PostMessageResponseSchema = z.object({
+  ok: z.boolean(),
+  channel: z.string(),
+  ts: z.string(), // Message timestamp (unique ID)
+  message: z.object({
+    type: z.string(),
+    text: z.string(),
+    user: z.string().optional(),
+    ts: z.string(),
+  }),
+});
+
+// Integration ID from the integrations panel
+const OPS_SLACK = "a1b2c3d4-5678-90ab-cdef-222222222222";
+
+export default api({
+  name: "SlackExample",
+  integrations: {
+    slack: slack(OPS_SLACK),
+  },
+  input: z.object({
+    channel: z.string(),
+    message: z.string(),
+  }),
+  output: z.object({
+    messageId: z.string(),
+  }),
+  async run(ctx, { channel, message }) {
+    const result = await ctx.integrations.slack.apiRequest(
+      {
+        method: "POST",
+        path: "/chat.postMessage",
+        body: {
+          channel,
+          text: message,
+        },
+      },
+      { response: PostMessageResponseSchema },
+    );
+
+    return { messageId: result.ts };
+  },
+});
+```
+
+### Post with Block Kit
+
+```typescript
+const result = await ctx.integrations.slack.apiRequest(
+  {
+    method: "POST",
+    path: "/chat.postMessage",
+    body: {
+      channel: "#alerts",
+      text: "New deployment", // Fallback text
+      blocks: [
+        {
+          type: "header",
+          text: {
+            type: "plain_text",
+            text: "Deployment Complete",
+          },
+        },
+        {
+          type: "section",
+          text: {
+            type: "mrkdwn",
+            text: "*Environment:* Production\n*Version:* v2.1.0",
+          },
+        },
+        {
+          type: "actions",
+          elements: [
+            {
+              type: "button",
+              text: { type: "plain_text", text: "View Logs" },
+              url: "https://logs.example.com",
+            },
+          ],
+        },
+      ],
+    },
+  },
+  { response: PostMessageResponseSchema },
+);
+```
+
+### List Channels
+
+```typescript
+const ListChannelsResponseSchema = z.object({
+  ok: z.boolean(),
+  channels: z.array(
+    z.object({
+      id: z.string(),
+      name: z.string(),
+      is_private: z.boolean(),
+      is_archived: z.boolean(),
+      num_members: z.number().optional(),
+    }),
+  ),
+  response_metadata: z
+    .object({
+      next_cursor: z.string().optional(),
+    })
+    .optional(),
+});
+
+const result = await ctx.integrations.slack.apiRequest(
+  {
+    method: "GET",
+    path: "/conversations.list",
+    params: {
+      types: "public_channel,private_channel",
+      limit: 100,
+    },
+  },
+  { response: ListChannelsResponseSchema },
+);
+
+result.channels.forEach((channel) => {
+  console.log(`#${channel.name} (${channel.id})`);
+});
+```
+
+### Get User Info
+
+```typescript
+const UserInfoResponseSchema = z.object({
+  ok: z.boolean(),
+  user: z.object({
+    id: z.string(),
+    name: z.string(),
+    real_name: z.string(),
+    profile: z.object({
+      email: z.string().optional(),
+      display_name: z.string(),
+      image_72: z.string().optional(),
+    }),
+    is_admin: z.boolean(),
+  }),
+});
+
+const result = await ctx.integrations.slack.apiRequest(
+  {
+    method: "GET",
+    path: "/users.info",
+    params: { user: "U123456789" },
+  },
+  { response: UserInfoResponseSchema },
+);
+
+console.log(`User: ${result.user.real_name} (${result.user.profile.email})`);
+```
+
+### Upload a File
+
+```typescript
+const FileUploadResponseSchema = z.object({
+  ok: z.boolean(),
+  file: z.object({
+    id: z.string(),
+    name: z.string(),
+    mimetype: z.string(),
+    permalink: z.string(),
+  }),
+});
+
+const result = await ctx.integrations.slack.apiRequest(
+  {
+    method: "POST",
+    path: "/files.upload",
+    body: {
+      channels: "C123456789",
+      filename: "report.csv",
+      content: "name,value\nfoo,123\nbar,456",
+      title: "Daily Report",
+    },
+  },
+  { response: FileUploadResponseSchema },
+);
+
+console.log(`File uploaded: ${result.file.permalink}`);
+```
+
+### Reply to a Thread
+
+```typescript
+const result = await ctx.integrations.slack.apiRequest(
+  {
+    method: "POST",
+    path: "/chat.postMessage",
+    body: {
+      channel: "#alerts",
+      text: "Thread reply message",
+      thread_ts: "1234567890.123456", // Parent message timestamp
+    },
+  },
+  { response: PostMessageResponseSchema },
+);
+```
+
+### Update a Message
+
+```typescript
+const UpdateMessageResponseSchema = z.object({
+  ok: z.boolean(),
+  channel: z.string(),
+  ts: z.string(),
+  text: z.string(),
+});
+
+const result = await ctx.integrations.slack.apiRequest(
+  {
+    method: "POST",
+    path: "/chat.update",
+    body: {
+      channel: "C123456789",
+      ts: "1234567890.123456", // Message to update
+      text: "Updated message text",
+    },
+  },
+  { response: UpdateMessageResponseSchema },
+);
+```
+
+## 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 slack.postMessage({ ... });
+await slack.listChannels();
+
+// CORRECT - Use apiRequest
+await ctx.integrations.slack.apiRequest(
+  { method: "POST", path: "/chat.postMessage", body: { ... } },
+  { response: PostMessageResponseSchema }
+);
+```
+
+### Bot Token vs User Token Permissions
+
+Different tokens have different permissions:
+
+```typescript
+// Bot tokens can:
+// - Post messages to channels the bot is in
+// - Read channel history (if added to channel)
+// - Upload files
+
+// User tokens can:
+// - Access all channels the user can see
+// - Perform actions as the user
+// - Access private channels the user is in
+
+// Check required scopes in Slack API docs for each endpoint
+```
+
+### Channel ID vs Channel Name
+
+Most API methods require channel ID, not name:
+
+```typescript
+// WRONG - Using channel name
+await ctx.integrations.slack.apiRequest(
+  {
+    method: "POST",
+    path: "/chat.postMessage",
+    body: {
+      channel: "#general", // May not work
+      text: "Hello",
+    },
+  },
+  { response: schema },
+);
+
+// CORRECT - Using channel ID
+await ctx.integrations.slack.apiRequest(
+  {
+    method: "POST",
+    path: "/chat.postMessage",
+    body: {
+      channel: "C123456789", // Channel ID
+      text: "Hello",
+    },
+  },
+  { response: schema },
+);
+```
+
+### Handling Pagination
+
+Many endpoints return paginated results:
+
+```typescript
+async function getAllChannels(slack: SlackClient) {
+  const allChannels: Channel[] = [];
+  let cursor: string | undefined;
+
+  do {
+    const result = await ctx.integrations.slack.apiRequest(
+      {
+        method: "GET",
+        path: "/conversations.list",
+        params: {
+          limit: 100,
+          ...(cursor && { cursor }),
+        },
+      },
+      { response: ListChannelsResponseSchema },
+    );
+
+    allChannels.push(...result.channels);
+    cursor = result.response_metadata?.next_cursor;
+  } while (cursor);
+
+  return allChannels;
+}
+```
+
+### Rate Limits
+
+Slack has rate limits (typically 1+ requests/second for most methods):
+
+```typescript
+// Slack returns 429 Too Many Requests when rate limited
+// The Retry-After header indicates when to retry
+```
+
+### Message Formatting
+
+Slack uses its own markdown variant (mrkdwn):
+
+```typescript
+const text = `
+*Bold text*
+_Italic text_
+~Strikethrough~
+\`Inline code\`
+\`\`\`
+Code block
+\`\`\`
+<https://example.com|Link text>
+<@U123456789> - Mention user
+<#C123456789> - Mention channel
+`;
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.slack.apiRequest(
+    { method: "POST", path: "/chat.postMessage", body: { ... } },
+    { response: PostMessageResponseSchema }
+  );
+
+  // Slack returns ok: false for API errors (not HTTP errors)
+  if (!result.ok) {
+    console.error("Slack API error");
+  }
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Slack API Documentation](https://api.slack.com/methods)
+- [chat.postMessage](https://api.slack.com/methods/chat.postMessage)
+- [conversations.list](https://api.slack.com/methods/conversations.list)
+- [Block Kit Builder](https://app.slack.com/block-kit-builder)
+- [OAuth Scopes](https://api.slack.com/scopes)

package/src/integrations/slack/client.ts

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

package/src/integrations/slack/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Slack integration module.
+ */
+
+export type { SlackClient } from "./types.js";
+export { SlackClientImpl } from "./client.js";

package/src/integrations/slack/types.ts

@@ -0,0 +1,50 @@
+/**
+ * Slack client types.
+ */
+
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
+
+/**
+ * Slack client for API interactions.
+ *
+ * Provides generic API request method for interacting with Slack's API.
+ * Use apiRequest() to make calls to any Slack API endpoint.
+ *
+ * @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 }
+ * );
+ *
+ * // List channels
+ * const ListChannelsResponseSchema = z.object({
+ *   channels: z.array(z.object({
+ *     id: z.string(),
+ *     name: z.string(),
+ *   })),
+ * });
+ *
+ * const result = await ctx.integrations.slack.apiRequest(
+ *   {
+ *     method: 'GET',
+ *     path: '/conversations.list',
+ *     params: { limit: 100 },
+ *   },
+ *   { response: ListChannelsResponseSchema }
+ * );
+ * ```
+ */
+export interface SlackClient extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}

package/src/integrations/smtp/client.ts

@@ -0,0 +1,72 @@
+/**
+ * SMTP client implementation.
+ *
+ * Uses the native SMTP plugin type from @superblocksteam/types.
+ * Sends emails with support for CC, BCC, reply-to, and attachments.
+ */
+
+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 { SmtpClient, SmtpSendOptions } from "./types.js";
+
+/**
+ * SMTP request type derived from proto definition.
+ */
+type SmtpRequest = PartialMessage<SmtpPlugin>;
+
+/**
+ * Internal implementation of SmtpClient.
+ *
+ * Constructs SMTP plugin requests matching the proto schema
+ * and executes them via the orchestrator.
+ */
+export class SmtpClientImpl implements SmtpClient, 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;
+  }
+
+  async send(
+    options: SmtpSendOptions,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    const request: SmtpRequest = {
+      from: options.from,
+      to: options.to,
+      subject: options.subject,
+      body: options.body,
+      cc: options.cc ?? "",
+      bcc: options.bcc ?? "",
+      replyTo: options.replyTo ?? "",
+      attachments: options.attachments ?? "",
+    };
+
+    try {
+      return await this.executeQuery(
+        request as Record<string, unknown>,
+        undefined,
+        metadata,
+      );
+    } catch (error) {
+      if (error instanceof IntegrationError) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, "send", error);
+    }
+  }
+}

package/src/integrations/smtp/index.ts

@@ -0,0 +1,8 @@
+/**
+ * SMTP integration client.
+ *
+ * @module
+ */
+
+export type { SmtpClient, SmtpSendOptions } from "./types.js";
+export { SmtpClientImpl } from "./client.js";

package/src/integrations/smtp/types.ts

@@ -0,0 +1,65 @@
+/**
+ * SMTP client types.
+ *
+ * Provides a typed interface for sending emails via SMTP.
+ */
+
+import type { BaseIntegrationClient } from "../../types.js";
+import type { TraceMetadata } from "../registry.js";
+
+/**
+ * Options for sending an email via SMTP.
+ */
+export interface SmtpSendOptions {
+  /** Sender email address */
+  from: string;
+
+  /** Recipient email address(es), comma-separated for multiple */
+  to: string;
+
+  /** Email subject line */
+  subject: string;
+
+  /** Email body content (HTML or plain text) */
+  body: string;
+
+  /** CC recipients, comma-separated for multiple */
+  cc?: string;
+
+  /** BCC recipients, comma-separated for multiple */
+  bcc?: string;
+
+  /** Reply-to email address */
+  replyTo?: string;
+
+  /**
+   * Email attachments as a JSON array of objects with fields:
+   * `content` (base64-encoded), `name` (filename), `type` (MIME type).
+   */
+  attachments?: string;
+}
+
+/**
+ * SMTP client for sending emails.
+ *
+ * @example
+ * ```typescript
+ * const mailer = ctx.integrations.mailer;
+ *
+ * await mailer.send({
+ *   from: 'noreply@example.com',
+ *   to: 'user@example.com',
+ *   subject: 'Hello',
+ *   body: '<h1>Welcome!</h1>',
+ * });
+ * ```
+ */
+export interface SmtpClient extends BaseIntegrationClient {
+  /**
+   * Send an email via SMTP.
+   *
+   * @param options - Email send options
+   * @returns The raw result from the SMTP plugin
+   */
+  send(options: SmtpSendOptions, metadata?: TraceMetadata): Promise<unknown>;
+}