paymongo-cli 1.4.4 → 1.4.7

package/.github/copilot-instructions.md

@@ -1,95 +1,95 @@
-# PayMongo CLI - AI Agent Instructions
-
-## Project Overview
-PayMongo CLI is a TypeScript-based developer tool for PayMongo payment integration with local webhook forwarding via ngrok tunneling. It uses **ESM modules** (`"type": "module"`) with Commander.js for CLI commands.
-
-## Architecture
-
-### Code Structure
-```
-src/
-├── commands/      # CLI commands (commander.js) - one file per top-level command
-├── services/      # Core business logic
-│   ├── api/       # ApiClient - PayMongo V1 API wrapper with retries & caching
-│   ├── config/    # ConfigManager - .paymongo file handling via cosmiconfig
-│   └── web/       # Express + Socket.io for GUI dashboard
-├── types/         # TypeScript definitions + Zod schemas
-└── utils/         # Shared utilities (errors, logging, cache, validation)
-```
-
-### Key Patterns
-
-**Error Handling** - Always use custom error classes from `src/utils/errors.ts`:
-```typescript
-import { PayMongoError, NetworkError, ConfigError, ApiKeyError } from '../utils/errors.js';
-throw new PayMongoError('User-friendly message', 'ERROR_CODE', 400);
-```
-
-**Retry Logic** - Use `withRetry()` for network operations:
-```typescript
-import { withRetry } from '../utils/errors.js';
-const result = await withRetry(() => apiCall(), { maxRetries: 3, silent: true });
-```
-
-**Lazy Loading** - Import heavy dependencies inside functions to keep CLI startup fast (<100ms):
-```typescript
-// ✓ Correct - lazy load inside action
-.action(async () => {
-  const { confirm } = await import('@inquirer/prompts');
-});
-// ✗ Wrong - top-level import slows startup
-import { confirm } from '@inquirer/prompts';
-```
-
-**ESM Imports** - Always use `.js` extension for local imports:
-```typescript
-import ConfigManager from '../services/config/manager.js';
-```
-
-## Configuration
-- Project config: `.paymongo` (JSON, managed via `ConfigManager`)
-- Global credentials: `~/.paymongo/credentials.enc` (AES-256-CBC encrypted)
-- Validation: Zod schemas in `src/types/schemas.ts`
-
-## Development Workflow
-
-### Commands
-```bash
-npm run build          # Compile TypeScript
-npm run dev            # Watch mode compilation
-npm link               # Test CLI globally as 'paymongo'
-npm test               # Jest with ESM (--experimental-vm-modules)
-npm run lint:fix       # ESLint auto-fix
-```
-
-### Testing Strategy
-- **Mocking ESM**: Use `jest.unstable_mockModule()` before dynamic imports
-- Structure: `tests/unit/`, `tests/integration/`
-- Mock external services (axios, ngrok, filesystem)
-
-Example test pattern:
-```typescript
-jest.unstable_mockModule('axios', () => ({ default: mockAxios }));
-const { ApiClient } = await import('../../src/services/api/client.js');
-```
-
-## Code Conventions
-
-### TypeScript
-- Strict mode enabled with `noImplicitAny`, `noUncheckedIndexedAccess`
-- Avoid `any` - use proper types from `src/types/paymongo.ts`
-- Config validation via Zod: `validateConfig()` from `src/types/schemas.ts`
-
-### Commit Messages
-Follow conventional commits: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`
-
-### Security
-- Never log API keys or sensitive data
-- Use `ConfigManager` for credential access
-- Keep `.paymongo` and `.env` in `.gitignore`
-
-## Key Files Reference
-- [src/services/api/client.ts](src/services/api/client.ts) - API wrapper with interceptors
-- [src/utils/errors.ts](src/utils/errors.ts) - Error classes + `withRetry()`
-- [src/types/schemas.ts](src/types/schemas.ts) - Zod validation schemas
-- [src/services/config/manager.ts](src/services/config/manager.ts) - Config file handling
+# PayMongo CLI - AI Agent Instructions
+
+## Project Overview
+PayMongo CLI is a TypeScript-based developer tool for PayMongo payment integration with local webhook forwarding via ngrok tunneling. It uses **ESM modules** (`"type": "module"`) with Commander.js for CLI commands.
+
+## Architecture
+
+### Code Structure
+```
+src/
+├── commands/      # CLI commands (commander.js) - one file per top-level command
+├── services/      # Core business logic
+│   ├── api/       # ApiClient - PayMongo V1 API wrapper with retries & caching
+│   ├── config/    # ConfigManager - .paymongo file handling via cosmiconfig
+│   └── web/       # Express + Socket.io for GUI dashboard
+├── types/         # TypeScript definitions + Zod schemas
+└── utils/         # Shared utilities (errors, logging, cache, validation)
+```
+
+### Key Patterns
+
+**Error Handling** - Always use custom error classes from `src/utils/errors.ts`:
+```typescript
+import { PayMongoError, NetworkError, ConfigError, ApiKeyError } from '../utils/errors.js';
+throw new PayMongoError('User-friendly message', 'ERROR_CODE', 400);
+```
+
+**Retry Logic** - Use `withRetry()` for network operations:
+```typescript
+import { withRetry } from '../utils/errors.js';
+const result = await withRetry(() => apiCall(), { maxRetries: 3, silent: true });
+```
+
+**Lazy Loading** - Import heavy dependencies inside functions to keep CLI startup fast (<100ms):
+```typescript
+// ✓ Correct - lazy load inside action
+.action(async () => {
+  const { confirm } = await import('@inquirer/prompts');
+});
+// ✗ Wrong - top-level import slows startup
+import { confirm } from '@inquirer/prompts';
+```
+
+**ESM Imports** - Always use `.js` extension for local imports:
+```typescript
+import ConfigManager from '../services/config/manager.js';
+```
+
+## Configuration
+- Project config: `.paymongo` (JSON, managed via `ConfigManager`)
+- Global credentials: `~/.paymongo/credentials.enc` (AES-256-CBC encrypted)
+- Validation: Zod schemas in `src/types/schemas.ts`
+
+## Development Workflow
+
+### Commands
+```bash
+npm run build          # Compile TypeScript
+npm run dev            # Watch mode compilation
+npm link               # Test CLI globally as 'paymongo'
+npm test               # Jest with ESM (--experimental-vm-modules)
+npm run lint:fix       # ESLint auto-fix
+```
+
+### Testing Strategy
+- **Mocking ESM**: Use `jest.unstable_mockModule()` before dynamic imports
+- Structure: `tests/unit/`, `tests/integration/`
+- Mock external services (axios, ngrok, filesystem)
+
+Example test pattern:
+```typescript
+jest.unstable_mockModule('axios', () => ({ default: mockAxios }));
+const { ApiClient } = await import('../../src/services/api/client.js');
+```
+
+## Code Conventions
+
+### TypeScript
+- Strict mode enabled with `noImplicitAny`, `noUncheckedIndexedAccess`
+- Avoid `any` - use proper types from `src/types/paymongo.ts`
+- Config validation via Zod: `validateConfig()` from `src/types/schemas.ts`
+
+### Commit Messages
+Follow conventional commits: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`
+
+### Security
+- Never log API keys or sensitive data
+- Use `ConfigManager` for credential access
+- Keep `.paymongo` and `.env` in `.gitignore`
+
+## Key Files Reference
+- [src/services/api/client.ts](src/services/api/client.ts) - API wrapper with interceptors
+- [src/utils/errors.ts](src/utils/errors.ts) - Error classes + `withRetry()`
+- [src/types/schemas.ts](src/types/schemas.ts) - Zod validation schemas
+- [src/services/config/manager.ts](src/services/config/manager.ts) - Config file handling

