feat(web-api): add blocks.validate method

.changeset/web-api-blocks-validate.md

@@ -0,0 +1,5 @@
+---
+"@slack/web-api": minor
+---
+
+Added the `blocks.validate` method. Call it as `client.blocks.validate({ blocks })` to validate a Block Kit payload (`blocks`, `message`, or `view`, each a JSON-encoded string) against the Block Kit schema, instead of the untyped `client.apiCall('blocks.validate', …)` escape hatch.

packages/web-api/src/methods.ts

@@ -113,6 +113,7 @@ import type {
   AuthRevokeArguments,
   AuthTeamsListArguments,
   AuthTestArguments,
+  BlocksValidateArguments,
   BookmarksAddArguments,
   BookmarksEditArguments,
   BookmarksListArguments,
@@ -382,6 +383,7 @@ import type {
   AuthRevokeResponse,
   AuthTeamsListResponse,
   AuthTestResponse,
+  BlocksValidateResponse,
   BookmarksAddResponse,
   BookmarksEditResponse,
   BookmarksListResponse,
@@ -1514,6 +1516,14 @@ export abstract class Methods extends EventEmitter<WebClientEvent> {
     remove: bindApiCall<BookmarksRemoveArguments, BookmarksRemoveResponse>(this, 'bookmarks.remove'),
   };
 
+  public readonly blocks = {
+    /**
+     * @description Validates an array of blocks, or a message or view payload.
+     * @see {@link https://docs.slack.dev/reference/methods/blocks.validate `blocks.validate` API reference}.
+     */
+    validate: bindApiCallWithOptionalArgument<BlocksValidateArguments, BlocksValidateResponse>(this, 'blocks.validate'),
+  };
+
   public readonly bots = {
     /**
      * @description Gets information about a bot user.

packages/web-api/src/types/request/blocks.ts

@@ -0,0 +1,14 @@
+import type { OptionalArgument } from '../helpers';
+import type { TokenOverridable } from './common';
+
+// https://docs.slack.dev/reference/methods/blocks.validate
+export type BlocksValidateArguments = OptionalArgument<
+  TokenOverridable & {
+    /** @description A JSON-encoded string of an array of blocks to validate. */
+    blocks?: string;
+    /** @description A JSON-encoded string of a message payload to validate. */
+    message?: string;
+    /** @description A JSON-encoded string of a view payload to validate. */
+    view?: string;
+  }
+>;

packages/web-api/src/types/request/index.ts

@@ -139,6 +139,7 @@ export type {
   AuthTeamsListArguments,
   AuthTestArguments,
 } from './auth';
+export type { BlocksValidateArguments } from './blocks';
 export type {
   BookmarksAddArguments,
   BookmarksEditArguments,

packages/web-api/src/types/response/BlocksValidateResponse.ts

@@ -0,0 +1,20 @@
+// NOTE: This response type is a minimal placeholder, written by hand rather than
+// generated by scripts/generate-web-api-types.sh, because no `blocks.validate.json`
+// sample exists yet in the upstream slackapi/java-slack-sdk logs. It covers the
+// fields common to every Web API response; the `errors[]` array returned on a failed
+// validation is intentionally omitted until a real sample can be captured and the
+// type regenerated. See HANDOFF / PR notes.
+
+import type { WebAPICallResult } from '../../WebClient';
+
+export type BlocksValidateResponse = WebAPICallResult & {
+  ok?: boolean;
+  error?: string;
+  needed?: string;
+  provided?: string;
+  response_metadata?: ResponseMetadata;
+};
+
+export interface ResponseMetadata {
+  messages?: string[];
+}

packages/web-api/src/types/response/index.ts

@@ -123,6 +123,7 @@ export { AssistantThreadsSetTitleResponse } from './AssistantThreadsSetTitleResp
 export { AuthRevokeResponse } from './AuthRevokeResponse';
 export { AuthTeamsListResponse } from './AuthTeamsListResponse';
 export { AuthTestResponse } from './AuthTestResponse';
+export { BlocksValidateResponse } from './BlocksValidateResponse';
 export { BookmarksAddResponse } from './BookmarksAddResponse';
 export { BookmarksEditResponse } from './BookmarksEditResponse';
 export { BookmarksListResponse } from './BookmarksListResponse';

packages/web-api/test/types/methods/blocks.test-d.ts

@@ -0,0 +1,14 @@
+import { expectAssignable } from 'tsd';
+import { WebClient } from '../../../src/WebClient';
+
+const web = new WebClient('TOKEN');
+
+// blocks.validate
+// -- happy path
+expectAssignable<Parameters<typeof web.blocks.validate>>([{}]); // all optional args
+expectAssignable<Parameters<typeof web.blocks.validate>>([]); // no arg is fine
+expectAssignable<Parameters<typeof web.blocks.validate>>([
+  { blocks: '[{"type":"section","text":{"type":"plain_text","text":"Hello world"}}]' },
+]);
+expectAssignable<Parameters<typeof web.blocks.validate>>([{ message: '{"blocks":[]}' }]);
+expectAssignable<Parameters<typeof web.blocks.validate>>([{ view: '{"type":"modal"}' }]);