@maroonedsoftware/slack 1.8.0

package/dist/slack.error.d.ts

@@ -0,0 +1,18 @@
+import { ServerkitError } from '@maroonedsoftware/errors';
+/**
+ * Domain error raised by the Slack package for non-HTTP failures (e.g.
+ * incoming-webhook POST failed, unknown handler dispatch).
+ *
+ * Extends {@link ServerkitError} so `errorMiddleware` renders a 500 with
+ * `{ message, details }` if one of these escapes a route handler. Inside
+ * route handlers, throw `httpError(...)` directly for status-coded responses.
+ */
+export declare class SlackError extends ServerkitError {
+}
+/**
+ * Type guard for {@link SlackError}. Narrows `unknown` to `SlackError` so
+ * `details`, `internalDetails`, and the chainable setters are accessible
+ * without further checks. Returns `true` for any subclass.
+ */
+export declare const IsSlackError: (error: unknown) => error is SlackError;
+//# sourceMappingURL=slack.error.d.ts.map

package/dist/slack.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.error.d.ts","sourceRoot":"","sources":["../src/slack.error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;;;;;GAOG;AACH,qBAAa,UAAW,SAAQ,cAAc;CAAG;AAEjD;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,UAAyC,CAAC"}

package/dist/slack.event.handler.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Metadata accompanying every dispatched Slack event. Includes the wrapping
+ * envelope fields (team/event IDs) plus the raw `event_callback` payload for
+ * handlers that need fields the typed `event` object doesn't expose.
+ */
+export type SlackEventContext = {
+    /** Slack workspace / team ID from the envelope. */
+    teamId: string;
+    /** Unique event ID Slack assigns to each delivery. */
+    eventId: string;
+    /** Unix timestamp the event was generated. */
+    eventTime: number;
+    /** Original `event_callback` envelope, untouched. */
+    envelope: SlackEventCallback;
+};
+/**
+ * Slack `event_callback` envelope. The shape is documented at
+ * https://api.slack.com/types/event. We type the wrapper but leave the inner
+ * `event` as `Record<string, unknown>` because the union of all Slack event
+ * payloads is large and consumers typically narrow per handler.
+ */
+export type SlackEventCallback = {
+    type: 'event_callback';
+    team_id: string;
+    api_app_id: string;
+    event: {
+        type: string;
+    } & Record<string, unknown>;
+    event_id: string;
+    event_time: number;
+    authorizations?: unknown[];
+    is_ext_shared_channel?: boolean;
+    event_context?: string;
+    [key: string]: unknown;
+};
+/**
+ * Handler for a single Slack event type (e.g. `app_mention`, `message`,
+ * `reaction_added`). Registered in {@link SlackEventHandlerMap}.
+ *
+ * Handlers should ack quickly — Slack retries any event that doesn't get a
+ * 2xx response within ~3 seconds. For slow work, enqueue a job
+ * (`@maroonedsoftware/jobbroker`) inside `handle` and return immediately.
+ */
+export interface SlackEventHandler<TEvent extends {
+    type: string;
+} & Record<string, unknown> = {
+    type: string;
+} & Record<string, unknown>> {
+    handle(event: TEvent, context: SlackEventContext): Promise<void>;
+}
+//# sourceMappingURL=slack.event.handler.d.ts.map

package/dist/slack.event.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.event.handler.d.ts","sourceRoot":"","sources":["../src/slack.event.handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB,CAAC,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACvI,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE"}

package/dist/slack.interaction.handler.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The supported interactive payload types Slack POSTs to the interactivity
+ * endpoint. Each maps to a different identifier shape (see
+ * {@link interactionRouteKey}).
+ */
+export type SlackInteractionType = 'block_actions' | 'view_submission' | 'view_closed' | 'shortcut' | 'message_action' | string;
+/**
+ * Loose typing for the interactive payload; consumers narrow per handler.
+ * Slack's payloads vary by type, but every variant has a `type` field plus
+ * one of: `actions[].action_id`, `view.callback_id`, or top-level `callback_id`.
+ */
+export type SlackInteractionPayload = {
+    type: SlackInteractionType;
+    team?: {
+        id: string;
+        domain?: string;
+    };
+    user?: {
+        id: string;
+        name?: string;
+    };
+    trigger_id?: string;
+    response_url?: string;
+    actions?: Array<{
+        action_id: string;
+        block_id?: string;
+        value?: string;
+        [key: string]: unknown;
+    }>;
+    view?: {
+        id: string;
+        callback_id: string;
+        [key: string]: unknown;
+    };
+    callback_id?: string;
+    [key: string]: unknown;
+};
+/**
+ * Optional response Slack accepts for `view_submission` / `view_closed`
+ * payloads (e.g. to display validation errors or update a modal).
+ */
+export type SlackInteractionResponse = {
+    response_action?: 'errors' | 'update' | 'push' | 'clear';
+    errors?: Record<string, string>;
+    view?: unknown;
+    [key: string]: unknown;
+};
+/**
+ * Handler for one interactive payload, keyed in {@link SlackInteractionHandlerMap}
+ * by `${type}:${identifier}` — see {@link interactionRouteKey}.
+ */
+export interface SlackInteractionHandler {
+    handle(payload: SlackInteractionPayload): Promise<SlackInteractionResponse | void>;
+}
+/**
+ * Computes the routing key used by {@link SlackDispatcher.dispatchInteraction}
+ * to look a handler up in {@link SlackInteractionHandlerMap}.
+ *
+ * - `block_actions` → `block_actions:<first action.action_id>`
+ * - `view_submission` / `view_closed` → `<type>:<view.callback_id>`
+ * - `shortcut` / `message_action` → `<type>:<callback_id>`
+ * - any other type with a `callback_id` → `<type>:<callback_id>`
+ *
+ * @returns The routing key, or `undefined` if the payload doesn't carry an
+ *   identifier we can route on (e.g. a `block_actions` payload with no actions).
+ */
+export declare const interactionRouteKey: (payload: SlackInteractionPayload) => string | undefined;
+//# sourceMappingURL=slack.interaction.handler.d.ts.map

