@infograb/notion-cli 5.9.0

package/bin/dev

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+const oclif = require('@oclif/core')
+
+const path = require('path')
+const project = path.join(__dirname, '..', 'tsconfig.json')
+
+// In dev mode -> use ts-node and dev plugins
+process.env.NODE_ENV = 'development'
+
+require('ts-node').register({project})
+
+// In dev mode, always show stack traces
+oclif.settings.debug = true;
+
+// Start the CLI
+oclif.run().then(oclif.flush).catch(oclif.Errors.handle)

package/bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\dev" %*

package/bin/run

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+const oclif = require('@oclif/core')
+
+// Check for updates asynchronously (doesn't block CLI execution)
+// This will notify users once per day if a new version is available
+try {
+  const { checkForUpdates } = require('../dist/utils/update-notifier')
+  checkForUpdates()
+} catch (error) {
+  // Silently fail if update check fails (e.g., during development)
+}
+
+oclif.run().then(require('@oclif/core/flush')).catch(require('@oclif/core/handle'))

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/dist/base-command.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Base Command with Envelope Support
+ *
+ * Extends oclif Command with automatic envelope wrapping for consistent JSON output.
+ * All commands should extend this class to get automatic envelope support.
+ */
+import { Command, Interfaces } from '@oclif/core';
+import { EnvelopeFormatter, OutputFlags } from './envelope';
+import { NotionCLIError } from './errors/index';
+/**
+ * Base command configuration
+ */
+export type CommandConfig = Interfaces.Config;
+/**
+ * BaseCommand - Extends oclif Command with envelope support
+ *
+ * Features:
+ * - Automatic envelope wrapping for JSON output
+ * - Consistent error handling
+ * - Execution time tracking
+ * - Version metadata injection
+ * - Stdout/stderr separation
+ */
+export declare abstract class BaseCommand extends Command {
+    protected envelope: EnvelopeFormatter;
+    protected shouldUseEnvelope: boolean;
+    /**
+     * Initialize command and create envelope formatter
+     */
+    init(): Promise<void>;
+    /**
+     * Cleanup hook - flushes disk cache and destroys HTTP agents before exit
+     */
+    finally(error?: Error): Promise<void>;
+    /**
+     * Determine if envelope should be used based on flags
+     */
+    protected checkEnvelopeUsage(flags: Record<string, unknown>): boolean;
+    /**
+     * Output success response with automatic envelope wrapping
+     *
+     * @param data - Response data
+     * @param flags - Command flags
+     * @param additionalMetadata - Optional metadata to include
+     */
+    protected outputSuccess<T>(data: T, flags: OutputFlags & Record<string, unknown>, additionalMetadata?: Record<string, unknown>): never;
+    /**
+     * Output error response with automatic envelope wrapping
+     *
+     * @param error - Error object
+     * @param flags - Command flags
+     * @param additionalContext - Optional error context
+     */
+    protected outputError(error: Error | NotionCLIError, flags: OutputFlags & Record<string, unknown>, additionalContext?: Record<string, unknown>): never;
+    /**
+     * Get appropriate exit code for error
+     */
+    private getExitCodeForError;
+    /**
+     * Catch handler that ensures proper envelope error output
+     */
+    catch(error: Error & {
+        exitCode?: number;
+    }): Promise<void>;
+}
+/**
+ * Standard flags that all envelope-enabled commands should include
+ */
+export declare const EnvelopeFlags: {
+    json: Interfaces.BooleanFlag<boolean>;
+    'compact-json': Interfaces.BooleanFlag<boolean>;
+    raw: Interfaces.BooleanFlag<boolean>;
+};