package/CHANGELOG.md

@@ -7,6 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.7] - 2026-02-27
+
+### Changed
+
+- **Error Handling** - Replaced all 60 `process.exit(1)` calls across 10 command files with a `CommandError` throw pattern and centralized global error handler in `index.ts`.
+- **CLI Version** - Version string is now dynamically read from `package.json` instead of being hardcoded, keeping User-Agent headers and `--version` output always in sync.
+- **Magic Numbers** - Extracted hardcoded cache TTL, rate limit thresholds, and API base URL into named constants in `constants.ts`.
+- **Async File I/O** - Converted synchronous `fs` operations to `fs/promises` in dev-mode hot paths:
+  - `webhook-store.ts`: Lazy async directory creation, all read/write operations non-blocking.
+  - `analytics/service.ts`: Async persistence with `_ready` promise to prevent constructor race conditions.
+  - `process-manager.ts`: All static methods async; updated 13 call sites across dev subcommands.
+- **Deduplicated ValidationError** - Removed duplicate `ValidationError` class from `validator.ts`; single definition now lives in `errors.ts` and is re-exported.
+- **DevServer Logging** - Replaced raw `console.log`/`console.error` calls in `DevServer` with structured `Logger` instance for consistent, controllable output.
+
+### Fixed
+
+- **Input Sanitization** - Enhanced `validateWebhookUrl()` with max URL length (2048 chars), automatic whitespace trimming, and rejection of URLs containing embedded credentials.
+- **Race Condition** - Fixed analytics service race where `loadEvents()` could overwrite in-memory state written by `recordEvent()` before async load completed.
+- **Unhandled Promises** - `recordEvent()` calls in `DevServer` are now properly awaited via extracted `processWebhookBody()` method, preventing silent failures.
+- **Bulk Import Errors** - `importWebhooks()` and `importPayments()` now catch file-not-found and malformed JSON errors, throwing descriptive `PayMongoError` instead of raw stack traces.
+
+### Added
+
+- **Unit Tests** - Added 62 new tests across 3 previously-uncovered modules:
+  - `BulkOperations` (19 tests): export/import, file errors, JSON validation, filename generation.
+  - `DevProcessManager` (22 tests): state persistence, process detection, log management, uptime formatting.
+  - `TeamService` (21 tests): key bundles, member management, serialization, team operations.
+
+### Security
+
+- Webhook URL validation now blocks URLs with embedded `user:pass@` credentials to prevent credential leakage.
+
+## [1.4.6] - 2026-02-03
+
+### Changed
+
+- **Config Validation** - Allowed loading configs without API keys and normalized optional fields to avoid setup lockouts.
+- **Webhook Signatures** - Standardized signature verification format across dev server, trigger, and generated templates.
+- **CLI Startup** - Lazy-loaded prompt dependencies in several commands for faster startup.
+
+### Fixed
+
+- **Analytics Persistence** - Stored analytics in a safe user directory with test override support.
+- **Dev Auto-Register** - Respected `dev.autoRegisterWebhook` in the dev command.
+- **Team Import** - Enabled `--force` to overwrite existing keys during team import.
+- **Config Import** - Validated imports with schema and normalized missing optional fields.
+
+## [1.4.5] - 2026-02-01
+
+### Changed
+
+- **Credential Encryption** - Migrated stored credentials to AES-256-GCM with scrypt-derived keys and per-machine salt, with automatic legacy AES-256-CBC migration on load.
+- **Init .gitignore Handling** - Made `.env` and `.paymongo` ignore entries idempotent and appended with a consistent header when missing.
+
+### Fixed
+
+- **API Key Errors** - Standardized missing secret key handling to throw `ApiKeyError` in the API client.
+- **Test Reliability** - Updated login and template tests for new encryption payloads and added DevServer webhook signature verification coverage.
+
 ## [1.4.4] - 2026-01-27
 
 ### Changed
