@catafal/notion-cli 5.9.0

package/dist/commands/db/query.js

@@ -0,0 +1,360 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const notion = require("../../notion");
+const client_1 = require("@notionhq/client");
+const fs = require("fs");
+const path = require("path");
+const helper_1 = require("../../helper");
+const notion_1 = require("../../notion");
+const base_flags_1 = require("../../base-flags");
+const errors_1 = require("../../errors");
+const notion_resolver_1 = require("../../utils/notion-resolver");
+const table_formatter_1 = require("../../utils/table-formatter");
+class DbQuery extends core_1.Command {
+    async run() {
+        const { flags, args } = await this.parse(DbQuery);
+        try {
+            // Handle deprecation warnings (output to stderr to not pollute stdout)
+            if (flags.rawFilter) {
+                console.error('⚠️  Warning: --rawFilter is deprecated and will be removed in v6.0.0');
+                console.error('   Use --filter instead: notion-cli db query DS_ID --filter \'...\'');
+                console.error('');
+            }
+            if (flags.fileFilter) {
+                console.error('⚠️  Warning: --fileFilter is deprecated and will be removed in v6.0.0');
+                console.error('   Use --file-filter instead: notion-cli db query DS_ID --file-filter ./filter.json');
+                console.error('');
+            }
+            // Resolve ID from URL, direct ID, or name (future)
+            const databaseId = await (0, notion_resolver_1.resolveNotionId)(args.database_id, 'database');
+            let queryParams;
+            // Build filter
+            let filter = undefined;
+            try {
+                if (flags.filter || flags.rawFilter) {
+                    // JSON filter object (new flag or deprecated rawFilter)
+                    const filterStr = flags.filter || flags.rawFilter;
+                    try {
+                        filter = JSON.parse(filterStr);
+                    }
+                    catch (error) {
+                        throw errors_1.NotionCLIErrorFactory.invalidJson(filterStr, error);
+                    }
+                }
+                else if (flags['file-filter'] || flags.fileFilter) {
+                    // Load from file (new flag or deprecated fileFilter)
+                    const filterFile = flags['file-filter'] || flags.fileFilter;
+                    // Resolve path and prevent directory traversal outside cwd
+                    const basePath = path.resolve('./');
+                    const fp = path.resolve(basePath, filterFile);
+                    if (!fp.startsWith(basePath)) {
+                        throw new Error(`Invalid file path: must be within current directory`);
+                    }
+                    let fj;
+                    try {
+                        fj = fs.readFileSync(fp, { encoding: 'utf-8' });
+                        filter = JSON.parse(fj);
+                    }
+                    catch (error) {
+                        if (error.code === 'ENOENT') {
+                            throw errors_1.NotionCLIErrorFactory.invalidJson(filterFile, new Error(`File not found: ${filterFile}`));
+                        }
+                        throw errors_1.NotionCLIErrorFactory.invalidJson(fj, error);
+                    }
+                }
+                else if (flags.search) {
+                    // Simple text search - convert to Notion filter
+                    // Search across common text properties using OR
+                    // Note: This searches properties named "Name", "Title", and "Description"
+                    // For more complex searches, use --filter with explicit property names
+                    filter = {
+                        or: [
+                            { property: 'Name', title: { contains: flags.search } },
+                            { property: 'Title', title: { contains: flags.search } },
+                            { property: 'Description', rich_text: { contains: flags.search } },
+                            { property: 'Name', rich_text: { contains: flags.search } },
+                        ]
+                    };
+                }
+                // Build sorts
+                const sorts = [];
+                const direction = flags['sort-direction'] == 'desc' ? 'descending' : 'ascending';
+                if (flags['sort-property']) {
+                    sorts.push({
+                        property: flags['sort-property'],
+                        direction: direction,
+                    });
+                }
+                // Build query parameters
+                queryParams = {
+                    data_source_id: databaseId,
+                    filter: filter,
+                    sorts: sorts.length > 0 ? sorts : undefined,
+                    page_size: flags['page-size'],
+                };
+            }
+            catch (e) {
+                // Re-throw NotionCLIError, wrap others
+                if (e instanceof errors_1.NotionCLIError) {
+                    throw e;
+                }
+                throw (0, errors_1.wrapNotionError)(e, {
+                    resourceType: 'database',
+                    userInput: args.database_id
+                });
+            }
+            // Fetch pages from database
+            let pages = [];
+            if (flags['page-all']) {
+                pages = await notion.fetchAllPagesInDS(databaseId, queryParams.filter);
+            }
+            else {
+                const res = await notion_1.client.dataSources.query(queryParams);
+                pages.push(...res.results);
+            }
+            // Apply minimal flag to strip metadata
+            if (flags.minimal) {
+                pages = (0, helper_1.stripMetadata)(pages);
+            }
+            // Apply property selection if --select flag is used
+            if (flags.select) {
+                const selectedProps = flags.select.split(',').map(p => p.trim());
+                pages = pages.map((page) => {
+                    if (page.object === 'page' && page.properties) {
+                        // Keep core fields, filter properties
+                        const filtered = {
+                            ...page,
+                            properties: {}
+                        };
+                        // Copy only selected properties
+                        selectedProps.forEach(propName => {
+                            if (page.properties[propName]) {
+                                filtered.properties[propName] = page.properties[propName];
+                            }
+                        });
+                        return filtered;
+                    }
+                    return page;
+                });
+            }
+            // Define columns for table output
+            const columns = {
+                title: {
+                    get: (row) => {
+                        if (row.object == 'data_source' && (0, client_1.isFullDataSource)(row)) {
+                            return (0, helper_1.getDataSourceTitle)(row);
+                        }
+                        if (row.object == 'page' && (0, client_1.isFullPage)(row)) {
+                            return (0, helper_1.getPageTitle)(row);
+                        }
+                        return 'Untitled';
+                    },
+                },
+                object: {},
+                id: {},
+                url: {},
+            };
+            // Handle compact JSON output
+            if (flags['compact-json']) {
+                (0, helper_1.outputCompactJson)(pages);
+                process.exit(0);
+                return;
+            }
+            // Handle markdown table output
+            if (flags.markdown) {
+                (0, helper_1.outputMarkdownTable)(pages, columns);
+                process.exit(0);
+                return;
+            }
+            // Handle pretty table output
+            if (flags.pretty) {
+                (0, helper_1.outputPrettyTable)(pages, columns);
+                // Show hint after table output (use first page as sample)
+                if (pages.length > 0) {
+                    (0, helper_1.showRawFlagHint)(pages.length, pages[0]);
+                }
+                process.exit(0);
+                return;
+            }
+            // Handle JSON output for automation
+            if (flags.json) {
+                this.log(JSON.stringify({
+                    success: true,
+                    data: pages,
+                    count: pages.length,
+                    timestamp: new Date().toISOString()
+                }, null, 2));
+                process.exit(0);
+                return;
+            }
+            // Handle raw JSON output (legacy)
+            if (flags.raw) {
+                (0, helper_1.outputRawJson)(pages);
+                process.exit(0);
+                return;
+            }
+            // Handle table output (default)
+            const options = {
+                printLine: this.log.bind(this),
+                ...flags,
+            };
+            (0, table_formatter_1.formatTable)(pages, columns, options);
+            // Show hint after table output to make -r flag discoverable
+            // Use first page as sample to count fields
+            if (pages.length > 0) {
+                (0, helper_1.showRawFlagHint)(pages.length, pages[0]);
+            }
+            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.query'
+                });
+            if (flags.json) {
+                this.log(JSON.stringify(cliError.toJSON(), null, 2));
+            }
+            else {
+                this.error(cliError.toHumanString());
+            }
+            process.exit(1);
+        }
+    }
+}
+DbQuery.description = 'Query a database';
+DbQuery.aliases = ['db:q'];
+DbQuery.examples = [
+    {
+        description: 'Query a database with full data (recommended for AI assistants)',
+        command: `$ notion-cli db query DATABASE_ID --raw`,
+    },
+    {
+        description: 'Query all records as JSON',
+        command: `$ notion-cli db query DATABASE_ID --json`,
+    },
+    {
+        description: 'Filter with JSON object (recommended for AI agents)',
+        command: `$ notion-cli db query DATABASE_ID --filter '{"property": "Status", "select": {"equals": "Done"}}' --json`,
+    },
+    {
+        description: 'Simple text search across properties',
+        command: `$ notion-cli db query DATABASE_ID --search "urgent" --json`,
+    },
+    {
+        description: 'Load complex filter from file',
+        command: `$ notion-cli db query DATABASE_ID --file-filter ./filter.json --json`,
+    },
+    {
+        description: 'Query with AND filter',
+        command: `$ notion-cli db query DATABASE_ID --filter '{"and": [{"property": "Status", "select": {"equals": "Done"}}, {"property": "Priority", "number": {"greater_than": 5}}]}' --json`,
+    },
+    {
+        description: 'Query using database URL',
+        command: `$ notion-cli db query https://notion.so/DATABASE_ID --json`,
+    },
+    {
+        description: 'Query with sorting',
+        command: `$ notion-cli db query DATABASE_ID --sort-property Name --sort-direction desc`,
+    },
+    {
+        description: 'Query with pagination',
+        command: `$ notion-cli db query DATABASE_ID --page-size 50`,
+    },
+    {
+        description: 'Get all pages (bypass pagination)',
+        command: `$ notion-cli db query DATABASE_ID --page-all`,
+    },
+    {
+        description: 'Output as CSV',
+        command: `$ notion-cli db query DATABASE_ID --csv`,
+    },
+    {
+        description: 'Output as markdown table',
+        command: `$ notion-cli db query DATABASE_ID --markdown`,
+    },
+    {
+        description: 'Output as compact JSON',
+        command: `$ notion-cli db query DATABASE_ID --compact-json`,
+    },
+    {
+        description: 'Output as pretty table',
+        command: `$ notion-cli db query DATABASE_ID --pretty`,
+    },
+    {
+        description: 'Select specific properties (60-80% token reduction)',
+        command: `$ notion-cli db query DATABASE_ID --select "title,status,priority" --json`,
+    },
+];
+DbQuery.args = {
+    database_id: core_1.Args.string({
+        required: true,
+        description: 'Database or data source ID or URL (required for automation)',
+    }),
+};
+DbQuery.flags = {
+    'page-size': core_1.Flags.integer({
+        char: 'p',
+        description: 'The number of results to return (1-100)',
+        min: 1,
+        max: 100,
+        default: 10,
+    }),
+    'page-all': core_1.Flags.boolean({
+        char: 'A',
+        description: 'Get all pages (bypass pagination)',
+        default: false,
+    }),
+    'sort-property': core_1.Flags.string({
+        description: 'The property to sort results by',
+    }),
+    'sort-direction': core_1.Flags.string({
+        options: ['asc', 'desc'],
+        description: 'The direction to sort results',
+        default: 'asc',
+    }),
+    raw: core_1.Flags.boolean({
+        char: 'r',
+        description: 'Output raw JSON (recommended for AI assistants - returns all page data)',
+        default: false,
+    }),
+    ...table_formatter_1.tableFlags,
+    ...base_flags_1.AutomationFlags,
+    ...base_flags_1.OutputFormatFlags,
+    // New simplified filter interface (placed AFTER table flags to override)
+    filter: core_1.Flags.string({
+        char: 'f',
+        description: 'Filter as JSON object (Notion filter API format)',
+        exclusive: ['search', 'file-filter', 'rawFilter', 'fileFilter'],
+    }),
+    'file-filter': core_1.Flags.string({
+        char: 'F',
+        description: 'Load filter from JSON file',
+        exclusive: ['filter', 'search', 'rawFilter', 'fileFilter'],
+    }),
+    search: core_1.Flags.string({
+        char: 's',
+        description: 'Simple text search (searches across title and common text properties)',
+        exclusive: ['filter', 'file-filter', 'rawFilter', 'fileFilter'],
+    }),
+    select: core_1.Flags.string({
+        description: 'Select specific properties to return (comma-separated). Reduces token usage by 60-80%.',
+        examples: ['title,status', 'title,status,priority,due_date'],
+    }),
+    // DEPRECATED: Keep for backward compatibility
+    rawFilter: core_1.Flags.string({
+        char: 'a',
+        description: 'DEPRECATED: Use --filter instead. JSON stringified filter string',
+        hidden: true,
+        exclusive: ['filter', 'search', 'file-filter', 'fileFilter'],
+    }),
+    fileFilter: core_1.Flags.string({
+        description: 'DEPRECATED: Use --file-filter instead. JSON filter file path',
+        hidden: true,
+        exclusive: ['filter', 'search', 'file-filter', 'rawFilter'],
+    }),
+};
+exports.default = DbQuery;

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

