@visus-io/notion-sdk-ts 3.0.2 → 3.1.1

package/dist/api/views.api.d.ts

@@ -0,0 +1,286 @@
+import type { NotionClient } from '../client';
+import { Page, View } from '../models';
+import { type NotionView, type PaginatedList, type PaginationParameters, type RequestStatus, type ViewDeleteResult, type ViewType } from '../schemas';
+import { BaseAPI } from './base.api';
+import type { DataSourceSort } from './dataSources.api';
+/**
+ * Options for listing views. Exactly one of `database_id`/`data_source_id` must be provided.
+ */
+export interface ListViewsOptions extends PaginationParameters {
+    /** List views for this database (mutually exclusive with data_source_id) */
+    database_id?: string;
+    /** List views for this data source (mutually exclusive with database_id) */
+    data_source_id?: string;
+}
+/**
+ * Options for creating a view. Provide exactly one of
+ * `database_id`/`view_id`/`create_database` to select the parent context.
+ */
+export interface CreateViewOptions {
+    /** The data source the view displays */
+    data_source_id: string;
+    /** The view name */
+    name: string;
+    /** The view layout type */
+    type: ViewType;
+    /** Attach the view to this existing database */
+    database_id?: string;
+    /** Clone the configuration of this existing view */
+    view_id?: string;
+    /** Create a new database to hold the view */
+    create_database?: true;
+    /** Filter configuration */
+    filter?: Record<string, unknown>;
+    /** Sort configuration */
+    sorts?: DataSourceSort[];
+    /** Quick filter configuration */
+    quick_filters?: Record<string, unknown>;
+    /** Per-layout configuration */
+    configuration?: Record<string, unknown>;
+    /** Where to place the new view relative to existing views */
+    position?: Record<string, unknown>;
+}
+/**
+ * Options for updating a view. All fields are optional.
+ * Pass `null` for `filter`, `sorts`, or `quick_filters` to clear the existing value.
+ */
+export interface UpdateViewOptions {
+    /** Rename the view */
+    name?: string;
+    /** Update or clear (`null`) the filter configuration */
+    filter?: Record<string, unknown> | null;
+    /** Update or clear (`null`) the sort configuration */
+    sorts?: DataSourceSort[] | null;
+    /** Update or clear (`null`) the quick filter configuration */
+    quick_filters?: Record<string, unknown> | null;
+    /** Shallow-merged per-layout configuration update */
+    configuration?: Record<string, unknown>;
+}
+/**
+ * Options for creating a view query.
+ */
+export interface CreateViewQueryOptions extends PaginationParameters {
+    /** Filter configuration */
+    filter?: Record<string, unknown>;
+    /** Sort configuration */
+    sorts?: DataSourceSort[];
+}
+/**
+ * Result of a view query. This shape differs from {@link PaginatedList}.
+ * It includes `totalCount` and `expiresAt`. After `expiresAt` passes,
+ * {@link ViewsAPI.queries.get} can no longer retrieve the query.
+ */
+export interface ViewQueryResult {
+    id: string;
+    viewId: string;
+    expiresAt: Date;
+    totalCount: number;
+    results: Page[];
+    nextCursor: string | null;
+    hasMore: boolean;
+    requestStatus?: RequestStatus;
+}
+/**
+ * Views API client for working with Notion views.
+ *
+ * Views control how a database/data source's rows are displayed (table, board,
+ * calendar, etc.). Requires API version 2025-09-03 or later.
+ *
+ * @category Views
+ */
+export declare class ViewsAPI extends BaseAPI<NotionView, View> {
+    protected readonly client: NotionClient;
+    protected config: {
+        schema: import("zod").ZodObject<{
+            object: import("zod").ZodLiteral<"view">;
+            id: import("zod").ZodUUID;
+            parent: import("zod").ZodObject<{
+                type: import("zod").ZodLiteral<"database_id">;
+                database_id: import("zod").ZodUUID;
+            }, import("zod/v4/core").$strip>;
+            data_source_id: import("zod").ZodNullable<import("zod").ZodUUID>;
+            name: import("zod").ZodString;
+            type: import("zod").ZodEnum<{
+                map: "map";
+                table: "table";
+                list: "list";
+                board: "board";
+                calendar: "calendar";
+                timeline: "timeline";
+                gallery: "gallery";
+                form: "form";
+                chart: "chart";
+                dashboard: "dashboard";
+            }>;
+            filter: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>>;
+            sorts: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodArray<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>>>;
+            quick_filters: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>>;
+            configuration: import("zod").ZodOptional<import("zod").ZodObject<{
+                type: import("zod").ZodEnum<{
+                    map: "map";
+                    table: "table";
+                    list: "list";
+                    board: "board";
+                    calendar: "calendar";
+                    timeline: "timeline";
+                    gallery: "gallery";
+                    form: "form";
+                    chart: "chart";
+                    dashboard: "dashboard";
+                }>;
+            }, import("zod/v4/core").$catchall<import("zod").ZodUnknown>>>;
+            created_time: import("zod").ZodUnion<readonly [import("zod").ZodISODateTime, import("zod").ZodISODate]>;
+            last_edited_time: import("zod").ZodUnion<readonly [import("zod").ZodISODateTime, import("zod").ZodISODate]>;
+            created_by: import("zod").ZodUnion<readonly [import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"user">;
+                id: import("zod").ZodUUID;
+                type: import("zod").ZodLiteral<"person">;
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                avatar_url: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodURL, import("zod").ZodNull]>>;
+                person: import("zod").ZodObject<{
+                    email: import("zod").ZodEmail;
+                    email_verified: import("zod").ZodOptional<import("zod").ZodBoolean>;
+                }, import("zod/v4/core").$strip>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"user">;
+                id: import("zod").ZodUUID;
+                type: import("zod").ZodLiteral<"bot">;
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                avatar_url: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodURL, import("zod").ZodNull]>>;
+                bot: import("zod").ZodObject<{
+                    owner: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"workspace">;
+                        workspace: import("zod").ZodLiteral<true>;
+                    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"user">;
+                    }, import("zod/v4/core").$strip>], "type">;
+                    workspace_name: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+                    workspace_id: import("zod").ZodOptional<import("zod").ZodString>;
+                    workspace_limits: import("zod").ZodOptional<import("zod").ZodObject<{
+                        max_file_upload_size_in_bytes: import("zod").ZodInt;
+                    }, import("zod/v4/core").$strip>>;
+                }, import("zod/v4/core").$strip>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"user">;
+                id: import("zod").ZodUUID;
+            }, import("zod/v4/core").$strip>]>;
+            last_edited_by: import("zod").ZodUnion<readonly [import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"user">;
+                id: import("zod").ZodUUID;
+                type: import("zod").ZodLiteral<"person">;
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                avatar_url: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodURL, import("zod").ZodNull]>>;
+                person: import("zod").ZodObject<{
+                    email: import("zod").ZodEmail;
+                    email_verified: import("zod").ZodOptional<import("zod").ZodBoolean>;
+                }, import("zod/v4/core").$strip>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"user">;
+                id: import("zod").ZodUUID;
+                type: import("zod").ZodLiteral<"bot">;
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                avatar_url: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodURL, import("zod").ZodNull]>>;
+                bot: import("zod").ZodObject<{
+                    owner: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"workspace">;
+                        workspace: import("zod").ZodLiteral<true>;
+                    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"user">;
+                    }, import("zod/v4/core").$strip>], "type">;
+                    workspace_name: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+                    workspace_id: import("zod").ZodOptional<import("zod").ZodString>;
+                    workspace_limits: import("zod").ZodOptional<import("zod").ZodObject<{
+                        max_file_upload_size_in_bytes: import("zod").ZodInt;
+                    }, import("zod/v4/core").$strip>>;
+                }, import("zod/v4/core").$strip>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"user">;
+                id: import("zod").ZodUUID;
+            }, import("zod/v4/core").$strip>]>;
+            url: import("zod").ZodURL;
+            dashboard_view_id: import("zod").ZodOptional<import("zod").ZodUUID>;
+        }, import("zod/v4/core").$strip>;
+        ModelClass: typeof View;
+        listType: "view";
+    };
+    constructor(client: NotionClient);
+    /**
+     * List the views for a database or data source.
+     *
+     * @param options - Exactly one of `database_id`/`data_source_id`, plus pagination
+     * @returns Paginated list of views
+     *
+     * @throws {NotionValidationError} If neither or both of `database_id`/`data_source_id` are provided
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    list(options: ListViewsOptions): Promise<PaginatedList<View>>;
+    /**
+     * Retrieve a view by ID.
+     *
+     * @param viewId - The ID of the view to retrieve
+     * @returns The view wrapped in a View model
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    retrieve(viewId: string): Promise<View>;
+    /**
+     * Create a new view.
+     *
+     * @param options - Options for creating the view
+     * @returns The created view wrapped in a View model
+     *
+     * @throws {NotionValidationError} If not exactly one of `database_id`/`view_id`/`create_database` is provided
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    create(options: CreateViewOptions): Promise<View>;
+    /**
+     * Update a view's name, filter, sorts, quick filters, or configuration.
+     *
+     * @param viewId - The ID of the view to update
+     * @param options - Options for updating the view
+     * @returns The updated view wrapped in a View model
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    update(viewId: string, options: UpdateViewOptions): Promise<View>;
+    /**
+     * Delete a view.
+     *
+     * Notion's delete-view response differs from other delete methods. It includes
+     * only `object`/`id`/`parent`/`type`, not the full view shape. This method
+     * returns the raw parsed result instead of a full {@link View} model.
+     *
+     * @param viewId - The ID of the view to delete
+     * @returns The partial view object returned by the API
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    delete(viewId: string): Promise<ViewDeleteResult>;
+    /**
+     * Sub-resource to query a view's rows. View queries are non-standard.
+     * Each query returns a `total_count` and an `expires_at` value. The query
+     * result expires about 15 minutes after creation.
+     */
+    readonly queries: {
+        /**
+         * Create a new query against a view.
+         *
+         * @see https://developers.notion.com/guides/data-apis/working-with-views
+         */
+        create: (viewId: string, options?: CreateViewQueryOptions) => Promise<ViewQueryResult>;
+        /**
+         * Retrieve the results of a previously created view query.
+         *
+         * @see https://developers.notion.com/guides/data-apis/working-with-views
+         */
+        get: (viewId: string, queryId: string) => Promise<ViewQueryResult>;
+        /**
+         * Delete a view query.
+         *
+         * @see https://developers.notion.com/guides/data-apis/working-with-views
+         */
+        delete: (viewId: string, queryId: string) => Promise<void>;
+    };
+}

