feat: add new api clients and improve docs by armando-rodriguez-cko · Pull Request #423 · checkout/checkout-sdk-node

armando-rodriguez-cko · 2026-02-10T17:21:42Z

Add new API clients and improve project documentation

📋 Summary

This PR adds support for 5 new API clients, updates 36 existing endpoints, improves project documentation, fixes a critical error handling bug, and enhances overall code quality. The SDK now provides comprehensive coverage of the Checkout.com API with better developer experience.

✨ New Features

New API Clients Added

Account Updater (cko.accountUpdater)
- Retrieve updated card credentials
- Support for Mastercard, Visa, American Express card schemes
- Automatic card expiry and status updates
Network Tokens (cko.networkTokens)
- Provision network tokens from card sources
- Get network token details (DPAN, expiry, state, TRID)
- Provision cryptograms for transactions
- Delete network tokens
Payment Methods (cko.paymentMethods)
- Get available payment methods for Processing Channel IDs
- Beta endpoint support
Identities - Complete identity verification suite (cko.identities)
- Applicants: Create, get, update, and anonymize applicant profiles
- AML Screenings: Create and retrieve AML verification screenings
- Face Authentications: Full face authentication workflow with attempts
- ID Document Verifications: Document verification with attempts and PDF reports
- Identity Verifications: Complete identity verification flows with PDF reports
- All submodules accessible via dedicated properties with backwards compatibility
Issuing - 10 new submodules (cko.issuing)
- Access: Manage issuing access credentials
- Cardholders: Create and manage cardholders
- Cards: Full card lifecycle (create, update, activate, renew, revoke, suspend, 3DS enrollment)
- Digital Cards: Retrieve digital card details
- Controls: Create and manage card controls
- Control Groups: Manage control groups by target
- Control Profiles: Create, update, manage control profiles and targets
- Disputes: Create, manage, and escalate issuing disputes
- Transactions: Query issuing transactions
- Simulate: Simulate issuing operations for testing
- All submodules accessible with backwards compatibility

🔄 Updates to Existing Endpoints

Updated 36 existing API endpoint implementations to align with latest API specifications:

Access, Apple Pay, Balances, Card Metadata, Customers, Disputes, Events, Files, Financial, Forward, Hosted Payments, Instruments, Issuing (base), Payment Contexts, Payment Sessions, Payment Setups, Payments Links, Platforms, Reconciliation, Reports, Risk, Sessions, Sources, Tokens, Transfers, Webhooks, Workflows
All APM-specific endpoints (Baloto, Boleto, Fawry, Giropay, iDEAL, Klarna, OXXO, Pago Fácil, Rapipago, SEPA)

📚 Documentation Improvements

README.md

Complete rewrite with improved structure and clarity (536 lines)
New HTTP Client Configuration section (fetch vs axios)
Expanded Base URL Configuration documentation (account-specific subdomain setup)
Updated Subdomain/Environment usage examples with real-world scenarios
Comprehensive Available Endpoints table (24 → 43 modules)
Deprecated APM endpoints clearly marked with migration guidance
Updated Error Handling table with accurate error.body information
Added special service URLs documentation (Balances, Files, Forward, Identity Verification, Transfers)
Updated test count (816 tests, 97.95% coverage)

New Files

CONTRIBUTING.md: Complete contribution guidelines
- Development setup instructions
- Code standards and conventional commit format
- Testing requirements
- Pull request process

TypeScript Definitions

Added missing config URLs: FORWARD_SANDBOX_URL, FORWARD_LIVE_URL, IDENTITY_VERIFICATION_SANDBOX_URL, IDENTITY_VERIFICATION_LIVE_URL
Updated error type definitions for AuthenticationError, ActionNotAllowed, NotFoundError to include body property

🐛 Bug Fixes

Critical Error Handling Fix

Issue: Error responses for 401/403/404 status codes were not propagating response body details to merchants, preventing visibility into error causes (e.g., "card_not_enrolled" in Sessions endpoint 403 responses).

Solution:

Modified AuthenticationError, ActionNotAllowed, NotFoundError constructors to accept and store error body
Updated determineError function to pass await errorJSON to these error classes
Added comprehensive tests verifying body propagation for all three status codes

Impact: Merchants can now access detailed error information via error.body for better debugging and error handling.

🔧 Configuration & Metadata Improvements

package.json

Enhanced description for better discoverability
Added 14 relevant keywords (checkout, payment-gateway, api, sdk, nodejs, typescript, etc.)
Added repository, bugs, and homepage URLs

LICENSE

Updated copyright year range from 2021 to 2021-2026

.npmignore

Removed duplicate "documentation" entry
Added missing config files (jsconfig.json, eslint.config.js)

jsconfig.json

Added ES2022 module configuration
Configured path aliases (@services, @api, @root)
Added include/exclude patterns

eslint.config.js

