@catafal/notion-cli 5.9.0

package/dist/commands/db/schema.js

@@ -0,0 +1,308 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const notion = require("../../notion");
+const schema_extractor_1 = require("../../utils/schema-extractor");
+const schema_examples_1 = require("../../utils/schema-examples");
+const errors_1 = require("../../errors");
+const notion_resolver_1 = require("../../utils/notion-resolver");
+class DbSchema extends core_1.Command {
+    async run() {
+        const { args, flags } = await this.parse(DbSchema);
+        try {
+            // Resolve ID from URL, direct ID, or name (future)
+            const dataSourceId = await (0, notion_resolver_1.resolveNotionId)(args.data_source_id, 'database');
+            // Fetch data source from Notion (uses caching)
+            const dataSource = await notion.retrieveDataSource(dataSourceId);
+            // Extract clean schema
+            let schema = (0, schema_extractor_1.extractSchema)(dataSource);
+            // Filter properties if specified
+            if (flags.properties) {
+                const propertyNames = flags.properties.split(',').map(p => p.trim());
+                schema = (0, schema_extractor_1.filterProperties)(schema, propertyNames);
+            }
+            // Generate examples if requested
+            if (flags['with-examples']) {
+                const examples = (0, schema_examples_1.generatePropertyExamples)(dataSource.properties);
+                const { writable, readOnly } = (0, schema_examples_1.groupExamplesByWritability)(examples);
+                // Determine output format
+                const outputFormat = flags.json ? 'json' : flags.output;
+                // Handle JSON output
+                if (outputFormat === 'json') {
+                    this.log(JSON.stringify({
+                        success: true,
+                        data: {
+                            schema: schema,
+                            examples: {
+                                writable: writable,
+                                read_only: readOnly,
+                                all: examples,
+                            },
+                        },
+                        metadata: {
+                            timestamp: new Date().toISOString(),
+                            command: 'db schema',
+                            examples_count: examples.length,
+                            writable_count: writable.length,
+                            read_only_count: readOnly.length,
+                        },
+                    }, null, 2));
+                    process.exit(0);
+                    return;
+                }
+                // Human-readable output with examples
+                this.outputSchemaWithExamples(schema, examples);
+                process.exit(0);
+                return;
+            }
+            // Regular schema output (without examples)
+            // Determine output format
+            const outputFormat = flags.json ? 'json' : flags.output;
+            // Handle markdown output
+            if (flags.markdown) {
+                const markdown = (0, schema_extractor_1.formatSchemaAsMarkdown)(schema);
+                this.log(markdown);
+                process.exit(0);
+                return;
+            }
+            // Handle JSON output (for AI agents)
+            if (outputFormat === 'json') {
+                this.log(JSON.stringify({
+                    success: true,
+                    data: schema,
+                    timestamp: new Date().toISOString(),
+                }, null, 2));
+                process.exit(0);
+                return;
+            }
+            // Handle YAML output
+            if (outputFormat === 'yaml') {
+                const yaml = this.formatAsYaml(schema);
+                this.log(yaml);
+                process.exit(0);
+                return;
+            }
+            // Handle table output (default)
+            this.outputTable(schema);
+            process.exit(0);
+        }
+        catch (error) {
+            const cliError = error instanceof errors_1.NotionCLIError
+                ? error
+                : (0, errors_1.wrapNotionError)(error, {
+                    resourceType: 'database',
+                    endpoint: 'dataSources.retrieve'
+                });
+            if (flags.json || flags.output === 'json') {
+                this.log(JSON.stringify(cliError.toJSON(), null, 2));
+            }
+            else {
+                this.error(cliError.toHumanString());
+            }
+            process.exit(1);
+        }
+    }
+    /**
+     * Output schema with examples in human-readable format
+     */
+    outputSchemaWithExamples(schema, examples) {
+        // First show basic schema info
+        this.log(`\n📋 ${schema.title}`);
+        if (schema.description) {
+            this.log(`   ${schema.description}`);
+        }
+        this.log(`   ID: ${schema.id}`);
+        if (schema.url) {
+            this.log(`   URL: ${schema.url}`);
+        }
+        this.log('');
+        // Group examples by writability
+        const { writable, readOnly } = (0, schema_examples_1.groupExamplesByWritability)(examples);
+        // Show writable properties with examples
+        if (writable.length > 0) {
+            this.log('✏️  Writable Properties (can be set via API)');
+            this.log('='.repeat(80));
+            for (const example of writable) {
+                this.log('');
+                this.log(`${example.property_name} (${example.property_type})`);
+                this.log(`  ${example.description}`);
+                this.log('');
+                this.log('  Simple value:');
+                this.log(`  ${JSON.stringify(example.simple_value)}`);
+                this.log('');
+                this.log('  Notion API payload:');
+                const payload = JSON.stringify(example.notion_payload, null, 2);
+                const indentedPayload = payload.split('\n').map(line => `  ${line}`).join('\n');
+                this.log(indentedPayload);
+                this.log('-'.repeat(80));
+            }
+        }
+        // Show read-only properties
+        if (readOnly.length > 0) {
+            this.log('');
+            this.log('🔒 Read-Only Properties (cannot be set via API)');
+            this.log('='.repeat(80));
+            for (const example of readOnly) {
+                this.log('');
+                this.log(`${example.property_name} (${example.property_type})`);
+                this.log(`  ${example.description}`);
+                this.log('-'.repeat(80));
+            }
+        }
+        this.log('');
+    }
+    /**
+     * Output schema as formatted table
+     */
+    outputTable(schema) {
+        this.log(`\n📋 ${schema.title}`);
+        if (schema.description) {
+            this.log(`   ${schema.description}`);
+        }
+        this.log(`   ID: ${schema.id}`);
+        if (schema.url) {
+            this.log(`   URL: ${schema.url}`);
+        }
+        this.log('');
+        if (schema.properties.length === 0) {
+            this.log('   No properties found.');
+            return;
+        }
+        // Calculate column widths
+        const nameWidth = Math.max(20, ...schema.properties.map(p => p.name.length));
+        const typeWidth = Math.max(12, ...schema.properties.map(p => p.type.length));
+        // Print header
+        this.log(`   ${'Name'.padEnd(nameWidth)} | ${'Type'.padEnd(typeWidth)} | Req | Details`);
+        this.log(`   ${'-'.repeat(nameWidth)}-+-${'-'.repeat(typeWidth)}-+-----+---------`);
+        // Print properties
+        for (const prop of schema.properties) {
+            const name = prop.name.padEnd(nameWidth);
+            const type = prop.type.padEnd(typeWidth);
+            const required = prop.required ? ' ✓ ' : '   ';
+            const details = prop.options
+                ? prop.options.slice(0, 3).join(', ') +
+                    (prop.options.length > 3 ? '...' : '')
+                : prop.description || '';
+            this.log(`   ${name} | ${type} | ${required} | ${details}`);
+        }
+        this.log('');
+    }
+    /**
+     * Format schema as YAML
+     */
+    formatAsYaml(schema) {
+        const lines = [];
+        lines.push('id: ' + schema.id);
+        lines.push('title: ' + schema.title);
+        if (schema.description) {
+            lines.push('description: ' + schema.description);
+        }
+        if (schema.url) {
+            lines.push('url: ' + schema.url);
+        }
+        lines.push('properties:');
+        for (const prop of schema.properties) {
+            lines.push(`  - name: ${prop.name}`);
+            lines.push(`    type: ${prop.type}`);
+            if (prop.required) {
+                lines.push(`    required: true`);
+            }
+            if (prop.options && prop.options.length > 0) {
+                lines.push(`    options:`);
+                for (const opt of prop.options) {
+                    lines.push(`      - ${opt}`);
+                }
+            }
+            if (prop.description) {
+                lines.push(`    description: ${prop.description}`);
+            }
+            if (prop.config) {
+                lines.push(`    config:`);
+                for (const [key, value] of Object.entries(prop.config)) {
+                    lines.push(`      ${key}: ${value}`);
+                }
+            }
+        }
+        return lines.join('\n');
+    }
+}
+DbSchema.description = 'Extract clean, AI-parseable schema from a Notion data source (table). ' +
+    'This command is optimized for AI agents and automation - it returns property names, ' +
+    'types, options (for select/multi-select), and configuration in an easy-to-parse format.';
+DbSchema.aliases = ['db:s', 'ds:schema', 'ds:s'];
+DbSchema.examples = [
+    {
+        description: 'Get full schema in JSON format (recommended for AI agents)',
+        command: '<%= config.bin %> db schema abc123def456 --output json',
+    },
+    {
+        description: 'Get schema with property payload examples (recommended for AI agents)',
+        command: '<%= config.bin %> db schema abc123def456 --with-examples --json',
+    },
+    {
+        description: 'Get schema using database URL',
+        command: '<%= config.bin %> db schema https://notion.so/DATABASE_ID --output json',
+    },
+    {
+        description: 'Get schema as formatted table',
+        command: '<%= config.bin %> db schema abc123def456',
+    },
+    {
+        description: 'Get schema with examples in human-readable format',
+        command: '<%= config.bin %> db schema abc123def456 --with-examples',
+    },
+    {
+        description: 'Get schema in YAML format',
+        command: '<%= config.bin %> db schema abc123def456 --output yaml',
+    },
+    {
+        description: 'Get only specific properties',
+        command: '<%= config.bin %> db schema abc123def456 --properties Name,Status,Tags --output json',
+    },
+    {
+        description: 'Get schema as markdown documentation',
+        command: '<%= config.bin %> db schema abc123def456 --markdown',
+    },
+    {
+        description: 'Parse schema with jq (extract property names)',
+        command: '<%= config.bin %> db schema abc123def456 --output json | jq \'.data.properties[].name\'',
+    },
+    {
+        description: 'Find all select/multi-select properties and their options',
+        command: '<%= config.bin %> db schema abc123def456 --output json | jq \'.data.properties[] | select(.options) | {name, options}\'',
+    },
+];
+DbSchema.args = {
+    data_source_id: core_1.Args.string({
+        required: true,
+        description: 'Data source ID or URL (the table whose schema you want to extract)',
+    }),
+};
+DbSchema.flags = {
+    output: core_1.Flags.string({
+        char: 'o',
+        description: 'Output format',
+        options: ['json', 'yaml', 'table'],
+        default: 'table',
+    }),
+    properties: core_1.Flags.string({
+        char: 'p',
+        description: 'Comma-separated list of properties to include (default: all)',
+    }),
+    markdown: core_1.Flags.boolean({
+        char: 'm',
+        description: 'Output as markdown documentation',
+        default: false,
+    }),
+    json: core_1.Flags.boolean({
+        char: 'j',
+        description: 'Output as JSON (shorthand for --output json)',
+        default: false,
+    }),
+    'with-examples': core_1.Flags.boolean({
+        char: 'e',
+        description: 'Include property payload examples for create/update operations',
+        default: false,
+    }),
+};
+exports.default = DbSchema;

