@tightknitai/slack-block-kit-validator 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tightknit and slack-block-kit-validator contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# slack-block-kit-validator
+
+[![CI](https://github.com/TightknitAI/slack-block-kit-validator/actions/workflows/ci.yml/badge.svg)](https://github.com/TightknitAI/slack-block-kit-validator/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@tightknitai/slack-block-kit-validator.svg)](https://www.npmjs.com/package/@tightknitai/slack-block-kit-validator)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+JSON Schema (draft 2020-12) and validation helpers for Slack Block Kit JSON. Catches invalid block payloads before Slack silently swallows them.
+
+## Why this exists
+
+Slack's API returns `200 OK` when you send malformed Block Kit JSON — the metadata is dropped and the message renders as plain text (or a modal opens blank). The only way to find out is to eyeball a real Slack channel. Slack hasn't open-sourced their validator.
+
+This package compiles every rule in <https://docs.slack.dev/reference/block-kit> into a single JSON Schema, plus a handful of helpers for the cross-payload rules JSON Schema can't express (duplicate `block_id`, cumulative markdown length, one-table-per-message, `focus_on_load` uniqueness, surface compatibility).
+
+## Install
+
+```sh
+pnpm add @tightknitai/slack-block-kit-validator
+```
+
+Node 20+. No runtime peer dependencies.
+
+## Quick start
+
+```ts
+import { validateBlockKit } from "@tightknitai/slack-block-kit-validator";
+
+const blocks = [
+  { type: "section", text: { type: "mrkdwn", text: "Hello *world*" } },
+];
+
+const { valid, errors } = validateBlockKit(blocks);
+if (!valid) {
+  console.error(errors);
+}
+```
+
+### Validating views
+
+`validateBlockKit` takes an optional `target` for modal / home view envelopes:
+
+```ts
+validateBlockKit(modalView, { target: "modal" });
+validateBlockKit(homeView, { target: "home" });
+```
+
+When `target` is `modal` or `home`, the surface-compatibility check is enforced automatically. For bare blocks arrays, pass `surface` explicitly:
+
+```ts
+validateBlockKit(blocks, { surface: "message" });
+// rejects input blocks, table on non-message surfaces, etc.
+```
+
+### Example output
+
+```ts
+validateBlockKit([
+  { type: "section" },
+  { type: "divider", block_id: "x" },
+  { type: "divider", block_id: "x" },
+]);
+
+// {
+//   valid: false,
+//   errors: [
+//     "/0 must match a schema in anyOf",
+//     "blocks[2].block_id must be unique — 'x' appears at index 1 and 2"
+//   ]
+// }
+```
+
+## Using the helpers à la carte
+
+The helpers are pure (no deps, no Ajv) and can be stacked on top of any validator — Zod, TypeBox, or a hand-rolled check:
+
+```ts
+import {
+  findDuplicateBlockIds,
+  checkCumulativeMarkdownLength,
+  checkSingleTableBlock,
+  checkFocusOnLoadUniqueness,
+  checkSurfaceCompatibility,
+} from "@tightknitai/slack-block-kit-validator";
+```
+
+### Using the raw JSON Schema
+
+Consuming from another validator, another language, or an OpenAPI spec:
+
+```ts
+import { slackBlockKitSchema } from "@tightknitai/slack-block-kit-validator";
+
+// With Ajv in a custom config
+const ajv = new Ajv2020({ strict: false, allErrors: true });
+const validate = ajv.compile(slackBlockKitSchema);
+```
+
+The schema uses `$defs` for every block, element, composition object, rich-text leaf, and view envelope, so non-JS consumers can also import the JSON (`@tightknitai/slack-block-kit-validator/schema.json`) and pick the subset they need.
+
+## API reference
+
+### Wrapper
+
+| Export | Signature | Description |
+|---|---|---|
+| `validateBlockKit` | `(input, opts?) => { valid, errors[] }` | Runs schema + all caveat helpers. Defaults to validating a bare blocks array. |
+| `ValidationResult` | `{ valid: boolean; errors: string[] }` | Return type. |
+| `ValidationTarget` | `'blocks' \| 'modal' \| 'home'` | What shape `input` should match. |
+| `ValidateBlockKitOptions` | `{ target?, surface? }` | Options bag. |
+| `Surface` | `'message' \| 'modal' \| 'home'` | Surface compatibility target. |
+
+### Helpers
+
+| Helper | Signature | What it checks |
+|---|---|---|
+| `findDuplicateBlockIds` | `(blocks) => string[]` | Duplicate `block_id` values in a blocks array. |
+| `checkCumulativeMarkdownLength` | `(blocks) => string[]` | Sum of all `markdown` block text > 12,000 chars. |
+| `checkSingleTableBlock` | `(blocks) => string[]` | More than one `table` block per payload. |
+| `checkFocusOnLoadUniqueness` | `(blocks) => string[]` | More than one element with `focus_on_load: true` in a view (walks nested elements + accessories). |
+| `checkSurfaceCompatibility` | `(blocks, surface) => string[]` | Blocks not allowed on the target surface (e.g. `input` on message, `video` on modal, `file_input` outside modals). |
+| `checkCardActionsMax` | `(blocks) => string[]` | More than `CARD_ACTIONS_MAX` action buttons on a card block. |
+| `checkNumberInputBounds` | `(blocks) => string[]` | `number_input` element with `min_value > max_value`. |
+| `checkResponseUrlEnabledContext` | `(blocks, surface?) => string[]` | `response_url_enabled` set in contexts that don't support it. |
+
+Each returns an array of human-readable error strings — empty when valid.
+
+### Schema
+
+| Export | Description |
+|---|---|
+| `slackBlockKitSchema` | The full JSON Schema as a parsed object. `$id` is `https://tightknit.com/schemas/slack-block-kit.schema.json`. |
+
+## Coverage
+
+- **18 blocks**: actions, alert, card, carousel, context, context_actions, divider, file, header, image, input, markdown, plan, rich_text, section, table, task_card, video.
+- **All block elements**: button, icon_button, workflow_button, feedback_buttons, plain_text / email / url / number inputs, datepicker, datetimepicker, timepicker, file_input, rich_text_input, checkboxes, radio_buttons, image, overflow, url source, and all 5 single + 5 multi-select menu variants.
+- **All 9 composition objects**: text (plain_text + mrkdwn), confirm, option (3 contextual variants), option_group, slack_file, dispatch_action_config, conversation_filter, trigger, workflow.
+- **Rich text**: 4 container kinds (section, list, preformatted, quote) + 10 leaf kinds (text, link, user, usergroup, team, channel, emoji, broadcast, color, date) with style flags.
+- **View envelopes**: `modal_view` + `home_view` under `$defs`.
+- **Cross-payload rules** (via helpers): dup `block_id`, cumulative markdown, single-table, `focus_on_load` uniqueness, surface compatibility.
+
+Every documented `maxLength`, regex (date / time / user ID / channel ID / team ID format), enum value, and array cardinality limit is enforced structurally.
+
+## What isn't enforced
+
+Server-side rules that need app-config context or deep equality checks the schema doesn't attempt:
+
+- Slack OAuth scope requirements (e.g. `links.embed:write` for video blocks).
+- Initial-value matching (e.g. `radio_buttons.initial_option` must equal one of `options` by deep equality).
+- `video_url` must match the app's configured unfurl domains.
+- 10 MB per-file limit on `file_input` uploads.
+- Slack's `block_id`-must-not-start-with `block_` rule is folklore (not stated on any current docs page) and intentionally not enforced.
+
+## Note on `undefined` properties
+
+`validateBlockKit` strips properties whose value is `undefined` before running Ajv. `JSON.stringify` drops these before the payload reaches Slack, so common builder patterns like `value: foo ?? undefined` are no-ops on the wire but would otherwise trip the schema's `additionalProperties: false`. Explicit `null` values are preserved — they survive `JSON.stringify` and may legitimately fail the schema.
+
+## Runtime & bundle considerations
+
+Ajv v8 + ajv-formats weigh ~50–60 KB gzipped, which is fine for Node test runs but noticeable in a Cloudflare Worker bundle. If you want runtime validation inside a Worker, use the package's `compile:standalone` script to emit a self-contained validator that doesn't import Ajv at runtime:
+
+```sh
+pnpm dlx ajv compile --spec=draft2020 --strict=false -c ajv-formats \
+  -s node_modules/@tightknitai/slack-block-kit-validator/dist/slack-block-kit.schema.json \
+  -o standalone-validator.js
+```
+
+For most apps the recommended pattern is **validate in tests only** — use `validateBlockKit` in unit tests next to your block builders, and let CI catch regressions before they hit production.
+
+## Keeping up with Slack
+
+Slack adds new block types and fields over time. To update:
+
+1. Diff the latest at <https://docs.slack.dev/reference/block-kit> against the commit history of `src/slack-block-kit.schema.json`.
+2. Add or amend the relevant `$defs/*` entry, including required / optional / maxLength / enum.
+3. For new top-level blocks, add to `$defs/block.oneOf` and the `modal_view` / `home_view` inner arrays if applicable.
+4. For new elements, add to the relevant parent-container whitelist (`actions_block_element`, `section_accessory_element`, `input_block_element`, `context_block_element`, or `context_actions_block_element`).
+5. Add fixtures to `test/` covering both valid and invalid payloads.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+---
+
+Maintained by the [Tightknit](https://tightknit.ai) team.

package/dist/helpers/check-card-actions-max.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Maximum number of action buttons allowed inside a single `card` block.
+ */
+export declare const CARD_ACTIONS_MAX = 2;
+/**
+ * Checks that every `card` block contains at most {@link CARD_ACTIONS_MAX}
+ * action buttons. Slack's card surface only renders up to two action buttons
+ * in the action row; additional buttons are clipped or rejected.
+ * @param blocks - array of Block Kit blocks
+ * @returns array of error messages (empty when no card exceeds the limit)
+ */
+export declare function checkCardActionsMax(blocks: readonly {
+    type?: string;
+    actions?: readonly unknown[];
+}[]): string[];
+//# sourceMappingURL=check-card-actions-max.d.ts.map

package/dist/helpers/check-card-actions-max.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-card-actions-max.d.ts","sourceRoot":"","sources":["../../src/helpers/check-card-actions-max.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,EAAE,GAAG,MAAM,EAAE,CAchH"}

package/dist/helpers/check-card-actions-max.js

@@ -0,0 +1,25 @@
+/**
+ * Maximum number of action buttons allowed inside a single `card` block.
+ */
+export const CARD_ACTIONS_MAX = 2;
+/**
+ * Checks that every `card` block contains at most {@link CARD_ACTIONS_MAX}
+ * action buttons. Slack's card surface only renders up to two action buttons
+ * in the action row; additional buttons are clipped or rejected.
+ * @param blocks - array of Block Kit blocks
+ * @returns array of error messages (empty when no card exceeds the limit)
+ */
+export function checkCardActionsMax(blocks) {
+    const errors = [];
+    blocks.forEach((block, i) => {
+        if (block?.type !== "card") {
+            return;
+        }
+        const actions = block.actions;
+        if (Array.isArray(actions) && actions.length > CARD_ACTIONS_MAX) {
+            errors.push(`blocks[${i}].actions card blocks allow at most ${CARD_ACTIONS_MAX} action buttons — found ${actions.length}`);
+        }
+    });
+    return errors;
+}
+//# sourceMappingURL=check-card-actions-max.js.map

package/dist/helpers/check-card-actions-max.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-card-actions-max.js","sourceRoot":"","sources":["../../src/helpers/check-card-actions-max.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAkE;IACpG,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC1B,IAAI,KAAK,EAAE,IAAI,KAAK,MAAM,EAAE,CAAC;YAC3B,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC9B,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,gBAAgB,EAAE,CAAC;YAChE,MAAM,CAAC,IAAI,CACT,UAAU,CAAC,uCAAuC,gBAAgB,2BAA2B,OAAO,CAAC,MAAM,EAAE,CAC9G,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/helpers/check-cumulative-markdown-length.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Checks the cumulative character length across all `markdown` blocks in a
+ * payload. Slack caps it at 12,000 chars per payload; the schema's per-block
+ * `maxLength` can't express this across siblings.
+ * @param blocks - array of Block Kit blocks
+ * @returns array of error messages (empty when under the limit)
+ */
+export declare function checkCumulativeMarkdownLength(blocks: readonly {
+    type?: string;
+    text?: string;
+}[]): string[];
+//# sourceMappingURL=check-cumulative-markdown-length.d.ts.map

package/dist/helpers/check-cumulative-markdown-length.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-cumulative-markdown-length.d.ts","sourceRoot":"","sources":["../../src/helpers/check-cumulative-markdown-length.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,MAAM,EAAE,CAa3G"}

package/dist/helpers/check-cumulative-markdown-length.js

@@ -0,0 +1,23 @@
+const CUMULATIVE_MARKDOWN_LIMIT = 12_000;
+/**
+ * Checks the cumulative character length across all `markdown` blocks in a
+ * payload. Slack caps it at 12,000 chars per payload; the schema's per-block
+ * `maxLength` can't express this across siblings.
+ * @param blocks - array of Block Kit blocks
+ * @returns array of error messages (empty when under the limit)
+ */
+export function checkCumulativeMarkdownLength(blocks) {
+    const total = blocks.reduce((sum, b) => {
+        if (b?.type !== "markdown" || typeof b.text !== "string") {
+            return sum;
+        }
+        return sum + b.text.length;
+    }, 0);
+    if (total > CUMULATIVE_MARKDOWN_LIMIT) {
+        return [
+            `cumulative markdown block text is ${total} chars — maximum across a payload is ${CUMULATIVE_MARKDOWN_LIMIT}`,
+        ];
+    }
+    return [];
+}
+//# sourceMappingURL=check-cumulative-markdown-length.js.map

package/dist/helpers/check-cumulative-markdown-length.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-cumulative-markdown-length.js","sourceRoot":"","sources":["../../src/helpers/check-cumulative-markdown-length.ts"],"names":[],"mappings":"AAAA,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,UAAU,6BAA6B,CAAC,MAAmD;IAC/F,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QACrC,IAAI,CAAC,EAAE,IAAI,KAAK,UAAU,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACzD,OAAO,GAAG,CAAC;QACb,CAAC;QACD,OAAO,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;IAC7B,CAAC,EAAE,CAAC,CAAC,CAAC;IACN,IAAI,KAAK,GAAG,yBAAyB,EAAE,CAAC;QACtC,OAAO;YACL,qCAAqC,KAAK,wCAAwC,yBAAyB,EAAE;SAC9G,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/helpers/check-focus-on-load-uniqueness.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Slack allows at most one interactive element with `focus_on_load: true` per
+ * view/payload. The walker recursively descends into every nested object and
+ * array and counts any node whose `focus_on_load` is literally `true` — it
+ * doesn't gate on element type, so for well-formed payloads this is
+ * equivalent to "one focused element per view." The walk is depth-limited so
+ * pathological inputs can't blow the stack.
+ * @param blocks - array of Block Kit blocks or anything with a nested shape
+ * @returns array of error messages (empty when zero or one node has `focus_on_load: true`)
+ */
+export declare function checkFocusOnLoadUniqueness(blocks: readonly unknown[]): string[];
+//# sourceMappingURL=check-focus-on-load-uniqueness.d.ts.map

package/dist/helpers/check-focus-on-load-uniqueness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-focus-on-load-uniqueness.d.ts","sourceRoot":"","sources":["../../src/helpers/check-focus-on-load-uniqueness.ts"],"names":[],"mappings":"AAQA;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,EAAE,CAoC/E"}

package/dist/helpers/check-focus-on-load-uniqueness.js

@@ -0,0 +1,52 @@
+/**
+ * Cap for recursive traversal of block payloads. Real Slack payloads are
+ * bounded by their structural limits (≤100 blocks, ≤25 elements per block,
+ * etc.), so genuine nesting never comes close to 50. Stop there to guard
+ * against adversarial or malformed inputs.
+ */
+const MAX_WALK_DEPTH = 50;
+/**
+ * Slack allows at most one interactive element with `focus_on_load: true` per
+ * view/payload. The walker recursively descends into every nested object and
+ * array and counts any node whose `focus_on_load` is literally `true` — it
+ * doesn't gate on element type, so for well-formed payloads this is
+ * equivalent to "one focused element per view." The walk is depth-limited so
+ * pathological inputs can't blow the stack.
+ * @param blocks - array of Block Kit blocks or anything with a nested shape
+ * @returns array of error messages (empty when zero or one node has `focus_on_load: true`)
+ */
+export function checkFocusOnLoadUniqueness(blocks) {
+    const paths = [];
+    const walk = (node, path, depth) => {
+        if (node == null || depth > MAX_WALK_DEPTH) {
+            return;
+        }
+        if (Array.isArray(node)) {
+            node.forEach((item, i) => {
+                walk(item, `${path}[${i}]`, depth + 1);
+            });
+            return;
+        }
+        if (typeof node !== "object") {
+            return;
+        }
+        const obj = node;
+        if (obj.focus_on_load === true) {
+            paths.push(path || "(root)");
+        }
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === "focus_on_load") {
+                continue;
+            }
+            walk(value, `${path}.${key}`, depth + 1);
+        }
+    };
+    blocks.forEach((block, i) => {
+        walk(block, `blocks[${i}]`, 0);
+    });
+    if (paths.length > 1) {
+        return [`only one element per view may have 'focus_on_load: true' — found ${paths.length} at ${paths.join(", ")}`];
+    }
+    return [];
+}
+//# sourceMappingURL=check-focus-on-load-uniqueness.js.map

package/dist/helpers/check-focus-on-load-uniqueness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-focus-on-load-uniqueness.js","sourceRoot":"","sources":["../../src/helpers/check-focus-on-load-uniqueness.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,cAAc,GAAG,EAAE,CAAC;AAE1B;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAA0B;IACnE,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,MAAM,IAAI,GAAG,CAAC,IAAa,EAAE,IAAY,EAAE,KAAa,EAAQ,EAAE;QAChE,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,GAAG,cAAc,EAAE,CAAC;YAC3C,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;gBACvB,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YACzC,CAAC,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,OAAO;QACT,CAAC;QACD,MAAM,GAAG,GAAG,IAA+B,CAAC;QAC5C,IAAI,GAAG,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,QAAQ,CAAC,CAAC;QAC/B,CAAC;QACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/C,IAAI,GAAG,KAAK,eAAe,EAAE,CAAC;gBAC5B,SAAS;YACX,CAAC;YACD,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,IAAI,GAAG,EAAE,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC1B,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,CAAC,oEAAoE,KAAK,CAAC,MAAM,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/helpers/check-number-input-bounds.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Slack's number_input docs say:
+ *   "The minimum value, cannot be greater than max_value."
+ *   "The maximum value, cannot be less than min_value."
+ * JSON Schema can't compare two sibling string-encoded numbers natively, so
+ * this helper walks the blocks array (bounded by MAX_WALK_DEPTH) and reports
+ * any number_input where min_value > max_value.
+ * @param blocks - array of Block Kit blocks or anything with a nested shape
+ * @returns array of human-readable error messages (empty when valid)
+ */
+export declare function checkNumberInputBounds(blocks: readonly unknown[]): string[];
+//# sourceMappingURL=check-number-input-bounds.d.ts.map

package/dist/helpers/check-number-input-bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-number-input-bounds.d.ts","sourceRoot":"","sources":["../../src/helpers/check-number-input-bounds.ts"],"names":[],"mappings":"AAwEA;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,EAAE,CA2B3E"}

package/dist/helpers/check-number-input-bounds.js

@@ -0,0 +1,96 @@
+/**
+ * Cap for recursive traversal of block payloads. Real Slack payloads are
+ * bounded by their structural limits (≤100 blocks, ≤25 elements per block,
+ * etc.), so genuine nesting never comes close to 50. Stop there to guard
+ * against adversarial or malformed inputs.
+ */
+const MAX_WALK_DEPTH = 50;
+/**
+ * Inspect a single node: if it looks like a `number_input` element whose
+ * `min_value` exceeds its `max_value`, push a human-readable error onto the
+ * accumulator. Non-matching nodes are ignored — recursion is the walker's job.
+ * @param node - the possibly-number_input node to inspect
+ * @param path - dotted path to the node for use in error messages
+ * @param errors - accumulator mutated in place with any error string
+ */
+const reportBoundsIssue = (node, path, errors) => {
+    if (node?.type !== "number_input") {
+        return;
+    }
+    if (typeof node.min_value !== "string" || typeof node.max_value !== "string") {
+        return;
+    }
+    const min = Number(node.min_value);
+    const max = Number(node.max_value);
+    if (!Number.isFinite(min) || !Number.isFinite(max)) {
+        return;
+    }
+    if (min > max) {
+        errors.push(`${path} number_input min_value (${node.min_value}) cannot be greater than max_value (${node.max_value})`);
+    }
+};
+/**
+ * Inspect a `number_input` node with `is_decimal_allowed: false` and flag any
+ * decimal string in `min_value`, `max_value`, or `initial_value`. Slack rejects
+ * decimal bounds/initial values on integer-only number inputs server-side, even
+ * though the docs don't spell out the constraint in plain language.
+ * @param node - the possibly-number_input node to inspect
+ * @param path - dotted path to the node for use in error messages
+ * @param errors - accumulator mutated in place with any error string
+ */
+const reportIntegerOnlyIssue = (node, path, errors) => {
+    if (node?.type !== "number_input") {
+        return;
+    }
+    if (node.is_decimal_allowed !== false) {
+        return;
+    }
+    const integerOnlyFields = ["min_value", "max_value", "initial_value"];
+    for (const field of integerOnlyFields) {
+        const raw = node[field];
+        if (typeof raw !== "string") {
+            continue;
+        }
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed) && !Number.isInteger(parsed)) {
+            errors.push(`${path} number_input ${field} ('${raw}') must be an integer when is_decimal_allowed is false`);
+        }
+    }
+};
+/**
+ * Slack's number_input docs say:
+ *   "The minimum value, cannot be greater than max_value."
+ *   "The maximum value, cannot be less than min_value."
+ * JSON Schema can't compare two sibling string-encoded numbers natively, so
+ * this helper walks the blocks array (bounded by MAX_WALK_DEPTH) and reports
+ * any number_input where min_value > max_value.
+ * @param blocks - array of Block Kit blocks or anything with a nested shape
+ * @returns array of human-readable error messages (empty when valid)
+ */
+export function checkNumberInputBounds(blocks) {
+    const errors = [];
+    const walk = (node, path, depth) => {
+        if (node == null || depth > MAX_WALK_DEPTH) {
+            return;
+        }
+        if (Array.isArray(node)) {
+            node.forEach((item, i) => {
+                walk(item, `${path}[${i}]`, depth + 1);
+            });
+            return;
+        }
+        if (typeof node !== "object") {
+            return;
+        }
+        reportBoundsIssue(node, path, errors);
+        reportIntegerOnlyIssue(node, path, errors);
+        for (const [key, value] of Object.entries(node)) {
+            walk(value, `${path}.${key}`, depth + 1);
+        }
+    };
+    blocks.forEach((block, i) => {
+        walk(block, `blocks[${i}]`, 0);
+    });
+    return errors;
+}
+//# sourceMappingURL=check-number-input-bounds.js.map

