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

package/dist/validate-block-kit.d.ts

@@ -0,0 +1,33 @@
+import { type Surface } from "./helpers/check-surface-compatibility";
+/**
+ * Result of a Block Kit validation.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Payload targets recognized by the wrapper. `blocks` validates a bare blocks
+ * array; `modal` / `home` validate a view envelope.
+ */
+export type ValidationTarget = "blocks" | "modal" | "home";
+export interface ValidateBlockKitOptions {
+    /** Which top-level shape to validate. Defaults to `blocks`. */
+    target?: ValidationTarget;
+    /**
+     * Which Slack surface the payload will render on. Used to enforce surface
+     * compatibility. When `target` is `modal` or `home`, the surface is derived
+     * automatically.
+     */
+    surface?: Surface;
+}
+/**
+ * Validates a Slack Block Kit payload against the JSON Schema and the set of
+ * caveat helpers (duplicate block_ids, cumulative markdown length, single-table,
+ * focus_on_load uniqueness, surface compatibility).
+ * @param input - the payload to validate
+ * @param options - target shape + optional surface
+ * @returns `{ valid, errors }` — `errors` is a flat array of human-readable messages
+ */
+export declare function validateBlockKit(input: unknown, options?: ValidateBlockKitOptions): ValidationResult;
+//# sourceMappingURL=validate-block-kit.d.ts.map

package/dist/validate-block-kit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-block-kit.d.ts","sourceRoot":"","sources":["../src/validate-block-kit.ts"],"names":[],"mappings":"AAQA,OAAO,EAA6B,KAAK,OAAO,EAAE,MAAM,uCAAuC,CAAC;AAIhG;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAqGD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,uBAA4B,GAAG,gBAAgB,CAkCxG"}

package/dist/validate-block-kit.js

