Use the HTTP/API and PostgreSQL packages

A package provides reusable protocols and contracts. Your program selects the business operations; your application configures connections, secrets and grants.

Install in a project

From your project directory, add the archives obtained from the package publisher:

touba package add ./touba.http-api-1.0.0.tar.gz
touba package add ./touba.sql-effects-1.0.0.tar.gz
touba package check

Touba verifies the files and records their digests. Dependencies live in packages/. For a registry, use the command on the package page and the operator's trust configuration.

Package	Contents	Application configuration
touba.http-api	Read tool, Response type, JavaScript/Python clients	Allowed HTTP origin, tool binding, network grant
touba.sql-effects	WriteReceipt type, JavaScript/Python transaction and effect ledger	PostgreSQL driver, connection, tables, business tool and effect contract

Read an API

In a handler at the project root:

import { createHttpClient } from './packages/touba.http-api/javascript/client.mjs';

const api = createHttpClient({ baseUrl: 'https://api.example.com' });
const response = await api.request('/catalog');

Python equivalent, after installing the helper in the project environment:

uv pip install ./packages/touba.http-api/python

from touba_http_api import create_http_client

api = create_http_client(base_url="https://api.example.com")
response = api.request("/catalog")

response contains status, body and content_type. Bind this client to the imported Read tool. The model chooses a path; the host configures the origin. Responses are limited to 1 MiB and the network timeout defaults to 10 seconds. Redirects are refused; HTTP error statuses remain responses for the application to handle explicitly. This package covers GET reads.

Write to PostgreSQL

The SQL package provides applyOnce in JavaScript and apply_once in Python. Apply packages/touba.sql-effects/sql/schema.sql once with the database owner. Give the handler account the required rights on this ledger and its business tables.

Inside the JavaScript handler, connect opens a fresh pg.Client, the SDK supplies context.effect, and request holds the identifier:

import { applyOnce } from './packages/touba.sql-effects/javascript/ledger.mjs';
import { createToolResult } from '@touba/sdk';

const result = await applyOnce({
  connect, effect: context.effect, operation: 'orders.mark-reviewed',
  write: async ({ query }) => {
    await query('UPDATE orders SET reviewed = true WHERE id = $1', [request]);
    return { value: request, receipt_ref: `order:${request}` };
  },
});
return createToolResult(result.value, { effectReceipt: result.effect_receipt });

For Python, install packages/touba.sql-effects/python in the environment with uv pip install or python -m pip install, then use the same contract:

from touba_sql_effects import apply_once
from touba_sdk import create_tool_result

def write(query):
    query("UPDATE orders SET reviewed = true WHERE id = %s", (request,))
    return {"value": request, "receipt_ref": "order:" + request}

result = apply_once(connect=connect, effect=context["effect"],
                    operation="orders.mark-reviewed", write=write)
return create_tool_result(result["value"], effect_receipt=result["effect_receipt"])

connect supplies a fresh DB-API connection, for example using pg8000. Both helpers close the connection. The callback contains only SQL queries for this transaction. The host owns the connection, deadlines and secrets; the tool declares its requirements and the manifest grants the corresponding rights. The effects guide shows this binding.

Understand retries

Situation	Outcome
First confirmed call	Business write and receipt committed in one transaction
Same identity and request	Stored result; callback is not rerun
Identity reused for another request	SqlEffectConflict refusal
SQL cancellation with confirmed rollback	not_applied receipt
Connection lost during COMMIT	unknown receipt; reconcile with the same identity

Keep the ledger while calls may be retried. A compensation is a new, explicitly declared business operation: see compensations.