package/dist/base-command.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * Base Command with Envelope Support
+ *
+ * Extends oclif Command with automatic envelope wrapping for consistent JSON output.
+ * All commands should extend this class to get automatic envelope support.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvelopeFlags = exports.BaseCommand = void 0;
+const core_1 = require("@oclif/core");
+const envelope_1 = require("./envelope");
+const index_1 = require("./errors/index");
+const disk_cache_1 = require("./utils/disk-cache");
+const http_agent_1 = require("./http-agent");
+/**
+ * BaseCommand - Extends oclif Command with envelope support
+ *
+ * Features:
+ * - Automatic envelope wrapping for JSON output
+ * - Consistent error handling
+ * - Execution time tracking
+ * - Version metadata injection
+ * - Stdout/stderr separation
+ */
+class BaseCommand extends core_1.Command {
+    constructor() {
+        super(...arguments);
+        this.shouldUseEnvelope = false;
+    }
+    /**
+     * Initialize command and create envelope formatter
+     */
+    async init() {
+        var _a;
+        await super.init();
+        // Initialize disk cache (load from disk)
+        const diskCacheEnabled = process.env.NOTION_CLI_DISK_CACHE_ENABLED !== 'false';
+        if (diskCacheEnabled) {
+            try {
+                await disk_cache_1.diskCacheManager.initialize();
+            }
+            catch (error) {
+                // Silently ignore disk cache initialization errors
+                if (process.env.DEBUG) {
+                    console.error('Failed to initialize disk cache:', error);
+                }
+            }
+        }
+        // Get command name from ID (e.g., "page:retrieve" -> "page retrieve")
+        const commandName = ((_a = this.id) === null || _a === void 0 ? void 0 : _a.replace(/:/g, ' ')) || 'unknown';
+        // Get version from config
+        const version = this.config.version;
+        // Initialize envelope formatter
+        this.envelope = new envelope_1.EnvelopeFormatter(commandName, version);
+    }
+    /**
+     * Cleanup hook - flushes disk cache and destroys HTTP agents before exit
+     */
+    async finally(error) {
+        // Destroy HTTP agents to close all connections
+        try {
+            (0, http_agent_1.destroyAgents)();
+        }
+        catch (agentError) {
+            // Silently ignore agent cleanup errors
+            if (process.env.DEBUG) {
+                console.error('Failed to destroy HTTP agents:', agentError);
+            }
+        }
+        // Flush disk cache before exit
+        const diskCacheEnabled = process.env.NOTION_CLI_DISK_CACHE_ENABLED !== 'false';
+        if (diskCacheEnabled) {
+            try {
+                await disk_cache_1.diskCacheManager.shutdown();
+            }
+            catch (shutdownError) {
+                // Silently ignore shutdown errors
+                if (process.env.DEBUG) {
+                    console.error('Failed to shutdown disk cache:', shutdownError);
+                }
+            }
+        }
+        await super.finally(error);
+    }
+    /**
+     * Determine if envelope should be used based on flags
+     */
+    checkEnvelopeUsage(flags) {
+        return !!(flags.json || flags['compact-json']);
+    }
+    /**
+     * Output success response with automatic envelope wrapping
+     *
+     * @param data - Response data
+     * @param flags - Command flags
+     * @param additionalMetadata - Optional metadata to include
+     */
+    outputSuccess(data, flags, additionalMetadata) {
+        // Check if we should use envelope
+        this.shouldUseEnvelope = this.checkEnvelopeUsage(flags);
+        if (this.shouldUseEnvelope) {
+            const envelope = this.envelope.wrapSuccess(data, additionalMetadata);
+            this.envelope.outputEnvelope(envelope, flags, this.log.bind(this));
+            process.exit(this.envelope.getExitCode(envelope));
+        }
+        else {
+            // Non-envelope output (table, markdown, etc.) - handled by caller
+            // This path should not normally be reached as caller handles non-JSON output
+            throw new Error('outputSuccess should only be called for JSON output');
+        }
+    }
+    /**
+     * Output error response with automatic envelope wrapping
+     *
+     * @param error - Error object
+     * @param flags - Command flags
+     * @param additionalContext - Optional error context
+     */
+    outputError(error, flags, additionalContext) {
+        // Wrap raw errors in NotionCLIError
+        const cliError = error instanceof index_1.NotionCLIError ? error : (0, index_1.wrapNotionError)(error);
+        // Check if we should use envelope
+        this.shouldUseEnvelope = this.checkEnvelopeUsage(flags);
+        if (this.shouldUseEnvelope) {
+            const envelope = this.envelope.wrapError(cliError, additionalContext);
+            this.envelope.outputEnvelope(envelope, flags, this.log.bind(this));
+            process.exit(this.envelope.getExitCode(envelope));
+        }
+        else {
+            // Non-JSON mode - use oclif's error handling
+            this.error(cliError.message, { exit: this.getExitCodeForError(cliError) });
+        }
+    }
+    /**
+     * Get appropriate exit code for error
+     */
+    getExitCodeForError(error) {
+        // CLI validation errors
+        if (error.code === 'VALIDATION_ERROR') {
+            return envelope_1.ExitCode.CLI_ERROR;
+        }
+        // API errors (default)
+        return envelope_1.ExitCode.API_ERROR;
+    }
+    /**
+     * Catch handler that ensures proper envelope error output
+     */
+    async catch(error) {
+        // If command has already handled the error via outputError, just propagate
+        if (error.exitCode !== undefined) {
+            throw error;
+        }
+        // Otherwise, wrap and handle the error
+        const cliError = (0, index_1.wrapNotionError)(error);
+        this.error(cliError.message, { exit: this.getExitCodeForError(cliError) });
+    }
+}
+exports.BaseCommand = BaseCommand;
+/**
+ * Standard flags that all envelope-enabled commands should include
+ */
+exports.EnvelopeFlags = {
+    json: core_1.Flags.boolean({
+        char: 'j',
+        description: 'Output as JSON envelope (recommended for automation)',
+        default: false,
+    }),
+    'compact-json': core_1.Flags.boolean({
+        char: 'c',
+        description: 'Output as compact JSON envelope (single-line, ideal for piping)',
+        default: false,
+        exclusive: ['markdown', 'pretty'],
+    }),
+    raw: core_1.Flags.boolean({
+        char: 'r',
+        description: 'Output raw API response without envelope (legacy mode)',
+        default: false,
+    }),
+};

