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

package/dist/schemas/emoji.schema.js

@@ -38,11 +38,13 @@ const z = __importStar(require("zod"));
 /**
  * Notion emoji object schema.
  *
- * Emojis can be used as icons for pages, databases, and other objects.
- * Contains the emoji character as a string.
+ * You can use emojis as icons for pages, databases, and other objects.
+ * This schema stores the emoji character as a string.
  *
  * Notion API reference:
  * https://developers.notion.com/reference/emoji-object
+ *
+ * @category Custom Emoji & Icons
  */
 exports.emojiSchema = z.object({
     type: z.literal('emoji'),

package/dist/schemas/file.schema.d.ts

@@ -2,8 +2,9 @@ import * as z from 'zod';
 /**
  * Notion file object schemas.
  *
- * Files can be Notion-hosted (uploaded through the UI), API-uploaded (via file upload API),
- * or externally hosted (with a URL). Used for page/block icons, covers, and file attachments.
+ * Files can be Notion-hosted (uploaded through the UI), API-uploaded (via the file upload
+ * API), or externally hosted (with a URL). This schema applies to page and block icons,
+ * covers, and file attachments.
  *
  * Notion API reference:
  * https://developers.notion.com/reference/file-object
@@ -30,6 +31,9 @@ declare const externalFileSchema: z.ZodObject<{
         url: z.ZodURL;
     }, z.core.$strip>;
 }, z.core.$strip>;
+/**
+ * @category File Uploads
+ */
 export declare const fileSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"file">;
     file: z.ZodObject<{
@@ -47,8 +51,20 @@ export declare const fileSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         url: z.ZodURL;
     }, z.core.$strip>;
 }, z.core.$strip>], "type">;
+/**
+ * @category File Uploads
+ */
 export type NotionFile = z.infer<typeof fileSchema>;
+/**
+ * @category File Uploads
+ */
 export type NotionHostedFile = z.infer<typeof notionFileSchema>;
+/**
+ * @category File Uploads
+ */
 export type UploadedFile = z.infer<typeof fileUploadSchema>;
+/**
+ * @category File Uploads
+ */
 export type ExternalFile = z.infer<typeof externalFileSchema>;
 export {};

package/dist/schemas/file.schema.js