Added code quality rules: prefer-const, no-var, eqeqeq, no-throw-literal, prefer-promise-reject-errors
Updated ecmaVersion to 2024
Removed unused variables from codebase

🧪 Testing

Added 3+ tests for all new API clients
Added comprehensive test suite for Payment Setups endpoint (previously missing)
Added 3 tests for error body propagation (401/403/404)
All 816 tests passing with 97.95% code coverage maintained
Test coverage breakdown: 97.95% statements, 90.83% branches, 100% functions

🔍 Code Quality

Fixed unused variables in EnvironmentSubdomain.js and files.js
ESLint clean (no warnings)
All code follows ES2022+ standards
TypeScript definitions manually updated and verified

📦 Commits Breakdown

feat(account-updater): Add Account Updater API client
feat(identities): Add Identities API with all submodules (6 submodules)
feat(issuing): Add new Issuing submodules (10 submodules)
feat(network-tokens): Add Network Tokens API client
feat(payment-methods): Add Payment Methods API client
feat: Integrate new API clients into SDK (Checkout.js, index.js exports)
feat: Update existing API endpoints (36 modules)
test(payment-setups): Add comprehensive test coverage
docs: Rewrite README with improved structure and HTTP client documentation
chore: Update package metadata, LICENSE, .npmignore, jsconfig.json
chore: Improve code quality with ESLint rules and remove unused variables
fix: Propagate error body for 401/403/404 status codes
docs(types): Add missing config URLs and update error types
docs: Update README and extract CONTRIBUTING to separate file

⚠️ Breaking Changes

None. All changes are backwards compatible. Existing code will continue to work without modifications.

🎯 Migration Notes

No migration required for existing implementations
New endpoints available immediately via SDK instance
APM-specific endpoints deprecated but still functional (use cko.payments instead)
Error handling improved: error.body now available for 401/403/404 responses

✅ Checklist

All tests passing (816 tests)
Code coverage maintained (97.95%)
ESLint clean (no warnings)
Build successful (68 files compiled)
TypeScript definitions updated
Documentation updated (README, CONTRIBUTING, types)
No breaking changes
Backwards compatibility maintained

📸 Test Results

  816 passing
  
  Coverage summary:
  Statements   : 97.95%
  Branches     : 90.83%
  Functions    : 100%
  Lines        : 97.92%

Ready for review and merge to master. This PR significantly expands SDK capabilities while maintaining high code quality and test coverage.

- Add FORWARD_SANDBOX_URL and FORWARD_LIVE_URL to config types - Add IDENTITY_VERIFICATION_SANDBOX_URL and IDENTITY_VERIFICATION_LIVE_URL to config types - Update AuthenticationError, ActionNotAllowed, NotFoundError to include error parameter and body property in error types

- Update error handling table: 401/403/404 now include error.body with details - Update test count from 813+ to 816 tests - Extract contributing guidelines to CONTRIBUTING.md - Remove broken RunKit section - Add link to CONTRIBUTING.md in README footer

src/api/identities/aml-screenings.js

david-ruiz-cko

See comment

… dedicated modules Split monolithic Checkout.js into specialized modules for better maintainability: - auth-builder.js: Centralized authentication configuration (OAuth, static keys, env vars) - special-urls.js: Service-specific URL calculation (files, transfers, balances, etc.) - endpoints-factory.js: Factory pattern for API endpoint initialization Reduces Checkout.js from ~200 lines to ~46 lines while improving code organization and testability.

Enhanced HTTP service layer with better error handling and response processing: - Improved error body propagation for 401/403/404 responses - Better handling of empty responses and edge cases - Refactored request/response processing for consistency - Enhanced error messages with more context These improvements provide better debugging information and more reliable error handling across all API endpoints.

…d submodules Extracted Platforms API into focused, maintainable submodules: - subentity.js: Sub-entity onboarding and management operations - files.js: File upload and retrieval for identity documentation - payment-instruments.js: Payment instrument management for payouts - payout-schedules.js: Payout schedule configuration - reserve-rules.js: Reserve rule management with ETag support Main Platforms class now delegates to submodules while maintaining backward compatibility through proxy methods. Reduces platforms.js from ~500 lines to ~106 lines. Includes TypeScript definitions for all new submodules with proper typing for method signatures and optional parameters.

…nd documentation Updated all API endpoint clients to leverage enhanced HTTP service layer: - Account Updater: Improved error handling - Apple Pay: Enhanced request validation - Balances: Better response processing - Customers: Updated documentation and error handling - Events: Improved query parameter handling - Forex: Enhanced error messages - Forward: Better request processing - Hosted Payments: Updated error handling - Identities (all submodules): Improved error propagation - Instruments: Added 204 No Content response handling - Payment Contexts: Enhanced validation - Reconciliation: Better error messages - Risk: Improved request handling - Sources: Enhanced error handling - Transfers: Updated documentation - Workflows: Better response processing All clients now benefit from improved error body propagation and more consistent error handling patterns.