@@ -288,6 +347,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 | Version | Release Date | Highlights                                                           |
 | ------- | ------------ | -------------------------------------------------------------------- |
+| [1.4.7] | 2026-02-27   | CommandError pattern, dynamic version, async FS, input sanitization  |
+| [1.4.6] | 2026-02-03   | Config validation, webhook signatures, lazy loading                  |
+| [1.4.5] | 2026-02-01   | AES-256-GCM encryption, .gitignore handling                          |
+| [1.4.4] | 2026-01-27   | Codebase modularization, integration testing                         |
 | [1.4.3] | 2026-01-26   | Enhanced error handling, test output cleanup, API client consolidation |
 | [1.4.1] | 2026-01-26   | Test coverage completion, ESLint compliance, documentation updates   |
 | [1.4.0] | 2026-01-26   | Code generation, HTTP client migration, GUI removal, performance optimization |
@@ -299,6 +362,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ---
 
 ## Upgrade Guide
+### Upgrading to 1.4.7
+
+```bash
+npm install -g paymongo-cli@latest
+```
+
+**Breaking Changes:** None. This is a backward-compatible patch release.
+
+**Improvements:**
+- All `process.exit(1)` calls replaced with structured error handling — CLI now exits cleanly through global error handlers
+- Sync file I/O in dev-mode hot paths converted to async for better event loop performance
+- Webhook URL validation hardened against credential leakage and oversized inputs
+- CLI version always matches `package.json` — no more stale User-Agent strings
+- Duplicate `ValidationError` class consolidated to single definition
+- DevServer uses structured Logger instead of raw console output
+- Bulk import operations now produce user-friendly error messages
+- 62 new unit tests covering BulkOperations, DevProcessManager, and TeamService
+
 ### Upgrading to 1.4.3
 
 ```bash
@@ -390,7 +471,10 @@ npm install -g paymongo-cli
 - [Issue Tracker](https://github.com/leodyversemilla07/paymongo-cli/issues)
 - [PayMongo API Documentation](https://developers.paymongo.com/)
 
-[Unreleased]: https://github.com/leodyversemilla07/paymongo-cli/compare/v1.4.4...HEAD
+[Unreleased]: https://github.com/leodyversemilla07/paymongo-cli/compare/v1.4.7...HEAD
+[1.4.7]: https://github.com/leodyversemilla07/paymongo-cli/compare/v1.4.6...v1.4.7
+[1.4.6]: https://github.com/leodyversemilla07/paymongo-cli/compare/v1.4.5...v1.4.6
+[1.4.5]: https://github.com/leodyversemilla07/paymongo-cli/compare/v1.4.4...v1.4.5
 [1.4.4]: https://github.com/leodyversemilla07/paymongo-cli/compare/v1.4.3...v1.4.4
 [1.4.3]: https://github.com/leodyversemilla07/paymongo-cli/compare/v1.4.1...v1.4.3
 [1.4.1]: https://github.com/leodyversemilla07/paymongo-cli/compare/v1.4.0...v1.4.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Leodyver Semilla
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2026 Leodyver Semilla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.