package/dist/helpers/check-number-input-bounds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-number-input-bounds.js","sourceRoot":"","sources":["../../src/helpers/check-number-input-bounds.ts"],"names":[],"mappings":"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"}

package/dist/helpers/check-response-url-enabled-context.d.ts

@@ -0,0 +1,25 @@
+import type { Surface } from "./check-surface-compatibility";
+type SelectLike = {
+    type?: string;
+    response_url_enabled?: boolean;
+};
+type BlockLike = {
+    type?: string;
+    accessory?: SelectLike;
+    element?: SelectLike;
+    elements?: SelectLike[];
+};
+/**
+ * Enforces Slack's `response_url_enabled` restriction:
+ * "This field only works with menus in input blocks in modals."
+ * (Docs: conversations_select / channels_select elements.)
+ *
+ * Flags any usage on a non-modal surface, and any usage outside an `input`
+ * block (e.g. as a section `accessory` or inside an `actions` block).
+ * @param blocks - array of Block Kit blocks
+ * @param surface - target surface (used to reject home/message usage)
+ * @returns array of human-readable error messages (empty when valid)
+ */
+export declare function checkResponseUrlEnabledContext(blocks: readonly BlockLike[], surface: Surface | undefined): string[];
+export {};
+//# sourceMappingURL=check-response-url-enabled-context.d.ts.map

