@catafal/notion-cli 5.9.0

package/dist/envelope.js

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvelopeFormatter = exports.ExitCode = void 0;
+exports.createEnvelopeFormatter = createEnvelopeFormatter;
+exports.isSuccessEnvelope = isSuccessEnvelope;
+exports.isErrorEnvelope = isErrorEnvelope;
+const index_1 = require("./errors/index");
+/**
+ * Exit codes for consistent process termination
+ */
+var ExitCode;
+(function (ExitCode) {
+    /** Command completed successfully */
+    ExitCode[ExitCode["SUCCESS"] = 0] = "SUCCESS";
+    /** API/Notion error (auth, not found, rate limit, network, etc.) */
+    ExitCode[ExitCode["API_ERROR"] = 1] = "API_ERROR";
+    /** CLI/validation error (invalid args, syntax, config issues) */
+    ExitCode[ExitCode["CLI_ERROR"] = 2] = "CLI_ERROR";
+})(ExitCode || (exports.ExitCode = ExitCode = {}));
+/**
+ * Maps error codes to appropriate exit codes
+ */
+function getExitCodeForError(errorCode) {
+    // CLI/validation errors
+    const cliErrors = [
+        index_1.NotionCLIErrorCode.VALIDATION_ERROR,
+        'VALIDATION_ERROR',
+        'CLI_ERROR',
+        'CONFIG_ERROR',
+        'INVALID_ARGUMENT',
+    ];
+    if (cliErrors.includes(errorCode)) {
+        return ExitCode.CLI_ERROR;
+    }
+    // All other errors are API-related
+    return ExitCode.API_ERROR;
+}
+/**
+ * Suggestion generator based on error codes
+ */
+function generateSuggestions(errorCode) {
+    const suggestions = [];
+    switch (errorCode) {
+        case index_1.NotionCLIErrorCode.UNAUTHORIZED:
+            suggestions.push('Verify your NOTION_TOKEN is set correctly');
+            suggestions.push('Check token at: https://www.notion.so/my-integrations');
+            break;
+        case index_1.NotionCLIErrorCode.NOT_FOUND:
+            suggestions.push('Verify the resource ID is correct');
+            suggestions.push('Ensure your integration has access to the resource');
+            suggestions.push('Try running: notion-cli sync');
+            break;
+        case index_1.NotionCLIErrorCode.RATE_LIMITED:
+            suggestions.push('Wait and retry - the CLI will auto-retry with backoff');
+            suggestions.push('Reduce request frequency if this persists');
+            break;
+        case index_1.NotionCLIErrorCode.VALIDATION_ERROR:
+            suggestions.push('Check command syntax: notion-cli [command] --help');
+            suggestions.push('Verify all required arguments are provided');
+            break;
+        case 'CLI_ERROR':
+        case 'CONFIG_ERROR':
+            suggestions.push('Run: notion-cli config set-token');
+            suggestions.push('Check your .env file configuration');
+            break;
+    }
+    return suggestions;
+}
+/**
+ * EnvelopeFormatter - Core utility for creating and outputting envelopes
+ */
+class EnvelopeFormatter {
+    /**
+     * Initialize formatter with command metadata
+     *
+     * @param commandName - Full command name (e.g., "page retrieve")
+     * @param version - CLI version from package.json
+     */
+    constructor(commandName, version) {
+        this.startTime = Date.now();
+        this.commandName = commandName;
+        this.version = version;
+    }
+    /**
+     * 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(data, additionalMetadata) {
+        const executionTime = Date.now() - this.startTime;
+        return {
+            success: true,
+            data,
+            metadata: {
+                timestamp: new Date().toISOString(),
+                command: this.commandName,
+                execution_time_ms: executionTime,
+                version: this.version,
+                ...additionalMetadata,
+            },
+        };
+    }
+    /**
+     * 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, additionalContext) {
+        const executionTime = Date.now() - this.startTime;
+        let errorDetails;
+        // Handle NotionCLIError
+        if (error instanceof index_1.NotionCLIError) {
+            errorDetails = {
+                code: error.code,
+                message: error.message,
+                details: { ...error.context, ...additionalContext },
+                suggestions: error.suggestions.map(s => s.description),
+                notionError: error.context.originalError,
+            };
+        }
+        // Handle standard Error
+        else if (error instanceof Error) {
+            errorDetails = {
+                code: 'UNKNOWN',
+                message: error.message,
+                details: { stack: error.stack, ...additionalContext },
+                suggestions: ['Check the error message for details'],
+            };
+        }
+        // Handle raw error objects
+        else {
+            errorDetails = {
+                code: error.code || 'UNKNOWN',
+                message: error.message || 'An unknown error occurred',
+                details: { ...error, ...additionalContext },
+                suggestions: generateSuggestions(error.code || 'UNKNOWN'),
+            };
+        }
+        return {
+            success: false,
+            error: errorDetails,
+            metadata: {
+                timestamp: new Date().toISOString(),
+                command: this.commandName,
+                execution_time_ms: executionTime,
+                version: this.version,
+            },
+        };
+    }
+    /**
+     * 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, flags, logFn = console.log) {
+        // Raw mode bypasses envelope - outputs data directly
+        if (flags.raw && envelope.success) {
+            logFn(JSON.stringify(envelope.data, null, 2));
+            return;
+        }
+        // Compact JSON - single line for piping
+        if (flags['compact-json']) {
+            logFn(JSON.stringify(envelope));
+            return;
+        }
+        // Default: Pretty JSON (--json flag or error state)
+        logFn(JSON.stringify(envelope, null, 2));
+    }
+    /**
+     * Get appropriate exit code for the envelope
+     *
+     * @param envelope - Success or error envelope
+     * @returns Exit code (0, 1, or 2)
+     */
+    getExitCode(envelope) {
+        if (envelope.success) {
+            return ExitCode.SUCCESS;
+        }
+        // Type narrowing: at this point, envelope is ErrorEnvelope
+        return getExitCodeForError(envelope.error.code);
+    }
+    /**
+     * 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, level = 'info') {
+        const prefix = {
+            info: '[INFO]',
+            warn: '[WARN]',
+            error: '[ERROR]',
+        }[level];
+        // Write to stderr to avoid polluting JSON output on stdout
+        console.error(`${prefix} ${message}`);
+    }
+    /**
+     * 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, maxRetries, delay) {
+        EnvelopeFormatter.writeDiagnostic(`Retry attempt ${attempt}/${maxRetries} after ${delay}ms`, 'warn');
+    }
+    /**
+     * Helper to log cache hits to stderr (for debugging)
+     *
+     * @param cacheKey - Cache key that was hit
+     */
+    static logCacheHit(cacheKey) {
+        if (process.env.DEBUG === 'true') {
+            EnvelopeFormatter.writeDiagnostic(`Cache hit: ${cacheKey}`, 'info');
+        }
+    }
+}
+exports.EnvelopeFormatter = EnvelopeFormatter;
+/**
+ * Convenience function to create an envelope formatter
+ *
+ * @param commandName - Full command name
+ * @param version - CLI version
+ * @returns New EnvelopeFormatter instance
+ */
+function createEnvelopeFormatter(commandName, version) {
+    return new EnvelopeFormatter(commandName, version);
+}
+/**
+ * Type guard to check if envelope is a success envelope
+ */
+function isSuccessEnvelope(envelope) {
+    return envelope.success === true;
+}
+/**
+ * Type guard to check if envelope is an error envelope
+ */
+function isErrorEnvelope(envelope) {
+    return envelope.success === false;
+}

