@catafal/notion-cli 5.9.0

package/dist/commands/user/retrieve.js

@@ -0,0 +1,103 @@
+"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");
+class UserRetrieve extends core_1.Command {
+    async run() {
+        const { args, flags } = await this.parse(UserRetrieve);
+        try {
+            let res = await notion.retrieveUser(args.user_id);
+            // Apply minimal flag to strip metadata
+            if (flags.minimal) {
+                res = (0, helper_1.stripMetadata)(res);
+            }
+            // 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 = {
+                id: {},
+                name: {},
+                object: {},
+                type: {},
+                person_or_bot: {
+                    header: 'person/bot',
+                    get: (row) => {
+                        if (row.type === 'person') {
+                            return row.person;
+                        }
+                        return row.bot;
+                    },
+                },
+                avatar_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: 'user',
+                    attemptedId: args.user_id,
+                    endpoint: 'users.retrieve'
+                });
+            if (flags.json) {
+                this.log(JSON.stringify(cliError.toJSON(), null, 2));
+            }
+            else {
+                this.error(cliError.toHumanString());
+            }
+            process.exit(1);
+        }
+    }
+}
+UserRetrieve.description = 'Retrieve a user';
+UserRetrieve.aliases = ['user:r'];
+UserRetrieve.examples = [
+    {
+        description: 'Retrieve a user',
+        command: `$ notion-cli user retrieve USER_ID`,
+    },
+    {
+        description: 'Retrieve a user and output raw json',
+        command: `$ notion-cli user retrieve USER_ID -r`,
+    },
+    {
+        description: 'Retrieve a user and output JSON for automation',
+        command: `$ notion-cli user retrieve USER_ID --json`,
+    },
+];
+UserRetrieve.args = {
+    user_id: core_1.Args.string(),
+};
+UserRetrieve.flags = {
+    raw: core_1.Flags.boolean({
+        char: 'r',
+        description: 'output raw json',
+    }),
+    ...table_formatter_1.tableFlags,
+    ...base_flags_1.AutomationFlags,
+};
+exports.default = UserRetrieve;

package/dist/commands/whoami.d.ts

