Block Record Retrieval

Build a helper that retrieves Notion block records by ID, reports missing entries, and exposes signed file URLs when requested.

Capabilities

Fetch block records

• Given an array of valid block IDs (with duplicates removed internally), returns a blocks map keyed by each unique ID that includes block metadata and leaves missing empty. @test

Identify missing blocks

• When some requested IDs do not resolve, missing lists those IDs while blocks only contains entries for IDs that were found. @test

Include signed file URLs

• When includeSignedUrls is true and a requested block contains file-based assets, the corresponding BlockRecord exposes a signedFileUrls map keyed by source URL. @test

Forward request options

• When requestOptions includes custom headers or timeout, the underlying HTTP calls use those options. @test

Implementation

@generates

API

export interface BlockRecord {
  id: string;
  type: string;
  properties?: Record<string, unknown>;
  content?: string[];
  signedFileUrls?: Record<string, string>;
  raw: unknown;
}

export interface FetchBlocksOptions {
  includeSignedUrls?: boolean;
  requestOptions?: {
    timeout?: number;
    headers?: Record<string, string>;
  };
}

export interface FetchBlocksResult {
  blocks: Record<string, BlockRecord>;
  missing: string[];
}

export function createBlockFetcher(authToken: string): {
  fetchBlocksById(
    blockIds: string[],
    options?: FetchBlocksOptions
  ): Promise<FetchBlocksResult>;
};

Dependencies { .dependencies }

notion-client { .dependency }

Client for requesting block records from Notion workspaces.

@satisfied-by