Core API Operations

/**
 * Creates a new Notion API client instance
 * @param options - Configuration options for the API client
 */
constructor(options?: NotionAPIOptions);

interface NotionAPIOptions {
  /** Base URL for Notion API (default: 'https://www.notion.so/api/v3') */
  apiBaseUrl?: string;
  /** Authentication token for private resources */
  authToken?: string;
  /** Active user ID for authenticated requests */
  activeUser?: string;
  /** User timezone (default: 'America/New_York') */
  userTimeZone?: string;
  /** Additional HTTP client options */
  kyOptions?: KyOptions;
}

import { NotionAPI } from "notion-client";

// Basic client for public pages
const api = new NotionAPI();

// Authenticated client for private resources
const authApi = new NotionAPI({
  authToken: "token_v2_value_from_cookies",
  activeUser: "user-uuid",
  userTimeZone: "UTC"
});

// Client with custom API base URL
const customApi = new NotionAPI({
  apiBaseUrl: "https://custom-notion-proxy.com/api/v3",
  kyOptions: {
    timeout: 30000,
    retry: 3
  }
});

/**
 * Fetches a complete Notion page with all content
 * @param pageId - The Notion page ID (with or without dashes)
 * @param options - Options for controlling fetch behavior
 * @returns Promise resolving to complete page data
 */
async getPage(pageId: string, options?: GetPageOptions): Promise<ExtendedRecordMap>;

interface GetPageOptions {
  /** Number of concurrent requests for fetching blocks (default: 3) */
  concurrency?: number;
  /** Fetch missing blocks automatically (default: true) */
  fetchMissingBlocks?: boolean;
  /** Fetch collection data automatically (default: true) */
  fetchCollections?: boolean;
  /** Generate signed URLs for files (default: true) */
  signFileUrls?: boolean;
  /** Number of blocks to fetch per chunk (default: 100) */
  chunkLimit?: number;
  /** Starting chunk number (default: 0) */
  chunkNumber?: number;
  /** Throw errors when collection fetching fails (default: false) */
  throwOnCollectionErrors?: boolean;
  /** Limit for collection data fetching (default: 999) */
  collectionReducerLimit?: number;
  /** Fetch pages referenced in relations (default: false) */
  fetchRelationPages?: boolean;
  /** HTTP client options for this request */
  kyOptions?: KyOptions;
}

interface ExtendedRecordMap {
  block: Record<string, BlockRecord>;
  collection: Record<string, CollectionRecord>;
  collection_view: Record<string, CollectionViewRecord>;
  notion_user: Record<string, UserRecord>;
  collection_query: Record<string, any>;
  signed_urls: Record<string, string>;
}

import { NotionAPI } from "notion-client";

const api = new NotionAPI();

// Fetch a complete page with all default options
const page = await api.getPage("067dd719-a912-471e-a9a3-ac10710e7fdf");

// Fetch page without collections for faster loading
const pageNoCollections = await api.getPage("067dd719", {
  fetchCollections: false,
  signFileUrls: false
});

// Fetch page with relation pages and custom limits
const pageWithRelations = await api.getPage("067dd719", {
  fetchRelationPages: true,
  collectionReducerLimit: 50,
  concurrency: 5
});

// Access page content
console.log("Page blocks:", Object.keys(page.block).length);
console.log("Collections:", Object.keys(page.collection).length);
console.log("Signed URLs:", Object.keys(page.signed_urls).length);

/**
 * Fetches raw page data without additional processing
 * @param pageId - The Notion page ID
 * @param options - Options for controlling fetch behavior
 * @returns Promise resolving to raw page chunk data
 */
async getPageRaw(pageId: string, options?: GetPageRawOptions): Promise<PageChunk>;

interface GetPageRawOptions {
  /** Number of blocks to fetch per chunk (default: 100) */
  chunkLimit?: number;
  /** Starting chunk number (default: 0) */
  chunkNumber?: number;
  /** HTTP client options for this request */
  kyOptions?: KyOptions;
}

interface PageChunk {
  recordMap: RecordMap;
  cursor: Cursor;
}

import { NotionAPI } from "notion-client";

const api = new NotionAPI();

// Fetch raw page data for performance
const rawPage = await api.getPageRaw("067dd719-a912-471e-a9a3-ac10710e7fdf");

// Fetch specific chunk of large page
const pageChunk = await api.getPageRaw("067dd719", {
  chunkLimit: 50,
  chunkNumber: 1
});

// Access raw record map
const blocks = rawPage.recordMap.block;
console.log("Raw blocks:", Object.keys(blocks).length);

/**
 * Low-level fetch method for custom API requests
 * @param options - Request configuration
 * @returns Promise resolving to API response
 */
async fetch<T>(options: FetchOptions): Promise<T>;

interface FetchOptions {
  /** API endpoint name (e.g., 'loadPageChunk', 'queryCollection') */
  endpoint: string;
  /** Request body data */
  body: object;
  /** HTTP client options for this request */
  kyOptions?: KyOptions;
  /** Additional HTTP headers */
  headers?: Record<string, string>;
}

import { NotionAPI } from "notion-client";

const api = new NotionAPI({ authToken: "your-token" });

// Custom API call to load page chunk
const customPageData = await api.fetch({
  endpoint: "loadPageChunk",
  body: {
    pageId: "067dd719-a912-471e-a9a3-ac10710e7fdf",
    limit: 50,
    cursor: { stack: [] },
    chunkNumber: 0,
    verticalColumns: false
  }
});

// Custom API call with additional headers
const customRequest = await api.fetch({
  endpoint: "customEndpoint",
  body: { data: "example" },
  headers: {
    "X-Custom-Header": "value"
  },
  kyOptions: {
    timeout: 15000
  }
});