Client Configuration

/**
 * Creates a new Notion client instance
 * @param options - Optional configuration options
 */
class Client {
  constructor(options?: ClientOptions);
}

interface ClientOptions {
  /** API token or OAuth access token for authentication */
  auth?: string;
  /** Request timeout in milliseconds (default: 60000) */
  timeoutMs?: number;
  /** Base API URL (default: "https://api.notion.com") */
  baseUrl?: string;
  /** Logging level (default: LogLevel.WARN) */
  logLevel?: LogLevel;
  /** Custom logger function */
  logger?: Logger;
  /** Notion API version (default: "2025-09-03") */
  notionVersion?: string;
  /** Custom fetch implementation */
  fetch?: SupportedFetch;
  /** HTTP agent for Node.js (ignored in browser) */
  agent?: Agent;
}

import { Client, LogLevel } from "@notionhq/client";

// Basic initialization with token
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
});

// Advanced configuration
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  timeoutMs: 30000,
  logLevel: LogLevel.DEBUG,
  notionVersion: "2025-09-03",
});

// OAuth initialization
const notion = new Client({
  auth: oauthAccessToken,
  logLevel: LogLevel.INFO,
});

/**
 * Sends a request to the Notion API
 * @param args - Request parameters including path, method, query, body
 * @returns Promise resolving to the response body
 */
request<ResponseBody>(args: RequestParameters): Promise<ResponseBody>;

interface RequestParameters {
  /** API endpoint path */
  path: string;
  /** HTTP method */
  method: "get" | "post" | "patch" | "delete";
  /** Query parameters */
  query?: Record<string, string | number | string[]> | URLSearchParams;
  /** Request body */
  body?: Record<string, unknown>;
  /** Form data parameters for file uploads */
  formDataParams?: Record<string, string | FileParam>;
  /** Additional headers */
  headers?: Record<string, string>;
  /** Override authentication for this request */
  auth?: string | {
    client_id: string;
    client_secret: string;
  };
}

type FileParam = {
  filename?: string;
  data: string | Blob;
};

// Custom API request
const response = await notion.request({
  path: "pages/abc123",
  method: "get",
  query: { filter_properties: ["title"] },
});

// Request with custom auth
const response = await notion.request({
  path: "users/me",
  method: "get",
  auth: customToken,
});

/**
 * Default Notion API version used by the client
 */
static readonly defaultNotionVersion: string;

enum LogLevel {
  DEBUG = "debug";
  INFO = "info";
  WARN = "warn";
  ERROR = "error";
}

interface Logger {
  (level: LogLevel, message: string, extraInfo: Record<string, unknown>): void;
}

type SupportedFetch = typeof fetch;

interface Agent {
  // Node.js HTTP agent interface
}