Notion

Author(s)

• Thomas Subotitsch Fabian Franz Steiner

Tags

Notion API Classes

Functions

New-NotionRichText New-NotionRichTextAnnotation New-NotionBookmarkBlock New-NotionBreadcrumbBlock New-NotionBulletedListItemBlock New-NotionCalloutBlock New-NotionChildPageBlock New-NotionChildDatabaseBlock New-NotionCodeBlock New-NotionColumnBlock New-NotionColumnListBlock New-NotionDividerBlock New-NotionEmbedBlock New-NotionEquationBlock New-NotionFileBlock Add-NotionHeaderToBlock New-NotionHeadingBlock New-NotionImageBlock New-NotionLinkPreviewBlock New-NotionNumberedListItemBlock New-NotionParagraphBlock New-NotionPdfBlock New-NotionQuoteBlock New-NotionSyncedBlock New-NotionTableBlock New-NotionTableOfContentsBlock New-NotionTableRowBlock New-NotionToDoBlock New-NotionToggleBlock New-NotionVideoBlock Add-NotionBlockToPage Get-NotionBlock Get-NotionBlockChildren New-NotionBlock Remove-NotionBlock Update-NotionBlock Add-NotionDatabaseProperty New-NotionDatabaseProperty Remove-NotionDatabaseProperty Add-NotionDatabaseToParent Add-NotionPageToDatabase Edit-NotionDatabase Get-NotionDatabase Move-NotionDatabaseToArchive New-NotionDatabase Remove-NotionDatabase Restore-NotionDatabase New-NotionEmoji New-NotionFile Get-NotionPageProperty Update-NotionPageProperty Get-NotionPage Get-NotionPageChildren Move-NotionPageToArchive New-NotionPage Remove-NotionPage Restore-NotionPage New-NotionParent Get-NotionUser Connect-Notion ConvertTo-NotionObject Disconnect-Notion Invoke-NotionApiCall zz1_Type_Accelerator zz2_Type_Accelerator

Dependencies

This module has no dependencies.

Release Notes

## [0.12.0] - 2025-08-23

### Added

- **`.github/copilot-instructions.md`**

 - Introduced internal documentation to guide GitHub Copilot in understanding the Notion PowerShell module:
   - Describes project structure, coding and testing conventions.
   - Covers class hierarchy, type usage, PowerShell best practices, and module loading order.
   - Includes inline code examples and module-specific conventions for cmdlets, parameters, and testing.

- **`source/Private/Remove-DefaultPropertyNames.ps1`**

 - Added utility function `Remove-DefaultPropertyNames` to filter out common .NET object property names, used during property conversion processes for cleaner hashtable parsing.

- **`source/Public/Database/Add-NotionDatabaseToParent.ps1`**
 - Introduced new cmdlet `Add-NotionDatabaseToParent`, wrapping the database creation API call in a reusable function.
 - Accepts parameters for `parent_obj`, `title`, and `properties`, returning a strongly-typed `notion_database` object.
 - Implements detailed parameter validation and integrates with `New-NotionDatabase` and object converters for simplified database creation logic.
- **`source/Classes/02_Page/PageProperties/01_pp.ps1`**
 - Enhanced `ConvertFromObject` method in `notion_pageproperties` to handle both hashtables and custom objects, using `Remove-DefaultPropertyNames` for cleaner property filtering.
- **`source/Classes/Database/DatabaseProperties/01_dp.ps1`**
 - Re-implemented `ConvertFromObject` method in `notion_databaseproperties` to support input validation and dynamic property extraction, aligning with improvements in `notion_pageproperties`.
- **`source/Public/zz1_Type_Accelerator.ps1`**
 - **Complete Type Accelerator Reorganization**: Added comprehensive type accelerators for all Database and Page Property classes, organized into clear sections:
   - **DatabaseProperties Section**: Added all database property classes (`notion_*_database_property`) and related classes (`DatabasePropertiesBase`, relation hierarchy, `notion_status_group`)
   - **PageProperties Section**: Added all page property classes (`notion_*_page_property`) and related classes (`PagePropertiesBase`, `notion_pageproperties`)
   - **Structure Cleanup**: Removed internal `*_structure` classes to keep type accelerators focused on main classes
   - **Proper Organization**: Moved misplaced classes (`notion_unique_id`, `notion_verification`) to appropriate sections
   - **Alphabetical Ordering**: All classes within sections are alphabetically sorted for better maintainability
- **Unit Tests**
 - Introduced `New-NotionDatabase.Tests.ps1` with Pester tests to validate the `New-NotionDatabase` function:
   - Ensures `-parent_obj` is mandatory.
   - Verifies creation with string titles and rich_text title objects.
   - Supports pre-converted `notion_databaseproperties`.
   - Confirms default values (archived, in_trash, is_inline) are unset.
 - Added `notion_database.Class.Tests.ps1` with Pester unit tests for the notion_database class, covering constructors, ConvertFromObject, default values, nested object conversions, and edge cases.
 - **Comprehensive Database Properties Test Suite**: Added complete Pester test coverage for all Database Property classes with extensive German inline comments:
   - **Database Property Tests**: Added individual Pester unit tests for all simple database property types (e.g., checkbox, created_by, created_time, date, email, files, formula, last_edited_by, last_edited_time, people, phone_number, rich_text, title, url). Each test file includes:
     - Constructor, property, and `ConvertFromObject` tests.
     - Inheritance validation from `DatabasePropertiesBase`.
     - Edge case coverage including nulls, type checks, and validation errors.
     - Consistent test structure and German inline documentation for clarity and maintainability.
   - **Complex Property Tests**: `12_dp_multi_select.Tests.ps1` (with options management and 100-item limit validation), `13_dp_number.Tests.ps1` (with format type support), `16_dp_relation.Tests.ps1` (with inheritance hierarchy for single/dual relations), `18_dp_rollup.Tests.ps1` (with fallback mechanisms), `19_dp_select.Tests.ps1` (with options management), `20_dp_status.Tests.ps1` (with groups and options), `23_dp_unique_id.Tests.ps1` (with prefix handling)
     - Each test file includes: Constructor Tests, Property Tests, ConvertFromObject Tests, Inheritance Tests from `DatabasePropertiesBase`
     - Comprehensive edge case handling: null values, empty arrays, type validation, parameter limits, and error conditions
     - All tests follow consistent structure with detailed German documentation for maintainability