@@ -39,8 +39,9 @@ const shared_schema_1 = require("./shared.schema");
 /**
  * Notion file object schemas.
  *
- * Files can be Notion-hosted (uploaded through the UI), API-uploaded (via file upload API),
- * or externally hosted (with a URL). Used for page/block icons, covers, and file attachments.
+ * Files can be Notion-hosted (uploaded through the UI), API-uploaded (via the file upload
+ * API), or externally hosted (with a URL). This schema applies to page and block icons,
+ * covers, and file attachments.
  *
  * Notion API reference:
  * https://developers.notion.com/reference/file-object
@@ -67,6 +68,9 @@ const externalFileSchema = z.object({
         url: z.url(),
     }),
 });
+/**
+ * @category File Uploads
+ */
 exports.fileSchema = z.discriminatedUnion('type', [
     notionFileSchema,
     fileUploadSchema,

package/dist/schemas/fileUpload.schema.d.ts

@@ -2,11 +2,14 @@ import * as z from 'zod';
 /**
  * Notion file upload object schema.
  *
- * File uploads represent files uploaded to Notion via the API. They have a temporary
- * upload URL and can be in various states (pending, uploaded, expired, failed).
+ * File uploads represent files uploaded to Notion through the API. Each file upload has
+ * a temporary upload URL. Each file upload has one of these states: pending, uploaded,
+ * expired, or failed.
  *
  * Notion API reference:
  * https://developers.notion.com/reference/file-upload-object
+ *
+ * @category File Uploads
  */
 export declare const fileUploadSchema: z.ZodObject<{
     object: z.ZodLiteral<"file_upload">;
@@ -26,4 +29,7 @@ export declare const fileUploadSchema: z.ZodObject<{
     complete_url: z.ZodString;
     file_import_result: z.ZodString;
 }, z.core.$strip>;
+/**
+ * @category File Uploads
+ */
 export type NotionFileUpload = z.infer<typeof fileUploadSchema>;

package/dist/schemas/fileUpload.schema.js

@@ -39,11 +39,14 @@ const shared_schema_1 = require("./shared.schema");
 /**
  * Notion file upload object schema.
  *
- * File uploads represent files uploaded to Notion via the API. They have a temporary
- * upload URL and can be in various states (pending, uploaded, expired, failed).
+ * File uploads represent files uploaded to Notion through the API. Each file upload has
+ * a temporary upload URL. Each file upload has one of these states: pending, uploaded,
+ * expired, or failed.
  *
  * Notion API reference:
  * https://developers.notion.com/reference/file-upload-object
+ *
+ * @category File Uploads
  */
 exports.fileUploadSchema = z.object({
     object: z.literal('file_upload'),

package/dist/schemas/icon.schema.d.ts

@@ -11,10 +11,19 @@ import * as z from 'zod';
  * Notion API reference:
  * https://developers.notion.com/reference/emoji-object
  */
-/** Colors available for native (icon-picker) icons. */
+/** Colors available for native (icon-picker) icons.
+ *
+ * @category Custom Emoji & Icons
+ */
 export declare const NATIVE_ICON_COLORS: readonly ["gray", "lightgray", "brown", "yellow", "orange", "green", "blue", "purple", "pink", "red"];
+/**
+ * @category Custom Emoji & Icons
+ */
 export type NativeIconColor = (typeof NATIVE_ICON_COLORS)[number];
-/** Native (icon-picker) icon. */
+/** Native (icon-picker) icon.
+ *
+ * @category Custom Emoji & Icons
+ */
 export declare const nativeIconSchema: z.ZodObject<{
     type: z.ZodLiteral<"icon">;
     icon: z.ZodObject<{
@@ -33,8 +42,14 @@ export declare const nativeIconSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+/**
+ * @category Custom Emoji & Icons
+ */
 export type NativeIcon = z.infer<typeof nativeIconSchema>;
-/** Custom emoji icon. */
+/** Custom emoji icon.
+ *
+ * @category Custom Emoji & Icons
+ */
 export declare const customEmojiIconSchema: z.ZodObject<{
     type: z.ZodLiteral<"custom_emoji">;
     custom_emoji: z.ZodObject<{
@@ -43,8 +58,14 @@ export declare const customEmojiIconSchema: z.ZodObject<{
         url: z.ZodOptional<z.ZodURL>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+/**
+ * @category Custom Emoji & Icons
+ */
 export type CustomEmojiIcon = z.infer<typeof customEmojiIconSchema>;
-/** Shared icon schema covering all icon object variants. */
+/** Shared icon schema covering all icon object variants.
+ *
+ * @category Custom Emoji & Icons
+ */
 export declare const iconSchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"file">;
     file: z.ZodObject<{
@@ -89,4 +110,7 @@ export declare const iconSchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z
         url: z.ZodOptional<z.ZodURL>;
     }, z.core.$strip>;
 }, z.core.$strip>]>;
+/**
+ * @category Custom Emoji & Icons
+ */
 export type NotionIcon = z.infer<typeof iconSchema>;

package/dist/schemas/icon.schema.js

@@ -49,7 +49,10 @@ const file_schema_1 = require("./file.schema");
  * Notion API reference:
  * https://developers.notion.com/reference/emoji-object
  */
-/** Colors available for native (icon-picker) icons. */
+/** Colors available for native (icon-picker) icons.
+ *
+ * @category Custom Emoji & Icons
+ */
 exports.NATIVE_ICON_COLORS = [
     'gray',
     'lightgray',
@@ -62,7 +65,10 @@ exports.NATIVE_ICON_COLORS = [
     'pink',
     'red',
 ];
-/** Native (icon-picker) icon. */
+/** Native (icon-picker) icon.
+ *
+ * @category Custom Emoji & Icons
+ */
 exports.nativeIconSchema = z.object({
     type: z.literal('icon'),
     icon: z.object({
@@ -70,7 +76,10 @@ exports.nativeIconSchema = z.object({
         color: z.enum(exports.NATIVE_ICON_COLORS).optional(),
     }),
 });
-/** Custom emoji icon. */
+/** Custom emoji icon.
+ *
+ * @category Custom Emoji & Icons
+ */
 exports.customEmojiIconSchema = z.object({
     type: z.literal('custom_emoji'),
     custom_emoji: z.object({
@@ -79,7 +88,10 @@ exports.customEmojiIconSchema = z.object({
         url: z.url().optional(),
     }),
 });
-/** Shared icon schema covering all icon object variants. */
+/** Shared icon schema covering all icon object variants.
+ *
+ * @category Custom Emoji & Icons
+ */
 exports.iconSchema = z.union([
     file_schema_1.fileSchema,
     emoji_schema_1.emojiSchema,

package/dist/schemas/meetingNotesQuery.schema.d.ts

@@ -4,12 +4,20 @@ import * as z from 'zod';
  *
  * Notion API reference:
  * https://developers.notion.com/reference/query-meeting-notes
+ *
+ * @category Pages
  */
 export declare const MEETING_NOTES_QUERY_PROPERTIES: readonly ["title", "attendees", "created_time", "created_by", "last_edited_time", "last_edited_by"];
+/**
+ * @category Pages
+ */
 export type MeetingNotesQueryProperty = (typeof MEETING_NOTES_QUERY_PROPERTIES)[number];
 /**
- * Response shape is genuinely non-standard: no `object` field, no `next_cursor` at
- * all -- pagination is controlled purely by `limit` (max 50 per request, no cursor).
+ * This response shape is non-standard. It has no `object` field and no `next_cursor`
+ * field. The `limit` parameter alone controls pagination, up to 50 results per request,
+ * with no cursor.
+ *
+ * @category Pages
  */
 export declare const meetingNotesQueryResponseSchema: z.ZodObject<{
     results: z.ZodArray<z.ZodObject<{
@@ -4184,4 +4192,7 @@ export declare const meetingNotesQueryResponseSchema: z.ZodObject<{
         }>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * @category Pages
+ */
 export type MeetingNotesQueryResponse = z.infer<typeof meetingNotesQueryResponseSchema>;

package/dist/schemas/meetingNotesQuery.schema.js

@@ -42,6 +42,8 @@ const pagination_schema_1 = require("./pagination.schema");
  *
  * Notion API reference:
  * https://developers.notion.com/reference/query-meeting-notes
+ *
+ * @category Pages
  */
 exports.MEETING_NOTES_QUERY_PROPERTIES = [
     'title',
@@ -52,8 +54,11 @@ exports.MEETING_NOTES_QUERY_PROPERTIES = [
     'last_edited_by',
 ];
 /**
- * Response shape is genuinely non-standard: no `object` field, no `next_cursor` at
- * all -- pagination is controlled purely by `limit` (max 50 per request, no cursor).
+ * This response shape is non-standard. It has no `object` field and no `next_cursor`
+ * field. The `limit` parameter alone controls pagination, up to 50 results per request,
+ * with no cursor.
+ *
+ * @category Pages
  */
 exports.meetingNotesQueryResponseSchema = z.object({
     results: z.array(block_schema_1.blockSchema),

package/dist/schemas/page.schema.d.ts

@@ -7,6 +7,8 @@ import * as z from 'zod';
  *
  * Notion API reference:
  * https://developers.notion.com/reference/page
+ *
+ * @category Pages
  */
 export declare const pageSchema: z.ZodObject<{
     object: z.ZodLiteral<"page">;
@@ -900,4 +902,7 @@ export declare const pageSchema: z.ZodObject<{
     url: z.ZodURL;
     public_url: z.ZodNullable<z.ZodURL>;
 }, z.core.$strip>;
+/**
+ * @category Pages
+ */
 export type NotionPage = z.infer<typeof pageSchema>;

package/dist/schemas/page.schema.js

@@ -49,6 +49,8 @@ const user_schema_1 = require("./user.schema");
  *
  * Notion API reference:
  * https://developers.notion.com/reference/page
+ *
+ * @category Pages
  */
 exports.pageSchema = z.object({
     object: z.literal('page'),

package/dist/schemas/pageMarkdown.schema.d.ts

@@ -7,6 +7,8 @@ import * as z from 'zod';
  *
  * Notion API reference:
  * https://developers.notion.com/guides/data-apis/working-with-markdown-content
+ *
+ * @category Pages
  */
 export declare const pageMarkdownSchema: z.ZodObject<{
     object: z.ZodLiteral<"page_markdown">;
@@ -15,12 +17,18 @@ export declare const pageMarkdownSchema: z.ZodObject<{
     truncated: z.ZodBoolean;
     unknown_block_ids: z.ZodArray<z.ZodUUID>;
 }, z.core.$strip>;
+/**
+ * @category Pages
+ */
 export type PageMarkdown = z.infer<typeof pageMarkdownSchema>;
 /**
- * `PATCH /v1/pages/{page_id}/markdown` returns `pageMarkdownSchema` synchronously, or
- * (when `allow_async: true` triggers async processing) an `async_task` handle to poll
- * via {@link AsyncTasksAPI}. Both response bodies carry a literal `object` field, so
- * they discriminate cleanly without needing the HTTP status code.
+ * `PATCH /v1/pages/{page_id}/markdown` returns `pageMarkdownSchema` synchronously. If
+ * `allow_async: true` triggers async processing, it returns an `async_task` handle
+ * instead. Poll the handle through {@link AsyncTasksAPI}. Both response bodies carry a
+ * literal `object` field, so you can discriminate between them without checking the
+ * HTTP status code.
+ *
+ * @category Pages
  */
 export declare const markdownContentResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     object: z.ZodLiteral<"page_markdown">;
@@ -56,4 +64,7 @@ export declare const markdownContentResponseSchema: z.ZodDiscriminatedUnion<[z.Z
         message: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>], "object">;
+/**
+ * @category Pages
+ */
 export type MarkdownContentResponse = z.infer<typeof markdownContentResponseSchema>;

package/dist/schemas/pageMarkdown.schema.js

@@ -44,6 +44,8 @@ const asyncTask_schema_1 = require("./asyncTask.schema");
  *
  * Notion API reference:
  * https://developers.notion.com/guides/data-apis/working-with-markdown-content
+ *
+ * @category Pages
  */
 exports.pageMarkdownSchema = z.object({
     object: z.literal('page_markdown'),
@@ -54,10 +56,13 @@ exports.pageMarkdownSchema = z.object({
     unknown_block_ids: z.array(z.uuid()).max(100),
 });
 /**
- * `PATCH /v1/pages/{page_id}/markdown` returns `pageMarkdownSchema` synchronously, or
- * (when `allow_async: true` triggers async processing) an `async_task` handle to poll
- * via {@link AsyncTasksAPI}. Both response bodies carry a literal `object` field, so
- * they discriminate cleanly without needing the HTTP status code.
+ * `PATCH /v1/pages/{page_id}/markdown` returns `pageMarkdownSchema` synchronously. If
+ * `allow_async: true` triggers async processing, it returns an `async_task` handle
+ * instead. Poll the handle through {@link AsyncTasksAPI}. Both response bodies carry a
+ * literal `object` field, so you can discriminate between them without checking the
+ * HTTP status code.
+ *
+ * @category Pages
  */
 exports.markdownContentResponseSchema = z.discriminatedUnion('object', [
     exports.pageMarkdownSchema,

package/dist/schemas/pageProperties.schema.d.ts

@@ -2,9 +2,9 @@ import * as z from 'zod';
 /**
  * Page property value schemas.
  *
- * These define the actual data values stored in page properties (database columns).
- * Different from property objects which define the schema/configuration.
- * Supports 23 property types including title, rich text, number, select, etc.
+ * These schemas define the data values in page properties (database columns).
+ * Property objects define the schema and configuration instead.
+ * This file supports 22 property types, including title, rich text, number, and select.
  *
  * Notion API reference:
  * https://developers.notion.com/reference/page-property-values
@@ -786,6 +786,9 @@ declare const verificationPropertySchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * @category Page Properties
+ */
 export declare const pagePropertiesSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     id: z.ZodString;
     type: z.ZodLiteral<"checkbox">;
@@ -1520,27 +1523,96 @@ export declare const pagePropertiesSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>], "type">;
+/**
+ * @category Page Properties
+ */
 export type NotionPageProperties = z.infer<typeof pagePropertiesSchema>;
+/**
+ * @category Page Properties
+ */
 export type CheckboxProperty = z.infer<typeof checkboxPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type CreatedByProperty = z.infer<typeof createdByPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type CreatedTimeProperty = z.infer<typeof createdTimePropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type DateProperty = z.infer<typeof datePropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type EmailProperty = z.infer<typeof emailPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type FilesProperty = z.infer<typeof filesPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type FormulaProperty = z.infer<typeof formulaPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type LastEditedByProperty = z.infer<typeof lastEditedByPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type LastEditedTimeProperty = z.infer<typeof lastEditedTimePropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type MultiSelectProperty = z.infer<typeof multiSelectPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type NumberProperty = z.infer<typeof numberPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type PeopleProperty = z.infer<typeof peoplePropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type PhoneNumberProperty = z.infer<typeof phoneNumberPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type RelationProperty = z.infer<typeof relationPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type RichTextProperty = z.infer<typeof richTextPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type RollupProperty = z.infer<typeof rollupPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type SelectProperty = z.infer<typeof selectPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type StatusProperty = z.infer<typeof statusPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type TitleProperty = z.infer<typeof titlePropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type UrlProperty = z.infer<typeof urlPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type UniqueIdProperty = z.infer<typeof uniqueIdPropertySchema>;
+/**
+ * @category Page Properties
+ */
 export type VerificationProperty = z.infer<typeof verificationPropertySchema>;
 export {};

package/dist/schemas/pageProperties.schema.js

@@ -42,9 +42,9 @@ const user_schema_1 = require("./user.schema");
 /**
  * Page property value schemas.
  *
- * These define the actual data values stored in page properties (database columns).
- * Different from property objects which define the schema/configuration.
- * Supports 23 property types including title, rich text, number, select, etc.
+ * These schemas define the data values in page properties (database columns).
+ * Property objects define the schema and configuration instead.
+ * This file supports 22 property types, including title, rich text, number, and select.
  *
  * Notion API reference:
  * https://developers.notion.com/reference/page-property-values
@@ -274,6 +274,9 @@ const verificationPropertySchema = z.object({
     })
         .nullable(),
 });
+/**
+ * @category Page Properties
+ */
 exports.pagePropertiesSchema = z.discriminatedUnion('type', [
     checkboxPropertySchema,
     createdByPropertySchema,

package/dist/schemas/pagination.schema.d.ts

@@ -3,28 +3,38 @@ import * as z from 'zod';
  * Pagination schemas and utilities.
  *
  * The Notion API uses cursor-based pagination for list endpoints. Responses include
- * results, a next_cursor, and has_more flag. This file provides reusable schemas
- * and types for working with paginated responses.
+ * results, a next_cursor, and a has_more flag. This file provides reusable schemas
+ * and types to work with paginated responses.
  *
  * Notion API reference:
  * https://developers.notion.com/reference/intro#pagination
  */
 /**
  * Paginated list response type.
- * As of API version 2025-09-03, 'data_source' and 'page_or_data_source' are used
- * instead of 'database' and 'page_or_database' in search results.
+ * As of API version 2025-09-03, search results use 'data_source' and
+ * 'page_or_data_source' instead of 'database' and 'page_or_database'.
+ *
+ * @category Pagination
  */
 export type PaginatedListType = 'block' | 'comment' | 'custom_emoji' | 'database' | 'data_source' | 'page' | 'page_or_database' | 'page_or_data_source' | 'property_item' | 'user' | 'view';
 /**
- * Reasons a query can be reported as incomplete despite `has_more` being `false`.
- * Currently only emitted when a query hits the 10,000-result pagination depth cap.
+ * Reasons why a query result can be incomplete even when `has_more` is `false`.
+ * This happens only when a query hits the 10,000-result pagination depth cap.
+ *
+ * @category Pagination
  */
 export declare const REQUEST_STATUS_INCOMPLETE_REASONS: readonly ["query_result_limit_reached"];
+/**
+ * @category Pagination
+ */
 export type RequestStatusIncompleteReason = (typeof REQUEST_STATUS_INCOMPLETE_REASONS)[number];
 /**
- * Signals that a query was truncated even though `has_more` is `false` -- e.g. data source,
- * view, and meeting-notes queries cap at 10,000 results. Callers that need every row must
- * detect this and re-query with a narrower filter (see the pagination helpers).
+ * This schema flags a truncated query even though `has_more` is `false`. For example,
+ * data source, view, and meeting-notes queries cap at 10,000 results. Callers that need
+ * every row must detect this. Then they must re-query with a narrower filter (see the
+ * pagination helpers).
+ *
+ * @category Pagination
  */
 export declare const requestStatusSchema: z.ZodObject<{
     type: z.ZodLiteral<"incomplete">;
@@ -32,9 +42,14 @@ export declare const requestStatusSchema: z.ZodObject<{
         query_result_limit_reached: "query_result_limit_reached";
     }>;
 }, z.core.$strip>;
+/**
+ * @category Pagination
+ */
 export type RequestStatus = z.infer<typeof requestStatusSchema>;
 /**
  * Base paginated list response schema.
+ *
+ * @category Pagination
  */
 export declare const paginatedListSchema: <T extends z.ZodTypeAny>(resultSchema: T) => z.ZodObject<{
     object: z.ZodLiteral<"list">;
@@ -63,15 +78,23 @@ export declare const paginatedListSchema: <T extends z.ZodTypeAny>(resultSchema:
 }, z.core.$strip>;
 /**
  * Pagination parameters for requests.
+ *
+ * @category Pagination
  */
 export interface PaginationParameters {
     /** The number of items to return (default: 100, max: 100) */
     page_size?: number;
-    /** The cursor value from a previous response to continue pagination (`null` is treated the same as omitted) */
+    /**
+     * The cursor value from a previous response.
+     * Pass it to continue pagination.
+     * The SDK treats `null` the same as omitted.
+     */
     start_cursor?: string | null;
 }
 /**
  * Helper to create paginated response type.
+ *
+ * @category Pagination
  */
 export type PaginatedList<T> = {
     object: 'list';

package/dist/schemas/pagination.schema.js

@@ -36,14 +36,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.paginatedListSchema = exports.requestStatusSchema = exports.REQUEST_STATUS_INCOMPLETE_REASONS = void 0;
 const z = __importStar(require("zod"));
 /**
- * Reasons a query can be reported as incomplete despite `has_more` being `false`.
- * Currently only emitted when a query hits the 10,000-result pagination depth cap.
+ * Reasons why a query result can be incomplete even when `has_more` is `false`.
+ * This happens only when a query hits the 10,000-result pagination depth cap.
+ *
+ * @category Pagination
  */
 exports.REQUEST_STATUS_INCOMPLETE_REASONS = ['query_result_limit_reached'];
 /**
- * Signals that a query was truncated even though `has_more` is `false` -- e.g. data source,
- * view, and meeting-notes queries cap at 10,000 results. Callers that need every row must
- * detect this and re-query with a narrower filter (see the pagination helpers).
+ * This schema flags a truncated query even though `has_more` is `false`. For example,
+ * data source, view, and meeting-notes queries cap at 10,000 results. Callers that need
+ * every row must detect this. Then they must re-query with a narrower filter (see the
+ * pagination helpers).
+ *
+ * @category Pagination
  */
 exports.requestStatusSchema = z.object({
     type: z.literal('incomplete'),
@@ -51,6 +56,8 @@ exports.requestStatusSchema = z.object({
 });
 /**
  * Base paginated list response schema.
+ *
+ * @category Pagination
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 const paginatedListSchema = (resultSchema) => {