package/dist/errors/enhanced-errors.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Enhanced AI-Friendly Error Handling System
+ *
+ * Provides context-rich errors with actionable suggestions for:
+ * - AI assistants debugging automation failures
+ * - Human users troubleshooting CLI issues
+ * - Automated systems logging meaningful errors
+ *
+ * Key Features:
+ * - Error codes for programmatic handling
+ * - Contextual suggestions with fix commands
+ * - Support for both human and JSON output
+ * - Notion API error mapping
+ * - Common scenario detection
+ */
+/**
+ * Comprehensive error codes covering all common scenarios
+ */
+export declare enum NotionCLIErrorCode {
+    UNAUTHORIZED = "UNAUTHORIZED",
+    TOKEN_MISSING = "TOKEN_MISSING",
+    TOKEN_INVALID = "TOKEN_INVALID",
+    TOKEN_EXPIRED = "TOKEN_EXPIRED",
+    PERMISSION_DENIED = "PERMISSION_DENIED",
+    INTEGRATION_NOT_SHARED = "INTEGRATION_NOT_SHARED",
+    NOT_FOUND = "NOT_FOUND",
+    OBJECT_NOT_FOUND = "OBJECT_NOT_FOUND",
+    DATABASE_NOT_FOUND = "DATABASE_NOT_FOUND",
+    PAGE_NOT_FOUND = "PAGE_NOT_FOUND",
+    BLOCK_NOT_FOUND = "BLOCK_NOT_FOUND",
+    INVALID_ID_FORMAT = "INVALID_ID_FORMAT",
+    INVALID_DATABASE_ID = "INVALID_DATABASE_ID",
+    INVALID_PAGE_ID = "INVALID_PAGE_ID",
+    INVALID_BLOCK_ID = "INVALID_BLOCK_ID",
+    INVALID_URL = "INVALID_URL",
+    DATABASE_ID_CONFUSION = "DATABASE_ID_CONFUSION",// data_source_id vs database_id
+    WORKSPACE_VS_DATABASE = "WORKSPACE_VS_DATABASE",// workspace ID instead of database ID
+    RATE_LIMITED = "RATE_LIMITED",
+    API_ERROR = "API_ERROR",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    TIMEOUT = "TIMEOUT",
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    INVALID_PROPERTY = "INVALID_PROPERTY",
+    INVALID_FILTER = "INVALID_FILTER",
+    INVALID_JSON = "INVALID_JSON",
+    MISSING_REQUIRED_FIELD = "MISSING_REQUIRED_FIELD",
+    CACHE_ERROR = "CACHE_ERROR",
+    WORKSPACE_NOT_SYNCED = "WORKSPACE_NOT_SYNCED",
+    UNKNOWN = "UNKNOWN",
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+/**
+ * Suggested fix with command example
+ */
+export interface ErrorSuggestion {
+    description: string;
+    command?: string;
+    link?: string;
+}
+/**
+ * Contextual error information for better debugging
+ */
+export interface ErrorContext {
+    /** The resource type being accessed */
+    resourceType?: 'database' | 'page' | 'block' | 'user' | 'workspace';
+    /** The ID that was attempted */
+    attemptedId?: string;
+    /** The input that led to the error */
+    userInput?: string;
+    /** The API endpoint that failed */
+    endpoint?: string;
+    /** HTTP status code if applicable */
+    statusCode?: number;
+    /** Original error from Notion API or other source */
+    originalError?: any;
+    /** Additional debug information */
+    metadata?: Record<string, any>;
+}
+/**
+ * Enhanced CLI Error with AI-friendly formatting
+ */
+export declare class NotionCLIError extends Error {
+    readonly code: NotionCLIErrorCode;
+    readonly userMessage: string;
+    readonly suggestions: ErrorSuggestion[];
+    readonly context: ErrorContext;
+    readonly timestamp: string;
+    constructor(code: NotionCLIErrorCode, userMessage: string, suggestions?: ErrorSuggestion[], context?: ErrorContext);
+    /**
+     * Format error for human-readable console output
+     */
+    toHumanString(): string;
+    /**
+     * Format error for JSON output (automation-friendly)
+     */
+    toJSON(): {
+        success: boolean;
+        error: {
+            code: NotionCLIErrorCode;
+            message: string;
+            suggestions: ErrorSuggestion[];
+            context: ErrorContext;
+            timestamp: string;
+        };
+    };
+    /**
+     * Format error for compact JSON (single-line)
+     */
+    toCompactJSON(): string;
+}
+/**
+ * Error factory functions for common scenarios
+ */
+export declare class NotionCLIErrorFactory {
+    /**
+     * Token is missing or not set
+     */
+    static tokenMissing(): NotionCLIError;
+    /**
+     * Token is invalid or expired
+     */
+    static tokenInvalid(): NotionCLIError;
+    /**
+     * Integration not shared with resource
+     */
+    static integrationNotShared(resourceType: 'database' | 'page', resourceId?: string): NotionCLIError;
+    /**
+     * Database/Page/Block not found
+     */
+    static resourceNotFound(resourceType: 'database' | 'page' | 'block', identifier: string): NotionCLIError;
+    /**
+     * Invalid ID format
+     */
+    static invalidIdFormat(input: string, resourceType?: 'database' | 'page' | 'block'): NotionCLIError;
+    /**
+     * Common confusion: using database_id when data_source_id is needed
+     */
+    static databaseIdConfusion(attemptedId: string): NotionCLIError;
+    /**
+     * Workspace not synced (cache miss for name resolution)
+     */
+    static workspaceNotSynced(databaseName: string): NotionCLIError;
+    /**
+     * Rate limited by Notion API
+     */
+    static rateLimited(retryAfter?: number): NotionCLIError;
+    /**
+     * Invalid JSON in filter or property value
+     */
+    static invalidJson(jsonString: string, parseError: Error): NotionCLIError;
+    /**
+     * Invalid property name or type
+     */
+    static invalidProperty(propertyName: string, databaseId?: string): NotionCLIError;
+    /**
+     * Network or connection error
+     */
+    static networkError(originalError: Error): NotionCLIError;
+}
+/**
+ * Map Notion API errors to CLI errors with context
+ */
+export declare function wrapNotionError(error: any, context?: ErrorContext): NotionCLIError;
+/**
+ * Handle CLI errors with proper formatting based on output mode
+ */
+export declare function handleCliError(error: any, outputJson?: boolean, context?: ErrorContext): never;