### Changed

- **`source/Classes/Block/08_Callout.ps1`**

 - Refactored constructor of `callout_structure` to accept rich text object(s) directly, replacing single string handling with `rich_text::ConvertFromObjects`, enhancing flexibility and correctness.

- **`source/Classes/Database/01_database.ps1`**

 - Reordered parameters in constructors of `notion_database` to place `parent` before `title` for consistent and intuitive usage.
 - Adjusted `ConvertFromObject` logic to correctly transform `title` and `description` fields using `foreach` with clearer formatting.

- **`source/Public/Database/New-NotionDatabase.ps1`**

 - Simplified rich text conversion for the `title` parameter using `rich_text::ConvertFromObjects`.
 - Refactored function to directly return a new `notion_database` object instead of manually building a body and invoking the API call, reducing redundancy and centralizing object construction logic.
 - Updated documentation to clarify parameter usage.

- **`source/Public/Database/Add-NotionPageToDatabase.ps1`**

 - Minor formatting and parameter declaration updates to align with standard PowerShell conventions.

- **`source/Public/Invoke-NotionApiCall.ps1`**

 - Unified casing for `param` and `process` keywords for consistency.
 - Updated format specifiers from `-F` to lowercase `-f`, aligning with PowerShell formatting best practices.
 - Cleaned up spacing and streamlined control flow for pagination logic in API call processing.

- **`source/Classes/00_General/17_notion_rollup.ps1`**

 - Added `Create` factory method to instantiate rollup subclasses based on rollup type (`array`, `date`, `number`, etc.), improving usability and maintainability.

- **`source/Classes/00_General/19_notion_select.ps1`**

 - Extended constructor overloads in `notion_select` to accept color and name parameters.
 - Improved object initialization with default color assignment.

- **`source/Classes/00_General/20_notion_status.ps1`**

 - Added default constructor for `notion_status`.
 - Enhanced overloaded constructors to default missing parameters and reduce errors during object construction.

- **`source/Classes/Database/DatabaseProperties/00_dp_base.ps1`**

 - Improved validation and error handling in `DatabasePropertiesBase::ConvertFromObject`.
 - Expanded switch statement for more readable property type conversion.
 - Ensures `null` inputs are properly caught with helpful errors.

- **`source/Classes/Database/DatabaseProperties/01_dp.ps1`**

 - Improved logic in `notion_databaseproperties::ConvertFromObject` to handle hashtables, custom objects, and existing instances more flexibly.
 - Added internal validation to `Add()` method to enforce proper typing and error reporting.

- **`source/Classes/Database/DatabaseProperties/09_dp_formula.ps1`**

 - Improved structure conversion logic with validation for missing `expression` field.
 - Added constructor-level documentation and default handling in `notion_formula_database_property`.

- **`source/Classes/Database/DatabaseProperties/12_dp_multi_select.ps1`**

 - Refactored `add` method to include validation for color and item limits.
 - Enhanced constructor overloads to allow immediate option injection.

- **`source/Classes/Database/DatabaseProperties/13_dp_number.ps1`**

 - Refined error checking for `notion_number_database_property_structure`.
 - Streamlined constructor input parsing and enum conversion.

- **`source/Classes/Database/DatabaseProperties/16_dp_relation.ps1`**

 - Removed `database_id` from structure constructors where no longer applicable.
 - Improved validation and error handling in all classes related to `notion_relation_database_property`.
 - Fixed improper use of `-invalidData` parameter in `Write-Error`.

- **`source/Classes/Database/DatabaseProperties/19_dp_select.ps1`**

 - Added overloads to `notion_select_database_property_structure` for adding options with or without colors and IDs.
 - Improved error handling and capped item count to 100.
 - Clarified and improved structure population logic.

- **`source/Classes/Database/DatabaseProperties/20_dp_status.ps1`**

 - Introduced constructors and `add` methods for programmatically building `notion_status_database_property_structure`.
 - Added null-checks and error validation in `ConvertFromObject` to reduce conversion-time failures.

- **`source/Classes/Database/DatabaseProperties/21_dp_title.ps1`**

 - Removed obsolete `TODO` comment.
 - Minor formatting cleanup.

- **`source/Classes/Database/DatabaseProperties/23_dp_unique_id.ps1`**

 - Improved null checking and early return in `ConvertFromObject`.
 - Replaced all raw type checks with consistent, safe PowerShell exception handling.
 - Reformatted parameter block and function declaration to align with PowerShell style standards.

### Fixed

- **`source/Classes/Database/01_database.ps1`**
 - Fixed constructor to ensure all kind of possible parameter types are handled correctly, including rich text objects for `title`.
- **`source/Classes/Database/DatabaseProperties/16_dp_relation.ps1`**
 - Fixed Write Error parameters to use `-Category InvalidData`, fixed the error message to include the actual type value, and removed the `-invalidData` parameter which is not a valid parameter for `Write-E