@hasna/connectors 0.3.16 → 0.4.0

package/connectors/connect-slack/CLAUDE.md

@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+connect-slack is a TypeScript CLI and library for Slack's API. It provides channel management, messaging, and user operations with multi-profile support for managing multiple workspaces.
+
+## Build & Run Commands
+
+```bash
+bun install           # Install dependencies
+bun run dev           # Run CLI in development
+bun run build         # Build for distribution
+bun run typecheck     # Type check
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (type: module)
+- Async/await for all async operations
+- Minimal dependencies: commander, chalk
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts     # HTTP client with Bearer auth
+│   ├── channels.ts   # Channels/Conversations API
+│   ├── messages.ts   # Messages API
+│   ├── users.ts      # Users API
+│   └── index.ts      # Main Slack class
+├── cli/
+│   └── index.ts      # CLI commands
+├── types/
+│   └── index.ts      # TypeScript types
+├── utils/
+│   ├── config.ts     # Multi-profile configuration
+│   └── output.ts     # CLI output formatting
+└── index.ts          # Library exports
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SLACK_BOT_TOKEN` | Bot token (xoxb-...) |
+| `SLACK_USER_TOKEN` | User token (xoxp-...) |
+| `SLACK_TEAM_ID` | Team/workspace ID |
+
+## Multi-Profile Configuration
+
+Configuration stored in `~/.connect/connect-slack/`:
+
+```
+~/.connect/connect-slack/
+├── current_profile
+└── profiles/
+    └── default/
+        ├── config.json
+        └── tokens.json
+```
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/connect-slack/README.md

@@ -0,0 +1,150 @@
+# @hasna/connect-slack
+
+Slack API connector with CLI and library support. Multi-profile configuration for managing multiple workspaces.
+
+## Installation
+
+```bash
+bun install -g @hasna/connect-slack
+```
+
+## Quick Start
+
+```bash
+# Set your bot token
+connect-slack config set-token xoxb-your-bot-token
+
+# Test authentication
+connect-slack test
+
+# Send a message
+connect-slack send general "Hello from CLI!"
+
+# List channels
+connect-slack channels list
+
+# View message history
+connect-slack messages history general --limit 10
+```
+
+## CLI Commands
+
+### Configuration
+
+```bash
+connect-slack config set-token <token>    # Set bot token
+connect-slack config set-user-token <token>  # Set user token
+connect-slack config set-channel <channel>   # Set default channel
+connect-slack config show                 # Show configuration
+connect-slack config clear                # Clear configuration
+```
+
+### Profile Management
+
+```bash
+connect-slack profile list                # List profiles
+connect-slack profile create <name>       # Create profile
+connect-slack profile use <name>          # Switch profile
+connect-slack profile delete <name>       # Delete profile
+connect-slack profile show                # Show current profile
+
+# Use specific profile for a command
+connect-slack --profile work channels list
+```
+
+### Channels
+
+```bash
+connect-slack channels list               # List channels
+connect-slack channels info <channel>     # Get channel info
+connect-slack channels join <channel>     # Join channel
+connect-slack channels leave <channel>    # Leave channel
+```
+
+### Messages
+
+```bash
+connect-slack send <channel> <text>              # Quick send
+connect-slack messages send <channel> <text>     # Send message
+connect-slack messages send <channel> <text> -t <ts>  # Reply to thread
+connect-slack messages history <channel>         # View history
+connect-slack messages search <query>            # Search messages
+```
+
+### Users
+
+```bash
+connect-slack users list                  # List users
+connect-slack users info <user>           # Get user info
+connect-slack test                        # Show current user
+```
+
+## Library Usage
+
+```typescript
+import { Slack } from '@hasna/connect-slack';
+
+const slack = new Slack({
+  accessToken: process.env.SLACK_BOT_TOKEN,
+});
+
+// Test authentication
+const auth = await slack.test();
+console.log(`Logged in as ${auth.user} in ${auth.team}`);
+
+// List channels
+const channels = await slack.channels.list();
+console.log(channels);
+
+// Send a message
+await slack.send('C1234567890', 'Hello from the library!');
+
+// Get message history
+const messages = await slack.messages.history({
+  channel: 'C1234567890',
+  limit: 10,
+});
+
+// List users
+const users = await slack.users.list();
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SLACK_BOT_TOKEN` | Bot token (xoxb-...) |
+| `SLACK_USER_TOKEN` | User token (xoxp-...) |
+| `SLACK_TEAM_ID` | Team/workspace ID |
+
+## Configuration Files
+
+Configuration is stored in `~/.connect/connect-slack/`:
+
+```
+~/.connect/connect-slack/
+├── current_profile          # Active profile name
+└── profiles/
+    ├── default/
+    │   ├── config.json      # Profile settings
+    │   └── tokens.json      # OAuth tokens
+    └── work/
+        ├── config.json
+        └── tokens.json
+```
+
+## Getting a Bot Token
+
+1. Go to [Slack API Apps](https://api.slack.com/apps)
+2. Create a new app or select existing
+3. Navigate to "OAuth & Permissions"
+4. Add required scopes:
+   - `channels:read`, `channels:history`, `channels:join`
+   - `chat:write`
+   - `users:read`
+5. Install to your workspace
+6. Copy the Bot User OAuth Token
+
+## License
+
+Apache-2.0

package/connectors/connect-slack/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@hasna/connect-slack",
+  "version": "0.0.1",
+  "description": "Slack API connector with CLI and library support",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "connect-slack": "bin/index.js"
+  },
+  "scripts": {
+    "dev": "bun run ./src/cli/index.ts",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "slack",
+    "api",
+    "cli",
+    "connector"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "restricted"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src",
+    "README.md",
+    "CLAUDE.md"
+  ]
+}

