@catafal/notion-cli 5.9.0

package/dist/utils/schema-examples.js

@@ -0,0 +1,359 @@
+"use strict";
+/**
+ * Property Example Generator for Notion API
+ *
+ * Generates copy-pastable property payload examples based on database schema.
+ * Helps AI agents understand the correct format for create/update operations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePropertyExamples = generatePropertyExamples;
+exports.formatExamplesForConsole = formatExamplesForConsole;
+exports.groupExamplesByWritability = groupExamplesByWritability;
+/**
+ * Generate property examples for all properties in a data source schema
+ *
+ * @param properties - Properties object from GetDataSourceResponse
+ * @returns Array of property examples
+ */
+function generatePropertyExamples(properties) {
+    const examples = [];
+    for (const [propName, propDef] of Object.entries(properties)) {
+        const example = generateExampleForType(propName, propDef);
+        if (example) {
+            examples.push(example);
+        }
+    }
+    return examples;
+}
+/**
+ * Generate example for a single property based on its type
+ *
+ * @param name - Property name
+ * @param propDef - Property definition from Notion API
+ * @returns Property example or null if unsupported
+ */
+function generateExampleForType(name, propDef) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    if (!propDef || !propDef.type) {
+        return null;
+    }
+    const type = propDef.type;
+    switch (type) {
+        case 'title':
+            return {
+                property_name: name,
+                property_type: 'title',
+                simple_value: 'My Page Title',
+                notion_payload: {
+                    [name]: {
+                        title: [{ text: { content: 'My Page Title' } }]
+                    }
+                },
+                description: 'Main title of the page (required for new pages)'
+            };
+        case 'rich_text':
+            return {
+                property_name: name,
+                property_type: 'rich_text',
+                simple_value: 'Some text content',
+                notion_payload: {
+                    [name]: {
+                        rich_text: [{ text: { content: 'Some text content' } }]
+                    }
+                },
+                description: 'Multi-line text with optional formatting'
+            };
+        case 'number': {
+            const numberFormat = ((_a = propDef.number) === null || _a === void 0 ? void 0 : _a.format) || 'number';
+            return {
+                property_name: name,
+                property_type: 'number',
+                simple_value: 42,
+                notion_payload: {
+                    [name]: { number: 42 }
+                },
+                description: `Numeric value (format: ${numberFormat})`
+            };
+        }
+        case 'checkbox':
+            return {
+                property_name: name,
+                property_type: 'checkbox',
+                simple_value: true,
+                notion_payload: {
+                    [name]: { checkbox: true }
+                },
+                description: 'Boolean true/false value'
+            };
+        case 'select': {
+            const selectOptions = ((_b = propDef.select) === null || _b === void 0 ? void 0 : _b.options) || [];
+            const firstOption = ((_c = selectOptions[0]) === null || _c === void 0 ? void 0 : _c.name) || 'Option Name';
+            const selectOptionsList = selectOptions.map((o) => o.name).join(', ');
+            return {
+                property_name: name,
+                property_type: 'select',
+                simple_value: firstOption,
+                notion_payload: {
+                    [name]: { select: { name: firstOption } }
+                },
+                description: selectOptions.length > 0
+                    ? `Single selection from: ${selectOptionsList}`
+                    : 'Single selection (no options defined yet)'
+            };
+        }
+        case 'multi_select': {
+            const multiOptions = ((_d = propDef.multi_select) === null || _d === void 0 ? void 0 : _d.options) || [];
+            const exampleOptions = multiOptions.slice(0, 2).map((o) => o.name);
+            const multiOptionsList = multiOptions.map((o) => o.name).join(', ');
+            return {
+                property_name: name,
+                property_type: 'multi_select',
+                simple_value: exampleOptions,
+                notion_payload: {
+                    [name]: {
+                        multi_select: exampleOptions.map((n) => ({ name: n }))
+                    }
+                },
+                description: multiOptions.length > 0
+                    ? `Multiple selections from: ${multiOptionsList}`
+                    : 'Multiple selections (no options defined yet)'
+            };
+        }
+        case 'status': {
+            const statusOptions = ((_e = propDef.status) === null || _e === void 0 ? void 0 : _e.options) || [];
+            const firstStatus = ((_f = statusOptions[0]) === null || _f === void 0 ? void 0 : _f.name) || 'Status Name';
+            const statusOptionsList = statusOptions.map((o) => o.name).join(', ');
+            return {
+                property_name: name,
+                property_type: 'status',
+                simple_value: firstStatus,
+                notion_payload: {
+                    [name]: { status: { name: firstStatus } }
+                },
+                description: statusOptions.length > 0
+                    ? `Status from: ${statusOptionsList}`
+                    : 'Status value (no options defined yet)'
+            };
+        }
+        case 'date':
+            return {
+                property_name: name,
+                property_type: 'date',
+                simple_value: '2025-12-31',
+                notion_payload: {
+                    [name]: { date: { start: '2025-12-31' } }
+                },
+                description: 'ISO date (YYYY-MM-DD) or date range with end property'
+            };
+        case 'url':
+            return {
+                property_name: name,
+                property_type: 'url',
+                simple_value: 'https://example.com',
+                notion_payload: {
+                    [name]: { url: 'https://example.com' }
+                },
+                description: 'Valid URL starting with http:// or https://'
+            };
+        case 'email':
+            return {
+                property_name: name,
+                property_type: 'email',
+                simple_value: 'user@example.com',
+                notion_payload: {
+                    [name]: { email: 'user@example.com' }
+                },
+                description: 'Valid email address'
+            };
+        case 'phone_number':
+            return {
+                property_name: name,
+                property_type: 'phone_number',
+                simple_value: '+1-555-123-4567',
+                notion_payload: {
+                    [name]: { phone_number: '+1-555-123-4567' }
+                },
+                description: 'Phone number (any format)'
+            };
+        case 'people':
+            return {
+                property_name: name,
+                property_type: 'people',
+                simple_value: ['user-id-1', 'user-id-2'],
+                notion_payload: {
+                    [name]: {
+                        people: [
+                            { id: 'user-id-1' },
+                            { id: 'user-id-2' }
+                        ]
+                    }
+                },
+                description: 'Array of Notion user IDs (use workspace users list to get IDs)'
+            };
+        case 'files':
+            return {
+                property_name: name,
+                property_type: 'files',
+                simple_value: 'https://example.com/file.pdf',
+                notion_payload: {
+                    [name]: {
+                        files: [
+                            {
+                                name: 'file.pdf',
+                                type: 'external',
+                                external: { url: 'https://example.com/file.pdf' }
+                            }
+                        ]
+                    }
+                },
+                description: 'External file URLs (Notion-hosted files cannot be set via API)'
+            };
+        case 'relation': {
+            const relatedDbId = ((_g = propDef.relation) === null || _g === void 0 ? void 0 : _g.database_id) || 'related-database-id';
+            return {
+                property_name: name,
+                property_type: 'relation',
+                simple_value: ['page-id-1', 'page-id-2'],
+                notion_payload: {
+                    [name]: {
+                        relation: [
+                            { id: 'page-id-1' },
+                            { id: 'page-id-2' }
+                        ]
+                    }
+                },
+                description: `Array of page IDs from related database (${relatedDbId})`
+            };
+        }
+        // Read-only property types (cannot be set via API)
+        case 'created_time':
+            return {
+                property_name: name,
+                property_type: 'created_time',
+                simple_value: null,
+                notion_payload: {},
+                description: 'Read-only: Automatically set when page is created'
+            };
+        case 'created_by':
+            return {
+                property_name: name,
+                property_type: 'created_by',
+                simple_value: null,
+                notion_payload: {},
+                description: 'Read-only: Automatically set to user who created the page'
+            };
+        case 'last_edited_time':
+            return {
+                property_name: name,
+                property_type: 'last_edited_time',
+                simple_value: null,
+                notion_payload: {},
+                description: 'Read-only: Automatically updated when page is edited'
+            };
+        case 'last_edited_by':
+            return {
+                property_name: name,
+                property_type: 'last_edited_by',
+                simple_value: null,
+                notion_payload: {},
+                description: 'Read-only: Automatically set to user who last edited the page'
+            };
+        case 'formula': {
+            const expression = ((_h = propDef.formula) === null || _h === void 0 ? void 0 : _h.expression) || 'unknown';
+            return {
+                property_name: name,
+                property_type: 'formula',
+                simple_value: null,
+                notion_payload: {},
+                description: `Read-only: Computed formula (${expression})`
+            };
+        }
+        case 'rollup': {
+            const rollupFunc = ((_j = propDef.rollup) === null || _j === void 0 ? void 0 : _j.function) || 'unknown';
+            return {
+                property_name: name,
+                property_type: 'rollup',
+                simple_value: null,
+                notion_payload: {},
+                description: `Read-only: Rollup aggregation (${rollupFunc})`
+            };
+        }
+        case 'unique_id':
+            return {
+                property_name: name,
+                property_type: 'unique_id',
+                simple_value: null,
+                notion_payload: {},
+                description: 'Read-only: Auto-incrementing unique ID'
+            };
+        case 'verification':
+            return {
+                property_name: name,
+                property_type: 'verification',
+                simple_value: null,
+                notion_payload: {},
+                description: 'Read-only: Verification status'
+            };
+        default:
+            // Unsupported or unknown type
+            return {
+                property_name: name,
+                property_type: type,
+                simple_value: null,
+                notion_payload: {},
+                description: `Unsupported property type: ${type}`
+            };
+    }
+}
+/**
+ * Format examples for human-readable console output
+ *
+ * @param examples - Array of property examples
+ * @returns Formatted string
+ */
+function formatExamplesForConsole(examples) {
+    const lines = [];
+    lines.push('');
+    lines.push('📋 Property Examples');
+    lines.push('='.repeat(80));
+    for (const example of examples) {
+        lines.push('');
+        lines.push(`${example.property_name} (${example.property_type})`);
+        lines.push(`  ${example.description}`);
+        if (example.simple_value !== null) {
+            lines.push('');
+            lines.push('  Simple value:');
+            lines.push(`  ${JSON.stringify(example.simple_value)}`);
+            lines.push('');
+            lines.push('  Notion API payload:');
+            const payload = JSON.stringify(example.notion_payload, null, 2);
+            const indentedPayload = payload.split('\n').map(line => `  ${line}`).join('\n');
+            lines.push(indentedPayload);
+        }
+        else {
+            lines.push('');
+            lines.push('  ⚠️  This property is read-only and cannot be set via API');
+        }
+        lines.push('-'.repeat(80));
+    }
+    return lines.join('\n');
+}
+/**
+ * Group examples by writability (writable vs read-only)
+ *
+ * @param examples - Array of property examples
+ * @returns Grouped examples
+ */
+function groupExamplesByWritability(examples) {
+    const writable = [];
+    const readOnly = [];
+    for (const example of examples) {
+        if (example.simple_value === null && Object.keys(example.notion_payload).length === 0) {
+            readOnly.push(example);
+        }
+        else {
+            writable.push(example);
+        }
+    }
+    return { writable, readOnly };
+}

