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

package/dist/schemas/view.schema.js

@@ -0,0 +1,134 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.viewQueryResponseSchema = exports.viewDeleteResponseSchema = exports.viewSchema = exports.viewConfigurationSchema = exports.VIEW_TYPES = void 0;
+const z = __importStar(require("zod"));
+const parent_schema_1 = require("./parent.schema");
+const page_schema_1 = require("./page.schema");
+const pagination_schema_1 = require("./pagination.schema");
+const shared_schema_1 = require("./shared.schema");
+const user_schema_1 = require("./user.schema");
+/**
+ * View object schema.
+ *
+ * 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',
+    'board',
+    'list',
+    'calendar',
+    'timeline',
+    'gallery',
+    'form',
+    'chart',
+    'map',
+    'dashboard',
+];
+/**
+ * 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(),
+    parent: parent_schema_1.databaseParentSchema,
+    data_source_id: z.uuid().nullable(),
+    name: z.string().trim(),
+    type: z.enum(exports.VIEW_TYPES),
+    filter: z.record(z.string(), z.unknown()).nullish(),
+    sorts: z.array(z.record(z.string(), z.unknown())).nullish(),
+    quick_filters: z.record(z.string(), z.unknown()).nullish(),
+    configuration: exports.viewConfigurationSchema.optional(),
+    created_time: shared_schema_1.notionDateStringSchema,
+    last_edited_time: shared_schema_1.notionDateStringSchema,
+    created_by: user_schema_1.userSchema,
+    last_edited_by: user_schema_1.userSchema,
+    url: z.url(),
+    // Widget/dashboard views only.
+    dashboard_view_id: z.uuid().optional(),
+});
+/**
+ * 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(),
+    parent: parent_schema_1.databaseParentSchema,
+    type: z.enum(exports.VIEW_TYPES),
+});
+/**
+ * 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'),
+    id: z.uuid(),
+    view_id: z.uuid(),
+    expires_at: shared_schema_1.notionDateStringSchema,
+    total_count: z.number(),
+    results: z.array(page_schema_1.pageSchema),
+    next_cursor: z.string().trim().nullable(),
+    has_more: z.boolean(),
+    request_status: pagination_schema_1.requestStatusSchema.optional(),
+});

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.0.2",
+  "version": "3.1.1",
   "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 .",
@@ -68,13 +71,13 @@
     "@types/node": "^25.2.1",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^10.0.0",
-    "eslint-plugin-zod": "4.8.0",
+    "eslint-plugin-zod": "4.9.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
     "msw": "2.15.0",
     "prettier": "^3.8.1",
     "prettier-plugin-packagejson": "^3.0.0",
-    "typescript": "^6.0.0",
+    "typescript": "^6.0.3",
     "typescript-eslint": "^8.54.0",
     "vitest": "^4.0.18"
   },