SDK
Official SDKs
The five official API Gateway SDKs (Python, JavaScript/TypeScript, PHP, .NET and Go): what they have in common, how to choose and how they differ.
On this page
Compense maintains one official SDK per language. All five are at version 1.1.0, cover the
115 operations in the v1 contract and share the same rules, verified with parity tests against the
pinned contract (gateway develop 9cf78da): the same verb, route and idempotency per operation, and
—in JS, PHP, .NET and Go— the exact same body the Python SDK sends.
compense-sdk-python
Python
The reference SDK. Sync and async client (httpx) and the
compense CLI.
@compense/sdk
JavaScript / TypeScript
Node 18+, Deno, Bun and edge. Zero dependencies, ESM and CommonJS, with types and a CLI.
compense/sdk
PHP
PHP 8.1+, any PSR-18 client, named arguments; ready for Laravel and Symfony.
Compense.Sdk
.NET
net8.0 and netstandard2.0, fully async, IHttpClientFactory and ASP.NET Core configuration.
compense-saas-sdk-go
Go
Go 1.21+, standard library only, context on every call and iterators.What they all do #
| Capability | Details |
|---|---|
| Authentication | X-API-Key header on every call; production, sandbox and dev environments, or your own base URL. |
| Idempotency | Idempotency-Key on every keyed write: yours or a generated UUIDv4. |
| Retries | 429/502/503/504 with exponential backoff, jitter and Retry-After; writes only with retryWrites. |
| Errors | Typed exceptions per code carrying the RFC 9457 Problem and its trace_id. |
| Amounts | Exact decimal text (MoneyCOP) from integers, decimals or text. |
| Pagination | Iterable Page and OffsetPage, with automatic traversal in JS, .NET and Go. |
| Deprecations | One warning per operation when the gateway sends Deprecation/Sunset. |
| Webhooks | Stateless HMAC-SHA256 verification, with multiple secrets (rotation), time tolerance and test-event detection; a catalog of 52 events. |
| Parity | Tests that fail if a contract operation isn’t covered or differs in verb, route or idempotency. |
What things are called in each one #
Names follow the contract’s operationIds, grouped by module, in each language’s convention. The
API reference shows the exact method for each operation in all five.
| Operation | Python | JavaScript / TS | PHP | .NET | Go |
|---|---|---|---|---|---|
payBill | client.wallet.bills.pay(...) | client.wallet.bills.pay({...}) | $client->wallet->bills->pay(...) | client.Wallet.Bills.PayAsync(...) | client.Wallet.Bills.Pay(ctx, &BillPayParams{...}) |
registerLoanPayment | client.loans.register_payment(...) | client.loans.registerPayment(id, {...}) | $client->loans->registerPayment(...) | client.Loans.RegisterPaymentAsync(...) | client.Loans.RegisterPayment(ctx, id, &LoanPaymentParams{...}) |
sendWebhookTestEvent | client.webhooks.endpoints.send_test(...) | client.webhooks.endpoints.sendTest(...) | $client->webhooks->endpoints->sendTest(...) | client.Webhooks.Endpoints.SendTestAsync(...) | client.Webhooks.Endpoints.SendTest(ctx, ...) |
| Verify a webhook | verify_webhook(body, headers, secret) | verifyWebhook(body, headers, secret) | Webhook::verify($body, $headers, $secret) | CompenseWebhooks.Verify(body, headers, secret) | webhook.Verify(body, header, secrets) |
| Convention | Python | JavaScript / TS | PHP | .NET | Go |
|---|---|---|---|---|---|
| Names | snake_case | camelCase | camelCase | PascalCase + Async | PascalCase |
| Parameters | named arguments | options object | named arguments (PHP 8) | named/optional parameters | *Params struct (or nil) + ...CallOption |
| Async | CompenseClient and AsyncCompenseClient | everything is a Promise | synchronous | everything is a Task with CancellationToken | synchronous with context.Context |
| Free-form fields | extra= / **fields | extra / fields | extra: / extra named arguments | IReadOnlyDictionary<string, object?> | Extra / Fields map[string]any |
compense CLI | yes | yes (npx compense) | no | no | no |
How to choose #
- Use the SDK for your system’s language. They all have the same coverage; there are no exclusive features except the CLI (Python and JS) and Python’s explicit async client.
- No SDK for your language? The contract is OpenAPI 3.1: call it over HTTP following the reference and apply the rules in Concepts (idempotency, retries and webhook verification are the ones people forget most).
- Several languages in your entity (organization)? Mixing them is safe: they speak the same contract and verify webhook signatures identically (the tests use vectors generated by the Python SDK).
Source code #
The repositories are private Appiasoft repositories; Compense grants read access during onboarding. Each one includes its README (in English), a Spanish guide per module and runnable examples.
| SDK | Repository | Spanish guides | Examples |
|---|---|---|---|
| Python | Appiasoft/compense-saas-sdk-python | Docs/features/ | README |
| JavaScript / TS | Appiasoft/compense-saas-sdk-js | docs/ | examples/ |
| PHP | Appiasoft/compense-saas-sdk-php | docs/ | examples/ |
| .NET | Appiasoft/compense-saas-sdk-dotnet | docs/modulos/ | examples/ |
| Go | Appiasoft/compense-saas-sdk-go | docs/ | examples/ |