package/dist/utils/schema-extractor.d.ts

@@ -0,0 +1,65 @@
+import { GetDataSourceResponse } from '@notionhq/client/build/src/api-endpoints';
+/**
+ * Property schema for AI agents - simplified and easy to parse
+ */
+export interface PropertySchema {
+    name: string;
+    type: string;
+    description?: string;
+    required?: boolean;
+    options?: string[];
+    config?: Record<string, any>;
+}
+/**
+ * Database schema in AI-friendly format
+ */
+export interface DataSourceSchema {
+    id: string;
+    title: string;
+    description?: string;
+    properties: PropertySchema[];
+    url?: string;
+}
+/**
+ * Extract clean, AI-parseable schema from Notion data source response
+ *
+ * This transforms the complex nested Notion API structure into a flat,
+ * easy-to-understand format that AI agents can work with directly.
+ *
+ * @param dataSource - Raw Notion data source response
+ * @returns Simplified schema object
+ */
+export declare function extractSchema(dataSource: GetDataSourceResponse): DataSourceSchema;
+/**
+ * Filter properties by names
+ *
+ * @param schema - Full schema
+ * @param propertyNames - Array of property names to include
+ * @returns Filtered schema
+ */
+export declare function filterProperties(schema: DataSourceSchema, propertyNames: string[]): DataSourceSchema;
+/**
+ * Format schema as human-readable table data
+ *
+ * @param schema - Schema to format
+ * @returns Array of objects for table display
+ */
+export declare function formatSchemaForTable(schema: DataSourceSchema): Array<Record<string, string>>;
+/**
+ * Format schema as markdown documentation
+ *
+ * @param schema - Schema to format
+ * @returns Markdown string
+ */
+export declare function formatSchemaAsMarkdown(schema: DataSourceSchema): string;
+/**
+ * Validate that a data object matches the schema
+ *
+ * @param schema - Schema to validate against
+ * @param data - Data object to validate
+ * @returns Validation result with errors
+ */
+export declare function validateAgainstSchema(schema: DataSourceSchema, data: Record<string, any>): {
+    valid: boolean;
+    errors: string[];
+};