@@ -0,0 +1,33 @@
+import { Command } from '@oclif/core';
+export default class DbRetrieve 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: {
+        markdown: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'compact-json': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        pretty: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        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>;
+        raw: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/db/retrieve.js

@@ -0,0 +1,134 @@
+"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 DbRetrieve extends core_1.Command {
+    async run() {
+        const { args, flags } = await this.parse(DbRetrieve);
+        try {
+            // Resolve ID from URL, direct ID, or name (future)
+            const dataSourceId = await (0, notion_resolver_1.resolveNotionId)(args.database_id, 'database');
+            let res = await notion.retrieveDataSource(dataSourceId);
+            // Apply minimal flag to strip metadata
+            if (flags.minimal) {
+                res = (0, helper_1.stripMetadata)(res);
+            }
+            // Define columns for table output
+            const columns = {
+                title: {
+                    get: (row) => {
+                        return (0, helper_1.getDataSourceTitle)(row);
+                    },
+                },
+                object: {},
+                id: {},
+                url: {},
+            };
+            // Handle compact JSON output
+            if (flags['compact-json']) {
+                (0, helper_1.outputCompactJson)(res);
+                process.exit(0);
+                return;
+            }
+            // Handle markdown table output
+            if (flags.markdown) {
+                (0, helper_1.outputMarkdownTable)([res], columns);
+                process.exit(0);
+                return;
+            }
+            // Handle pretty table output
+            if (flags.pretty) {
+                (0, helper_1.outputPrettyTable)([res], columns);
+                // Show hint after table output
+                (0, helper_1.showRawFlagHint)(1, res);
+                process.exit(0);
+                return;
+            }
+            // 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 (default)
+            const options = {
+                printLine: this.log.bind(this),
+                ...flags,
+            };
+            (0, table_formatter_1.formatTable)([res], columns, options);
+            // Show hint after table output to make -r flag discoverable
+            (0, helper_1.showRawFlagHint)(1, res);
+            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) {
+                this.log(JSON.stringify(cliError.toJSON(), null, 2));
+            }
+            else {
+                this.error(cliError.toHumanString());
+            }
+            process.exit(1);
+        }
+    }
+}
+DbRetrieve.description = 'Retrieve a data source (table) schema and properties';
+DbRetrieve.aliases = ['db:r', 'ds:retrieve', 'ds:r'];
+DbRetrieve.examples = [
+    {
+        description: 'Retrieve a data source with full schema (recommended for AI assistants)',
+        command: 'notion-cli db retrieve DATA_SOURCE_ID -r',
+    },
+    {
+        description: 'Retrieve a data source schema via data_source_id',
+        command: 'notion-cli db retrieve DATA_SOURCE_ID',
+    },
+    {
+        description: 'Retrieve a data source via URL',
+        command: 'notion-cli db retrieve https://notion.so/DATABASE_ID',
+    },
+    {
+        description: 'Retrieve a data source and output as markdown table',
+        command: 'notion-cli db retrieve DATA_SOURCE_ID --markdown',
+    },
+    {
+        description: 'Retrieve a data source and output as compact JSON',
+        command: 'notion-cli db retrieve DATA_SOURCE_ID --compact-json',
+    },
+];
+DbRetrieve.args = {
+    database_id: core_1.Args.string({
+        required: true,
+        description: 'Data source ID or URL (the ID of the table whose schema you want to retrieve)',
+    }),
+};
+DbRetrieve.flags = {
+    raw: core_1.Flags.boolean({
+        char: 'r',
+        description: 'output raw json (recommended for AI assistants - returns full schema)',
+    }),
+    ...table_formatter_1.tableFlags,
+    ...base_flags_1.AutomationFlags,
+    ...base_flags_1.OutputFormatFlags,
+};
+exports.default = DbRetrieve;

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

@@ -0,0 +1,32 @@
+import { Command } from '@oclif/core';
+export default class DbSchema extends Command {
+    static description: string;
+    static aliases: string[];
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static args: {
+        data_source_id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        output: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        properties: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        markdown: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'with-examples': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    /**
+     * Output schema with examples in human-readable format
+     */
+    private outputSchemaWithExamples;
+    /**
+     * Output schema as formatted table
+     */
+    private outputTable;
+    /**
+     * Format schema as YAML
+     */
+    private formatAsYaml;
+}