@@ -0,0 +1,19 @@
+import { Command } from '@oclif/core';
+export default class Whoami extends Command {
+    static description: string;
+    static aliases: string[];
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    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>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/whoami.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_flags_1 = require("../base-flags");
+const notion = require("../notion");
+const cache_1 = require("../cache");
+const errors_1 = require("../errors");
+const workspace_cache_1 = require("../utils/workspace-cache");
+const token_validator_1 = require("../utils/token-validator");
+class Whoami extends core_1.Command {
+    async run() {
+        var _a;
+        const { flags } = await this.parse(Whoami);
+        const startTime = Date.now();
+        try {
+            // Verify NOTION_TOKEN is set (throws if not)
+            (0, token_validator_1.validateNotionToken)();
+            // Get bot user info (with retry and caching)
+            const user = await notion.botUser();
+            // Get cache stats from in-memory cache
+            const cacheStats = cache_1.cacheManager.getStats();
+            const cacheHitRate = cache_1.cacheManager.getHitRate();
+            // Load workspace cache (databases.json)
+            const cache = await (0, workspace_cache_1.loadCache)();
+            // Calculate connection latency
+            const latencyMs = Date.now() - startTime;
+            // Extract bot info safely
+            let botInfo = null;
+            let workspaceInfo = null;
+            if (user.type === 'bot') {
+                const botUser = user;
+                if (botUser.bot && typeof botUser.bot === 'object' && 'owner' in botUser.bot) {
+                    botInfo = {
+                        owner: botUser.bot.owner,
+                        workspace_name: botUser.bot.workspace_name,
+                        workspace_id: botUser.bot.workspace_id,
+                    };
+                    // Build workspace info if available
+                    if (botUser.bot.workspace_name) {
+                        workspaceInfo = {
+                            name: botUser.bot.workspace_name,
+                            id: botUser.bot.workspace_id,
+                        };
+                    }
+                }
+            }
+            // Build response data
+            const data = {
+                bot: {
+                    id: user.id,
+                    name: user.name || 'Unnamed Bot',
+                    type: user.type,
+                    ...(botInfo && { bot_info: botInfo })
+                },
+                workspace: workspaceInfo,
+                api_version: '2022-06-28',
+                cli_version: this.config.version,
+                cache_status: {
+                    enabled: !flags['no-cache'] && cache_1.cacheManager.isEnabled(),
+                    in_memory: {
+                        size: cacheStats.size,
+                        hits: cacheStats.hits,
+                        misses: cacheStats.misses,
+                        hit_rate: cacheHitRate,
+                        evictions: cacheStats.evictions,
+                    },
+                    workspace: {
+                        databases_cached: ((_a = cache === null || cache === void 0 ? void 0 : cache.databases) === null || _a === void 0 ? void 0 : _a.length) || 0,
+                        last_sync: (cache === null || cache === void 0 ? void 0 : cache.lastSync) || null,
+                        cache_version: (cache === null || cache === void 0 ? void 0 : cache.version) || null,
+                    }
+                },
+                connection: {
+                    status: 'connected',
+                    latency_ms: latencyMs
+                }
+            };
+            // Output JSON envelope
+            if (flags.json) {
+                this.log(JSON.stringify({
+                    success: true,
+                    data,
+                    metadata: {
+                        timestamp: new Date().toISOString(),
+                        command: 'whoami',
+                        execution_time_ms: latencyMs
+                    }
+                }, null, 2));
+                process.exit(0);
+            }
+            // Human-readable output
+            this.log('\nConnection Status');
+            this.log('='.repeat(60));
+            this.log(`Status:      Connected`);
+            this.log(`Latency:     ${data.connection.latency_ms}ms`);
+            this.log('\nBot Information');
+            this.log('='.repeat(60));
+            this.log(`Name:        ${data.bot.name}`);
+            this.log(`ID:          ${data.bot.id}`);
+            this.log(`Type:        ${data.bot.type}`);
+            if (data.workspace) {
+                this.log('\nWorkspace Information');
+                this.log('='.repeat(60));
+                this.log(`Name:        ${data.workspace.name || 'N/A'}`);
+                if (data.workspace.id) {
+                    this.log(`ID:          ${data.workspace.id}`);
+                }
+            }
+            this.log('\nAPI & CLI Version');
+            this.log('='.repeat(60));
+            this.log(`CLI:         ${data.cli_version}`);
+            this.log(`API:         ${data.api_version}`);
+            this.log('\nCache Status');
+            this.log('='.repeat(60));
+            this.log(`Enabled:     ${data.cache_status.enabled ? 'Yes' : 'No'}`);
+            if (data.cache_status.enabled) {
+                this.log('\nIn-Memory Cache:');
+                this.log(`  Size:        ${data.cache_status.in_memory.size} entries`);
+                this.log(`  Hits:        ${data.cache_status.in_memory.hits}`);
+                this.log(`  Misses:      ${data.cache_status.in_memory.misses}`);
+                this.log(`  Hit Rate:    ${(data.cache_status.in_memory.hit_rate * 100).toFixed(1)}%`);
+                this.log(`  Evictions:   ${data.cache_status.in_memory.evictions}`);
+                this.log('\nWorkspace Cache:');
+                this.log(`  Databases:   ${data.cache_status.workspace.databases_cached}`);
+                if (data.cache_status.workspace.last_sync) {
+                    const syncDate = new Date(data.cache_status.workspace.last_sync);
+                    this.log(`  Last Sync:   ${syncDate.toLocaleString()}`);
+                }
+                else {
+                    this.log(`  Last Sync:   Never (run 'notion-cli sync' to initialize)`);
+                }
+            }
+            this.log('\n' + '='.repeat(60));
+            this.log('\nConnection verified successfully!');
+            // Provide helpful tips
+            if (!cache || cache.databases.length === 0) {
+                this.log('\nTip: Run "notion-cli sync" to cache workspace databases for faster lookups');
+            }
+            process.exit(0);
+        }
+        catch (error) {
+            const cliError = (0, errors_1.wrapNotionError)(error, {
+                endpoint: 'users.botUser',
+                resourceType: 'user'
+            });
+            if (flags.json) {
+                this.log(JSON.stringify(cliError.toJSON(), null, 2));
+            }
+            else {
+                this.error(cliError.toHumanString());
+            }
+            process.exit(1);
+        }
+    }
+}
+Whoami.description = 'Verify API connectivity and show workspace context';
+Whoami.aliases = ['test', 'health', 'connectivity'];
+Whoami.examples = [
+    {
+        description: 'Check connection and show bot info',
+        command: '$ notion-cli whoami',
+    },
+    {
+        description: 'Check connection and output as JSON',
+        command: '$ notion-cli whoami --json',
+    },
+    {
+        description: 'Bypass cache for fresh connectivity test',
+        command: '$ notion-cli whoami --no-cache',
+    },
+];
+Whoami.flags = {
+    ...base_flags_1.AutomationFlags,
+};
+exports.default = Whoami;

package/dist/deduplication.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Request deduplication manager
+ * Ensures only one in-flight request per unique key
+ */
+export interface DeduplicationStats {
+    hits: number;
+    misses: number;
+    pending: number;
+}
+export declare class DeduplicationManager {
+    private pending;
+    private stats;
+    constructor();
+    /**
+     * Execute a function with deduplication
+     * If the same key is already in-flight, returns the existing promise
+     * @param key Unique identifier for the request
+     * @param fn Function to execute if no in-flight request exists
+     * @returns Promise resolving to the function result
+     */
+    execute<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get deduplication statistics
+     * @returns Object containing hits, misses, and pending count
+     */
+    getStats(): DeduplicationStats;
+    /**
+     * Clear all pending requests and reset statistics
+     */
+    clear(): void;
+    /**
+     * Safety cleanup for stale entries
+     * This should rarely be needed as promises clean themselves up
+     * @param _maxAge Maximum age in milliseconds (default: 30000)
+     */
+    cleanup(_maxAge?: number): void;
+}
+/**
+ * Global singleton instance for use across the application
+ */
+export declare const deduplicationManager: DeduplicationManager;

package/dist/deduplication.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Request deduplication manager
+ * Ensures only one in-flight request per unique key
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deduplicationManager = exports.DeduplicationManager = void 0;
+class DeduplicationManager {
+    constructor() {
+        this.pending = new Map();
+        this.stats = { hits: 0, misses: 0 };
+    }
+    /**
+     * Execute a function with deduplication
+     * If the same key is already in-flight, returns the existing promise
+     * @param key Unique identifier for the request
+     * @param fn Function to execute if no in-flight request exists
+     * @returns Promise resolving to the function result
+     */
+    async execute(key, fn) {
+        // Check for in-flight request
+        const existing = this.pending.get(key);
+        if (existing) {
+            this.stats.hits++;
+            return existing;
+        }
+        // Create new request
+        this.stats.misses++;
+        const promise = fn().finally(() => {
+            this.pending.delete(key);
+        });
+        this.pending.set(key, promise);
+        return promise;
+    }
+    /**
+     * Get deduplication statistics
+     * @returns Object containing hits, misses, and pending count
+     */
+    getStats() {
+        return {
+            ...this.stats,
+            pending: this.pending.size,
+        };
+    }
+    /**
+     * Clear all pending requests and reset statistics
+     */
+    clear() {
+        this.pending.clear();
+        this.stats = { hits: 0, misses: 0 };
+    }
+    /**
+     * Safety cleanup for stale entries
+     * This should rarely be needed as promises clean themselves up
+     * @param _maxAge Maximum age in milliseconds (default: 30000)
+     */
+    cleanup(_maxAge = 30000) {
+        // Note: In practice, promises clean themselves up via finally()
+        // This is a safety mechanism for edge cases
+        const currentSize = this.pending.size;
+        if (currentSize > 0) {
+            // Log warning if cleanup is needed
+            console.warn(`DeduplicationManager cleanup called with ${currentSize} pending requests`);
+        }
+    }
+}
+exports.DeduplicationManager = DeduplicationManager;
+/**
+ * Global singleton instance for use across the application
+ */
+exports.deduplicationManager = new DeduplicationManager();

package/dist/envelope.d.ts

@@ -0,0 +1,169 @@
+/**
+ * JSON Envelope Standardization System for Notion CLI
+ *
+ * Provides consistent machine-readable output across all commands with:
+ * - Standard success/error envelopes
+ * - Metadata tracking (command, timestamp, execution time)
+ * - Exit code standardization (0=success, 1=API error, 2=CLI error)
+ * - Proper stdout/stderr separation
+ */
+import { NotionCLIErrorCode } from './errors/index';
+/**
+ * Standard metadata included in all envelopes
+ */
+export interface EnvelopeMetadata {
+    /** ISO 8601 timestamp when the command was executed */
+    timestamp: string;
+    /** Full command name (e.g., "page retrieve", "db query") */
+    command: string;
+    /** Execution time in milliseconds */
+    execution_time_ms: number;
+    /** CLI version for debugging and compatibility */
+    version: string;
+}
+/**
+ * Success envelope structure
+ * Used when a command completes successfully
+ */
+export interface SuccessEnvelope<T = any> {
+    success: true;
+    data: T;
+    metadata: EnvelopeMetadata;
+}
+/**
+ * Error details structure
+ */
+export interface ErrorDetails {
+    /** Semantic error code (e.g., "DATABASE_NOT_FOUND", "RATE_LIMITED") */
+    code: NotionCLIErrorCode | string;
+    /** Human-readable error message */
+    message: string;
+    /** Additional context about the error */
+    details?: any;
+    /** Actionable suggestions for the user */
+    suggestions?: string[];
+    /** Original Notion API error (if applicable) */
+    notionError?: any;
+}
+/**
+ * Error envelope structure
+ * Used when a command fails
+ */
+export interface ErrorEnvelope {
+    success: false;
+    error: ErrorDetails;
+    metadata: Omit<EnvelopeMetadata, 'execution_time_ms'> & {
+        execution_time_ms?: number;
+    };
+}
+/**
+ * Union type for all envelope responses
+ */
+export type Envelope<T = any> = SuccessEnvelope<T> | ErrorEnvelope;
+/**
+ * Exit codes for consistent process termination
+ */
+export declare enum ExitCode {
+    /** Command completed successfully */
+    SUCCESS = 0,
+    /** API/Notion error (auth, not found, rate limit, network, etc.) */
+    API_ERROR = 1,
+    /** CLI/validation error (invalid args, syntax, config issues) */
+    CLI_ERROR = 2
+}
+/**
+ * Output flags that determine envelope formatting
+ */
+export interface OutputFlags {
+    json?: boolean;
+    'compact-json'?: boolean;
+    raw?: boolean;
+    markdown?: boolean;
+    pretty?: boolean;
+    csv?: boolean;
+}
+/**
+ * EnvelopeFormatter - Core utility for creating and outputting envelopes
+ */
+export declare class EnvelopeFormatter {
+    private startTime;
+    private commandName;
+    private version;
+    /**
+     * Initialize formatter with command metadata
+     *
+     * @param commandName - Full command name (e.g., "page retrieve")
+     * @param version - CLI version from package.json
+     */
+    constructor(commandName: string, version: string);
+    /**
+     * Create success envelope with data and metadata
+     *
+     * @param data - The actual response data
+     * @param additionalMetadata - Optional additional metadata fields
+     * @returns Success envelope ready for output
+     */
+    wrapSuccess<T>(data: T, additionalMetadata?: Record<string, any>): SuccessEnvelope<T>;
+    /**
+     * Create error envelope from Error, NotionCLIError, or raw error object
+     *
+     * @param error - Error instance or error object
+     * @param additionalContext - Optional additional error context
+     * @returns Error envelope ready for output
+     */
+    wrapError(error: any, additionalContext?: Record<string, any>): ErrorEnvelope;
+    /**
+     * Output envelope to stdout with proper formatting
+     * Handles flag-based format selection and stdout/stderr separation
+     *
+     * @param envelope - Success or error envelope
+     * @param flags - Output format flags
+     * @param logFn - Logging function (typically this.log from Command)
+     */
+    outputEnvelope(envelope: Envelope, flags: OutputFlags, logFn?: (message: string) => void): void;
+    /**
+     * Get appropriate exit code for the envelope
+     *
+     * @param envelope - Success or error envelope
+     * @returns Exit code (0, 1, or 2)
+     */
+    getExitCode(envelope: Envelope): ExitCode;
+    /**
+     * Write diagnostic messages to stderr (won't pollute JSON on stdout)
+     * Useful for retry messages, cache hits, debug info, etc.
+     *
+     * @param message - Diagnostic message
+     * @param level - Message level (info, warn, error)
+     */
+    static writeDiagnostic(message: string, level?: 'info' | 'warn' | 'error'): void;
+    /**
+     * Helper to log retry attempts to stderr (doesn't pollute JSON output)
+     *
+     * @param attempt - Retry attempt number
+     * @param maxRetries - Maximum retry attempts
+     * @param delay - Delay before next retry in milliseconds
+     */
+    static logRetry(attempt: number, maxRetries: number, delay: number): void;
+    /**
+     * Helper to log cache hits to stderr (for debugging)
+     *
+     * @param cacheKey - Cache key that was hit
+     */
+    static logCacheHit(cacheKey: string): void;
+}
+/**
+ * Convenience function to create an envelope formatter
+ *
+ * @param commandName - Full command name
+ * @param version - CLI version
+ * @returns New EnvelopeFormatter instance
+ */
+export declare function createEnvelopeFormatter(commandName: string, version: string): EnvelopeFormatter;
+/**
+ * Type guard to check if envelope is a success envelope
+ */
+export declare function isSuccessEnvelope<T>(envelope: Envelope<T>): envelope is SuccessEnvelope<T>;
+/**
+ * Type guard to check if envelope is an error envelope
+ */
+export declare function isErrorEnvelope(envelope: Envelope): envelope is ErrorEnvelope;