Utilities

Types and helpers for building and validating Block Kit payloads.

assertValid()

function assertValid(payload): asserts payload is JsonObject;

Asserts that an object is a valid Block Kit payload.

Validation walks nested blocks, elements, views, and composition objects and reports the first failing field through a typed validation error.

Parameters

Parameter	Type	Description
payload	JsonValue	JSON value to validate.

Returns

asserts payload is JsonObject

Throws

InvalidUsageError when the payload violates a supported Block Kit constraint.

---

blockKitBuilderUrl()

function blockKitBuilderUrl(payload, teamId?): string;

Builds a Block Kit Builder URL containing a serialized payload.

Parameters

Parameter	Type	Description
payload	JsonObject | JsonObject[]	A complete payload or a list of blocks.
teamId?	string	Optional workspace ID used in the Builder URL.

Returns

string

A URL that opens the payload in Slack's Block Kit Builder.

---

BlockKitPayload

type BlockKitPayload = JsonObject;

Generic validated Block Kit object.

---

Buildable<Value>

type Buildable<Value> = 
  | Value
  | FluentBuilder<object, Value>
  | Value extends readonly infer Item[] ? readonly Buildable<Item>[] : never;

A value accepted by a fluent parent: wire data, nested data, or another builder.

Type Parameters

Type Parameter
Value

---

FactorySettings

Per-call behavior supported by every public factory.

Properties

Property	Type	Description
validate?	boolean	Whether to validate the constructed object immediately. Defaults to true. Disable only when intentionally creating an intermediate partial object.

---

FluentBuilder<Input, Output>

type FluentBuilder<Input, Output> = FluentMethods<Input, Output> & object;

Typed, chainable construction of a plain Slack wire object.

Type Declaration

Name	Type	Description
build()	(settings?) => Output	Materialises and validates the completed Slack object.

Type Parameters

Type Parameter
Input extends object
Output

---

FluentGroupBuilder<Input, Output>

type FluentGroupBuilder<Input, Output> = FluentBuilder<Input, Output[]>;

A fluent component that expands to multiple values in a parent collection.

Type Parameters

Type Parameter
Input extends object
Output

---

JsonObject

Object with JSON-compatible values and Slack-shaped string keys.

Indexable

[key: string]: JsonValue

JSON field value by wire-format key.

---

JsonPrimitive

type JsonPrimitive = boolean | number | string | null;

JSON scalar accepted by Slack payloads.

---

JsonValue

type JsonValue = 
  | JsonPrimitive
  | JsonObject
  | JsonValue[];

Recursive JSON value accepted by Slack payloads.

---

SlackCompatibleBlock

type SlackCompatibleBlock = SlackWire<KnownBlock>;

Compatibility helper for call sites that accept Slack's official block types.

---

SlackObject<Type>

type SlackObject<Type> = JsonObject & object;

Slack-shaped JSON object whose type field is known.

Type Declaration

Name	Type	Description
type	Type	Discriminator identifying the Block Kit object on Slack's wire format.

Type Parameters

Type Parameter
Type extends string

---

SlackWire<Type>

type SlackWire<Type> = Type & JsonObject;

Official Slack SDK type intersected with its JSON wire representation.

Type Parameters

Type Parameter
Type

---

validate()

function validate(payload): payload is JsonObject;

Checks whether a value is a valid Block Kit payload without throwing for validation failures.

Validation identifies objects by their type field, so it enforces required fields and limits for every typed block, element, view, and rich-text object, and it validates type-less options, option_groups, confirm, filter, slack_file, and plan tasks objects contextually through their typed parents. A payload without a type is checked against Slack's message-wide rules: every attachment needs blocks, and markdown block text and data table cell text are limited across the whole payload. Known asymmetries with factory validation remain for type-less objects that appear without a typed parent: standalone confirmation dialogs, options, option groups, attachments, workflow objects, and chart axis configurations pass unchecked, message block counts and surface placement are checked only by the message factories, and one-of rules enforced only by factory signatures (for example slackFile requiring exactly one source) are not rediscovered from raw JSON. The contents of message metadata event_payload objects are always treated as opaque user data and skipped.

Parameters

Parameter	Type	Description
payload	unknown	Unknown value to validate.

Returns

payload is JsonObject

true for a valid payload; otherwise false.