package/dist/helpers/check-response-url-enabled-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-response-url-enabled-context.d.ts","sourceRoot":"","sources":["../../src/helpers/check-response-url-enabled-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAE7D,KAAK,UAAU,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AACpE,KAAK,SAAS,GAAG;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;CACzB,CAAC;AAUF;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,EAAE,CAgCnH"}

package/dist/helpers/check-response-url-enabled-context.js

@@ -0,0 +1,42 @@
+const SELECT_TYPES_WITH_RESPONSE_URL = new Set(["conversations_select", "channels_select"]);
+const hasResponseUrlEnabled = (node) => !!node &&
+    node.response_url_enabled === true &&
+    typeof node.type === "string" &&
+    SELECT_TYPES_WITH_RESPONSE_URL.has(node.type);
+/**
+ * Enforces Slack's `response_url_enabled` restriction:
+ * "This field only works with menus in input blocks in modals."
+ * (Docs: conversations_select / channels_select elements.)
+ *
+ * Flags any usage on a non-modal surface, and any usage outside an `input`
+ * block (e.g. as a section `accessory` or inside an `actions` block).
+ * @param blocks - array of Block Kit blocks
+ * @param surface - target surface (used to reject home/message usage)
+ * @returns array of human-readable error messages (empty when valid)
+ */
+export function checkResponseUrlEnabledContext(blocks, surface) {
+    const errors = [];
+    blocks.forEach((block, i) => {
+        // Section accessory — never a valid host.
+        if (hasResponseUrlEnabled(block.accessory)) {
+            errors.push(`blocks[${i}].accessory sets response_url_enabled — only valid on select menus inside input blocks in modals`);
+        }
+        // Actions block elements — never a valid host.
+        if (Array.isArray(block.elements)) {
+            block.elements.forEach((el, j) => {
+                if (hasResponseUrlEnabled(el)) {
+                    errors.push(`blocks[${i}].elements[${j}] sets response_url_enabled — only valid on select menus inside input blocks in modals`);
+                }
+            });
+        }
+        // Input block element — valid ONLY when surface is explicitly 'modal'.
+        // An undefined surface means we have no confirmation this is a modal
+        // payload, so we flag it conservatively rather than assume modal intent.
+        if (block.type === "input" && hasResponseUrlEnabled(block.element) && surface !== "modal") {
+            const surfaceLabel = surface ?? "unspecified";
+            errors.push(`blocks[${i}].element sets response_url_enabled on surface '${surfaceLabel}' — only valid when surface is explicitly 'modal'`);
+        }
+    });
+    return errors;
+}
+//# sourceMappingURL=check-response-url-enabled-context.js.map