package/dist/base-flags.d.ts

@@ -0,0 +1,14 @@
+export declare const AutomationFlags: {
+    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>;
+};
+export declare const OutputFormatFlags: {
+    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>;
+};

package/dist/base-flags.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutputFormatFlags = exports.AutomationFlags = void 0;
+const core_1 = require("@oclif/core");
+exports.AutomationFlags = {
+    json: core_1.Flags.boolean({
+        char: 'j',
+        description: 'Output as JSON (recommended for automation)',
+        default: false,
+    }),
+    'page-size': core_1.Flags.integer({
+        description: 'Items per page (1-100, default: 100 for automation)',
+        min: 1,
+        max: 100,
+        default: 100,
+    }),
+    retry: core_1.Flags.boolean({
+        description: 'Auto-retry on rate limit (respects Retry-After header)',
+        default: true,
+    }),
+    timeout: core_1.Flags.integer({
+        description: 'Request timeout in milliseconds',
+        default: 30000,
+    }),
+    'no-cache': core_1.Flags.boolean({
+        description: 'Bypass cache and force fresh API calls',
+        default: false,
+    }),
+    verbose: core_1.Flags.boolean({
+        char: 'v',
+        description: 'Enable verbose logging to stderr (retry events, cache stats) - never pollutes stdout',
+        default: false,
+        env: 'NOTION_CLI_VERBOSE',
+    }),
+    minimal: core_1.Flags.boolean({
+        description: 'Strip unnecessary metadata (created_by, last_edited_by, object fields, request_id, etc.) - reduces response size by ~40%',
+        default: false,
+    }),
+};
+exports.OutputFormatFlags = {
+    markdown: core_1.Flags.boolean({
+        char: 'm',
+        description: 'Output as markdown table (GitHub-flavored)',
+        default: false,
+        exclusive: ['compact-json', 'pretty'],
+    }),
+    'compact-json': core_1.Flags.boolean({
+        char: 'c',
+        description: 'Output as compact JSON (single-line, ideal for piping)',
+        default: false,
+        exclusive: ['markdown', 'pretty'],
+    }),
+    pretty: core_1.Flags.boolean({
+        char: 'P',
+        description: 'Output as pretty table with borders',
+        default: false,
+        exclusive: ['markdown', 'compact-json'],
+    }),
+};

package/dist/cache.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Simple in-memory caching layer for Notion API responses
+ * Supports TTL (time-to-live) and cache invalidation
+ * Integrated with disk cache for persistence across CLI invocations
+ */
+export interface CacheEntry<T> {
+    data: T;
+    timestamp: number;
+    ttl: number;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    sets: number;
+    evictions: number;
+    size: number;
+}
+export interface CacheConfig {
+    enabled: boolean;
+    defaultTtl: number;
+    maxSize: number;
+    ttlByType: {
+        dataSource: number;
+        database: number;
+        user: number;
+        page: number;
+        block: number;
+    };
+}
+export declare class CacheManager {
+    private cache;
+    private stats;
+    private config;
+    constructor(config?: Partial<CacheConfig>);
+    /**
+     * Generate a cache key from resource type and identifiers
+     */
+    private generateKey;
+    /**
+     * Check if a cache entry is still valid
+     */
+    private isValid;
+    /**
+     * Evict expired entries
+     */
+    private evictExpired;
+    /**
+     * Evict oldest entries if cache is full
+     */
+    private evictOldest;
+    /**
+     * Get a value from cache (checks memory, then disk)
+     */
+    get<T>(type: string, ...identifiers: Array<string | number | object>): Promise<T | null>;
+    /**
+     * Set a value in cache with optional custom TTL (writes to memory and disk)
+     */
+    set<T>(type: string, data: T, customTtl?: number, ...identifiers: Array<string | number | object>): void;
+    /**
+     * Invalidate specific cache entries by type and optional identifiers
+     */
+    invalidate(type: string, ...identifiers: Array<string | number | object>): void;
+    /**
+     * Clear all cache entries (memory and disk)
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Get cache hit rate
+     */
+    getHitRate(): number;
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get current configuration
+     */
+    getConfig(): CacheConfig;
+}
+export declare const cacheManager: CacheManager;