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

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

@@ -37,6 +37,9 @@ declare const partialUserSchema: z.ZodObject<{
     object: z.ZodLiteral<"user">;
     id: z.ZodUUID;
 }, z.core.$strip>;
+/**
+ * @category Users
+ */
 export declare const userSchema: z.ZodUnion<readonly [z.ZodObject<{
     object: z.ZodLiteral<"user">;
     id: z.ZodUUID;
@@ -70,8 +73,20 @@ export declare const userSchema: z.ZodUnion<readonly [z.ZodObject<{
     object: z.ZodLiteral<"user">;
     id: z.ZodUUID;
 }, z.core.$strip>]>;
+/**
+ * @category Users
+ */
 export type NotionUser = z.infer<typeof userSchema>;
+/**
+ * @category Users
+ */
 export type PersonUser = z.infer<typeof personUserSchema>;
+/**
+ * @category Users
+ */
 export type BotUser = z.infer<typeof botUserSchema>;
+/**
+ * @category Users
+ */
 export type PartialUser = z.infer<typeof partialUserSchema>;
 export {};

package/dist/schemas/user.schema.js

@@ -38,8 +38,8 @@ const z = __importStar(require("zod"));
 /**
  * Notion user object schemas.
  *
- * Users can be people, bots, or partial user objects (just id and object type).
- * Used throughout the API for created_by and last_edited_by fields.
+ * Users can be people, bots, or partial user objects (only id and object type).
+ * The created_by and last_edited_by fields use this schema throughout the API.
  *
  * Notion API reference:
  * https://developers.notion.com/reference/user
@@ -89,4 +89,7 @@ const partialUserSchema = z.object({
     object: z.literal('user'),
     id: z.uuid(),
 });
+/**
+ * @category Users
+ */
 exports.userSchema = z.union([personUserSchema, botUserSchema, partialUserSchema]);

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

@@ -2,19 +2,30 @@ import * as z from 'zod';
 /**
  * View object schema.
  *
- * Views control how a database/data source's rows are displayed (table, board,
- * calendar, etc.). As of API version 2025-09-03, views have their own endpoints.
+ * A view controls how a database or data source displays its rows, for example as a
+ * table, board, or calendar. As of API version 2025-09-03, views have their own
+ * endpoints.
  *
  * Notion API reference:
  * https://developers.notion.com/guides/data-apis/working-with-views
+ *
+ * @category Views
  */
 export declare const VIEW_TYPES: readonly ["table", "board", "list", "calendar", "timeline", "gallery", "form", "chart", "map", "dashboard"];
+/**
+ * @category Views
+ */
 export type ViewType = (typeof VIEW_TYPES)[number];
 /**
- * Per-layout view configuration. Exact per-type fields (e.g. table column order, board
- * group-by property) haven't been confirmed against a live response, so this is kept
- * permissive -- tagged on `type`, with all other fields passed through unmodeled -- so
- * unknown fields round-trip instead of being stripped or rejected.
+ * Configuration for a single view layout.
+ *
+ * Notion has not confirmed the exact fields for each view type against a live
+ * response. Examples include the table column order and the board group-by
+ * property. This schema stays permissive. It tags the object by its `type`
+ * field and passes all other fields through without validation. As a result,
+ * unknown fields round-trip unchanged instead of the schema rejecting them.
+ *
+ * @category Views
  */
 export declare const viewConfigurationSchema: z.ZodObject<{
     type: z.ZodEnum<{
@@ -30,7 +41,13 @@ export declare const viewConfigurationSchema: z.ZodObject<{
         dashboard: "dashboard";
     }>;
 }, z.core.$catchall<z.ZodUnknown>>;
+/**
+ * @category Views
+ */
 export type ViewConfiguration = z.infer<typeof viewConfigurationSchema>;
+/**
+ * @category Views
+ */
 export declare const viewSchema: z.ZodObject<{
     object: z.ZodLiteral<"view">;
     id: z.ZodUUID;
@@ -140,8 +157,16 @@ export declare const viewSchema: z.ZodObject<{
     url: z.ZodURL;
     dashboard_view_id: z.ZodOptional<z.ZodUUID>;
 }, z.core.$strip>;
+/**
+ * @category Views
+ */
 export type NotionView = z.infer<typeof viewSchema>;
-/** Delete-a-view returns a partial object: only object/id/parent/type. */
+/**
+ * Notion's delete-view response includes only `object`, `id`, `parent`, and `type`.
+ * It omits the rest of the view shape.
+ *
+ * @category Views
+ */
 export declare const viewDeleteResponseSchema: z.ZodObject<{
     object: z.ZodLiteral<"view">;
     id: z.ZodUUID;
@@ -162,10 +187,16 @@ export declare const viewDeleteResponseSchema: z.ZodObject<{
         dashboard: "dashboard";
     }>;
 }, z.core.$strip>;
+/**
+ * @category Views
+ */
 export type ViewDeleteResult = z.infer<typeof viewDeleteResponseSchema>;
 /**
- * View query response schema. Non-standard pagination shape: `object: "view_query"`,
- * plus `expires_at`/`total_count`; queries expire roughly 15 minutes after creation.
+ * View query response schema. This response has a non-standard pagination shape:
+ * `object: "view_query"`, plus `expires_at` and `total_count`. Queries expire
+ * about 15 minutes after creation.
+ *
+ * @category Views
  */
 export declare const viewQueryResponseSchema: z.ZodObject<{
     object: z.ZodLiteral<"view_query">;
@@ -404,6 +435,9 @@ export declare const viewQueryResponseSchema: z.ZodObject<{
             }, z.core.$strip>, z.ZodObject<{
                 type: z.ZodLiteral<"string">;
                 string: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"unsupported">;
+                unsupported: z.ZodObject<{}, z.core.$strip>;
             }, z.core.$strip>], "type">;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;
@@ -1074,4 +1108,7 @@ export declare const viewQueryResponseSchema: z.ZodObject<{
         }>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * @category Views
+ */
 export type ViewQueryResponse = z.infer<typeof viewQueryResponseSchema>;

package/dist/schemas/view.schema.js

@@ -43,11 +43,14 @@ const user_schema_1 = require("./user.schema");
 /**
  * View object schema.
  *
- * Views control how a database/data source's rows are displayed (table, board,
- * calendar, etc.). As of API version 2025-09-03, views have their own endpoints.
+ * A view controls how a database or data source displays its rows, for example as a
+ * table, board, or calendar. As of API version 2025-09-03, views have their own
+ * endpoints.
  *
  * Notion API reference:
  * https://developers.notion.com/guides/data-apis/working-with-views
+ *
+ * @category Views
  */
 exports.VIEW_TYPES = [
     'table',
@@ -62,16 +65,24 @@ exports.VIEW_TYPES = [
     'dashboard',
 ];
 /**
- * Per-layout view configuration. Exact per-type fields (e.g. table column order, board
- * group-by property) haven't been confirmed against a live response, so this is kept
- * permissive -- tagged on `type`, with all other fields passed through unmodeled -- so
- * unknown fields round-trip instead of being stripped or rejected.
+ * Configuration for a single view layout.
+ *
+ * Notion has not confirmed the exact fields for each view type against a live
+ * response. Examples include the table column order and the board group-by
+ * property. This schema stays permissive. It tags the object by its `type`
+ * field and passes all other fields through without validation. As a result,
+ * unknown fields round-trip unchanged instead of the schema rejecting them.
+ *
+ * @category Views
  */
 exports.viewConfigurationSchema = z
     .object({
     type: z.enum(exports.VIEW_TYPES),
 })
     .catchall(z.unknown());
+/**
+ * @category Views
+ */
 exports.viewSchema = z.object({
     object: z.literal('view'),
     id: z.uuid(),
@@ -91,7 +102,12 @@ exports.viewSchema = z.object({
     // Widget/dashboard views only.
     dashboard_view_id: z.uuid().optional(),
 });
-/** Delete-a-view returns a partial object: only object/id/parent/type. */
+/**
+ * Notion's delete-view response includes only `object`, `id`, `parent`, and `type`.
+ * It omits the rest of the view shape.
+ *
+ * @category Views
+ */
 exports.viewDeleteResponseSchema = z.object({
     object: z.literal('view'),
     id: z.uuid(),
@@ -99,8 +115,11 @@ exports.viewDeleteResponseSchema = z.object({
     type: z.enum(exports.VIEW_TYPES),
 });
 /**
- * View query response schema. Non-standard pagination shape: `object: "view_query"`,
- * plus `expires_at`/`total_count`; queries expire roughly 15 minutes after creation.
+ * View query response schema. This response has a non-standard pagination shape:
+ * `object: "view_query"`, plus `expires_at` and `total_count`. Queries expire
+ * about 15 minutes after creation.
+ *
+ * @category Views
  */
 exports.viewQueryResponseSchema = z.object({
     object: z.literal('view_query'),

package/dist/validation.d.ts

@@ -1,7 +1,9 @@
 /**
- * Notion API request size limits.
+ * Maximum sizes the Notion API allows in a request.
  *
  * @see https://developers.notion.com/reference/request-limits#size-limits
+ *
+ * @category Client & Core
  */
 export declare const LIMITS: {
     /** Maximum characters in a single rich text `text.content` field. */
@@ -34,9 +36,10 @@ export declare const LIMITS: {
 /**
  * Thrown when a value exceeds a Notion API size limit.
  *
- * This error is raised client-side *before* the request is sent, giving
- * callers an early, actionable error message instead of a generic 400 from
- * the API.
+ * The SDK throws this error before it sends the request. This gives you an
+ * early, actionable message instead of a generic 400 response from the API.
+ *
+ * @category Errors
  */
 export declare class NotionValidationError extends Error {
     constructor(message: string);
@@ -45,11 +48,15 @@ export declare class NotionValidationError extends Error {
  * Assert that a string does not exceed `maxLength` characters.
  *
  * @throws {NotionValidationError}
+ *
+ * @category Client & Core
  */
 export declare function validateStringLength(value: string, maxLength: number, label: string): void;
 /**
  * Assert that an array does not exceed `maxLength` elements.
  *
  * @throws {NotionValidationError}
+ *
+ * @category Client & Core
  */
 export declare function validateArrayLength(array: unknown[], maxLength: number, label: string): void;

package/dist/validation.js

@@ -4,9 +4,11 @@ exports.NotionValidationError = exports.LIMITS = void 0;
 exports.validateStringLength = validateStringLength;
 exports.validateArrayLength = validateArrayLength;
 /**
- * Notion API request size limits.
+ * Maximum sizes the Notion API allows in a request.
  *
  * @see https://developers.notion.com/reference/request-limits#size-limits
+ *
+ * @category Client & Core
  */
 exports.LIMITS = {
     /** Maximum characters in a single rich text `text.content` field. */
@@ -39,9 +41,10 @@ exports.LIMITS = {
 /**
  * Thrown when a value exceeds a Notion API size limit.
  *
- * This error is raised client-side *before* the request is sent, giving
- * callers an early, actionable error message instead of a generic 400 from
- * the API.
+ * The SDK throws this error before it sends the request. This gives you an
+ * early, actionable message instead of a generic 400 response from the API.
+ *
+ * @category Errors
  */
 class NotionValidationError extends Error {
     constructor(message) {
@@ -60,6 +63,8 @@ exports.NotionValidationError = NotionValidationError;
  * Assert that a string does not exceed `maxLength` characters.
  *
  * @throws {NotionValidationError}
+ *
+ * @category Client & Core
  */
 function validateStringLength(value, maxLength, label) {
     if (value.length > maxLength) {
@@ -73,6 +78,8 @@ function validateStringLength(value, maxLength, label) {
  * Assert that an array does not exceed `maxLength` elements.
  *
  * @throws {NotionValidationError}
+ *
+ * @category Client & Core
  */
 function validateArrayLength(array, maxLength, label) {
     if (array.length > maxLength) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visus-io/notion-sdk-ts",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "private": false,
   "description": "TypeScript SDK for the Notion API",
   "keywords": [
@@ -38,6 +38,9 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "docs:build": "cd docs && bun run build",
+    "docs:dev": "cd docs && bun run dev",
+    "docs:install": "cd docs && bun install",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "eslint .",
@@ -60,26 +63,27 @@
     ]
   },
   "dependencies": {
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@commitlint/cli": "^21.0.0",
-    "@commitlint/config-conventional": "^21.0.0",
-    "@types/node": "^25.2.1",
-    "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^10.0.0",
-    "eslint-plugin-zod": "4.9.0",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@types/bun": "^1.4.0",
+    "@types/node": "^25.9.5",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10.9.0",
+    "eslint-plugin-zod": "4.12.0",
     "husky": "^9.1.7",
-    "lint-staged": "^16.2.7",
+    "lint-staged": "^16.4.0",
     "msw": "2.15.0",
-    "prettier": "^3.8.1",
-    "prettier-plugin-packagejson": "^3.0.0",
-    "typescript": "^6.0.0",
-    "typescript-eslint": "^8.54.0",
-    "vitest": "^4.0.18"
+    "prettier": "^3.9.6",
+    "prettier-plugin-packagejson": "^3.0.2",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^4.1.11"
   },
   "engines": {
-    "bun": ">=1.3.10",
-    "node": ">=18.0.0"
+    "bun": ">=1.4.0",
+    "node": ">=22.0.0"
   }
 }