@@ -0,0 +1,135 @@
+import Ajv2020 from "ajv/dist/2020";
+import addFormats from "ajv-formats";
+import { checkCardActionsMax } from "./helpers/check-card-actions-max";
+import { checkCumulativeMarkdownLength } from "./helpers/check-cumulative-markdown-length";
+import { checkFocusOnLoadUniqueness } from "./helpers/check-focus-on-load-uniqueness";
+import { checkNumberInputBounds } from "./helpers/check-number-input-bounds";
+import { checkResponseUrlEnabledContext } from "./helpers/check-response-url-enabled-context";
+import { checkSingleTableBlock } from "./helpers/check-single-table-block";
+import { checkSurfaceCompatibility } from "./helpers/check-surface-compatibility";
+import { findDuplicateBlockIds } from "./helpers/find-duplicate-block-ids";
+import schema from "./slack-block-kit.schema.json";
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+addFormats(ajv);
+ajv.addSchema(schema, "slack-block-kit");
+const compile = (ref) => ajv.compile({ $ref: `slack-block-kit#/$defs/${ref}` });
+const validators = {
+    blocks: ajv.compile({ $ref: "slack-block-kit" }),
+    modal: compile("modal_view"),
+    home: compile("home_view"),
+};
+const formatAjvError = (err) => {
+    const path = err.instancePath || "(root)";
+    return `${path} ${err.message ?? "failed validation"}`;
+};
+const resolveSurface = (target, surface) => {
+    if (target === "modal") {
+        return "modal";
+    }
+    if (target === "home") {
+        return "home";
+    }
+    return surface;
+};
+const extractBlocks = (input, target) => {
+    if (target === "blocks") {
+        return Array.isArray(input) ? input : [];
+    }
+    if (input != null && typeof input === "object" && "blocks" in input) {
+        const { blocks } = input;
+        return Array.isArray(blocks) ? blocks : [];
+    }
+    return [];
+};
+/**
+ * Cap for recursive traversal of 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. Matches the cap used in the other walkers
+ * (`check-focus-on-load-uniqueness`, `check-number-input-bounds`).
+ */
+const MAX_STRIP_DEPTH = 50;
+/**
+ * Recursively normalizes a payload to mirror the shape Slack will actually see
+ * after `JSON.stringify`:
+ *   - drops object properties whose value is `undefined` (so common builder
+ *     patterns like `value: foo ?? undefined` don't trip `additionalProperties:
+ *     false`)
+ *   - replaces `undefined` array slots with `null` (matching
+ *     `JSON.stringify([undefined]) === '[null]'`), so schemas that accept
+ *     explicit null placeholders still pass
+ *
+ * Depth-limited at {@link MAX_STRIP_DEPTH} to avoid stack overflow on
+ * pathological inputs — nodes beyond that depth are returned as-is.
+ * @param input - any value that may contain undefined-valued properties
+ * @param depth - internal recursion depth counter
+ * @returns a deep copy of the input with undefined properties removed and
+ *   undefined array slots replaced with null
+ */
+const stripUndefined = (input, depth = 0) => {
+    if (depth > MAX_STRIP_DEPTH) {
+        return input;
+    }
+    if (Array.isArray(input)) {
+        // Use a manual length-indexed loop (not `.map`) so that sparse holes are
+        // visited and normalized to null — `Array.prototype.map` skips missing
+        // indices, but `JSON.stringify([, 1])` emits `'[null,1]'`, so the wire
+        // shape includes nulls.
+        const result = new Array(input.length);
+        for (let i = 0; i < input.length; i++) {
+            const item = input[i];
+            result[i] = item === undefined ? null : stripUndefined(item, depth + 1);
+        }
+        return result;
+    }
+    if (input !== null && typeof input === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(input)) {
+            // Skip prototype-pollution vectors. A payload containing `__proto__`,
+            // `constructor`, or `prototype` as a key would otherwise be assigned
+            // via bracket notation into `result`, which can mutate the prototype
+            // chain instead of setting a regular property.
+            if (key === "__proto__" || key === "constructor" || key === "prototype") {
+                continue;
+            }
+            if (value !== undefined) {
+                result[key] = stripUndefined(value, depth + 1);
+            }
+        }
+        return result;
+    }
+    return input;
+};
+/**
+ * Validates a Slack Block Kit payload against the JSON Schema and the set of
+ * caveat helpers (duplicate block_ids, cumulative markdown length, single-table,
+ * focus_on_load uniqueness, surface compatibility).
+ * @param input - the payload to validate
+ * @param options - target shape + optional surface
+ * @returns `{ valid, errors }` — `errors` is a flat array of human-readable messages
+ */
+export function validateBlockKit(input, options = {}) {
+    const target = options.target ?? "blocks";
+    const surface = resolveSurface(target, options.surface);
+    const normalizedInput = stripUndefined(input);
+    const errors = [];
+    const validator = validators[target];
+    if (!validator(normalizedInput)) {
+        for (const err of validator.errors ?? []) {
+            errors.push(formatAjvError(err));
+        }
+    }
+    const blocks = extractBlocks(normalizedInput, target);
+    errors.push(...findDuplicateBlockIds(blocks));
+    errors.push(...checkCumulativeMarkdownLength(blocks));
+    errors.push(...checkSingleTableBlock(blocks));
+    errors.push(...checkCardActionsMax(blocks));
+    errors.push(...checkFocusOnLoadUniqueness(blocks));
+    errors.push(...checkNumberInputBounds(blocks));
+    errors.push(...checkResponseUrlEnabledContext(blocks, surface));
+    if (surface) {
+        errors.push(...checkSurfaceCompatibility(blocks, surface));
+    }
+    return { valid: errors.length === 0, errors };
+}
+//# sourceMappingURL=validate-block-kit.js.map

package/dist/validate-block-kit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-block-kit.js","sourceRoot":"","sources":["../src/validate-block-kit.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tightknitai/slack-block-kit-validator",
+  "version": "0.1.0-alpha.0",
+  "description": "JSON Schema (draft 2020-12) and validation helpers for Slack Block Kit payloads.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./schema.json": "./dist/slack-block-kit.schema.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.11",
+    "@vitest/coverage-v8": "^4.1.4",
+    "ajv-cli": "^5.0.0",
+    "lefthook": "^2.1.5",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TightknitAI/slack-block-kit-validator.git"
+  },
+  "homepage": "https://github.com/TightknitAI/slack-block-kit-validator",
+  "bugs": {
+    "url": "https://github.com/TightknitAI/slack-block-kit-validator/issues"
+  },
+  "author": "Tightknit <https://tightknit.ai>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "slack",
+    "block-kit",
+    "json-schema",
+    "validator",
+    "ajv"
+  ],
+  "scripts": {
+    "build": "tsc && cp src/slack-block-kit.schema.json dist/slack-block-kit.schema.json",
+    "build:clean": "rm -rf dist && pnpm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome check .",
+    "lint:fix": "biome check --fix .",
+    "format": "biome format --write .",
+    "validate-schema": "ajv compile --spec=draft2020 --strict=false -c ajv-formats -s src/slack-block-kit.schema.json",
+    "compile:standalone": "mkdir -p dist && ajv compile --spec=draft2020 --strict=false -c ajv-formats -s src/slack-block-kit.schema.json -o dist/standalone-validator.js"
+  }
+}