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

package/dist/helpers/file.helpers.d.ts

@@ -74,8 +74,8 @@ declare function nativeIcon(name: string, color?: NativeIconColor): NativeIconRe
  */
 declare function customEmojiIcon(id: string): CustomEmojiIconRef;
 /**
- * Helpers for constructing icon objects (emoji, external URL, file upload,
- * native icon, or custom emoji).
+ * Helpers that create icon objects: emoji, external URL, file upload, native
+ * icon, or custom emoji.
  *
  * @example
  * ```ts
@@ -87,6 +87,8 @@ declare function customEmojiIcon(id: string): CustomEmojiIconRef;
  *   // ...
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const icon: {
     emoji: typeof emojiIcon;
@@ -114,7 +116,7 @@ declare function externalCover(url: string): ExternalRef;
  */
 declare function fileUploadCover(id: string): FileUploadRef;
 /**
- * Helpers for constructing cover image objects.
+ * Helpers that create cover image objects.
  *
  * @example
  * ```ts
@@ -126,6 +128,8 @@ declare function fileUploadCover(id: string): FileUploadRef;
  *   // ...
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const cover: {
     external: typeof externalCover;
@@ -150,10 +154,10 @@ declare function externalFile(url: string): ExternalRef;
  */
 declare function uploadFile(id: string): FileUploadRef;
 /**
- * Helpers for constructing general Notion file objects.
+ * Helpers that create general Notion file objects.
  *
- * Useful for file blocks, image blocks, audio blocks, video blocks,
- * and file property entries.
+ * Use these helpers for file blocks, image blocks, audio blocks, video
+ * blocks, and file property entries.
  *
  * @example
  * ```ts
@@ -162,6 +166,8 @@ declare function uploadFile(id: string): FileUploadRef;
  * notionFile.external('https://example.com/doc.pdf')
  * notionFile.upload('upload-id')
  * ```
+ *
+ * @category Helpers
  */
 export declare const notionFile: {
     external: typeof externalFile;

package/dist/helpers/file.helpers.js

@@ -60,8 +60,8 @@ function customEmojiIcon(id) {
     return { type: 'custom_emoji', custom_emoji: { id } };
 }
 /**
- * Helpers for constructing icon objects (emoji, external URL, file upload,
- * native icon, or custom emoji).
+ * Helpers that create icon objects: emoji, external URL, file upload, native
+ * icon, or custom emoji.
  *
  * @example
  * ```ts
@@ -73,6 +73,8 @@ function customEmojiIcon(id) {
  *   // ...
  * });
  * ```
+ *
+ * @category Helpers
  */
 exports.icon = {
     emoji: emojiIcon,
@@ -107,7 +109,7 @@ function fileUploadCover(id) {
     return { type: 'file_upload', file_upload: { id } };
 }
 /**
- * Helpers for constructing cover image objects.
+ * Helpers that create cover image objects.
  *
  * @example
  * ```ts
@@ -119,6 +121,8 @@ function fileUploadCover(id) {
  *   // ...
  * });
  * ```
+ *
+ * @category Helpers
  */
 exports.cover = {
     external: externalCover,
@@ -150,10 +154,10 @@ function uploadFile(id) {
     return { type: 'file_upload', file_upload: { id } };
 }
 /**
- * Helpers for constructing general Notion file objects.
+ * Helpers that create general Notion file objects.
  *
- * Useful for file blocks, image blocks, audio blocks, video blocks,
- * and file property entries.
+ * Use these helpers for file blocks, image blocks, audio blocks, video
+ * blocks, and file property entries.
  *
  * @example
  * ```ts
@@ -162,6 +166,8 @@ function uploadFile(id) {
  * notionFile.external('https://example.com/doc.pdf')
  * notionFile.upload('upload-id')
  * ```
+ *
+ * @category Helpers
  */
 exports.notionFile = {
     external: externalFile,

package/dist/helpers/filter.helpers.d.ts

@@ -157,6 +157,8 @@ declare function or(...conditions: FilterCondition[]): FilterCondition;
  *   ),
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const filter: {
     text: (property: string) => TextFilter;

package/dist/helpers/filter.helpers.js

@@ -305,6 +305,8 @@ function or(...conditions) {
  *   ),
  * });
  * ```
+ *
+ * @category Helpers
  */
 exports.filter = {
     // Property filters

package/dist/helpers/pagination.helpers.d.ts

@@ -1,10 +1,10 @@
 import type { PaginatedList } from '../schemas';
 /**
- * Pagination helper utilities for collecting all results from paginated Notion API endpoints.
+ * Pagination helpers that collect all results from paginated Notion API endpoints.
  *
- * The Notion API uses cursor-based pagination. All list endpoints return a `PaginatedList<T>`
- * with `results`, `next_cursor`, and `has_more` properties. These helpers automate the process
- * of fetching all pages.
+ * The Notion API uses cursor-based pagination. Each list endpoint returns a
+ * `PaginatedList<T>` object with `results`, `next_cursor`, and `has_more` properties.
+ * These helpers fetch every page automatically.
  *
  * @example
  * ```typescript
@@ -35,14 +35,16 @@ import type { PaginatedList } from '../schemas';
  */
 /**
  * Fetch function that returns a paginated list.
- * Receives an optional cursor and returns the next page of results.
+ * This function receives an optional cursor. It returns the next page of results.
+ *
+ * @category Pagination
  */
 export type PaginatedFetchFunction<T> = (cursor?: string) => Promise<PaginatedList<T>>;
 /**
  * Collects all results from a paginated endpoint by automatically following cursors.
  *
- * This function will keep fetching pages until `has_more` is `false`, collecting all
- * results into a single array. Use this when you need all results at once.
+ * This function fetches pages until `has_more` is `false`. It collects all results
+ * into one array. Use this function when you need all results at once.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Array containing all results from all pages
@@ -82,14 +84,16 @@ export type PaginatedFetchFunction<T> = (cursor?: string) => Promise<PaginatedLi
  *   })
  * );
  * ```
+ *
+ * @category Pagination
  */
 export declare function paginate<T>(fetchPage: PaginatedFetchFunction<T>): Promise<T[]>;
 /**
  * Creates an async iterator that yields individual items from paginated results.
  *
- * This function provides memory-efficient iteration over large result sets by fetching
- * one page at a time and yielding items as needed. Use this with `for await...of` when
- * you want to process results one by one without loading everything into memory.
+ * This function iterates over large result sets without loading everything into
+ * memory. It fetches one page at a time and yields items as needed. Use this function
+ * with `for await...of` to process results one at a time.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @yields Individual items from each page
@@ -124,13 +128,15 @@ export declare function paginate<T>(fetchPage: PaginatedFetchFunction<T>): Promi
  *   console.log(result.url);
  * }
  * ```
+ *
+ * @category Pagination
  */
 export declare function paginateIterator<T>(fetchPage: PaginatedFetchFunction<T>): AsyncGenerator<T, void, undefined>;
 /**
- * Collects all results and returns both the items and pagination metadata.
+ * Collects all results. Returns the items together with pagination metadata.
  *
- * This function is useful when you need to know how many pages were fetched
- * or want to track the total number of API calls made.
+ * Use this function when you need the page count or the total number of API
+ * calls.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Object containing all results and pagination metadata
@@ -143,6 +149,8 @@ export declare function paginateIterator<T>(fetchPage: PaginatedFetchFunction<T>
  *
  * console.log(`Fetched ${totalCount} blocks across ${pageCount} pages`);
  * ```
+ *
+ * @category Pagination
  */
 export declare function paginateWithMetadata<T>(fetchPage: PaginatedFetchFunction<T>): Promise<{
     items: T[];
@@ -150,29 +158,33 @@ export declare function paginateWithMetadata<T>(fetchPage: PaginatedFetchFunctio
     totalCount: number;
 }>;
 /**
- * Fetch function for windowed row collection. Same as {@link PaginatedFetchFunction} plus
- * a second parameter carrying the ISO 8601 `created_time` lower bound for the *next*
- * window, present once the previous window was capped at the query result limit
- * (`request_status.type === 'incomplete'`). The caller merges this into their own
- * created_time-ascending query, e.g. `filter.createdTime('Created time').onOrAfter(createdTimeCursor)`.
+ * Fetch function for windowed row collection. It extends
+ * {@link PaginatedFetchFunction} with a second parameter: the ISO 8601
+ * `created_time` lower bound for the next window. This parameter appears only
+ * after the previous window hits the query result limit
+ * (`request_status.type === 'incomplete'`). Merge this bound into your own
+ * created_time-ascending query, for example
+ * `filter.createdTime().onOrAfter(createdTimeCursor)`.
+ *
+ * @category Pagination
  */
 export type WindowedFetchFunction<T extends {
     id: string;
     createdTime: Date;
 }> = (cursor: string | undefined, createdTimeCursor: string | undefined) => Promise<PaginatedList<T>>;
 /**
- * Iterates over every row of a data source query, transparently working around the
- * API's 10,000-result-per-query cap.
- *
- * Data source (and view) queries cap at 10,000 results; when capped, the response's
- * `has_more` is still `false`, so following `next_cursor`/`has_more` alone silently
- * truncates the result set. When a window is capped (`request_status.type ===
- * 'incomplete'`), this starts a new query filtered to `created_time >=` the last row
- * seen, de-duplicating by `id` across the window boundary. Requires the query to be
- * sorted by `created_time` ascending.
- *
- * @param fetchWindow - Function that fetches one page, given the current cursor and
- * (once a window has been capped) a `created_time` lower bound for the next window
+ * Iterates over every row of a data source query. It works around the API's
+ * 10,000-result-per-query cap.
+ *
+ * Data source and view queries cap at 10,000 results. When a query hits this cap, the
+ * response's `has_more` field is still `false`. Following `next_cursor` and `has_more`
+ * alone silently truncates the result set. When a window hits the cap
+ * (`request_status.type === 'incomplete'`), this function starts a new query filtered
+ * to `created_time >=` the last row seen. It de-duplicates rows by `id` across the
+ * window boundary. The query must sort by `created_time` in ascending order.
+ *
+ * @param fetchWindow - Function that fetches one page. Pass the current cursor. After
+ * a window hits the cap, also pass a `created_time` lower bound for the next window.
  * @yields Individual rows across all windows
  *
  * @example
@@ -182,24 +194,28 @@ export type WindowedFetchFunction<T extends {
  *     start_cursor: cursor,
  *     sorts: [{ timestamp: 'created_time', direction: 'ascending' }],
  *     filter: createdTimeCursor
- *       ? filter.and(baseFilter, filter.createdTime('Created time').onOrAfter(createdTimeCursor))
+ *       ? filter.and(baseFilter, filter.createdTime().onOrAfter(createdTimeCursor))
  *       : baseFilter,
  *   }),
  * );
  * ```
+ *
+ * @category Pagination
  */
 export declare function iterateAllDataSourceRows<T extends {
     id: string;
     createdTime: Date;
 }>(fetchWindow: WindowedFetchFunction<T>): AsyncGenerator<T, void, undefined>;
 /**
- * Collects every row of a data source query into an array, transparently working
- * around the API's 10,000-result-per-query cap. See {@link iterateAllDataSourceRows}
- * for the windowing behavior.
+ * Collects every row of a data source query into an array. It works around the API's
+ * 10,000-result-per-query cap. See {@link iterateAllDataSourceRows} for the windowing
+ * behavior.
  *
- * @param fetchWindow - Function that fetches one page, given the current cursor and
- * (once a window has been capped) a `created_time` lower bound for the next window
+ * @param fetchWindow - Function that fetches one page. Pass the current cursor. After
+ * a window hits the cap, also pass a `created_time` lower bound for the next window.
  * @returns Array containing all rows across all windows
+ *
+ * @category Pagination
  */
 export declare function collectAllDataSourceRows<T extends {
     id: string;

package/dist/helpers/pagination.helpers.js

@@ -8,8 +8,8 @@ exports.collectAllDataSourceRows = collectAllDataSourceRows;
 /**
  * Collects all results from a paginated endpoint by automatically following cursors.
  *
- * This function will keep fetching pages until `has_more` is `false`, collecting all
- * results into a single array. Use this when you need all results at once.
+ * This function fetches pages until `has_more` is `false`. It collects all results
+ * into one array. Use this function when you need all results at once.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Array containing all results from all pages
@@ -49,6 +49,8 @@ exports.collectAllDataSourceRows = collectAllDataSourceRows;
  *   })
  * );
  * ```
+ *
+ * @category Pagination
  */
 async function paginate(fetchPage) {
     const all = [];
@@ -63,9 +65,9 @@ async function paginate(fetchPage) {
 /**
  * Creates an async iterator that yields individual items from paginated results.
  *
- * This function provides memory-efficient iteration over large result sets by fetching
- * one page at a time and yielding items as needed. Use this with `for await...of` when
- * you want to process results one by one without loading everything into memory.
+ * This function iterates over large result sets without loading everything into
+ * memory. It fetches one page at a time and yields items as needed. Use this function
+ * with `for await...of` to process results one at a time.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @yields Individual items from each page
@@ -100,6 +102,8 @@ async function paginate(fetchPage) {
  *   console.log(result.url);
  * }
  * ```
+ *
+ * @category Pagination
  */
 async function* paginateIterator(fetchPage) {
     let cursor;
@@ -112,10 +116,10 @@ async function* paginateIterator(fetchPage) {
     } while (cursor);
 }
 /**
- * Collects all results and returns both the items and pagination metadata.
+ * Collects all results. Returns the items together with pagination metadata.
  *
- * This function is useful when you need to know how many pages were fetched
- * or want to track the total number of API calls made.
+ * Use this function when you need the page count or the total number of API
+ * calls.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Object containing all results and pagination metadata
@@ -128,6 +132,8 @@ async function* paginateIterator(fetchPage) {
  *
  * console.log(`Fetched ${totalCount} blocks across ${pageCount} pages`);
  * ```
+ *
+ * @category Pagination
  */
 async function paginateWithMetadata(fetchPage) {
     const items = [];
@@ -146,18 +152,18 @@ async function paginateWithMetadata(fetchPage) {
     };
 }
 /**
- * Iterates over every row of a data source query, transparently working around the
- * API's 10,000-result-per-query cap.
- *
- * Data source (and view) queries cap at 10,000 results; when capped, the response's
- * `has_more` is still `false`, so following `next_cursor`/`has_more` alone silently
- * truncates the result set. When a window is capped (`request_status.type ===
- * 'incomplete'`), this starts a new query filtered to `created_time >=` the last row
- * seen, de-duplicating by `id` across the window boundary. Requires the query to be
- * sorted by `created_time` ascending.
- *
- * @param fetchWindow - Function that fetches one page, given the current cursor and
- * (once a window has been capped) a `created_time` lower bound for the next window
+ * Iterates over every row of a data source query. It works around the API's
+ * 10,000-result-per-query cap.
+ *
+ * Data source and view queries cap at 10,000 results. When a query hits this cap, the
+ * response's `has_more` field is still `false`. Following `next_cursor` and `has_more`
+ * alone silently truncates the result set. When a window hits the cap
+ * (`request_status.type === 'incomplete'`), this function starts a new query filtered
+ * to `created_time >=` the last row seen. It de-duplicates rows by `id` across the
+ * window boundary. The query must sort by `created_time` in ascending order.
+ *
+ * @param fetchWindow - Function that fetches one page. Pass the current cursor. After
+ * a window hits the cap, also pass a `created_time` lower bound for the next window.
  * @yields Individual rows across all windows
  *
  * @example
@@ -167,14 +173,21 @@ async function paginateWithMetadata(fetchPage) {
  *     start_cursor: cursor,
  *     sorts: [{ timestamp: 'created_time', direction: 'ascending' }],
  *     filter: createdTimeCursor
- *       ? filter.and(baseFilter, filter.createdTime('Created time').onOrAfter(createdTimeCursor))
+ *       ? filter.and(baseFilter, filter.createdTime().onOrAfter(createdTimeCursor))
  *       : baseFilter,
  *   }),
  * );
  * ```
+ *
+ * @category Pagination
  */
 async function* iterateAllDataSourceRows(fetchWindow) {
-    const seenIds = new Set();
+    // Rows repeat across a window boundary only when they share the exact `created_time`
+    // used as the next window's lower bound (results are sorted ascending by created_time,
+    // so ties are always contiguous). Tracking only that trailing tie group -- instead of
+    // every id ever yielded -- keeps memory bounded regardless of result set size.
+    let tailTimeMs;
+    let tailIds = new Set();
     let cursor;
     let createdTimeCursor;
     let lastCreatedTime;
@@ -183,10 +196,15 @@ async function* iterateAllDataSourceRows(fetchWindow) {
         const response = await fetchWindow(cursor, createdTimeCursor);
         let yieldedThisWindow = false;
         for (const item of response.results) {
-            if (seenIds.has(item.id)) {
+            const itemTimeMs = item.createdTime.getTime();
+            if (tailTimeMs !== undefined && itemTimeMs === tailTimeMs && tailIds.has(item.id)) {
                 continue;
             }
-            seenIds.add(item.id);
+            if (tailTimeMs === undefined || itemTimeMs > tailTimeMs) {
+                tailTimeMs = itemTimeMs;
+                tailIds = new Set();
+            }
+            tailIds.add(item.id);
             lastCreatedTime = item.createdTime;
             yieldedThisWindow = true;
             yield item;
@@ -214,13 +232,15 @@ async function* iterateAllDataSourceRows(fetchWindow) {
     }
 }
 /**
- * Collects every row of a data source query into an array, transparently working
- * around the API's 10,000-result-per-query cap. See {@link iterateAllDataSourceRows}
- * for the windowing behavior.
+ * Collects every row of a data source query into an array. It works around the API's
+ * 10,000-result-per-query cap. See {@link iterateAllDataSourceRows} for the windowing
+ * behavior.
  *
- * @param fetchWindow - Function that fetches one page, given the current cursor and
- * (once a window has been capped) a `created_time` lower bound for the next window
+ * @param fetchWindow - Function that fetches one page. Pass the current cursor. After
+ * a window hits the cap, also pass a `created_time` lower bound for the next window.
  * @returns Array containing all rows across all windows
+ *
+ * @category Pagination
  */
 async function collectAllDataSourceRows(fetchWindow) {
     const all = [];

package/dist/helpers/parent.helpers.d.ts

@@ -22,8 +22,8 @@ declare function database(databaseId: string): {
 };
 /**
  * Create a data source parent object.
- * Both data_source_id and database_id are required when creating a page
- * with a data source parent.
+ * A page with a data source parent needs both `data_source_id` and
+ * `database_id`.
  *
  * @example
  * ```ts
@@ -51,7 +51,7 @@ declare function workspace(): {
     workspace: true;
 };
 /**
- * Create a block parent object (used for comments on blocks).
+ * Create a block parent object for comments on blocks.
  *
  * @example
  * ```ts
@@ -86,6 +86,8 @@ declare function blockParent(blockId: string): {
  *   rich_text: [...],
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const parent: {
     page: typeof page;

package/dist/helpers/parent.helpers.js

@@ -28,8 +28,8 @@ function database(databaseId) {
 }
 /**
  * Create a data source parent object.
- * Both data_source_id and database_id are required when creating a page
- * with a data source parent.
+ * A page with a data source parent needs both `data_source_id` and
+ * `database_id`.
  *
  * @example
  * ```ts
@@ -56,7 +56,7 @@ function workspace() {
     return { workspace: true };
 }
 /**
- * Create a block parent object (used for comments on blocks).
+ * Create a block parent object for comments on blocks.
  *
  * @example
  * ```ts
@@ -94,6 +94,8 @@ function blockParent(blockId) {
  *   rich_text: [...],
  * });
  * ```
+ *
+ * @category Helpers
  */
 exports.parent = {
     page,

package/dist/helpers/property.helpers.d.ts

@@ -255,6 +255,8 @@ declare function files(entries: FileEntry[]): {
  *   },
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const prop: {
     title: typeof title;

package/dist/helpers/property.helpers.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.prop = void 0;
 const validation_1 = require("../validation");
 const richText_helpers_1 = require("./richText.helpers");
-/** Resolve rich text input to a `NotionRichText` array. */
+/** Resolve rich text input to a `NotionRichText`. */
 function resolveRichText(input) {
     if (typeof input === 'string') {
         (0, validation_1.validateStringLength)(input, validation_1.LIMITS.RICH_TEXT_CONTENT, 'Rich text content');
@@ -278,6 +278,8 @@ function files(entries) {
  *   },
  * });
  * ```
+ *
+ * @category Helpers
  */
 exports.prop = {
     title,

package/dist/helpers/richText.helpers.d.ts

@@ -5,8 +5,9 @@ import type { NotionColor, NotionRichText, NotionUser, TextRichText } from '../s
  * Do not instantiate directly — use the {@link richText} factory function or
  * the static helpers on it (`richText.mentionPage`, `richText.equation`, etc.).
  *
- * Call `.build()` to produce a `NotionRichText` array (single-element),
- * or pass builders directly to `richText.join()` which calls `.build()` for you.
+ * Call `.build()` to produce a single-element `NotionRichText`.
+ * Alternatively, pass builders directly to `richText.join()`. This method
+ * calls `.build()` for you.
  *
  * @example
  * ```ts
@@ -26,6 +27,8 @@ import type { NotionColor, NotionRichText, NotionUser, TextRichText } from '../s
  *   richText('!'),
  * );
  * ```
+ *
+ * @category Rich Text
  */
 export declare class RichTextBuilder {
     /** @internal */
@@ -52,7 +55,7 @@ export declare class RichTextBuilder {
      */
     link(url: string): this;
     /**
-     * Build a single-element `NotionRichText` array from this builder.
+     * Build a single-element `NotionRichText` from this builder.
      */
     build(): NotionRichText;
 }
@@ -99,8 +102,8 @@ declare function mentionLinkPreview(url: string): RichTextBuilder;
  */
 declare function equation(expression: string): RichTextBuilder;
 /**
- * Combine multiple rich text builders (or pre-built `NotionRichText` arrays)
- * into a single `NotionRichText` array.
+ * Combine multiple rich text builders (or pre-built `NotionRichText` values)
+ * into a single `NotionRichText`.
  *
  * @example
  * ```ts
@@ -136,6 +139,8 @@ declare function join(...parts: Array<RichTextBuilder | NotionRichText>): Notion
  *   richText('italic').italic(),
  * );
  * ```
+ *
+ * @category Rich Text
  */
 export declare const richText: typeof createRichText & {
     mentionPage: typeof mentionPage;

package/dist/helpers/richText.helpers.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.richText = exports.RichTextBuilder = void 0;
 const validation_1 = require("../validation");
 /**
- * Default annotations object with no formatting applied.
+ * Default annotations object with no formatting.
  */
 const DEFAULT_ANNOTATIONS = {
     bold: false,
@@ -19,8 +19,9 @@ const DEFAULT_ANNOTATIONS = {
  * Do not instantiate directly — use the {@link richText} factory function or
  * the static helpers on it (`richText.mentionPage`, `richText.equation`, etc.).
  *
- * Call `.build()` to produce a `NotionRichText` array (single-element),
- * or pass builders directly to `richText.join()` which calls `.build()` for you.
+ * Call `.build()` to produce a single-element `NotionRichText`.
+ * Alternatively, pass builders directly to `richText.join()`. This method
+ * calls `.build()` for you.
  *
  * @example
  * ```ts
@@ -40,6 +41,8 @@ const DEFAULT_ANNOTATIONS = {
  *   richText('!'),
  * );
  * ```
+ *
+ * @category Rich Text
  */
 class RichTextBuilder {
     /** @internal */
@@ -93,7 +96,7 @@ class RichTextBuilder {
         return this;
     }
     /**
-     * Build a single-element `NotionRichText` array from this builder.
+     * Build a single-element `NotionRichText` from this builder.
      */
     build() {
         return [{ ...this.segment, annotations: { ...this.annotations } }];
@@ -218,8 +221,8 @@ function equation(expression) {
     return new RichTextBuilder(segment);
 }
 /**
- * Combine multiple rich text builders (or pre-built `NotionRichText` arrays)
- * into a single `NotionRichText` array.
+ * Combine multiple rich text builders (or pre-built `NotionRichText` values)
+ * into a single `NotionRichText`.
  *
  * @example
  * ```ts
@@ -269,6 +272,8 @@ function join(...parts) {
  *   richText('italic').italic(),
  * );
  * ```
+ *
+ * @category Rich Text
  */
 exports.richText = Object.assign(createRichText, {
     mentionPage,