tesote-sdk

Official client SDKs for the equipo.tesote.com API. One repo, seven languages, identical surface.

Language	Package	Install
TypeScript	@tesote.com/sdk	npm i @tesote.com/sdk
Python	tesote-sdk	pip install tesote-sdk
Ruby	tesote-sdk	gem install tesote-sdk
Java	com.tesote:sdk	Maven Central
PHP	tesote/sdk	composer require tesote/sdk
Go	github.com/tesote/sdk/go	go get github.com/tesote/sdk/go
C# / .NET	Tesote.Sdk	dotnet add package Tesote.Sdk

Full docs: https://www.tesote.com/docs/sdk

---

Quick start

TypeScript (@tesote.com/sdk)

import { V2Client } from '@tesote.com/sdk'

const tesote = new V2Client({ apiKey: process.env.TESOTE_API_KEY! })
const accounts = await tesote.accounts.list()

Python (tesote-sdk)

from tesote_sdk import V2Client

tesote = V2Client(api_key=os.environ["TESOTE_API_KEY"])
for account in tesote.accounts.list_all():
    print(account.id, account.balance)

Ruby (tesote-sdk)

require 'tesote_sdk'

tesote = TesoteSdk::V2::Client.new(api_key: ENV.fetch('TESOTE_API_KEY'))
tesote.accounts.list.each { |a| puts a.id }

Go (github.com/tesote/sdk/go)

import tesote "github.com/tesote/sdk/go/v2"

c := tesote.New(tesote.Config{APIKey: os.Getenv("TESOTE_API_KEY")})
accounts, _ := c.Accounts.List(ctx, nil)

PHP (tesote/sdk)

use Tesote\Sdk\V2\Client;

$tesote = new Client(['apiKey' => getenv('TESOTE_API_KEY')]);
$accounts = $tesote->accounts->list();

Java (com.tesote:sdk)

import com.tesote.sdk.v2.V2Client;

var tesote = V2Client.builder().apiKey(System.getenv("TESOTE_API_KEY")).build();
var accounts = tesote.accounts().list();

C# / .NET (Tesote.Sdk)

using Tesote.Sdk;

var tesote = new V2Client(new ClientOptions { ApiKey = Environment.GetEnvironmentVariable("TESOTE_API_KEY")! });
var accounts = await tesote.Accounts.ListAsync();

---

What you get

• Versioned clients side-by-side — V1Client, V2Client from the same import. Pick per call site, mix in one process. Old versions never get removed.
• Transport-level reliability — automatic retries with backoff + jitter, rate-limit-aware throttling, opt-in response caching, idempotency keys for mutations.
• Typed errors with full context — one class per error_code, every error carries request_id, http_status, retry_after, response_body. Catch the narrow type you care about; ignore the rest.
• Cursor pagination — list() for one page, listAll() for an iterator. Mutation-mid-iteration surfaces a typed MutationDuringPaginationError, not silent corruption.

---

API versions

Version	Adds
v1	Accounts, transactions (read-only)
v2	+ sync sessions, transaction orders, batches, payment methods, bulk + search

Both ship from every SDK. Back-compat is permanent.

---

Auth

Authorization: Bearer <api_key>

Get a key from your Tesote workspace settings. The SDK never persists it; it lives on the client instance only.

---

Errors

import { RateLimitExceededError, WorkspaceSuspendedError } from '@tesote.com/sdk'

try {
  await tesote.transactions.bulk(items)
} catch (e) {
  if (e instanceof RateLimitExceededError) {
    console.log(`retry in ${e.retryAfter}s; req ${e.requestId}`)
  } else if (e instanceof WorkspaceSuspendedError) {
    // contact support
  } else {
    throw e
  }
}

Full error taxonomy: docs/architecture/errors.md.

---

Development

This repo is a multi-language monorepo. Each language is independently testable and releasable.

Task	Command (per-language dir)
Test	bun test · pytest · bundle exec rspec · ./gradlew test · composer test · go test ./... · dotnet test
Lint	language-native (biome, ruff, rubocop, spotless, phpstan, golangci-lint, dotnet format)
Replay-record	bin/record-cassettes (per-language; needs staging key)

CI runs on Blacksmith 2vcpu runners. Releases are tag-driven per language: ts-v1.4.2, python-v0.9.0, etc. See docs/architecture/release.md.

---

Architecture

Doc	Topic
versioning.md	v1/v2 coexistence, back-compat policy
transport.md	retries, caching, rate-limits, idempotency, pagination
errors.md	typed-error taxonomy, "good error" definition
resources.md	endpoint inventory by version
auth.md	bearer token, key-type rules
testing.md	unit / replay / smoke layers, cross-language parity
release.md	Blacksmith CI + per-language tag releases

Start here: docs/architecture/README.md.

---

Contributing

Issues and PRs welcome. Read CLAUDE.md and the architecture docs first — public-API changes need to land in all seven languages in the same PR.

License

MIT.