Install the SDK · Compense Docs

There’s one official SDK per language. All five cover all 115 operations of the gateway with the same names (adapted to each language’s conventions) and handle what every integration ends up doing by hand: authentication, Idempotency-Key on writes, retries with backoff, typed problem+json errors, pagination, deprecation warnings and webhook verification. They’re all on version 1.1.0 and target API v1 (aligned SemVer: SDK major = API major).

Requirements #

SDK	Package	Requirements	Dependencies
Python	`compense-sdk-python` (imported as `compense_gateway`)	Python 3.9+	`httpx` (sync and async client)
JavaScript / TypeScript	`@compense/sdk`	Node.js 18+ (also Deno, Bun and edge)	None: uses native `fetch`. ESM and CommonJS with types
PHP	`compense/sdk`	PHP 8.1+	Any PSR-18 client (Guzzle suggested)
.NET	`Compense.Sdk`	`net8.0` or `netstandard2.0` (.NET Framework 4.6.2+)	`System.Text.Json`, `Microsoft.Extensions.Http`
Go	`github.com/Appiasoft/compense-saas-sdk-go`	Go 1.21+ (iterators with 1.23+)	Standard library only

Installation #

Install

pip install compense-sdk-python

npm install @compense/sdk
# or: pnpm add @compense/sdk · yarn add @compense/sdk

composer require compense/sdk guzzlehttp/guzzle
# any PSR-18 client works, e.g.: composer require compense/sdk symfony/http-client nyholm/psr7

dotnet add package Compense.Sdk --version 1.1.0

go get github.com/Appiasoft/compense-saas-sdk-go@v1.1.0

# Nothing to install: any HTTP client works.
curl --version

Your package manager can't find the SDK?

