@nakanoaas/notion-valibot-schema 0.0.4 → 0.0.6

package/README.md

@@ -1,28 +1,72 @@
 # Notion Valibot Schema
 
-[![npm](https://img.shields.io/npm/v/%40nakanoaas%2Fnotion-valibot-schema)](https://www.npmjs.com/package/@nakanoaas/notion-valibot-schema) [![JSR](https://jsr.io/badges/@nakanoaas/notion-valibot-schema)](https://jsr.io/@nakanoaas/notion-valibot-schema)
+[![npm version](https://img.shields.io/npm/v/%40nakanoaas%2Fnotion-valibot-schema)](https://www.npmjs.com/package/@nakanoaas/notion-valibot-schema)
+[![JSR version](https://jsr.io/badges/@nakanoaas/notion-valibot-schema)](https://jsr.io/@nakanoaas/notion-valibot-schema)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A small collection of **[Valibot](https://github.com/fabian-hiller/valibot)** schemas for the Notion API.
+**Turn Notion's nested API responses into clean, typed JavaScript values.**
 
-It helps you **validate and transform** Notion `properties` into plain JavaScript values (e.g. `string`, `number`, `Date`, `string[]`) so you can work with the results without dealing with Notion’s nested property shapes.
+This library provides a collection of [Valibot](https://github.com/fabian-hiller/valibot) schemas specifically designed to handle Notion API objects. It doesn't just validate; it **transforms** deeply nested Notion properties into simple, usable primitives like `string`, `number`, `Date`, and `boolean`.
 
-## Install
+## The Problem
 
-### npm / pnpm / yarn
+When you fetch a page from Notion, properties are deeply nested. To access them type-safely, you end up writing **verbose type guards for every single property**.
 
-```bash
-npm i @nakanoaas/notion-valibot-schema valibot
+```ts
+// 😫 The "Native" Way (Boilerplate Hell)
+
+// 1. Get the property
+const statusProp = page.properties["Status"];
+
+// 2. Check if it exists and has the correct type
+if (statusProp?.type === "status" && statusProp.status) {
+  // 3. Finally access the value
+  console.log(statusProp.status.name); // "In Progress"
+}
+
+// Repeat this for every property... 
+const tagsProp = page.properties["Tags"];
+if (tagsProp?.type === "multi_select") {
+  console.log(tagsProp.multi_select.map(t => t.name)); 
+}
 ```
 
+## The Solution
+
+With `@nakanoaas/notion-valibot-schema`, you get this:
+
+```ts
+// After parsing
+{
+  Status: "In Progress",
+  Tags: ["Urgent", "Work"],
+  DueDate: new Date("2023-12-25")
+}
+```
+
+No more checking for `property.type === 'date'`, handling `null`, or digging through 3 layers of objects just to get a string.
+
+## Features
+
+- 🧩 **Composable**: Works seamlessly with standard Valibot schemas (`v.object`, `v.array`, etc.).
+- ✨ **Transformative**: Automatically extracts values (e.g., `RichText[]` -> `string`).
+- 🔒 **Type-Safe**: Full TypeScript support with inferred types.
+- ✅ **Well Tested**: Backed by a comprehensive test suite covering edge cases.
+- 🛠 **Comprehensive**: Supports complex properties like Rollups, Formulas, and Relations.
+
+## Installation
+
+### Node.js (npm / pnpm / yarn / bun)
+
 ```bash
-pnpm add @nakanoaas/notion-valibot-schema valibot
+npm install @nakanoaas/notion-valibot-schema valibot
 ```
 
 ```bash
-yarn add @nakanoaas/notion-valibot-schema valibot
+pnpm add @nakanoaas/notion-valibot-schema valibot
 ```
 
-### JSR
+### Deno / JSR
 
 ```bash
 deno add @nakanoaas/notion-valibot-schema @valibot/valibot
@@ -30,101 +74,126 @@ deno add @nakanoaas/notion-valibot-schema @valibot/valibot
 
 ## Usage
 
-### Parse a Notion database page (common pattern)
+### Basic Example
 
-This example shows how to parse a page returned by `notion.pages.retrieve()` (or an item from `notion.dataSources.query().results`) and turn its `properties` into plain values.
+Here is how to validate and transform a Notion page retrieved from the API.
 
 ```ts
 import * as v from "valibot";
 import {
-  CheckboxSchema,
-  FilesSchema,
-  MultiSelectSchema,
-  NullableDateSchema,
-  NullableNumberSchema,
-  NullableUrlSchema,
-  RelationSchema,
+  TitleSchema,
   RichTextSchema,
   StatusSchema,
-  TitleSchema,
+  MultiSelectSchema,
+  NullableDateSchema,
+  CheckboxSchema,
 } from "@nakanoaas/notion-valibot-schema";
 
-// Property keys must match your database property names exactly.
-const NotionTaskPageSchema = v.object({
+// 1. Define your schema based on your Database properties
+const TaskPageSchema = v.object({
   id: v.string(),
   properties: v.object({
-    Name: TitleSchema, // -> string
-    Notes: RichTextSchema, // -> string
-    Status: StatusSchema(v.picklist(["ToDo", "In Progress", "Done"])), // -> "ToDo" | "In Progress" | "Done"
-    Tags: MultiSelectSchema(v.string()), // -> string[]
-    Due: NullableDateSchema, // -> Date | null
-    Points: NullableNumberSchema, // -> number | null
-    Done: CheckboxSchema, // -> boolean
-    Website: NullableUrlSchema, // -> string | null
-    Attachments: FilesSchema, // -> string[] (URLs)
-    Related: RelationSchema, // -> string[] (page IDs)
+    // Map "Name" property -> string
+    Name: TitleSchema,
+    
+    // Map "Description" property -> string
+    Description: RichTextSchema,
+    
+    // Map "Status" property -> "ToDo" | "Doing" | "Done"
+    Status: StatusSchema(v.picklist(["ToDo", "Doing", "Done"])),
+    
+    // Map "Tags" -> string[]
+    Tags: MultiSelectSchema(v.string()),
+    
+    // Map "Due Date" -> Date | null
+    DueDate: NullableDateSchema,
+    
+    // Map "IsUrgent" -> boolean
+    IsUrgent: CheckboxSchema,
   }),
 });
 
-// Fetch a page with the Notion SDK
-// const page = await notion.pages.retrieve({ page_id: "..." });
+// 2. Fetch data from Notion
+const page = await notion.pages.retrieve({ page_id: "..." });
 
-// Validate + transform
-const task = v.parse(NotionTaskPageSchema, page);
+// 3. Parse and transform
+const task = v.parse(TaskPageSchema, page);
 
-// task.properties is now easy to use
-task.properties.Name; // string
-task.properties.Due; // Date | null
-task.properties.Tags; // string[]
+// 4. Use your clean data
+console.log(task.properties.Name);       // "Buy Milk" (string)
+console.log(task.properties.DueDate);    // Date object or null
+console.log(task.properties.Tags);       // ["Personal", "Shopping"] (string[])
 ```
 
-### Parse query results
+### Handling Lists (Query Results)
+
+To parse the results of a database query:
 
 ```ts
-import * as v from "valibot";
+const TaskListSchema = v.array(TaskPageSchema);
+
+const { results } = await notion.databases.query({ database_id: "..." });
+const tasks = v.parse(TaskListSchema, results);
+```
 
-const NotionTaskListSchema = v.array(NotionTaskPageSchema);
+## Schema Reference
+
+> 📚 **For complete API documentation, including all available schemas and types, please visit the [JSR Documentation](https://jsr.io/@nakanoaas/notion-valibot-schema/doc).**
+
+| Notion Property | Schema | Transformed Output (Type) |
+| :--- | :--- | :--- |
+| **Text** / Title | `TitleSchema` / `RichTextSchema` | `string` |
+| **Number** | `NumberSchema` / `NullableNumberSchema` | `number` / `number \| null` |
+| **Checkbox** | `CheckboxSchema` | `boolean` |
+| **Select** | `SelectSchema(schema)` | `Inferred<schema>` |
+| **Multi-Select** | `MultiSelectSchema(schema)` | `Inferred<schema>[]` |
+| **Status** | `StatusSchema(schema)` | `Inferred<schema>` |
+| **Date** | `DateSchema` / `NullableDateSchema` | `Date` / `Date \| null` |
+| **Relation** | `RelationSchema` | `string[]` (Page IDs) |
+| **Relation** (Single) | `SingleRelationSchema` | `string` (Page ID) |
+| **URL** | `UrlSchema` | `string` |
+| **Email** | `EmailSchema` | `string` |
+| **Phone** | `PhoneNumberSchema` | `string` |
+| **Files** | `FilesSchema` | `string[]` (URLs) |
+| **Created/Edited By** | `CreatedBySchema` / `LastEditedBySchema` | `string` (User ID) |
+| **Created/Edited Time**| `CreatedTimeSchema` / `LastEditedTimeSchema` | `Date` |
+
+### Advanced Schemas
+
+#### Formulas
+Formulas in Notion can return different types (string, number, boolean, date). Use `FormulaSchema` with a specific inner schema to handle this.
 
-// const { results } = await notion.dataSources.query({ data_source_id: "..." });
-const tasks = v.parse(NotionTaskListSchema, results);
+```ts
+import { FormulaSchema, RichTextSchema } from "@nakanoaas/notion-valibot-schema";
+
+const MySchema = v.object({
+  // If your formula returns text
+  MyFormula: FormulaSchema(RichTextSchema), 
+});
 ```
 
-## Exports
-
-This package re-exports all schemas from `src/index.ts`.
-
-- **Text**
-  - `TitleSchema`: `{ title: RichText[] }` → `string`
-  - `RichTextSchema`: `{ rich_text: RichText[] }` → `string`
-- **Numbers**
-  - `NumberSchema`: `{ number: number }` → `number`
-  - `NullableNumberSchema`: `{ number: number | null }` → `number | null`
-- **Dates**
-  - `DateSchema`: `{ date: { start: string } }` → `Date`
-  - `NullableDateSchema`: `{ date: { start: string } | null }` → `Date | null`
-  - `FullDateSchema`: `{ date: { start: string; end: string } }` → `{ start: Date; end: Date }`
-  - `NullableFullDateSchema`: `{ date: { start: string; end: string | null } | null }` → `{ start: Date; end: Date | null } | null`
-- **Select-like**
-  - `SelectSchema(schema)`: `{ select: { name: ... } }` → inferred
-  - `NullableSelectSchema(schema)`: `{ select: { name: ... } | null }` → inferred | `null`
-  - `StatusSchema(schema)`: `{ status: { name: ... } }` → inferred
-  - `NullableStatusSchema(schema)`: `{ status: { name: ... } | null }` → inferred | `null`
-  - `MultiSelectSchema(schema)`: `{ multi_select: { name: ... }[] }` → inferred[]
-- **Other common property types**
-  - `CheckboxSchema`: `{ checkbox: boolean }` → `boolean`
-  - `EmailSchema` / `NullableEmailSchema`
-  - `PhoneNumberSchema` / `NullablePhoneNumberSchema`
-  - `UrlSchema` / `NullableUrlSchema`
-  - `RelationSchema`: `{ relation: { id: string }[] }` → `string[]`
-  - `FilesSchema`: `{ files: (file | external)[] }` → `string[]` (URLs)
-
-And more: created/last-edited fields, rollup, formula, unique_id, people, place, verification, etc.
-
-## Notes
-
-- **Property names are user-defined** in Notion. In your schema, keys like `Name` / `Status` must match the names in your database.
-- These schemas focus on **parsing property values**, so you can embed them in your own page/database schemas.
+#### Rollups
+Rollups are powerful but complex. We provide helpers for common rollup types.
+
+```ts
+import { 
+  RollupNumberSchema, 
+  RollupDateSchema, 
+  RollupArraySchema 
+} from "@nakanoaas/notion-valibot-schema";
+
+const MySchema = v.object({
+  // Sum/Average rollup (returns number)
+  TotalCost: RollupNumberSchema,
+  
+  // Date rollup (returns Date)
+  LatestMeeting: RollupDateSchema,
+  
+  // Array rollup (e.g., pulling tags from related items)
+  AllTags: RollupArraySchema(v.string())
+});
+```
 
 ## License
 
-MIT
+MIT © [Nakano as a Service](https://github.com/nakanoasaservice)

package/dist/checkbox.cjs

@@ -3,6 +3,35 @@ let valibot = require("valibot");
 valibot = require_rolldown_runtime.__toESM(valibot);
 
 //#region src/checkbox.ts
+/**
+* Schema to extract the `checkbox` property from a Notion page property.
+*
+* **Input:**
+* ```
+* {
+*   checkbox: boolean;
+* }
+* ```
+*
+* **Output:** `boolean`
+*
+* @example
+* ```ts
+* import * as v from "valibot";
+* import { CheckboxSchema } from "@nakanoaas/notion-valibot-utils";
+*
+* const PageSchema = v.object({
+*   id: v.string(),
+*   properties: v.object({
+*     Checkbox: CheckboxSchema,
+*   }),
+* });
+*
+* const page = await notion.pages.retrieve({ page_id: "..." });
+* const parsed = v.parse(PageSchema, page);
+* // parsed.properties.Checkbox: boolean
+* ```
+*/
 const CheckboxSchema = valibot.pipe(valibot.object({ checkbox: valibot.boolean() }), valibot.transform((v) => v.checkbox));
 
 //#endregion

package/dist/checkbox.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"checkbox.cjs","names":["v"],"sources":["../src/checkbox.ts"],"sourcesContent":["import * as v from \"valibot\";\n\nexport const CheckboxSchema = v.pipe(\n\tv.object({\n\t\tcheckbox: v.boolean(),\n\t}),\n\tv.transform((v) => v.checkbox),\n);\n"],"mappings":";;;;;AAEA,MAAa,iBAAiBA,QAAE,KAC/BA,QAAE,OAAO,EACR,UAAUA,QAAE,SAAS,EACrB,CAAC,EACFA,QAAE,WAAW,MAAM,EAAE,SAAS,CAC9B"}
+{"version":3,"file":"checkbox.cjs","names":["v"],"sources":["../src/checkbox.ts"],"sourcesContent":["import * as v from \"valibot\";\n\n/**\n * Schema to extract the `checkbox` property from a Notion page property.\n *\n * **Input:**\n * ```\n * {\n *   checkbox: boolean;\n * }\n * ```\n *\n * **Output:** `boolean`\n *\n * @example\n * ```ts\n * import * as v from \"valibot\";\n * import { CheckboxSchema } from \"@nakanoaas/notion-valibot-utils\";\n *\n * const PageSchema = v.object({\n *   id: v.string(),\n *   properties: v.object({\n *     Checkbox: CheckboxSchema,\n *   }),\n * });\n *\n * const page = await notion.pages.retrieve({ page_id: \"...\" });\n * const parsed = v.parse(PageSchema, page);\n * // parsed.properties.Checkbox: boolean\n * ```\n */\nexport const CheckboxSchema = v.pipe(\n\tv.object({\n\t\tcheckbox: v.boolean(),\n\t}),\n\tv.transform((v) => v.checkbox),\n);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,MAAa,iBAAiBA,QAAE,KAC/BA,QAAE,OAAO,EACR,UAAUA,QAAE,SAAS,EACrB,CAAC,EACFA,QAAE,WAAW,MAAM,EAAE,SAAS,CAC9B"}

package/dist/checkbox.d.cts

@@ -1,6 +1,36 @@
 import * as v from "valibot";
 
 //#region src/checkbox.d.ts
+
+/**
+ * Schema to extract the `checkbox` property from a Notion page property.
+ *
+ * **Input:**
+ * ```
+ * {
+ *   checkbox: boolean;
+ * }
+ * ```
+ *
+ * **Output:** `boolean`
+ *
+ * @example
+ * ```ts
+ * import * as v from "valibot";
+ * import { CheckboxSchema } from "@nakanoaas/notion-valibot-utils";
+ *
+ * const PageSchema = v.object({
+ *   id: v.string(),
+ *   properties: v.object({
+ *     Checkbox: CheckboxSchema,
+ *   }),
+ * });
+ *
+ * const page = await notion.pages.retrieve({ page_id: "..." });
+ * const parsed = v.parse(PageSchema, page);
+ * // parsed.properties.Checkbox: boolean
+ * ```
+ */
 declare const CheckboxSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
   readonly checkbox: v.BooleanSchema<undefined>;
 }, undefined>, v.TransformAction<{

package/dist/checkbox.d.mts

@@ -1,6 +1,36 @@
 import * as v from "valibot";
 
 //#region src/checkbox.d.ts
+
+/**
+ * Schema to extract the `checkbox` property from a Notion page property.
+ *
+ * **Input:**
+ * ```
+ * {
+ *   checkbox: boolean;
+ * }
+ * ```
+ *
+ * **Output:** `boolean`
+ *
+ * @example
+ * ```ts
+ * import * as v from "valibot";
+ * import { CheckboxSchema } from "@nakanoaas/notion-valibot-utils";
+ *
+ * const PageSchema = v.object({
+ *   id: v.string(),
+ *   properties: v.object({
+ *     Checkbox: CheckboxSchema,
+ *   }),
+ * });
+ *
+ * const page = await notion.pages.retrieve({ page_id: "..." });
+ * const parsed = v.parse(PageSchema, page);
+ * // parsed.properties.Checkbox: boolean
+ * ```
+ */
 declare const CheckboxSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
   readonly checkbox: v.BooleanSchema<undefined>;
 }, undefined>, v.TransformAction<{

package/dist/checkbox.mjs

@@ -1,6 +1,35 @@
 import * as v from "valibot";
 
 //#region src/checkbox.ts
+/**
+* Schema to extract the `checkbox` property from a Notion page property.
+*
+* **Input:**
+* ```
+* {
+*   checkbox: boolean;
+* }
+* ```
+*
+* **Output:** `boolean`
+*
+* @example
+* ```ts
+* import * as v from "valibot";
+* import { CheckboxSchema } from "@nakanoaas/notion-valibot-utils";
+*
+* const PageSchema = v.object({
+*   id: v.string(),
+*   properties: v.object({
+*     Checkbox: CheckboxSchema,
+*   }),
+* });
+*
+* const page = await notion.pages.retrieve({ page_id: "..." });
+* const parsed = v.parse(PageSchema, page);
+* // parsed.properties.Checkbox: boolean
+* ```
+*/
 const CheckboxSchema = v.pipe(v.object({ checkbox: v.boolean() }), v.transform((v$1) => v$1.checkbox));
 
 //#endregion

package/dist/checkbox.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"checkbox.mjs","names":["v"],"sources":["../src/checkbox.ts"],"sourcesContent":["import * as v from \"valibot\";\n\nexport const CheckboxSchema = v.pipe(\n\tv.object({\n\t\tcheckbox: v.boolean(),\n\t}),\n\tv.transform((v) => v.checkbox),\n);\n"],"mappings":";;;AAEA,MAAa,iBAAiB,EAAE,KAC/B,EAAE,OAAO,EACR,UAAU,EAAE,SAAS,EACrB,CAAC,EACF,EAAE,WAAW,QAAMA,IAAE,SAAS,CAC9B"}
+{"version":3,"file":"checkbox.mjs","names":["v"],"sources":["../src/checkbox.ts"],"sourcesContent":["import * as v from \"valibot\";\n\n/**\n * Schema to extract the `checkbox` property from a Notion page property.\n *\n * **Input:**\n * ```\n * {\n *   checkbox: boolean;\n * }\n * ```\n *\n * **Output:** `boolean`\n *\n * @example\n * ```ts\n * import * as v from \"valibot\";\n * import { CheckboxSchema } from \"@nakanoaas/notion-valibot-utils\";\n *\n * const PageSchema = v.object({\n *   id: v.string(),\n *   properties: v.object({\n *     Checkbox: CheckboxSchema,\n *   }),\n * });\n *\n * const page = await notion.pages.retrieve({ page_id: \"...\" });\n * const parsed = v.parse(PageSchema, page);\n * // parsed.properties.Checkbox: boolean\n * ```\n */\nexport const CheckboxSchema = v.pipe(\n\tv.object({\n\t\tcheckbox: v.boolean(),\n\t}),\n\tv.transform((v) => v.checkbox),\n);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,MAAa,iBAAiB,EAAE,KAC/B,EAAE,OAAO,EACR,UAAU,EAAE,SAAS,EACrB,CAAC,EACF,EAAE,WAAW,QAAMA,IAAE,SAAS,CAC9B"}

package/dist/created-by.cjs

@@ -4,7 +4,82 @@ let valibot = require("valibot");
 valibot = require_rolldown_runtime.__toESM(valibot);
 
 //#region src/created-by.ts
+/**
+* Schema to extract the `created_by` person object from a Notion page.
+*
+* **Input:**
+* ```
+* {
+*   created_by: {
+*     id: string;
+*     object: "user" | "bot" | "group";
+*     name: string | null;
+*     ...
+*   }
+* }
+* ```
+*
+* **Output:**
+* ```
+* {
+*   id: string;
+*   object: "user" | "bot" | "group";
+*   name: string | null;
+* }
+* ```
+*
+* @example
+* ```ts
+* import * as v from "valibot";
+* import { CreatedBySchema } from "@nakanoaas/notion-valibot-schema";
+*
+* const PageSchema = v.object({
+*   id: v.string(),
+*   properties: v.object({
+*     CreatedBy: CreatedBySchema,
+*   }),
+* });
+*
+* const page = await notion.pages.retrieve({ page_id: "..." });
+* const parsed = v.parse(PageSchema, page);
+* // parsed.properties.CreatedBy: { id: string; object: "user" | "bot" | "group"; name: string | null }
+* ```
+*/
 const CreatedBySchema = valibot.pipe(valibot.object({ created_by: require_people.PersonSchema }), valibot.transform((v) => v.created_by));
+/**
+* Schema to extract the `created_by` person ID from a Notion page.
+*
+* **Input:**
+* ```
+* {
+*   created_by: {
+*     id: string;
+*     object: "user" | "bot" | "group";
+*     name: string | null;
+*     ...
+*   }
+* }
+* ```
+*
+* **Output:** `string`
+*
+* @example
+* ```ts
+* import * as v from "valibot";
+* import { CreatedByIdSchema } from "@nakanoaas/notion-valibot-schema";
+*
+* const PageSchema = v.object({
+*   id: v.string(),
+*   properties: v.object({
+*     CreatedById: CreatedByIdSchema,
+*   }),
+* });
+*
+* const page = await notion.pages.retrieve({ page_id: "..." });
+* const parsed = v.parse(PageSchema, page);
+* // parsed.properties.CreatedById: string
+* ```
+*/
 const CreatedByIdSchema = valibot.pipe(valibot.object({ created_by: require_people.PersonSchema }), valibot.transform((v) => v.created_by.id));
 
 //#endregion

package/dist/created-by.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"created-by.cjs","names":["v","PersonSchema"],"sources":["../src/created-by.ts"],"sourcesContent":["import * as v from \"valibot\";\n\nimport { PersonSchema } from \"./people\";\n\nexport const CreatedBySchema = v.pipe(\n\tv.object({\n\t\tcreated_by: PersonSchema,\n\t}),\n\tv.transform((v) => v.created_by),\n);\n\nexport const CreatedByIdSchema = v.pipe(\n\tv.object({\n\t\tcreated_by: PersonSchema,\n\t}),\n\tv.transform((v) => v.created_by.id),\n);\n"],"mappings":";;;;;;AAIA,MAAa,kBAAkBA,QAAE,KAChCA,QAAE,OAAO,EACR,YAAYC,6BACZ,CAAC,EACFD,QAAE,WAAW,MAAM,EAAE,WAAW,CAChC;AAED,MAAa,oBAAoBA,QAAE,KAClCA,QAAE,OAAO,EACR,YAAYC,6BACZ,CAAC,EACFD,QAAE,WAAW,MAAM,EAAE,WAAW,GAAG,CACnC"}
+{"version":3,"file":"created-by.cjs","names":["v","PersonSchema"],"sources":["../src/created-by.ts"],"sourcesContent":["import * as v from \"valibot\";\n\nimport { PersonSchema } from \"./people\";\n\n/**\n * Schema to extract the `created_by` person object from a Notion page.\n *\n * **Input:**\n * ```\n * {\n *   created_by: {\n *     id: string;\n *     object: \"user\" | \"bot\" | \"group\";\n *     name: string | null;\n *     ...\n *   }\n * }\n * ```\n *\n * **Output:**\n * ```\n * {\n *   id: string;\n *   object: \"user\" | \"bot\" | \"group\";\n *   name: string | null;\n * }\n * ```\n *\n * @example\n * ```ts\n * import * as v from \"valibot\";\n * import { CreatedBySchema } from \"@nakanoaas/notion-valibot-schema\";\n *\n * const PageSchema = v.object({\n *   id: v.string(),\n *   properties: v.object({\n *     CreatedBy: CreatedBySchema,\n *   }),\n * });\n *\n * const page = await notion.pages.retrieve({ page_id: \"...\" });\n * const parsed = v.parse(PageSchema, page);\n * // parsed.properties.CreatedBy: { id: string; object: \"user\" | \"bot\" | \"group\"; name: string | null }\n * ```\n */\nexport const CreatedBySchema = v.pipe(\n\tv.object({\n\t\tcreated_by: PersonSchema,\n\t}),\n\tv.transform((v) => v.created_by),\n);\n\n/**\n * Schema to extract the `created_by` person ID from a Notion page.\n *\n * **Input:**\n * ```\n * {\n *   created_by: {\n *     id: string;\n *     object: \"user\" | \"bot\" | \"group\";\n *     name: string | null;\n *     ...\n *   }\n * }\n * ```\n *\n * **Output:** `string`\n *\n * @example\n * ```ts\n * import * as v from \"valibot\";\n * import { CreatedByIdSchema } from \"@nakanoaas/notion-valibot-schema\";\n *\n * const PageSchema = v.object({\n *   id: v.string(),\n *   properties: v.object({\n *     CreatedById: CreatedByIdSchema,\n *   }),\n * });\n *\n * const page = await notion.pages.retrieve({ page_id: \"...\" });\n * const parsed = v.parse(PageSchema, page);\n * // parsed.properties.CreatedById: string\n * ```\n */\nexport const CreatedByIdSchema = v.pipe(\n\tv.object({\n\t\tcreated_by: PersonSchema,\n\t}),\n\tv.transform((v) => v.created_by.id),\n);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,MAAa,kBAAkBA,QAAE,KAChCA,QAAE,OAAO,EACR,YAAYC,6BACZ,CAAC,EACFD,QAAE,WAAW,MAAM,EAAE,WAAW,CAChC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCD,MAAa,oBAAoBA,QAAE,KAClCA,QAAE,OAAO,EACR,YAAYC,6BACZ,CAAC,EACFD,QAAE,WAAW,MAAM,EAAE,WAAW,GAAG,CACnC"}

package/dist/created-by.d.cts

@@ -1,6 +1,48 @@
 import * as v from "valibot";
 
 //#region src/created-by.d.ts
+
+/**
+ * Schema to extract the `created_by` person object from a Notion page.
+ *
+ * **Input:**
+ * ```
+ * {
+ *   created_by: {
+ *     id: string;
+ *     object: "user" | "bot" | "group";
+ *     name: string | null;
+ *     ...
+ *   }
+ * }
+ * ```
+ *
+ * **Output:**
+ * ```
+ * {
+ *   id: string;
+ *   object: "user" | "bot" | "group";
+ *   name: string | null;
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * import * as v from "valibot";
+ * import { CreatedBySchema } from "@nakanoaas/notion-valibot-schema";
+ *
+ * const PageSchema = v.object({
+ *   id: v.string(),
+ *   properties: v.object({
+ *     CreatedBy: CreatedBySchema,
+ *   }),
+ * });
+ *
+ * const page = await notion.pages.retrieve({ page_id: "..." });
+ * const parsed = v.parse(PageSchema, page);
+ * // parsed.properties.CreatedBy: { id: string; object: "user" | "bot" | "group"; name: string | null }
+ * ```
+ */
 declare const CreatedBySchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
   readonly created_by: v.ObjectSchema<{
     readonly id: v.StringSchema<undefined>;
@@ -18,6 +60,40 @@ declare const CreatedBySchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
   object: "user" | "bot" | "group";
   name: string | null;
 }>]>;
+/**
+ * Schema to extract the `created_by` person ID from a Notion page.
+ *
+ * **Input:**
+ * ```
+ * {
+ *   created_by: {
+ *     id: string;
+ *     object: "user" | "bot" | "group";
+ *     name: string | null;
+ *     ...
+ *   }
+ * }
+ * ```
+ *
+ * **Output:** `string`
+ *
+ * @example
+ * ```ts
+ * import * as v from "valibot";
+ * import { CreatedByIdSchema } from "@nakanoaas/notion-valibot-schema";
+ *
+ * const PageSchema = v.object({
+ *   id: v.string(),
+ *   properties: v.object({
+ *     CreatedById: CreatedByIdSchema,
+ *   }),
+ * });
+ *
+ * const page = await notion.pages.retrieve({ page_id: "..." });
+ * const parsed = v.parse(PageSchema, page);
+ * // parsed.properties.CreatedById: string
+ * ```
+ */
 declare const CreatedByIdSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
   readonly created_by: v.ObjectSchema<{
     readonly id: v.StringSchema<undefined>;