package/connectors/connect-slack/src/api/channels.ts

@@ -0,0 +1,112 @@
+import type { SlackClient } from './client';
+import type {
+  SlackChannel,
+  ConversationsListResponse,
+  ConversationsListOptions,
+} from '../types';
+
+/**
+ * Channels/Conversations API
+ */
+export class ChannelsApi {
+  constructor(private readonly client: SlackClient) {}
+
+  /**
+   * List all conversations/channels
+   */
+  async list(options: Omit<ConversationsListOptions, 'channel'> = {}): Promise<SlackChannel[]> {
+    const allChannels: SlackChannel[] = [];
+    let cursor: string | undefined;
+
+    do {
+      const response = await this.client.get<ConversationsListResponse>(
+        'conversations.list',
+        {
+          types: options.types || 'public_channel,private_channel',
+          exclude_archived: options.exclude_archived ?? true,
+          limit: options.limit || 200,
+          cursor,
+        }
+      );
+
+      allChannels.push(...response.channels);
+      cursor = response.response_metadata?.next_cursor;
+    } while (cursor && allChannels.length < (options.limit || 1000));
+
+    return allChannels;
+  }
+
+  /**
+   * Get channel info by ID
+   */
+  async info(channelId: string): Promise<SlackChannel> {
+    const response = await this.client.get<{ ok: boolean; channel: SlackChannel }>(
+      'conversations.info',
+      { channel: channelId }
+    );
+    return response.channel;
+  }
+
+  /**
+   * Find a channel by name
+   */
+  async findByName(name: string): Promise<SlackChannel | undefined> {
+    const channels = await this.list();
+    const normalizedName = name.replace(/^#/, '');
+    return channels.find(c => c.name === normalizedName || c.name_normalized === normalizedName);
+  }
+
+  /**
+   * Join a channel
+   */
+  async join(channelId: string): Promise<SlackChannel> {
+    const response = await this.client.post<{ ok: boolean; channel: SlackChannel }>(
+      'conversations.join',
+      { channel: channelId }
+    );
+    return response.channel;
+  }
+
+  /**
+   * Leave a channel
+   */
+  async leave(channelId: string): Promise<void> {
+    await this.client.post('conversations.leave', { channel: channelId });
+  }
+
+  /**
+   * Create a new channel
+   */
+  async create(name: string, isPrivate = false): Promise<SlackChannel> {
+    const response = await this.client.post<{ ok: boolean; channel: SlackChannel }>(
+      'conversations.create',
+      { name, is_private: isPrivate }
+    );
+    return response.channel;
+  }
+
+  /**
+   * Archive a channel
+   */
+  async archive(channelId: string): Promise<void> {
+    await this.client.post('conversations.archive', { channel: channelId });
+  }
+
+  /**
+   * Unarchive a channel
+   */
+  async unarchive(channelId: string): Promise<void> {
+    await this.client.post('conversations.unarchive', { channel: channelId });
+  }
+
+  /**
+   * Get members of a channel
+   */
+  async members(channelId: string, limit = 200): Promise<string[]> {
+    const response = await this.client.get<{ ok: boolean; members: string[] }>(
+      'conversations.members',
+      { channel: channelId, limit }
+    );
+    return response.members;
+  }
+}

package/connectors/connect-slack/src/api/client.ts

@@ -0,0 +1,97 @@
+import type { SlackConfig, SlackApiResponse, OutputFormat } from '../types';
+import { SlackApiError } from '../types';
+
+const DEFAULT_BASE_URL = 'https://slack.com/api';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown>;
+  format?: OutputFormat;
+}
+
+export class SlackClient {
+  private readonly token: string;
+  private readonly baseUrl: string;
+
+  constructor(config: SlackConfig) {
+    const token = config.accessToken || config.botToken;
+    if (!token) {
+      throw new Error('Slack token is required (accessToken or botToken)');
+    }
+    this.token = token;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const url = new URL(`${this.baseUrl}/${path}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  async request<T extends SlackApiResponse>(
+    path: string,
+    options: RequestOptions = {}
+  ): Promise<T> {
+    const { method = 'GET', params, body } = options;
+
+    const headers: Record<string, string> = {
+      'Authorization': `Bearer ${this.token}`,
+      'Content-Type': 'application/json; charset=utf-8',
+    };
+
+    const url = this.buildUrl(path, method === 'GET' ? params : undefined);
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers,
+    };
+
+    if (body && method === 'POST') {
+      fetchOptions.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    if (!response.ok) {
+      throw new SlackApiError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        'http_error',
+        response.status
+      );
+    }
+
+    const data = await response.json() as T;
+
+    if (!data.ok) {
+      throw new SlackApiError(
+        data.error || 'Unknown Slack API error',
+        data.error || 'unknown_error'
+      );
+    }
+
+    return data;
+  }
+
+  async get<T extends SlackApiResponse>(
+    path: string,
+    params?: Record<string, string | number | boolean | undefined>
+  ): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T extends SlackApiResponse>(
+    path: string,
+    body?: Record<string, unknown>
+  ): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body });
+  }
+}

package/connectors/connect-slack/src/api/index.ts

@@ -0,0 +1,42 @@
+import type { SlackConfig } from '../types';
+import { SlackClient } from './client';
+import { ChannelsApi } from './channels';
+import { MessagesApi } from './messages';
+import { UsersApi } from './users';
+
+export { SlackClient } from './client';
+export { ChannelsApi } from './channels';
+export { MessagesApi } from './messages';
+export { UsersApi } from './users';
+
+/**
+ * Main Slack API class
+ */
+export class Slack {
+  private readonly client: SlackClient;
+
+  public readonly channels: ChannelsApi;
+  public readonly messages: MessagesApi;
+  public readonly users: UsersApi;
+
+  constructor(config: SlackConfig) {
+    this.client = new SlackClient(config);
+    this.channels = new ChannelsApi(this.client);
+    this.messages = new MessagesApi(this.client);
+    this.users = new UsersApi(this.client);
+  }
+
+  /**
+   * Test authentication
+   */
+  async test() {
+    return this.users.me();
+  }
+
+  /**
+   * Send a message to a channel (convenience method)
+   */
+  async send(channel: string, text: string) {
+    return this.messages.sendText(channel, text);
+  }
+}

package/connectors/connect-slack/src/api/messages.ts

@@ -0,0 +1,127 @@
+import type { SlackClient } from './client';
+import type {
+  SlackMessage,
+  ConversationsHistoryResponse,
+  ConversationsHistoryOptions,
+  ChatPostMessageResponse,
+  ChatPostMessageOptions,
+} from '../types';
+
+/**
+ * Messages API
+ */
+export class MessagesApi {
+  constructor(private readonly client: SlackClient) {}
+
+  /**
+   * Get message history for a channel
+   */
+  async history(options: ConversationsHistoryOptions): Promise<SlackMessage[]> {
+    const response = await this.client.get<ConversationsHistoryResponse>(
+      'conversations.history',
+      {
+        channel: options.channel,
+        limit: options.limit || 100,
+        cursor: options.cursor,
+        oldest: options.oldest,
+        latest: options.latest,
+        inclusive: options.inclusive,
+      }
+    );
+
+    return response.messages;
+  }
+
+  /**
+   * Send a message to a channel
+   */
+  async send(options: ChatPostMessageOptions): Promise<ChatPostMessageResponse> {
+    return this.client.post<ChatPostMessageResponse>('chat.postMessage', {
+      channel: options.channel,
+      text: options.text,
+      blocks: options.blocks,
+      attachments: options.attachments,
+      thread_ts: options.thread_ts,
+      reply_broadcast: options.reply_broadcast,
+      unfurl_links: options.unfurl_links,
+      unfurl_media: options.unfurl_media,
+      mrkdwn: options.mrkdwn ?? true,
+    });
+  }
+
+  /**
+   * Send a simple text message
+   */
+  async sendText(channel: string, text: string): Promise<ChatPostMessageResponse> {
+    return this.send({ channel, text });
+  }
+
+  /**
+   * Reply in a thread
+   */
+  async reply(channel: string, threadTs: string, text: string): Promise<ChatPostMessageResponse> {
+    return this.send({ channel, text, thread_ts: threadTs });
+  }
+
+  /**
+   * Update a message
+   */
+  async update(channel: string, ts: string, text: string): Promise<SlackMessage> {
+    const response = await this.client.post<{ ok: boolean; message: SlackMessage }>(
+      'chat.update',
+      { channel, ts, text }
+    );
+    return response.message;
+  }
+
+  /**
+   * Delete a message
+   */
+  async delete(channel: string, ts: string): Promise<void> {
+    await this.client.post('chat.delete', { channel, ts });
+  }
+
+  /**
+   * Add a reaction to a message
+   */
+  async addReaction(channel: string, timestamp: string, emoji: string): Promise<void> {
+    await this.client.post('reactions.add', {
+      channel,
+      timestamp,
+      name: emoji.replace(/:/g, ''),
+    });
+  }
+
+  /**
+   * Remove a reaction from a message
+   */
+  async removeReaction(channel: string, timestamp: string, emoji: string): Promise<void> {
+    await this.client.post('reactions.remove', {
+      channel,
+      timestamp,
+      name: emoji.replace(/:/g, ''),
+    });
+  }
+
+  /**
+   * Get thread replies
+   */
+  async thread(channel: string, ts: string, limit = 100): Promise<SlackMessage[]> {
+    const response = await this.client.get<{ ok: boolean; messages: SlackMessage[] }>(
+      'conversations.replies',
+      { channel, ts, limit }
+    );
+    return response.messages;
+  }
+
+  /**
+   * Search messages
+   */
+  async search(query: string, count = 20): Promise<SlackMessage[]> {
+    const response = await this.client.get<{
+      ok: boolean;
+      messages: { matches: SlackMessage[] };
+    }>('search.messages', { query, count });
+    return response.messages.matches;
+  }
+}