@cuylabs/channel-slack 0.1.0

package/dist/bolt.d.ts

@@ -0,0 +1,344 @@
+import { Application } from 'express';
+import { AppOptions, ExpressReceiverOptions, App, ExpressReceiver, SocketModeReceiverOptions } from '@slack/bolt';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { L as Logger } from './logging-Bl3HfcC8.js';
+
+/**
+ * OAuth and installation type declarations for the direct Slack adapter.
+ *
+ * Pure types — no runtime imports beyond `node:http` request/response.
+ * Mirrors the public surface of `@slack/oauth` enough that callers can
+ * implement custom installation/state stores without depending on Bolt's
+ * internal types.
+ */
+
+type SlackDirectAuthMode = "single-workspace" | "oauth" | "authorize";
+interface SlackOAuthError extends Error {
+    code: string;
+}
+interface SlackInstallURLOptions {
+    scopes?: string[];
+    userScopes?: string[];
+    redirectUri?: string;
+    metadata?: string;
+    teamId?: string;
+}
+interface SlackInstallationQuery {
+    teamId: string | undefined;
+    enterpriseId: string | undefined;
+    userId?: string;
+    conversationId?: string;
+    isEnterpriseInstall: boolean;
+}
+interface SlackInstallation {
+    team?: {
+        id: string;
+        name?: string;
+    } | undefined;
+    enterprise?: {
+        id: string;
+        name?: string;
+    } | undefined;
+    user: {
+        id: string;
+        token?: string;
+        refreshToken?: string;
+        expiresAt?: number;
+        scopes?: string[];
+    };
+    bot?: {
+        token: string;
+        refreshToken?: string;
+        expiresAt?: number;
+        scopes: string[];
+        id?: string;
+        userId?: string;
+    };
+    incomingWebhook?: {
+        url: string;
+        channel?: string;
+        channelId?: string;
+        configurationUrl?: string;
+    };
+    appId?: string;
+    tokenType?: "bot";
+    enterpriseUrl?: string;
+    isEnterpriseInstall?: boolean;
+    authVersion?: "v1" | "v2";
+    metadata?: string;
+}
+interface SlackInstallationStore {
+    storeInstallation(installation: SlackInstallation, logger?: unknown): Promise<void>;
+    fetchInstallation(query: SlackInstallationQuery, logger?: unknown): Promise<SlackInstallation>;
+    deleteInstallation?(query: SlackInstallationQuery, logger?: unknown): Promise<void>;
+}
+interface SlackStateStore {
+    generateStateParam(installOptions: SlackInstallURLOptions, now: Date): Promise<string>;
+    verifyStateParam(now: Date, state: string): Promise<SlackInstallURLOptions>;
+}
+interface SlackOAuthInstallPathOptions {
+    beforeRedirection?: (request: IncomingMessage, response: ServerResponse, options?: SlackInstallURLOptions) => Promise<boolean>;
+}
+interface SlackOAuthCallbackOptions {
+    beforeInstallation?: (options: SlackInstallURLOptions, request: IncomingMessage, response: ServerResponse) => Promise<boolean>;
+    afterInstallation?: (installation: SlackInstallation, options: SlackInstallURLOptions, request: IncomingMessage, response: ServerResponse) => Promise<boolean>;
+    success?: (installation: SlackInstallation, options: SlackInstallURLOptions, request: IncomingMessage, response: ServerResponse) => void;
+    successAsync?: (installation: SlackInstallation, options: SlackInstallURLOptions, request: IncomingMessage, response: ServerResponse) => Promise<void>;
+    failure?: (error: SlackOAuthError, options: SlackInstallURLOptions, request: IncomingMessage, response: ServerResponse) => void;
+    failureAsync?: (error: SlackOAuthError, options: SlackInstallURLOptions, request: IncomingMessage, response: ServerResponse) => Promise<void>;
+}
+interface SlackAuthorizeSource {
+    teamId: string | undefined;
+    enterpriseId: string | undefined;
+    userId?: string;
+    conversationId?: string;
+    isEnterpriseInstall: boolean;
+}
+interface SlackAuthorizeResult {
+    botToken?: string;
+    userToken?: string;
+    botId?: string;
+    botUserId?: string;
+    userId?: string;
+    teamId?: string;
+    enterpriseId?: string;
+    [key: string]: unknown;
+}
+type SlackAuthorizeFn = (source: SlackAuthorizeSource, body?: unknown) => Promise<SlackAuthorizeResult>;
+interface SlackSingleWorkspaceAuthOptions {
+    mode?: "single-workspace";
+    botToken?: string;
+    botId?: string;
+    botUserId?: string;
+}
+interface SlackOAuthAuthOptions {
+    mode: "oauth";
+    clientId?: string;
+    clientSecret?: string;
+    stateSecret?: string;
+    installationStore: SlackInstallationStore;
+    stateStore?: SlackStateStore;
+    stateVerification?: boolean;
+    legacyStateVerification?: boolean;
+    stateCookieName?: string;
+    stateCookieExpirationSeconds?: number;
+    redirectUri?: string;
+    scopes?: string[];
+    userScopes?: string[];
+    metadata?: string;
+    installPath?: string;
+    callbackPath?: string;
+    renderHtmlForInstallPath?: (url: string) => string;
+    installPathOptions?: SlackOAuthInstallPathOptions;
+    callbackOptions?: SlackOAuthCallbackOptions;
+    directInstall?: boolean;
+    authVersion?: "v1" | "v2";
+    authorizationUrl?: string;
+}
+interface SlackCustomAuthorizeAuthOptions {
+    mode: "authorize";
+    authorize: SlackAuthorizeFn;
+}
+type SlackDirectAuthOptions = SlackSingleWorkspaceAuthOptions | SlackOAuthAuthOptions | SlackCustomAuthorizeAuthOptions;
+
+/**
+ * `createSlackBoltApp` — builds a Bolt `App` + `ExpressReceiver` pair from
+ * the package's structured `CreateSlackBoltAppOptions`. Supports
+ * single-workspace, OAuth, and custom-authorize auth modes.
+ */
+
+interface CreateSlackBoltAppOptions {
+    /**
+     * Slack signing secret used to verify inbound requests.
+     * Defaults to `SLACK_SIGNING_SECRET`.
+     */
+    signingSecret?: string;
+    /**
+     * Exact Slack Events API endpoint path.
+     * Defaults to `/slack/events`.
+     */
+    path?: string;
+    /**
+     * Direct-mode auth configuration.
+     *
+     * - omit for single-workspace token mode
+     * - use `{ mode: "oauth", ... }` for Bolt-managed installs
+     * - use `{ mode: "authorize", authorize }` for external token resolution
+     */
+    auth?: SlackDirectAuthOptions;
+    /**
+     * Convenience override for single-workspace mode.
+     * Defaults to `SLACK_BOT_TOKEN`.
+     */
+    botToken?: string;
+    /**
+     * Pre-existing Express app to mount onto.
+     */
+    app?: Application;
+    processBeforeResponse?: boolean;
+    signatureVerification?: boolean;
+    /**
+     * Additional Bolt `App` options passed through after this package sets
+     * receiver/auth. Use for logger/clientOptions and other native Bolt config.
+     */
+    boltAppOptions?: Partial<Omit<AppOptions, "receiver" | "token" | "authorize" | "botId" | "botUserId">>;
+    /**
+     * Additional Bolt `ExpressReceiver` options passed through after this
+     * package sets signing/auth/endpoints. Use for router, custom properties,
+     * and receiver-level error handlers.
+     */
+    receiverOptions?: Partial<Omit<ExpressReceiverOptions, "signingSecret" | "endpoints" | "processBeforeResponse" | "signatureVerification" | "app" | "clientId" | "clientSecret" | "stateSecret" | "installationStore" | "redirectUri" | "scopes" | "installerOptions">>;
+}
+interface CreateSlackBoltAppResult {
+    /** Bolt `App` used for event registration and outbound Slack calls. */
+    boltApp: App;
+    /** Bolt `ExpressReceiver` that owns request verification and OAuth routes. */
+    receiver: ExpressReceiver;
+    /** Express app that should receive `receiver.router`. */
+    app: Application;
+    /** Resolved direct auth mode. */
+    authMode: SlackDirectAuthMode;
+    /** Exact normalized events endpoint path. */
+    routePath: string;
+}
+declare function createSlackBoltApp(options?: CreateSlackBoltAppOptions): Promise<CreateSlackBoltAppResult>;
+
+/**
+ * `createSlackSocketBoltApp` — builds a Socket Mode Bolt `App` from the
+ * package's structured auth options. Mirrors `createSlackBoltApp` without
+ * owning any assistant/app surface mounting.
+ */
+
+type ControlledSocketBoltAppOption = "receiver" | "socketMode" | "appToken" | "token" | "authorize" | "botId" | "botUserId" | "clientId" | "clientSecret" | "stateSecret" | "redirectUri" | "installationStore" | "scopes" | "installerOptions";
+type ControlledSocketModeReceiverOption = "appToken" | "clientId" | "clientSecret" | "stateSecret" | "redirectUri" | "installationStore" | "scopes" | "installerOptions" | "logger" | "logLevel";
+interface CreateSlackSocketBoltAppOptions {
+    /**
+     * Slack app-level token (`xapp-...`) with `connections:write` scope.
+     * @default process.env.SLACK_APP_TOKEN
+     */
+    appToken?: string;
+    /**
+     * Convenience override for single-workspace mode.
+     * @default process.env.SLACK_BOT_TOKEN
+     */
+    botToken?: string;
+    /**
+     * Direct-mode auth configuration.
+     *
+     * - omit for single-workspace token mode
+     * - use `{ mode: "oauth", ... }` for Bolt-managed installs
+     * - use `{ mode: "authorize", authorize }` for external token resolution
+     */
+    auth?: SlackDirectAuthOptions;
+    /**
+     * Additional Bolt `App` options passed after this package sets Socket Mode
+     * and auth. Use for logger/clientOptions and non-auth native Bolt config.
+     */
+    boltAppOptions?: Partial<Omit<AppOptions, ControlledSocketBoltAppOption>>;
+    /**
+     * Additional native Socket Mode receiver options. Use this for websocket
+     * health tuning such as ping timeouts, reconnect behavior, and receiver
+     * error handling. Auth/OAuth fields stay controlled by this helper.
+     */
+    socketModeReceiverOptions?: Partial<Omit<SocketModeReceiverOptions, ControlledSocketModeReceiverOption>>;
+}
+interface CreateSlackSocketBoltAppResult {
+    boltApp: App;
+    authMode: SlackDirectAuthMode;
+}
+declare function createSlackSocketBoltApp(options?: CreateSlackSocketBoltAppOptions): Promise<CreateSlackSocketBoltAppResult>;
+
+interface SlackSocketModeProcessLockOptions {
+    appSlug: string;
+    appToken?: string;
+    enabled?: boolean;
+    lockDir?: string;
+    logger?: Logger;
+}
+interface SlackSocketModeProcessLock {
+    path: string;
+    release(): void;
+}
+declare function acquireSlackSocketModeProcessLock({ appSlug, appToken, enabled, lockDir, logger, }: SlackSocketModeProcessLockOptions): SlackSocketModeProcessLock | undefined;
+
+type SlackSdkLogLevel = "debug" | "info" | "warn" | "error";
+interface SlackSdkLogger {
+    debug(...msg: unknown[]): void;
+    error(...msg: unknown[]): void;
+    getLevel(): SlackSdkLogLevel;
+    info(...msg: unknown[]): void;
+    setLevel(nextLevel: SlackSdkLogLevel): void;
+    setName(nextName: string): void;
+    warn(...msg: unknown[]): void;
+}
+type SlackSocketModeRuntimePolicy = "single-instance" | "external-coordination";
+interface SlackSocketModeReceiverRuntimeOptions {
+    autoReconnectEnabled?: boolean;
+    clientPingTimeout?: number;
+    pingPongLoggingEnabled?: boolean;
+    serverPingTimeout?: number;
+}
+interface SlackSocketModeRuntimeOptions {
+    appSlug: string;
+    appToken?: string;
+    autoReconnectEnabled?: boolean;
+    clientPingTimeoutMs?: number;
+    exitProcess?: (code: number) => never | void;
+    lockDir?: string;
+    lockEnabled?: boolean;
+    logger?: Logger;
+    logLevel?: "debug" | "info" | "warn" | "error";
+    pingPongLoggingEnabled?: boolean;
+    restartGuardEnabled?: boolean;
+    restartGuardMaxWarnings?: number;
+    restartGuardWindowMs?: number;
+    runtimePolicy?: SlackSocketModeRuntimePolicy;
+    serverPingTimeoutMs?: number;
+}
+interface SlackSocketModeRuntime {
+    boltAppOptions: {
+        logger: SlackSdkLogger;
+    };
+    close(): void;
+    socketModeReceiverOptions: SlackSocketModeReceiverRuntimeOptions;
+}
+interface SlackSocketModeRestartGuard {
+    record(message: string): void;
+}
+declare function createSlackSocketModeRuntime({ appSlug, appToken, autoReconnectEnabled, clientPingTimeoutMs, exitProcess, lockDir, lockEnabled, logger, logLevel, pingPongLoggingEnabled, restartGuardEnabled, restartGuardMaxWarnings, restartGuardWindowMs, runtimePolicy, serverPingTimeoutMs, }: SlackSocketModeRuntimeOptions): SlackSocketModeRuntime;
+declare function createSlackSocketModeRestartGuard({ enabled, exitProcess, logger, maxWarnings, windowMs, }: {
+    enabled: boolean;
+    exitProcess: (code: number) => never | void;
+    logger?: Logger;
+    maxWarnings: number;
+    windowMs: number;
+}): SlackSocketModeRestartGuard;
+declare function createSlackSdkLogger({ level, logger, restartGuard, }: {
+    level: "debug" | "info" | "warn" | "error";
+    logger?: Logger;
+    restartGuard?: SlackSocketModeRestartGuard;
+}): SlackSdkLogger;
+declare function redactSlackSocketModeLogValue(value: unknown, depth?: number): unknown;
+
+declare class InMemorySlackInstallationStore implements SlackInstallationStore {
+    private devDB;
+    storeInstallation(installation: SlackInstallation): Promise<void>;
+    fetchInstallation(query: SlackInstallationQuery): Promise<SlackInstallation>;
+    deleteInstallation(query: SlackInstallationQuery): Promise<void>;
+}
+declare function createInMemorySlackInstallationStore(): SlackInstallationStore;
+declare class JsonFileSlackInstallationStore implements SlackInstallationStore {
+    private readonly filePath;
+    private pending;
+    constructor(filePath: string);
+    storeInstallation(installation: SlackInstallation): Promise<void>;
+    fetchInstallation(query: SlackInstallationQuery): Promise<SlackInstallation>;
+    deleteInstallation(query: SlackInstallationQuery): Promise<void>;
+    private withLock;
+    private readInstallations;
+    private writeInstallations;
+}
+declare function createJsonFileSlackInstallationStore(filePath: string): SlackInstallationStore;
+declare function getSlackInstallationKey(input: SlackInstallation | SlackInstallationQuery): string;
+
+export { type CreateSlackBoltAppOptions, type CreateSlackBoltAppResult, type CreateSlackSocketBoltAppOptions, type CreateSlackSocketBoltAppResult, InMemorySlackInstallationStore, JsonFileSlackInstallationStore, type SlackAuthorizeFn, type SlackAuthorizeResult, type SlackAuthorizeSource, type SlackCustomAuthorizeAuthOptions, type SlackDirectAuthMode, type SlackDirectAuthOptions, type SlackInstallation, type SlackInstallationQuery, type SlackInstallationStore, type SlackOAuthAuthOptions, type SlackOAuthCallbackOptions, type SlackOAuthError, type SlackOAuthInstallPathOptions, type SlackSdkLogLevel, type SlackSdkLogger, type SlackSingleWorkspaceAuthOptions, type SlackSocketModeProcessLock, type SlackSocketModeProcessLockOptions, type SlackSocketModeReceiverRuntimeOptions, type SlackSocketModeRestartGuard, type SlackSocketModeRuntime, type SlackSocketModeRuntimeOptions, type SlackSocketModeRuntimePolicy, type SlackStateStore, acquireSlackSocketModeProcessLock, createInMemorySlackInstallationStore, createJsonFileSlackInstallationStore, createSlackBoltApp, createSlackSdkLogger, createSlackSocketBoltApp, createSlackSocketModeRestartGuard, createSlackSocketModeRuntime, getSlackInstallationKey, redactSlackSocketModeLogValue };