package/dist/api/views.api.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViewsAPI = void 0;
+const models_1 = require("../models");
+const base_model_1 = require("../models/base.model");
+const schemas_1 = require("../schemas");
+const validation_1 = require("../validation");
+const base_api_1 = require("./base.api");
+function toViewQueryResult(response) {
+    const parsed = schemas_1.viewQueryResponseSchema.parse(response);
+    return {
+        id: parsed.id,
+        viewId: parsed.view_id,
+        expiresAt: new Date(parsed.expires_at),
+        totalCount: parsed.total_count,
+        results: parsed.results.map((page) => new models_1.Page(page, base_model_1.TRUSTED)),
+        nextCursor: parsed.next_cursor,
+        hasMore: parsed.has_more,
+        requestStatus: parsed.request_status,
+    };
+}
+/**
+ * Views API client for working with Notion views.
+ *
+ * Views control how a database/data source's rows are displayed (table, board,
+ * calendar, etc.). Requires API version 2025-09-03 or later.
+ *
+ * @category Views
+ */
+class ViewsAPI extends base_api_1.BaseAPI {
+    constructor(client) {
+        super(client);
+        this.client = client;
+        this.config = {
+            schema: schemas_1.viewSchema,
+            ModelClass: models_1.View,
+            listType: 'view',
+        };
+        /**
+         * Sub-resource to query a view's rows. View queries are non-standard.
+         * Each query returns a `total_count` and an `expires_at` value. The query
+         * result expires about 15 minutes after creation.
+         */
+        this.queries = {
+            /**
+             * Create a new query against a view.
+             *
+             * @see https://developers.notion.com/guides/data-apis/working-with-views
+             */
+            create: async (viewId, options) => {
+                const body = {};
+                if (options?.filter) {
+                    body.filter = options.filter;
+                }
+                if (options?.sorts) {
+                    body.sorts = options.sorts;
+                }
+                Object.assign(body, this.buildPaginationBody(options));
+                const response = await this.client.request({
+                    method: 'POST',
+                    path: `/views/${viewId}/queries`,
+                    body: Object.keys(body).length > 0 ? body : undefined,
+                });
+                return toViewQueryResult(response);
+            },
+            /**
+             * Retrieve the results of a previously created view query.
+             *
+             * @see https://developers.notion.com/guides/data-apis/working-with-views
+             */
+            get: async (viewId, queryId) => {
+                const response = await this.client.request({
+                    method: 'GET',
+                    path: `/views/${viewId}/queries/${queryId}`,
+                });
+                return toViewQueryResult(response);
+            },
+            /**
+             * Delete a view query.
+             *
+             * @see https://developers.notion.com/guides/data-apis/working-with-views
+             */
+            delete: async (viewId, queryId) => {
+                await this.client.request({
+                    method: 'DELETE',
+                    path: `/views/${viewId}/queries/${queryId}`,
+                });
+            },
+        };
+    }
+    /**
+     * List the views for a database or data source.
+     *
+     * @param options - Exactly one of `database_id`/`data_source_id`, plus pagination
+     * @returns Paginated list of views
+     *
+     * @throws {NotionValidationError} If neither or both of `database_id`/`data_source_id` are provided
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    async list(options) {
+        if (Boolean(options.database_id) === Boolean(options.data_source_id)) {
+            throw new validation_1.NotionValidationError('Exactly one of database_id or data_source_id must be provided');
+        }
+        const query = {
+            ...(options.database_id ? { database_id: options.database_id } : {}),
+            ...(options.data_source_id ? { data_source_id: options.data_source_id } : {}),
+            ...this.buildPaginationQuery(options),
+        };
+        return this.listResources('/views', query);
+    }
+    /**
+     * Retrieve a view by ID.
+     *
+     * @param viewId - The ID of the view to retrieve
+     * @returns The view wrapped in a View model
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    async retrieve(viewId) {
+        return this.retrieveResource(`/views/${viewId}`);
+    }
+    /**
+     * Create a new view.
+     *
+     * @param options - Options for creating the view
+     * @returns The created view wrapped in a View model
+     *
+     * @throws {NotionValidationError} If not exactly one of `database_id`/`view_id`/`create_database` is provided
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    async create(options) {
+        const selectorCount = [options.database_id, options.view_id, options.create_database].filter((value) => value !== undefined).length;
+        if (selectorCount !== 1) {
+            throw new validation_1.NotionValidationError('Exactly one of database_id, view_id, or create_database must be provided');
+        }
+        return this.createResource('/views', options);
+    }
+    /**
+     * Update a view's name, filter, sorts, quick filters, or configuration.
+     *
+     * @param viewId - The ID of the view to update
+     * @param options - Options for updating the view
+     * @returns The updated view wrapped in a View model
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    async update(viewId, options) {
+        return this.updateResource(`/views/${viewId}`, options);
+    }
+    /**
+     * Delete a view.
+     *
+     * Notion's delete-view response differs from other delete methods. It includes
+     * only `object`/`id`/`parent`/`type`, not the full view shape. This method
+     * returns the raw parsed result instead of a full {@link View} model.
+     *
+     * @param viewId - The ID of the view to delete
+     * @returns The partial view object returned by the API
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    async delete(viewId) {
+        const response = await this.client.request({
+            method: 'DELETE',
+            path: `/views/${viewId}`,
+        });
+        return schemas_1.viewDeleteResponseSchema.parse(response);
+    }
+}
+exports.ViewsAPI = ViewsAPI;

package/dist/client.d.ts

@@ -1,10 +1,14 @@
 /**
- * The Notion API version targeted by this SDK.
- * All schemas, request bodies, helpers, and models are coupled to this version.
+ * The Notion API version this SDK uses.
+ * All schemas, request bodies, helpers, and models depend on this version.
+ *
+ * @category Client & Core
  */
 export declare const NOTION_VERSION: "2026-03-11";
 /**
  * Configuration options for the Notion client.
+ *
+ * @category Client & Core
  */
 export interface NotionClientOptions {
     /** Notion integration token (Bearer token) */
@@ -33,47 +37,43 @@ export interface RequestOptions {
  * Base HTTP client for Notion API requests.
  */
 export declare class NotionClient {
-    private readonly auth;
     private readonly baseUrl;
     private readonly timeoutMs;
     private readonly fetchImpl;
     private readonly maxRetries;
     private readonly retryOnRateLimit;
+    private readonly requestHeaders;
     constructor(options: NotionClientOptions);
     /**
-     * Makes an HTTP request to the Notion API with retry logic for rate limits.
+     * Send a request to the Notion API.
+     * Retry automatically on rate-limited and overloaded responses.
      */
     request<T>(options: RequestOptions): Promise<T>;
     /**
-     * Makes a single HTTP request to the Notion API.
+     * Send one HTTP request to the Notion API.
      */
     private makeRequest;
     /**
-     * Computes a fallback retry delay using exponential backoff.
-     * Used when the `Retry-After` response header is absent.
+     * Calculate a fallback retry delay with exponential backoff.
+     * Use this delay when the response has no `Retry-After` header.
      * Formula: 2^attempt * 1000 ms, capped at 60 seconds.
      */
     private getRetryAfter;
     /**
-     * Sleeps for the specified duration in milliseconds.
+     * Pause for the given duration, in milliseconds.
      */
     private sleep;
     /**
-     * Builds the full URL with query parameters.
+     * Build the full URL with query parameters.
      */
     private buildUrl;
     /**
-     * Builds request headers.
-     */
-    private buildHeaders;
-    /**
-     * Parses the `Retry-After` response header into milliseconds.
-     * Returns `undefined` when the header is absent or not a valid
-     * non-negative integer.
+     * Parse the `Retry-After` response header into milliseconds.
+     * Return `undefined` if the header is missing or not a valid non-negative number.
      */
     private parseRetryAfterHeader;
     /**
-     * Handles error responses from the API.
+     * Handle an error response from the API.
      */
     private handleErrorResponse;
 }

package/dist/client.js

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NotionClient = exports.NOTION_VERSION = void 0;
 const errors_1 = require("./errors");
 /**
- * The Notion API version targeted by this SDK.
- * All schemas, request bodies, helpers, and models are coupled to this version.
+ * The Notion API version this SDK uses.
+ * All schemas, request bodies, helpers, and models depend on this version.
+ *
+ * @category Client & Core
  */
 exports.NOTION_VERSION = '2026-03-11';
 /**
@@ -12,15 +14,20 @@ exports.NOTION_VERSION = '2026-03-11';
  */
 class NotionClient {
     constructor(options) {
-        this.auth = options.auth;
-        this.baseUrl = options.baseUrl ?? 'https://api.notion.com';
+        this.baseUrl = `${options.baseUrl ?? 'https://api.notion.com'}/v1`;
         this.timeoutMs = options.timeoutMs ?? 60000;
         this.fetchImpl = options.fetch ?? fetch;
         this.maxRetries = options.maxRetries ?? 3;
         this.retryOnRateLimit = options.retryOnRateLimit ?? true;
+        this.requestHeaders = {
+            Authorization: `Bearer ${options.auth}`,
+            'Content-Type': 'application/json',
+            'Notion-Version': exports.NOTION_VERSION,
+        };
     }
     /**
-     * Makes an HTTP request to the Notion API with retry logic for rate limits.
+     * Send a request to the Notion API.
+     * Retry automatically on rate-limited and overloaded responses.
      */
     async request(options) {
         let lastError;
@@ -29,10 +36,10 @@ class NotionClient {
                 return await this.makeRequest(options);
             }
             catch (error) {
-                // Only retry on rate limit errors if retry is enabled
+                // Retry rate-limited requests (if enabled) and service-overload (529)
+                // responses, which the API recommends always retrying.
                 if (error instanceof errors_1.NotionAPIError &&
-                    error.isRateLimited() &&
-                    this.retryOnRateLimit &&
+                    ((error.isRateLimited() && this.retryOnRateLimit) || error.isServiceOverloaded()) &&
                     attempt < this.maxRetries) {
                     // Prefer the server-supplied Retry-After value; fall back to
                     // exponential backoff when the header is absent.
@@ -49,17 +56,16 @@ class NotionClient {
         throw lastError ?? new Error('Request failed after all retries');
     }
     /**
-     * Makes a single HTTP request to the Notion API.
+     * Send one HTTP request to the Notion API.
      */
     async makeRequest(options) {
         const url = this.buildUrl(options.path, options.query);
-        const headers = this.buildHeaders();
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
         try {
             const response = await this.fetchImpl(url, {
                 method: options.method,
-                headers,
+                headers: this.requestHeaders,
                 body: options.body ? JSON.stringify(options.body) : undefined,
                 signal: controller.signal,
             });
@@ -89,8 +95,8 @@ class NotionClient {
         }
     }
     /**
-     * Computes a fallback retry delay using exponential backoff.
-     * Used when the `Retry-After` response header is absent.
+     * Calculate a fallback retry delay with exponential backoff.
+     * Use this delay when the response has no `Retry-After` header.
      * Formula: 2^attempt * 1000 ms, capped at 60 seconds.
      */
     getRetryAfter(attempt) {
@@ -98,16 +104,16 @@ class NotionClient {
         return Math.min(backoffMs, 60000); // Cap at 60 seconds
     }
     /**
-     * Sleeps for the specified duration in milliseconds.
+     * Pause for the given duration, in milliseconds.
      */
     sleep(ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }
     /**
-     * Builds the full URL with query parameters.
+     * Build the full URL with query parameters.
      */
     buildUrl(path, query) {
-        const url = new URL(`${this.baseUrl}/v1${path}`);
+        const url = new URL(`${this.baseUrl}${path}`);
         if (query) {
             Object.entries(query).forEach(([key, value]) => {
                 if (value === undefined) {
@@ -124,19 +130,8 @@ class NotionClient {
         return url.toString();
     }
     /**
-     * Builds request headers.
-     */
-    buildHeaders() {
-        return {
-            Authorization: `Bearer ${this.auth}`,
-            'Content-Type': 'application/json',
-            'Notion-Version': exports.NOTION_VERSION,
-        };
-    }
-    /**
-     * Parses the `Retry-After` response header into milliseconds.
-     * Returns `undefined` when the header is absent or not a valid
-     * non-negative integer.
+     * Parse the `Retry-After` response header into milliseconds.
+     * Return `undefined` if the header is missing or not a valid non-negative number.
      */
     parseRetryAfterHeader(response) {
         const header = response.headers.get('Retry-After');
@@ -150,7 +145,7 @@ class NotionClient {
         return Math.ceil(seconds) * 1000;
     }
     /**
-     * Handles error responses from the API.
+     * Handle an error response from the API.
      */
     async handleErrorResponse(response) {
         const retryAfterMs = this.parseRetryAfterHeader(response);