@microfox/slack
Version:
This package provides a lightweight, proxy interface to the official Slack Web API, offering a curated set of the most commonly used functions for building Slack integrations. It is designed to be simple, efficient, and easy to integrate into your project
343 lines (340 loc) • 13.3 kB
text/typescript
import { WebClientOptions, ConversationsListResponse, ConversationsInfoResponse, UsersListResponse, UsersLookupByEmailResponse, ChatPostMessageResponse, RemindersAddResponse, ConversationsCreateResponse, ReactionsAddResponse, UsersInfoResponse, UsersConversationsResponse, ConversationsJoinResponse, ConversationsInviteResponse, ConversationsKickResponse, FilesInfoResponse, ConversationsHistoryResponse, FilesCompleteUploadExternalResponse } from '@slack/web-api';
import { Buffer } from 'buffer';
declare class MicrofoxSlackClient {
private web;
constructor(token: string, options?: WebClientOptions);
/**
* Lists channels in a workspace.
* @param cursor A cursor to the next page of results.
* @param limit The maximum number of channels to return.
* @param types Channel types to include. Defaults to all types (public, private, im).
*/
getChannels({ cursor, limit, types, }: {
cursor?: string;
limit?: number;
types?: ('public' | 'private' | 'im')[];
}): Promise<{
channels: ConversationsListResponse['channels'];
nextCursor: string | undefined;
}>;
/**
* Lists channel IDs and names in a workspace.
* @param cursor A cursor to the next page of results.
* @param limit The maximum number of channels to return.
* @param types Channel types to include. Defaults to all types (public, private, im).
*/
getChannelsIds({ cursor, limit, types, }: {
cursor?: string;
limit?: number;
types?: ('public' | 'private' | 'im')[];
}): Promise<{
channels: {
id: string;
name: string;
}[];
nextCursor: string | undefined;
}>;
/**
* Fetches information about a conversation.
* @param channelId Conversation ID to fetch information for.
*/
getChannelConversationInfo({ channelId }: {
channelId: string;
}): Promise<ConversationsInfoResponse['channel']>;
/**
* Lists all users in a workspace.
* @param cursor A cursor to the next page of results.
* @param limit The maximum number of users to return.
* @param includeBots Whether to include bots.
*/
getActiveUsers({ cursor, limit, includeBots, }: {
cursor?: string;
limit?: number;
includeBots?: boolean;
}): Promise<{
users: UsersListResponse['members'];
nextCursor: string | undefined;
}>;
/**
* Lists all users in a workspace.
* @param cursor A cursor to the next page of results.
* @param limit The maximum number of users to return.
* @param includeBots Whether to include bots.
*/
getActiveUsersIds({ cursor, limit, includeBots, }: {
includeBots?: boolean;
cursor?: string;
limit?: number;
}): Promise<{
users: {
id: string;
name: string;
real_name: string;
display_name: string;
title: string;
email: string;
}[];
nextCursor: string | undefined;
}>;
/**
* Lists all users in a channel.
* @param channelId Channel ID to get members of.
*/
getChannelMembers({ channelId, includeBots, limit, nextCursor }: {
channelId: string;
includeBots?: boolean;
limit?: number;
nextCursor?: string;
}): Promise<{
members: {
id: string;
name: string;
is_bot: boolean;
real_name: string;
display_name: string;
title: string;
email: string;
is_deleted: boolean;
}[];
nextCursor: string | undefined;
}>;
/**
* Finds a user by their email address.
* @param email The email address of the user to find.
*/
getUserByEmail({ email }: {
email: string;
}): Promise<UsersLookupByEmailResponse['user']>;
/**
* Finds users by their email addresses.
* @param emails The email addresses of the users to find.
*/
getUsersByEmails({ emails }: {
emails: string[];
}): Promise<UsersLookupByEmailResponse['user'][]>;
/**
* Sends a direct message to a user.
* @param userId The ID of the user to message.
* @param text The text of the message to send.
* @param username Optional custom username for the message.
* @param icon_url Optional URL to an image to use as the icon for the message.
*/
messageUser({ userId, text, username, icon_url, }: {
userId: string;
text: string;
username?: string;
icon_url?: string;
}): Promise<ChatPostMessageResponse>;
/**
* Sends a message to a channel.
* @param channelId The ID of the channel to message.
* @param text The text of the message to send.
* @param username Optional custom username for the message.
* @param icon_url Optional URL to an image to use as the icon for the message.
*/
messageChannel({ channelId, text, username, icon_url, }: {
channelId: string;
text: string;
username?: string;
icon_url?: string;
}): Promise<ChatPostMessageResponse>;
/**
* Sends a direct message to multiple users with optional templating.
* @param userIds The IDs of the users to message.
* @param text The text of the message to send. Can include template variables for personalization.
* @param username Optional custom username for the message.
* @param icon_url Optional URL to an image to use as the icon for the message.
*
* Available template variables:
* - {mention} - Mentions the user (@username)
* - {user_name} - User's name (fallback: username -> real_name -> display_name)
* - {user_email} - User's email address
* - {user_title} - User's job title
* - {user_phone} - User's phone number
* - {user_status} - User's status text
* - {user_avatar} - User's profile image URL
* - {first_name} - User's first name
* - {last_name} - User's last name
*
* @example
* ```typescript
* // Simple message
* await client.messageUsers({
* userIds: ['U1234567890', 'U0987654321'],
* text: "Hello everyone!"
* });
*
* // Templated message
* await client.messageUsers({
* userIds: ['U1234567890', 'U0987654321'],
* text: "Hi {mention}! Your title is {user_title} and email is {user_email}."
* });
* ```
*/
messageUsers({ userIds, text, username, icon_url, }: {
userIds: string[];
text: string;
username?: string;
icon_url?: string;
}): Promise<ChatPostMessageResponse[]>;
/**
* Sends a message to multiple channels.
* @param channelIds The IDs of the channels to message.
* @param text The text of the message to send.
* @param username Optional custom username for the message.
* @param icon_url Optional URL to an image to use as the icon for the message.
*/
messageChannels({ channelIds, text, username, icon_url, }: {
channelIds: string[];
text: string;
username?: string;
icon_url?: string;
}): Promise<ChatPostMessageResponse[]>;
/**
* Sets a reminder for a user.
* @param userId The ID of the user to set a reminder for.
* @param text The text of the reminder.
* @param time A string describing when the reminder should fire (e.g., "in 5 minutes" or a Unix timestamp).
*/
setReminder({ userId, text, time }: {
userId: string;
text: string;
time: string;
}): Promise<RemindersAddResponse>;
/**
* Creates a new channel.
* @param name The name of the channel to create.
* @param isPrivate Whether the channel should be private. Defaults to false.
* @param join Whether to join the channel after creation. Defaults to true.
* @param userIds Optional array of user IDs to add to the channel after creation.
*/
createChannel({ name, isPrivate, userIds, }: {
name: string;
isPrivate?: boolean;
join?: boolean;
userIds?: string[];
}): Promise<ConversationsCreateResponse['channel']>;
/**
* Adds a reaction to a message.
* @param channelId The ID of the channel where the message is.
* @param timestamp The timestamp of the message to react to.
* @param reaction The name of the emoji to use for the reaction.
*/
reactMessage({ channelId, timestamp, reaction }: {
channelId: string;
timestamp: string;
reaction: string;
}): Promise<ReactionsAddResponse>;
/**
* Gets information about a user.
* @param userId The ID of the user to get information for.
*/
getUserInfo({ userId }: {
userId: string;
}): Promise<UsersInfoResponse['user']>;
/**
* Fetches a list of conversations a user is a member of.
* @param userId The ID of the user to fetch conversations for.
* @param cursor A cursor to the next page of results.
* @param limit The maximum number of conversations to return.
* @param types An array of conversation types to include.
* @param excludeArchived Whether to exclude archived conversations.
*/
getUserChannels({ userId, cursor, limit, types, excludeArchived, }: {
userId: string;
cursor?: string;
limit?: number;
types?: ('public_channel' | 'private_channel' | 'mpim' | 'im')[];
excludeArchived?: boolean;
}): Promise<{
channels: UsersConversationsResponse['channels'];
nextCursor: string | undefined;
}>;
/**
* Replies to a message in a thread.
* @param channelId The ID of the channel where the message is.
* @param thread_ts The timestamp of the message to reply to, establishing the thread.
* @param text The text of the reply.
* @param username Optional custom username for the message.
* @param icon_url Optional URL to an image to use as the icon for the message.
*/
replyMessage({ channelId, thread_ts, text, username, icon_url, }: {
channelId: string;
thread_ts: string;
text: string;
username?: string;
icon_url?: string;
}): Promise<ChatPostMessageResponse>;
/**
* Joins a channel.
* @param channelId The ID of the channel to join.
*/
joinChannel({ channelId }: {
channelId: string;
}): Promise<ConversationsJoinResponse>;
/**
* Adds multiple users to a channel.
* @param channelId The ID of the channel to add users to.
* @param userIds Array of user IDs to add to the channel.
*/
addUsersToChannel({ channelId, userIds }: {
channelId: string;
userIds: string[];
}): Promise<ConversationsInviteResponse[]>;
/**
* Removes a user from a channel.
* @param channelId The ID of the channel to remove the user from.
* @param userId The ID of the user to remove.
*/
removeUserFromChannel({ channelId, userId }: {
channelId: string;
userId: string;
}): Promise<ConversationsKickResponse>;
/**
* Gets information about a file.
* @param fileId The ID of the file to get information for.
*/
getFileInfo({ fileId }: {
fileId: string;
}): Promise<FilesInfoResponse['file']>;
/**
* Fetches a conversation's history of messages and events.
* @param channelId Conversation ID to fetch history for.
* @param limit The maximum number of items to return.
* @param latest End of the time range of messages to include in results.
* @param oldest Start of the time range of messages to include in results.
* @param inclusive Include messages with latest or oldest timestamps in results.
* @param cursor Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request's response_metadata.
*/
getConversationHistory({ channelId, limit, latest, oldest, inclusive, cursor, }: {
channelId: string;
limit?: number;
latest?: string;
oldest?: string;
inclusive?: boolean;
cursor?: string;
}): Promise<{
messages: ConversationsHistoryResponse['messages'];
nextCursor: string | undefined;
}>;
/**
* Uploads a file to a channel using an external URL.
* @param filename The name of the file.
* @param file A Buffer containing the file content.
* @param channelId The ID of the channel to upload the file to. Can be a comma-separated list of strings.
* @param alt_text Description of image for screen-reader.
* @param snippet_type Syntax type of the snippet being uploaded.
* @param initialComment The message text introducing the file in specified channels.
* @param title An optional title for the file.
*/
uploadFile({ filename, file, channelId, alt_text, snippet_type, initialComment, title, }: {
filename: string;
file: Buffer;
channelId?: string;
alt_text?: string;
snippet_type?: string;
initialComment?: string;
title?: string;
}): Promise<FilesCompleteUploadExternalResponse['files']>;
}
export { MicrofoxSlackClient };