…t and integration folders Major restructuring of test suite for better organization and maintainability: Reorganized test modules: - Identities: Split into submodules (aml-screenings, applicants, face-authentications, id-document-verifications, identity-verifications, delegation) - Issuing: Split into submodules (access, cardholders, cards, control-groups, control-profiles, controls, digital-cards, disputes, simulate, transactions) - Platforms: Split into submodules (files, payment-instruments, payout-schedules, reserve-rules, subentity) - Instruments: Split into unit and integration tests Renamed for consistency: - card-metadata.js → card-metadata-unit.js - customers.js → customers-unit.js - Added corresponding *-it.js files for integration tests Deleted consolidated monolithic test files: - test/balances/balances.js (split into unit/integration) - test/instruments/instruments.js (440 lines → modular structure) - test/issuing/issuing-it.js, issuing-unit.js (split into submodules) - test/identities/*-unit.js, identities-it.js (split into submodules) - test/platforms/platforms-unit.js (split into submodules) - test/reconciliation/reconciliation.js (split into unit tests) - test/reports/reports.js (split into unit tests) - test/risk/risk.js (split into unit tests) Updated all existing tests: - Enhanced test coverage for new error handling - Updated assertions for improved HTTP responses - Added tests for 204 No Content handling in instruments - Improved test organization and naming conventions Total: ~51 new/reorganized test files with better separation of concerns between unit and integration tests.

Updated documentation to reflect architectural improvements: - Added documentation for new modular structure - Enhanced configuration examples with subdomain usage - Updated API client usage examples - Improved error handling documentation - Added examples for Platforms submodules - Updated installation and setup instructions Updated .gitignore: - Added .cursor/ directory - Added docs/ directory for generated documentation - Added *_REVIEW.md pattern for review files - Added swagger-spec.json and swagger.* patterns - Improved organization and comments These changes provide better guidance for SDK users and contributors, reflecting the improved architecture and new capabilities.

sonarqubecloud · 2026-03-02T14:11:35Z

Quality Gate passed

Issues
15 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

armando-rodriguez-cko added 12 commits February 10, 2026 18:03

feat: add Account Updater API client

4630b01

feat: add Identities API client

4b3b575

feat: expand Issuing API client with new submodules

968a342

feat: add Network Tokens API client

bd7d6f4

feat: add Payment Methods API client

e80db4d

feat: register new API clients in main SDK

4fada41

feat: update existing endpoint clients

ef0f574

docs: improve README with HTTP client config and base URL documentation

3b095cd

chore: update project metadata and configuration

fd088ae

chore: improve linting configuration and fix warnings

199f965

test: update payment setups tests

5460335

fix: propagate error body for 401/403/404

8d5623d

armando-rodriguez-cko requested a review from a team February 10, 2026 17:21

armando-rodriguez-cko added 2 commits February 10, 2026 19:30

david-ruiz-cko reviewed Feb 11, 2026

View reviewed changes

src/api/identities/aml-screenings.js Outdated Show resolved Hide resolved

david-ruiz-cko requested changes Feb 11, 2026

View reviewed changes

armando-rodriguez-cko marked this pull request as draft February 11, 2026 10:15

armando-rodriguez-cko added 6 commits March 2, 2026 15:02

armando-rodriguez-cko requested a review from david-ruiz-cko March 2, 2026 14:06

armando-rodriguez-cko marked this pull request as ready for review March 2, 2026 14:06

david-ruiz-cko approved these changes Mar 2, 2026

View reviewed changes

armando-rodriguez-cko merged commit 1c187d5 into master Mar 3, 2026
3 checks passed

armando-rodriguez-cko deleted the feature/add-new-api-clients-and-improve-docs branch March 3, 2026 10:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add new api clients and improve docs#423

feat: add new api clients and improve docs#423
armando-rodriguez-cko merged 20 commits intomasterfrom
feature/add-new-api-clients-and-improve-docs

armando-rodriguez-cko commented Feb 10, 2026 •

edited

Loading

Uh oh!

Uh oh!

david-ruiz-cko left a comment

Uh oh!

sonarqubecloud bot commented Mar 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Conversation

armando-rodriguez-cko commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add new API clients and improve project documentation

📋 Summary

✨ New Features

New API Clients Added

🔄 Updates to Existing Endpoints

📚 Documentation Improvements

README.md

New Files

TypeScript Definitions

🐛 Bug Fixes

Critical Error Handling Fix

🔧 Configuration & Metadata Improvements

package.json

LICENSE

.npmignore

jsconfig.json

eslint.config.js

🧪 Testing

🔍 Code Quality

📦 Commits Breakdown

⚠️ Breaking Changes

🎯 Migration Notes

✅ Checklist

📸 Test Results

Uh oh!

Uh oh!

david-ruiz-cko left a comment

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Mar 2, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

armando-rodriguez-cko commented Feb 10, 2026 •

edited

Loading