package/dist/helpers/check-response-url-enabled-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-response-url-enabled-context.js","sourceRoot":"","sources":["../../src/helpers/check-response-url-enabled-context.ts"],"names":[],"mappings":"AAUA,MAAM,8BAA8B,GAAG,IAAI,GAAG,CAAC,CAAC,sBAAsB,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAE5F,MAAM,qBAAqB,GAAG,CAAC,IAA4B,EAAW,EAAE,CACtE,CAAC,CAAC,IAAI;IACN,IAAI,CAAC,oBAAoB,KAAK,IAAI;IAClC,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;IAC7B,8BAA8B,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,8BAA8B,CAAC,MAA4B,EAAE,OAA4B;IACvG,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC1B,0CAA0C;QAC1C,IAAI,qBAAqB,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3C,MAAM,CAAC,IAAI,CACT,UAAU,CAAC,kGAAkG,CAC9G,CAAC;QACJ,CAAC;QACD,+CAA+C;QAC/C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE;gBAC/B,IAAI,qBAAqB,CAAC,EAAE,CAAC,EAAE,CAAC;oBAC9B,MAAM,CAAC,IAAI,CACT,UAAU,CAAC,cAAc,CAAC,wFAAwF,CACnH,CAAC;gBACJ,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;QACD,uEAAuE;QACvE,qEAAqE;QACrE,yEAAyE;QACzE,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,qBAAqB,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;YAC1F,MAAM,YAAY,GAAG,OAAO,IAAI,aAAa,CAAC;YAC9C,MAAM,CAAC,IAAI,CACT,UAAU,CAAC,mDAAmD,YAAY,mDAAmD,CAC9H,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/helpers/check-single-table-block.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Checks that a payload contains at most one `table` block. Slack rejects
+ * multi-table messages with `invalid_attachments` / `only_one_table_allowed`.
+ * @param blocks - array of Block Kit blocks
+ * @returns array of error messages (empty when zero or one `table` block present)
+ */
+export declare function checkSingleTableBlock(blocks: readonly {
+    type?: string;
+}[]): string[];
+//# sourceMappingURL=check-single-table-block.d.ts.map

