skills/plugins/document-navigator/docs/communication/messaging/slack-client/README.md

@suaveplan/slack-client - Typed deterministic Slack client — Slack Web API + incoming-webhook surface, Zod-validated boundaries, OpenTelemetry-instrumented hot paths, injectable Clock/Rng/Logger/FetchLike, stable defineCodes('SLACK', [...]) error registry. Universal: runs unchanged in Bun, Node, and the browser.

Typed, deterministic Slack client — Web API + incoming-webhook surface — with Zod-validated boundaries, OpenTelemetry-instrumented hot paths, injectable Clock / Rng / LoggerLike / FetchLike, and a stable defineCodes("SLACK", […]) error registry.

Universal: runs unchanged in Bun, Node, and the browser.

Documentation tree

• classify — classify.ts exports two pure mapping functions that fold transport-level failure signals into the stable `SLACK_CODES…
• retry-after — retry-after.ts exports a single pure function parseRetryAfterMs(response, clock?) that converts an HTTP `Retry-Afte…
• slack-api-client — SlackApiClient is the typed transport for the Slack Web API. It exposes the six methods downstream packages rely on —…
• error-codes — error-codes.ts is the single source of truth for every error the @suaveplan/slack-client package can throw. It regi…
  • error-codes — error-codes.ts is the single source of truth for every error the @suaveplan/slack-client package can throw. It regi…
• fakes — fake-fetch.ts exports FakeFetch, the deterministic test double the package's own unit tests use to exercise every t…
  • fake-fetch — fake-fetch.ts exports FakeFetch, the deterministic test double the package's own unit tests use to exercise every t…
• otel — metrics.ts registers four OpenTelemetry instruments under the meter name @suaveplan/slack-client and exports the he…
  • metrics — metrics.ts registers four OpenTelemetry instruments under the meter name @suaveplan/slack-client and exports the he…
• schemas — schemas.ts exports the Zod schemas that validate every public option bag and every Slack Web API request payload that…
  • schemas — schemas.ts exports the Zod schemas that validate every public option bag and every Slack Web API request payload that…
• webhook — SlackWebhook is the simpler half of the package — a typed wrapper around Slack's incoming-webhook URLs. Where `SlackA…
  • slack-webhook — SlackWebhook is the simpler half of the package — a typed wrapper around Slack's incoming-webhook URLs. Where `SlackA…

Install

bun add @suaveplan/slack-client

Two clients

• SlackApiClient — Slack Web API. Token-authenticated. Supports sendMessage, updateMessage, deleteMessage, listChannels, getChannelInfo, listUsers, getStatus.
• SlackWebhook — Slack incoming webhooks. URL-authenticated. Supports send and sendText.

Quickstart

import { SlackApiClient, SlackWebhook } from "@suaveplan/slack-client";

const api = new SlackApiClient({ token: process.env["SLACK_TOKEN"]! });
await api.sendMessage({ channel: "C0123", text: "Deploy succeeded." });

const hook = new SlackWebhook({
    webhookUrl: "https://hooks.slack.com/services/T/B/X",
});
await hook.sendText("Build broken on main.");

Modules

• error-codes — SLACK_CODES registry + 8 typed error subclasses.
• types/slack-client — public shapes.
• schemas/schemas — Zod boundary schemas.
• client/slack-api-client — Slack Web API client.
• client/retry-after — Retry-After / x-ratelimit-reset parser.
• client/classify — HTTP-status + Slack-error string classifier.
• webhook/slack-webhook — incoming-webhook client.
• otel/metrics — four OpenTelemetry instruments.
• fakes/fake-fetch — deterministic FetchLike test double.

Error codes

All eight reasons land under the SLACK.* namespace:

• SLACK.API_ERROR — generic non-ok response from the Slack API.
• SLACK.AUTH_ERROR — token rejected (HTTP 401/403, invalid_auth, token_revoked, account_inactive).
• SLACK.RATE_LIMITED — HTTP 429; context.retryAfterMs carries parsed delay.
• SLACK.CHANNEL_NOT_FOUND — HTTP 404 or channel_not_found / is_archived / not_in_channel.
• SLACK.WORKSPACE_NOT_FOUND — team_not_found / no_workspace.
• SLACK.CONFIG_MISSING — empty/invalid token or webhook URL at construct time.
• SLACK.WEBHOOK_FAILED — webhook POST returned non-2xx (non-auth).
• SLACK.TIMEOUT — internal timeoutMs fired OR caller AbortSignal aborted OR network failure.

OpenTelemetry

Four instruments under meter @suaveplan/slack-client@0.1.0:

• slack.requests (counter) — { method, outcome }
• slack.errors (counter) — { method, code }
• slack.latency_ms (histogram, unit ms) — { method, outcome }
• slack.webhook_sends (counter) — { outcome }

License

MIT