feat: add new api clients and improve docs #423

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

sonarqubecloud · 2026-02-10T18:46:20Z

Quality Gate passed

Issues
2 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

david-ruiz-cko · 2026-02-11T08:36:34Z

src/api/identities/aml-screenings.js

+    async createAMLVerification(body) {
+        try {
+            const url = `${
+                this.config.host.includes('sandbox') ? IDENTITY_VERIFICATION_SANDBOX_URL : IDENTITY_VERIFICATION_LIVE_URL


Cannot be this repeated url code a constant of the class initialized only once when the client is created?.
Other clients use config variables like httpclient, all this logic seems more suitable in the config class. same for other clients like this one that have here this url condition.

david-ruiz-cko

See comment

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

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

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

Uh oh!

armando-rodriguez-cko commented Feb 10, 2026 •

edited

Loading

Uh oh!

sonarqubecloud bot commented Feb 10, 2026

Uh oh!

david-ruiz-cko Feb 11, 2026 •

edited

Loading

Uh oh!

david-ruiz-cko left a comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

feat: add new api clients and improve docs #423

Are you sure you want to change the base?

feat: add new api clients and improve docs #423

Uh oh!

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!

sonarqubecloud bot commented Feb 10, 2026

Quality Gate passed

Uh oh!

david-ruiz-cko Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

david-ruiz-cko left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

armando-rodriguez-cko commented Feb 10, 2026 •

edited

Loading

david-ruiz-cko Feb 11, 2026 •

edited

Loading