package/dist/slack.interaction.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.interaction.handler.d.ts","sourceRoot":"","sources":["../src/slack.interaction.handler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,iBAAiB,GAAG,aAAa,GAAG,UAAU,GAAG,gBAAgB,GAAG,MAAM,CAAC;AAEhI;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IAClG,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,eAAe,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CAAC;CACpF;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS,uBAAuB,KAAG,MAAM,GAAG,SAmB/E,CAAC"}

package/dist/slack.signature.d.ts

@@ -0,0 +1,65 @@
+/** Default replay-protection window in seconds (5 minutes — matches Slack's recommendation). */
+export declare const SLACK_SIGNATURE_DEFAULT_MAX_AGE_SECONDS = 300;
+/**
+ * Reason codes attached to {@link SlackError.internalDetails} when verification
+ * fails. Useful for callers that want to log structured reasons without
+ * pattern-matching on error messages.
+ */
+export type SlackSignatureFailureReason = 'missing_timestamp' | 'invalid_timestamp' | 'stale_timestamp' | 'missing_signature' | 'invalid_signature';
+/**
+ * Inputs to {@link verifySlackSignature}. All values are taken verbatim from
+ * the request — the helper does no header lookups or body reads of its own.
+ */
+export type VerifySlackSignatureInput = {
+    /** App signing secret (`SlackConfig.signingSecret`). */
+    signingSecret: string;
+    /** Raw, unparsed request body — exactly as Slack sent it. */
+    rawBody: string;
+    /** Value of the `X-Slack-Request-Timestamp` header. */
+    timestamp: string | undefined;
+    /** Value of the `X-Slack-Signature` header (e.g. `"v0=abc123…"`). */
+    signature: string | undefined;
+    /**
+     * Maximum age in seconds before the request is rejected as a replay.
+     * Defaults to {@link SLACK_SIGNATURE_DEFAULT_MAX_AGE_SECONDS}.
+     */
+    maxAgeSeconds?: number;
+    /**
+     * Override for the current Unix time in seconds. Mostly useful for tests;
+     * defaults to `Math.floor(Date.now() / 1000)`.
+     */
+    now?: number;
+};
+/**
+ * Verifies a Slack request signature against the app signing secret.
+ *
+ * Implements Slack's v0 scheme:
+ * 1. Reject the request if `X-Slack-Request-Timestamp` is missing, non-numeric,
+ *    or older than `maxAgeSeconds` (replay protection).
+ * 2. Compute `v0=` + `HMAC-SHA256(signingSecret, "v0:{timestamp}:{rawBody}")`
+ *    as hex.
+ * 3. Compare against the provided `X-Slack-Signature` value using a
+ *    constant-time compare.
+ *
+ * Pure: no request/context coupling. The caller extracts the headers and raw
+ * body from whatever transport it's using and passes them in.
+ *
+ * @throws {@link SlackError} on any failure. The error's `internalDetails.reason`
+ *   is one of {@link SlackSignatureFailureReason}; map to HTTP 401 at the route boundary.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   verifySlackSignature({
+ *     signingSecret: config.signingSecret,
+ *     rawBody,
+ *     timestamp: req.headers['x-slack-request-timestamp'],
+ *     signature: req.headers['x-slack-signature'],
+ *   });
+ * } catch (err) {
+ *   throw httpError(401).withCause(err);
+ * }
+ * ```
+ */
+export declare const verifySlackSignature: (input: VerifySlackSignatureInput) => void;
+//# sourceMappingURL=slack.signature.d.ts.map

package/dist/slack.signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack.signature.d.ts","sourceRoot":"","sources":["../src/slack.signature.ts"],"names":[],"mappings":"AAGA,gGAAgG;AAChG,eAAO,MAAM,uCAAuC,MAAM,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GACnC,mBAAmB,GACnB,mBAAmB,GACnB,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,CAAC;AAExB;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,qEAAqE;IACrE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,yBAAyB,KAAG,IAkDvE,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@maroonedsoftware/slack",
+  "version": "1.8.0",
+  "description": "Slack utilities for ServerKit.",
+  "author": {
+    "name": "Marooned Software",
+    "url": "https://github.com/MaroonedSoftware/serverkit"
+  },
+  "bugs": {
+    "url": "https://github.com/MaroonedSoftware/serverkit/issues"
+  },
+  "homepage": "https://github.com/MaroonedSoftware/serverkit/packages/slack#readme",
+  "keywords": [
+    "backend",
+    "slack",
+    "serverkit",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MaroonedSoftware/serverkit.git"
+  },
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "files": [
+    "dist/**"
+  ],
+  "dependencies": {
+    "@slack/web-api": "^7.15.1",
+    "injectkit": "^1.2.0",
+    "@maroonedsoftware/errors": "1.6.0",
+    "@maroonedsoftware/logger": "1.1.0"
+  },
+  "devDependencies": {
+    "@repo/config-eslint": "0.2.1",
+    "@repo/config-typescript": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --sourcemap --dts && tsc --emitDeclarationOnly --declaration",
+    "build:ci": "eslint --max-warnings=0 && pnpm run build",
+    "lint": "eslint --fix",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage"
+  }
+}