SDKs & Plugins

This section tracks SDK availability for v2 and cross-version compatibility. Package names, repositories, and maintainers below are placeholders and should be updated as SDKs are published.

SDK Roadmap (Placeholders)

Contributions & Endorsement

We welcome contributions for SDKs that are not yet implemented. If you build one and it passes the standards below, we can endorse it in the docs.

To request endorsement, open a pull request with:

1. SDK repository link.
2. README link.
3. Test summary.
4. Version compatibility notes.
5. Confirmation that all checklist items are satisfied.

SDK Documentation & Quality Standards

1. Function-Level Documentation

Each public method must include:

• Purpose
• Parameters
• Return type
• Thrown errors (if applicable)
• Usage example where helpful

Avoid line-by-line comments except when logic is non-obvious, security-sensitive, or protocol-level.

2. Error Handling Requirements

Network errors must handle:

• DNS failures
• Timeouts
• Connection drops
• Retry exhaustion

API errors must handle:

• 4xx responses
• 5xx responses
• Malformed responses
• Unexpected schema changes

All errors must include:

• error_code
• error_type
• error_message

Use typed error objects. Never throw raw errors or leak internal implementation details. Business-state failures (for example payment failed) are not exceptions unless defined by API contract.

3. Configuration Rules

• Use a single centralized configuration module.
• Configuration must be immutable after initialization.
• Expected env vars:
  • CHAPA_PRIVATE_KEY
  • CHAPA_WEBHOOK_SECRET
• Env var names must be overridable by users.

4. Type Safety

• Strict type safety is required.
• Avoid any.
• Use explicit request/response interfaces.
• Use enums for known states.
• Use discriminated unions where applicable.
• Public API must expose full type definitions.

5. Amount Handling

• Users provide amount in base currency unit.
• SDK converts internally to smallest unit.
• No floating-point precision errors.
• Use safe integer math where possible.

6. Method Design Rules

• A method must not take more than 3 arguments.
• If more than 3 are needed, use one object parameter.
• Group methods by API domain (payments, refunds, customers, webhooks).
• Keep naming consistent across modules.

7. Repository Rules

• Repository must stay private until officially approved for public release.
• Do not publish to public registries without authorization.

8. LLM & Agent Compatibility

SDKs must be agent-friendly:

• Clear method naming
• Predictable signatures
• Stable response structures
• No hidden side effects
• Deterministic outputs

Include an agent rules file describing:

• Safe usage patterns
• Expected inputs
• Known constraints
• Idempotency guidance
• Error handling patterns

9. Git Commit Standards

Use Conventional Commits:

• feat:
• fix:
• docs:
• refactor:
• test:
• chore:

Examples:

• feat(payments): add create payment method
• fix(webhooks): correct signature verification logic
• test(customers): add unit tests for create method

10. Testing Requirements

• Tests for each public method
• Success, failure, and edge cases
• Mocked network calls
• Error transformation validation
• Amount conversion validation
• Configuration override validation

11. README Requirements

Each SDK must include:

• Installation instructions
• Environment setup
• Configuration example
• Code snippets
• Error handling example
• Webhook verification example (if applicable)
• Version compatibility info
• Contribution guidelines

12. Language Best Practices

Follow language-native best practices for:

• Package structure
• Dependency management
• Error handling
• Module exports
• Naming conventions
• Testing framework
• Linting and formatting
• Build configuration

13. Final Verification Checklist

• All public methods documented
• Errors structured correctly
• Configuration centralized and immutable
• Environment variables overridable
• Amount conversion handled internally
• No method exceeds three parameters
• Logical grouping followed
• Repository private
• Agent rules file included
• Conventional commits followed
• Tests written for each public method
• README complete
• Language best practices followed
• Assignment confirmed in Confluence