The SDKs aren’t on the public registries (PyPI, npm, Packagist, NuGet) yet: they’re distributed as releases of their private GitHub repositories. During onboarding Compense gives your team read access, and you download the package from each repo’s v1.1.0 release (compense-saas-sdk-python, -js, -php, -dotnet, -go in the Appiasoft organization). It installs the same way: pip install ./compense_sdk_python-1.1.0-py3-none-any.whl, npm install ./compense-sdk-1.1.0.tgz, dotnet add package Compense.Sdk --source ./artifacts, a vcs repository (or path with the zip) in composer.json, and for Go set GOPRIVATE=github.com/Appiasoft/* before go get. Each release has the exact instructions.

Create the client #

Create one client per key and reuse it: they’re all safe for concurrent use and keep a connection pool.

import os
from compense_gateway import CompenseClient, AsyncCompenseClient

client = CompenseClient(api_key=os.environ["COMPENSE_API_KEY"], environment="sandbox")

# Same surface, everything awaitable (FastAPI, aiohttp…):
async_client = AsyncCompenseClient(api_key=os.environ["COMPENSE_API_KEY"], environment="sandbox")

import { CompenseClient } from "@compense/sdk";            // ESM / TypeScript
// const { CompenseClient } = require("@compense/sdk");    // CommonJS

const client = new CompenseClient({ apiKey: process.env.COMPENSE_API_KEY!, environment: "sandbox" });

<?php
require __DIR__ . '/vendor/autoload.php';

use Compense\Sdk\CompenseClient;

$client = new CompenseClient(apiKey: getenv('COMPENSE_API_KEY'), environment: 'sandbox');

using Compense.Sdk;

// Console app or service without DI:
using var client = new CompenseClient(
    Environment.GetEnvironmentVariable("COMPENSE_API_KEY")!, CompenseEnvironment.Sandbox);

// ASP.NET Core: typed client with IHttpClientFactory, configured from appsettings/environment variables
// (Compense__ApiKey, Compense__Environment, Compense__Timeout, Compense__Retry__MaxAttempts…)
builder.Services.AddCompense(builder.Configuration.GetSection("Compense"));

import compense "github.com/Appiasoft/compense-saas-sdk-go"

client, err := compense.NewClient(os.Getenv("COMPENSE_API_KEY"),
	compense.WithEnvironment(compense.Sandbox))
if err != nil {
	log.Fatal(err) // *compense.ConfigError: empty key, unknown environment or invalid URL
}

export COMPENSE_BASE_URL="https://sandbox.dev.compense.co/gw"
curl "$COMPENSE_BASE_URL/v1/gateway/health/" -H "X-API-Key: $COMPENSE_API_KEY"

Client options #

The same knobs exist in all five SDKs:

Option	Python	JavaScript / TS	PHP	.NET	Go
Environment	`environment=`	`environment`	`environment:`	`CompenseEnvironment` / `Environment`	`WithEnvironment`
Custom base URL (overrides the environment)	`base_url=`	`baseUrl`	`baseUrl:`	`BaseUrl`	`WithBaseURL`
Per-attempt timeout	`timeout=` (s)	`timeout` (ms)	`timeout:` (s)	`Timeout` (`TimeSpan`)	`WithTimeout`
Retries	`retry=RetryConfig(...)`	`retry: {...}`	`retry: new RetryConfig(...)`	`Retry = new RetryOptions {...}`	`WithRetry(RetryConfig{...})`
Retry writes	`RetryConfig(retry_writes=True)`	`retryWrites: true`	`RetryConfig(retryWrites: true)`	`RetryWrites = true`	`WithRetryWrites(true)`
Custom HTTP client	`http_client=` / `transport=` (httpx)	`fetch`	`httpClient:` (PSR-18)	`new CompenseClient(httpClient, options)`	`WithHTTPClient`
Deprecation warnings	`compense_gateway` logger	`logger`	`logger:` (PSR-3)	`ILogger` (`Compense.Sdk`)	`WithLogger` (`slog`)

Example with everything configured:

from compense_gateway import CompenseClient, RetryConfig

client = CompenseClient(
    api_key=os.environ["COMPENSE_API_KEY"],
    environment="sandbox",
    timeout=30.0,
    retry=RetryConfig(max_attempts=5, backoff_base=0.5, backoff_max=30.0, jitter=True),
)

const client = new CompenseClient({
  apiKey: process.env.COMPENSE_API_KEY!,
  environment: "sandbox",
  timeout: 30_000,
  retry: { maxAttempts: 5, backoffBaseMs: 500, backoffMaxMs: 30_000, jitter: true, retryWrites: false },
  logger: console,
});

use Compense\Sdk\CompenseClient;
use Compense\Sdk\RetryConfig;

$client = new CompenseClient(
    apiKey: getenv('COMPENSE_API_KEY'),
    environment: 'sandbox',
    timeout: 30.0,
    retry: new RetryConfig(maxAttempts: 5, backoffBase: 0.5, backoffMax: 30.0, jitter: true),
);

var client = new CompenseClient(new CompenseClientOptions
{
    ApiKey = Environment.GetEnvironmentVariable("COMPENSE_API_KEY")!,
    Environment = CompenseEnvironment.Sandbox,
    Timeout = TimeSpan.FromSeconds(30),
    Retry = new RetryOptions
    {
        MaxAttempts = 5, BackoffBase = TimeSpan.FromSeconds(0.5),
        BackoffMax = TimeSpan.FromSeconds(30), Jitter = true,
    },
});

client, err := compense.NewClient(os.Getenv("COMPENSE_API_KEY"),
	compense.WithEnvironment(compense.Sandbox),
	compense.WithTimeout(30*time.Second),
	compense.WithRetry(compense.RetryConfig{MaxAttempts: 5}),
	compense.WithUserAgent("horizonte-erp/2.0"),
)

# With plain HTTP, timeouts and retries are up to you:
curl --max-time 30 --retry 3 --retry-all-errors "$COMPENSE_BASE_URL/v1/gateway/health/" \
  -H "X-API-Key: $COMPENSE_API_KEY"
# Careful! --retry is only safe on reads or on writes with the same Idempotency-Key.

Each option is covered in detail in Retries and backoff and on each SDK’s page. Next step: your first call.