package/dist/helpers/check-single-table-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-single-table-block.d.ts","sourceRoot":"","sources":["../../src/helpers/check-single-table-block.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,MAAM,EAAE,CAWpF"}

package/dist/helpers/check-single-table-block.js

@@ -0,0 +1,19 @@
+/**
+ * Checks that a payload contains at most one `table` block. Slack rejects
+ * multi-table messages with `invalid_attachments` / `only_one_table_allowed`.
+ * @param blocks - array of Block Kit blocks
+ * @returns array of error messages (empty when zero or one `table` block present)
+ */
+export function checkSingleTableBlock(blocks) {
+    const indices = [];
+    blocks.forEach((block, i) => {
+        if (block?.type === "table") {
+            indices.push(i);
+        }
+    });
+    if (indices.length > 1) {
+        return [`only one 'table' block is allowed per message — found ${indices.length} at indices ${indices.join(", ")}`];
+    }
+    return [];
+}
+//# sourceMappingURL=check-single-table-block.js.map

package/dist/helpers/check-single-table-block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-single-table-block.js","sourceRoot":"","sources":["../../src/helpers/check-single-table-block.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAoC;IACxE,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC1B,IAAI,KAAK,EAAE,IAAI,KAAK,OAAO,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,yDAAyD,OAAO,CAAC,MAAM,eAAe,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/helpers/check-surface-compatibility.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Surfaces where Block Kit payloads are rendered. Each has a different set of
+ * blocks/elements it accepts.
+ */
+export type Surface = "message" | "modal" | "home";
+/**
+ * Reports any blocks whose type is not allowed on the given surface. Slack's
+ * surface compatibility matrix is documented at
+ * https://docs.slack.dev/surfaces/. Element-level restrictions (e.g. `file_input`
+ * only valid in modals) are checked here by looking at each input block's inner
+ * `element.type`.
+ * @param blocks - array of Block Kit blocks
+ * @param surface - target surface
+ * @returns array of error messages (empty when all blocks are surface-compatible)
+ */
+export declare function checkSurfaceCompatibility(blocks: readonly {
+    type?: string;
+    element?: {
+        type?: string;
+    };
+}[], surface: Surface): string[];
+//# sourceMappingURL=check-surface-compatibility.d.ts.map