package/dist/utils/schema-extractor.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSchema = extractSchema;
+exports.filterProperties = filterProperties;
+exports.formatSchemaForTable = formatSchemaForTable;
+exports.formatSchemaAsMarkdown = formatSchemaAsMarkdown;
+exports.validateAgainstSchema = validateAgainstSchema;
+/**
+ * Extract clean, AI-parseable schema from Notion data source response
+ *
+ * This transforms the complex nested Notion API structure into a flat,
+ * easy-to-understand format that AI agents can work with directly.
+ *
+ * @param dataSource - Raw Notion data source response
+ * @returns Simplified schema object
+ */
+function extractSchema(dataSource) {
+    const properties = [];
+    // Extract title from data source
+    const title = extractTitle(dataSource);
+    // Extract description if available
+    const description = extractDescription(dataSource);
+    // Process each property in the data source
+    if (dataSource.properties) {
+        for (const [propName, propConfig] of Object.entries(dataSource.properties)) {
+            const schema = extractPropertySchema(propName, propConfig);
+            if (schema) {
+                properties.push(schema);
+            }
+        }
+    }
+    return {
+        id: dataSource.id,
+        title,
+        description,
+        properties,
+        url: 'url' in dataSource ? dataSource.url : undefined,
+    };
+}
+/**
+ * Extract title from data source
+ */
+function extractTitle(dataSource) {
+    if ('title' in dataSource && Array.isArray(dataSource.title)) {
+        return dataSource.title
+            .map((t) => t.plain_text || '')
+            .join('')
+            .trim() || 'Untitled';
+    }
+    return 'Untitled';
+}
+/**
+ * Extract description from data source
+ */
+function extractDescription(dataSource) {
+    if ('description' in dataSource && Array.isArray(dataSource.description)) {
+        const desc = dataSource.description
+            .map((d) => d.plain_text || '')
+            .join('')
+            .trim();
+        return desc || undefined;
+    }
+    return undefined;
+}
+/**
+ * Extract individual property schema
+ */
+function extractPropertySchema(name, config) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    if (!config || !config.type) {
+        return null;
+    }
+    const schema = {
+        name,
+        type: config.type,
+    };
+    // Handle select and multi-select with options
+    if (config.type === 'select' && ((_a = config.select) === null || _a === void 0 ? void 0 : _a.options)) {
+        schema.options = config.select.options.map((opt) => opt.name);
+        schema.description = `Select one: ${schema.options.join(', ')}`;
+    }
+    if (config.type === 'multi_select' && ((_b = config.multi_select) === null || _b === void 0 ? void 0 : _b.options)) {
+        schema.options = config.multi_select.options.map((opt) => opt.name);
+        schema.description = `Select multiple: ${schema.options.join(', ')}`;
+    }
+    // Handle status property (similar to select)
+    if (config.type === 'status' && ((_c = config.status) === null || _c === void 0 ? void 0 : _c.options)) {
+        schema.options = config.status.options.map((opt) => opt.name);
+        schema.description = `Status: ${schema.options.join(', ')}`;
+    }
+    // Handle formula properties
+    if (config.type === 'formula' && ((_d = config.formula) === null || _d === void 0 ? void 0 : _d.expression)) {
+        schema.config = {
+            expression: config.formula.expression,
+        };
+        schema.description = `Formula: ${config.formula.expression}`;
+    }
+    // Handle rollup properties
+    if (config.type === 'rollup') {
+        schema.config = {
+            relation_property: (_e = config.rollup) === null || _e === void 0 ? void 0 : _e.relation_property_name,
+            rollup_property: (_f = config.rollup) === null || _f === void 0 ? void 0 : _f.rollup_property_name,
+            function: (_g = config.rollup) === null || _g === void 0 ? void 0 : _g.function,
+        };
+        schema.description = 'Rollup from related database';
+    }
+    // Handle relation properties
+    if (config.type === 'relation') {
+        schema.config = {
+            database_id: (_h = config.relation) === null || _h === void 0 ? void 0 : _h.database_id,
+            type: (_j = config.relation) === null || _j === void 0 ? void 0 : _j.type,
+        };
+        schema.description = 'Relation to another database';
+    }
+    // Handle number properties with format
+    if (config.type === 'number' && ((_k = config.number) === null || _k === void 0 ? void 0 : _k.format)) {
+        schema.config = {
+            format: config.number.format,
+        };
+        schema.description = `Number (${config.number.format})`;
+    }
+    // Mark title property as required
+    if (config.type === 'title') {
+        schema.required = true;
+        schema.description = 'Title (required)';
+    }
+    return schema;
+}
+/**
+ * Filter properties by names
+ *
+ * @param schema - Full schema
+ * @param propertyNames - Array of property names to include
+ * @returns Filtered schema
+ */
+function filterProperties(schema, propertyNames) {
+    const lowerNames = propertyNames.map(n => n.toLowerCase());
+    return {
+        ...schema,
+        properties: schema.properties.filter(p => lowerNames.includes(p.name.toLowerCase())),
+    };
+}
+/**
+ * Format schema as human-readable table data
+ *
+ * @param schema - Schema to format
+ * @returns Array of objects for table display
+ */
+function formatSchemaForTable(schema) {
+    return schema.properties.map(prop => {
+        var _a;
+        return ({
+            name: prop.name,
+            type: prop.type,
+            required: prop.required ? 'Yes' : 'No',
+            options: ((_a = prop.options) === null || _a === void 0 ? void 0 : _a.join(', ')) || '-',
+            description: prop.description || '-',
+        });
+    });
+}
+/**
+ * Format schema as markdown documentation
+ *
+ * @param schema - Schema to format
+ * @returns Markdown string
+ */
+function formatSchemaAsMarkdown(schema) {
+    var _a;
+    const lines = [];
+    lines.push(`# ${schema.title}`);
+    lines.push('');
+    if (schema.description) {
+        lines.push(schema.description);
+        lines.push('');
+    }
+    lines.push(`**Database ID:** \`${schema.id}\``);
+    if (schema.url) {
+        lines.push(`**URL:** ${schema.url}`);
+    }
+    lines.push('');
+    lines.push('## Properties');
+    lines.push('');
+    lines.push('| Name | Type | Required | Options/Details |');
+    lines.push('|------|------|----------|-----------------|');
+    for (const prop of schema.properties) {
+        const required = prop.required ? '✓' : '';
+        const details = ((_a = prop.options) === null || _a === void 0 ? void 0 : _a.join(', ')) || prop.description || '';
+        lines.push(`| ${prop.name} | ${prop.type} | ${required} | ${details} |`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Validate that a data object matches the schema
+ *
+ * @param schema - Schema to validate against
+ * @param data - Data object to validate
+ * @returns Validation result with errors
+ */
+function validateAgainstSchema(schema, data) {
+    const errors = [];
+    // Check required properties
+    for (const prop of schema.properties) {
+        if (prop.required && !(prop.name in data)) {
+            errors.push(`Missing required property: ${prop.name}`);
+        }
+    }
+    // Check property types and options
+    for (const [key, value] of Object.entries(data)) {
+        const propSchema = schema.properties.find(p => p.name === key);
+        if (!propSchema) {
+            errors.push(`Unknown property: ${key}`);
+            continue;
+        }
+        // Validate select/multi-select options
+        if (propSchema.options && propSchema.options.length > 0) {
+            if (propSchema.type === 'select') {
+                if (typeof value === 'string' && !propSchema.options.includes(value)) {
+                    errors.push(`Invalid option for ${key}: ${value}. Must be one of: ${propSchema.options.join(', ')}`);
+                }
+            }
+            if (propSchema.type === 'multi_select') {
+                if (Array.isArray(value)) {
+                    const invalidOptions = value.filter(v => !propSchema.options.includes(v));
+                    if (invalidOptions.length > 0) {
+                        errors.push(`Invalid options for ${key}: ${invalidOptions.join(', ')}`);
+                    }
+                }
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}

package/dist/utils/shell-config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shell Configuration Utility
+ *
+ * Detects the user's shell and persists environment variables (e.g., NOTION_TOKEN)
+ * to the appropriate rc file (.zshrc, .bashrc, etc.).
+ *
+ * Used by both `config set-token` and `init` commands to avoid duplicating
+ * shell detection and rc file writing logic.
+ */
+/**
+ * Detect the current shell from the SHELL environment variable.
+ * Falls back to bash on Unix, powershell on Windows.
+ */
+export declare function detectShell(): string;
+/**
+ * Resolve the path to the shell's rc/config file.
+ */
+export declare function getRcFilePath(shell: string): string;
+/**
+ * Persist a Notion token to the user's shell rc file.
+ *
+ * Reads the rc file, checks if NOTION_TOKEN already exists (replaces it if so),
+ * otherwise appends a new export line. Creates the file if it doesn't exist.
+ *
+ * Returns the shell name and rc file path so callers can inform the user.
+ */
+export declare function persistToken(token: string): Promise<{
+    rcFile: string;
+    shell: string;
+}>;