package/dist/commands/db/update.d.ts

@@ -0,0 +1,31 @@
+import { Command } from '@oclif/core';
+export default class DbUpdate extends Command {
+    static description: string;
+    static aliases: string[];
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static args: {
+        database_id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'page-size': import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        retry: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        timeout: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'no-cache': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        minimal: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        columns: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        sort: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        filter: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        csv: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        extended: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'no-truncate': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'no-header': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        title: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        raw: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/db/update.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const table_formatter_1 = require("../../utils/table-formatter");
+const notion = require("../../notion");
+const helper_1 = require("../../helper");
+const base_flags_1 = require("../../base-flags");
+const errors_1 = require("../../errors");
+const notion_resolver_1 = require("../../utils/notion-resolver");
+class DbUpdate extends core_1.Command {
+    async run() {
+        const { args, flags } = await this.parse(DbUpdate);
+        try {
+            // Resolve ID from URL, direct ID, or name (future)
+            const dataSourceId = await (0, notion_resolver_1.resolveNotionId)(args.database_id, 'database');
+            const dsTitle = flags.title;
+            // TODO: support other properties (description, properties schema, etc.)
+            const dsProps = {
+                data_source_id: dataSourceId,
+                title: [
+                    {
+                        type: 'text',
+                        text: {
+                            content: dsTitle,
+                        },
+                    },
+                ],
+            };
+            const res = await notion.updateDataSource(dsProps);
+            // Handle JSON output for automation
+            if (flags.json) {
+                this.log(JSON.stringify({
+                    success: true,
+                    data: res,
+                    timestamp: new Date().toISOString()
+                }, null, 2));
+                process.exit(0);
+                return;
+            }
+            // Handle raw JSON output (legacy)
+            if (flags.raw) {
+                (0, helper_1.outputRawJson)(res);
+                process.exit(0);
+                return;
+            }
+            // Handle table output
+            const columns = {
+                title: {
+                    get: (row) => {
+                        return (0, helper_1.getDataSourceTitle)(row);
+                    },
+                },
+                object: {},
+                id: {},
+                url: {},
+            };
+            const options = {
+                printLine: this.log.bind(this),
+                ...flags,
+            };
+            (0, table_formatter_1.formatTable)([res], columns, options);
+            process.exit(0);
+        }
+        catch (error) {
+            const cliError = error instanceof errors_1.NotionCLIError
+                ? error
+                : (0, errors_1.wrapNotionError)(error, {
+                    resourceType: 'database',
+                    attemptedId: args.database_id,
+                    endpoint: 'dataSources.update'
+                });
+            if (flags.json) {
+                this.log(JSON.stringify(cliError.toJSON(), null, 2));
+            }
+            else {
+                this.error(cliError.toHumanString());
+            }
+            process.exit(1);
+        }
+    }
+}
+DbUpdate.description = 'Update a data source (table) title and properties';
+DbUpdate.aliases = ['db:u', 'ds:update', 'ds:u'];
+DbUpdate.examples = [
+    {
+        description: 'Update a data source with a specific data_source_id and title',
+        command: `$ notion-cli db update DATA_SOURCE_ID -t 'My Data Source'`,
+    },
+    {
+        description: 'Update a data source via URL',
+        command: `$ notion-cli db update https://notion.so/DATABASE_ID -t 'My Data Source'`,
+    },
+    {
+        description: 'Update a data source with a specific data_source_id and output raw json',
+        command: `$ notion-cli db update DATA_SOURCE_ID -t 'My Table' -r`,
+    },
+];
+DbUpdate.args = {
+    database_id: core_1.Args.string({
+        required: true,
+        description: 'Data source ID or URL (the ID of the table you want to update)',
+    }),
+};
+DbUpdate.flags = {
+    title: core_1.Flags.string({
+        char: 't',
+        description: 'New database title',
+        required: true,
+    }),
+    raw: core_1.Flags.boolean({
+        char: 'r',
+        description: 'output raw json',
+    }),
+    ...table_formatter_1.tableFlags,
+    ...base_flags_1.AutomationFlags,
+};
+exports.default = DbUpdate;

package/dist/commands/doctor.d.ts

@@ -0,0 +1,50 @@
+import { Command } from '@oclif/core';
+export default class Doctor extends Command {
+    static description: string;
+    static aliases: string[];
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    /**
+     * Check Node.js version meets requirement (>=18.0.0)
+     */
+    private checkNodeVersion;
+    /**
+     * Check if NOTION_TOKEN environment variable is set
+     */
+    private checkTokenSet;
+    /**
+     * Check if token format is valid
+     * Accepts both "secret_" prefix (internal integrations) and "ntn_" prefix (OAuth tokens)
+     */
+    private checkTokenFormat;
+    /**
+     * Check network connectivity to api.notion.com
+     */
+    private checkNetworkConnectivity;
+    /**
+     * Check if can connect to Notion API (whoami check)
+     */
+    private checkApiConnection;
+    /**
+     * Check if workspace cache exists
+     */
+    private checkCacheExists;
+    /**
+     * Check if cache is fresh (< 24 hours old) or needs sync
+     */
+    private checkCacheFreshness;
+    /**
+     * Test HTTPS connection to a host
+     */
+    private checkHttpsConnection;
+    /**
+     * Print human-readable output
+     */
+    private printHumanReadable;
+}