### Setup Python Development Environment

Source: https://github.com/zonastery/bursar/blob/main/CONTRIBUTING.md

Commands to clone the repository and install dependencies using uv.

```bash
git clone https://github.com/Zonastery/bursar.git
cd bursar/python
uv sync                       # runtime deps
uv sync --extra test          # ruff, pyright, pytest, testcontainers
# or, for the full dev group (notebooks, psycopg2, etc.):
uv sync --group dev
```

--------------------------------

### Setup JavaScript Development Environment

Source: https://github.com/zonastery/bursar/blob/main/CONTRIBUTING.md

Command to install dependencies for the JavaScript SDK using Bun.

```bash
cd bursar/javascript
bun ci                        # Bun 1.3.14; installs the committed bun.lock
```

--------------------------------

### Install project dependencies

Source: https://github.com/zonastery/bursar/blob/main/docs/README.md

Initializes the development environment by installing Python and Node.js dependencies across the repository directories.

```bash
cd python
uv sync --group dev
uv pip install --python .venv sphinx sphinx-markdown-builder
source .venv/bin/activate
cd ../javascript
bun ci
cd ../docs
npm ci
```

--------------------------------

### Install Python package and run migrations

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/quickstart.mdx

Installs the Bursar Python package with PostgreSQL support and initializes the database schema.

```bash
python -m pip install "bursar[postgres]"
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/bursar"
bursar migrate
```

--------------------------------

### Install and Migrate Bursar

Source: https://github.com/zonastery/bursar/blob/main/README.md

Install the package and apply the database migrations using the CLI.

```bash
pip install bursar[postgres]
export DATABASE_URL=postgresql://...
bursar migrate
```

--------------------------------

### Run Database Migrations

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/javascript-api/index.mdx

Install the Python CLI and execute migrations using the DATABASE_URL environment variable.

```bash
pip install "bursar[postgres]"
DATABASE_URL=postgres://... bursar migrate
```

--------------------------------

### Start Docusaurus development server

Source: https://github.com/zonastery/bursar/blob/main/docs/README.md

Launches the local development server, which automatically triggers the prestart hook to regenerate API and notebook artifacts.

```bash
npm start
```

--------------------------------

### Run Python Integration Tests with Docker

Source: https://github.com/zonastery/bursar/blob/main/CONTRIBUTING.md

Commands to start a PostgreSQL container and run tests against it.

```bash
docker run -d --name bursar-pg -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=bursar -p 5432:5432 \
  public.ecr.aws/supabase/postgres:17.6.1.156
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/bursar uv run pytest
```

--------------------------------

### Install Bursar Google ADK plugin

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/guides/google-adk.mdx

Install the Bursar package with the required Google ADK and Postgres extras.

```bash
pip install "bursar[google-adk,postgres]"
```

--------------------------------

### Initialize credit lifecycle environment

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/04_credit_lifecycle.ipynb

Sets up a temporary PostgreSQL store, publishes pricing configuration, and initializes a user account with a pro plan.

```python
from decimal import Decimal

from bursar.metrics import UsageMetrics
from shared import cleanup, base_config, publish_config, start_postgres_store, USER_ADA


def completion(output=Decimal(500)):
    return UsageMetrics(
        operation="completion",
        measures={
            "input_tokens": Decimal(1000),
            "output_tokens": output,
            "cache_read_tokens": Decimal(200),
        },
        dimensions={"model": "gpt-4o"},
    )


def execution(jobs=Decimal(1)):
    return UsageMetrics(
        operation="execution",
        measures={"jobs": jobs, "compute_seconds": Decimal(30)},
        dimensions={"model": "gpt-4o"},
    )


store, pgdata = start_postgres_store()
bursar = publish_config(store, base_config())
bursar.accounts.on_account_created(USER_ADA, "signup")
bursar.credits.set_user_plan(USER_ADA, "pro")
print("temporary postgres:", pgdata)
```

--------------------------------

### Bootstrap a tenant with configuration

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/13_cli_and_deployment.ipynb

Provisions a tenant and applies an initial configuration in one step. The configuration file is validated before the tenant is created.

```bash
bursar tenant bootstrap promo pricing.prod.yaml --label "initial: standard rate card"
# -> Tenant 3f6a2b7e-8c1d-4e9a-9f2b-7c0d5e1a3b4c bootstrapped successfully (config applied).
```

--------------------------------

### Install Bursar with Postgres support

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/python-api/index.mdx

Install the package with the required Postgres backend dependencies.

```bash
pip install "bursar[postgres]"
```

--------------------------------

### Install Bursar SDK

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/javascript-api/index.mdx

Install the package via npm. Requires Node.js 22 or newer.

```bash
npm install @zonastery/bursar
```

--------------------------------

### Initialize Bursar environment and create account

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/05_plans_and_allowances.ipynb

Sets up a temporary Postgres store and initializes the Bursar configuration, creating a user account on the default free plan.

```python
from decimal import Decimal

from bursar.metrics import UsageMetrics
from shared import cleanup, base_config, publish_config, start_postgres_store, USER_ADA


def completion(output=Decimal(500)):
    return UsageMetrics(
        operation="completion",
        measures={
            "input_tokens": Decimal(1000),
            "output_tokens": output,
            "cache_read_tokens": Decimal(200),
        },
        dimensions={"model": "gpt-4o"},
    )


def execution(jobs=Decimal(1)):
    return UsageMetrics(
        operation="execution",
        measures={"jobs": jobs, "compute_seconds": Decimal(30)},
        dimensions={"model": "gpt-4o"},
    )


store, pgdata = start_postgres_store()
bursar = publish_config(store, base_config())
bursar.accounts.on_account_created(USER_ADA, "signup")
print("created on plan:", bursar.credits.get_user_plan(USER_ADA).plan_key)
```

--------------------------------

### PricingEngine.fromDict

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/javascript-api/pricing-engine.mdx

Initializes a new PricingEngine instance from a canonical configuration dictionary.

```APIDOC
## PricingEngine.fromDict

### Description
Creates a new PricingEngine instance. Validates the configuration document and throws ConfigError if invalid fields or references are detected.

### Signature
`PricingEngine.fromDict(configDict: object): PricingEngine`

### Parameters
- **configDict** (object) - Required - A canonical configuration document.
```

--------------------------------

### Create a tenant

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/quickstart.mdx

Initializes a new tenant and sets the environment variable for the tenant ID.

```bash
bursar tenant create acme --display-name "Acme"
export BURSAR_TENANT_ID="018f7f5f-7b4a-7000-8000-000000000001"
```

--------------------------------

### PricingEngine.from_dict

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/python-api/pricing-engine.mdx

Initializes a new PricingEngine instance from a canonical configuration dictionary.

```APIDOC
## PricingEngine.from_dict(config_dict)

### Description
Creates a new PricingEngine instance. Validates the configuration document and raises ConfigError if invalid fields, measures, or dimensions are detected.

### Parameters
- **config_dict** (dict) - Required - A canonical configuration document.

### Example
```python
from bursar import PricingEngine
engine = PricingEngine.from_dict(config_dict)
```
```

--------------------------------

### Build the PricingEngine from a configuration

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/02_pricing_engine.ipynb

Constructs a stateless PricingEngine instance using a validated configuration dictionary.

```python
from decimal import Decimal

from bursar.engine import PricingEngine
from bursar.metrics import UsageMetrics
from shared import base_config

engine = PricingEngine.from_dict(base_config())
print("engine built from canonical config")
```

--------------------------------

### Install and Update Bursar Skill

Source: https://github.com/zonastery/bursar/blob/main/skills/README.md

Commands to manage the Bursar skill installation at project or global levels, and to update existing project-scoped skills.

```bash
npx skills add zonastery/bursar@bursar
```

```bash
npx skills add zonastery/bursar@bursar --global
```

```bash
npx skills update --project
```

--------------------------------

### Percentile Function Usage

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/concepts/expressions.mdx

Examples of calculating percentiles using linear interpolation.

```text
percentile(50, input_tokens, output_tokens, tool_calls)  # median of 3 values
percentile(0, a, b, c)                                    # min
percentile(100, a, b, c)                                  # max
```

--------------------------------

### Bootstrap tenant pricing

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/guides/multitenancy.mdx

Provision a tenant while simultaneously publishing initial pricing from a configuration file.

```bash
export BURSAR_TENANT_ID=018f7f5f-7b4a-7000-8000-000000000001
bursar tenant bootstrap acme ./pricing.yaml \
  --display-name "Acme"
```

--------------------------------

### Update project-scoped skills

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/agent-skills.mdx

Update skills installed at the project level after a new Bursar release.

```bash
npx skills update --project
```

--------------------------------

### Initialize Bursar sandbox environment

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/06_quotas_and_spend_caps.ipynb

Sets up a temporary Postgres store and configures a user with a pro plan and initial credits.

```python
from decimal import Decimal

from bursar.metrics import UsageMetrics
from shared import cleanup, base_config, publish_config, start_postgres_store, USER_ADA


def completion(output=Decimal(500)):
    return UsageMetrics(
        operation="completion",
        measures={
            "input_tokens": Decimal(1000),
            "output_tokens": output,
            "cache_read_tokens": Decimal(200),
        },
        dimensions={"model": "gpt-4o"},
    )


store, pgdata = start_postgres_store()
bursar = publish_config(store, base_config())
bursar.accounts.on_account_created(USER_ADA, "signup")
bursar.credits.set_user_plan(USER_ADA, "pro")
bursar.credits.add_credits(USER_ADA, Decimal("200.00"), entry_type="purchase", idempotency_key="topup")
print("ready")
```

--------------------------------

### Create a Tenant

Source: https://github.com/zonastery/bursar/blob/main/README.md

Initialize a new tenant using the Bursar CLI.

```bash
bursar tenant create acme --id 018f7f5f-7b4a-7000-8000-000000000001
```

--------------------------------

### Initialize Bursar environment

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/07_credit_tiers_and_expiry.ipynb

Sets up the Postgres store and initializes the user account with a pro plan and initial purchased credits.

```python
from decimal import Decimal
from datetime import UTC, datetime, timedelta
from time import sleep

from bursar.metrics import UsageMetrics
from shared import cleanup, base_config, publish_config, start_postgres_store, USER_ADA


def completion(output=Decimal(500)):
    return UsageMetrics(
        operation="completion",
        measures={
            "input_tokens": Decimal(1000),
            "output_tokens": output,
            "cache_read_tokens": Decimal(200),
        },
        dimensions={"model": "gpt-4o"},
    )


store, pgdata = start_postgres_store()
bursar = publish_config(store, base_config())
bursar.accounts.on_account_created(USER_ADA, "signup")
bursar.credits.set_user_plan(USER_ADA, "pro")
bursar.credits.add_credits(USER_ADA, Decimal("100.00"), entry_type="purchase", idempotency_key="buy")
print("ready")
```

--------------------------------

### Install Bursar skill via CLI

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/agent-skills.mdx

Use the Skills CLI to add the Bursar skill to your project or globally.

```bash
npx skills add zonastery/bursar@bursar
```

```bash
npx skills add zonastery/bursar@bursar --global
```

--------------------------------

### Initialize Bursar environment for lease testing

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/08_leases_and_financial_safety.ipynb

Sets up a temporary Postgres store and configures a user with credits to prepare for lease operations.

```python
from decimal import Decimal
from time import sleep

from bursar.metrics import UsageMetrics
from shared import cleanup, base_config, publish_config, start_postgres_store, USER_ADA


def execution(jobs=Decimal(1)):
    return UsageMetrics(
        operation="execution",
        measures={"jobs": jobs, "compute_seconds": Decimal(30)},
        dimensions={"model": "gpt-4o"},
    )


store, pgdata = start_postgres_store()
bursar = publish_config(store, base_config())
bursar.accounts.on_account_created(USER_ADA, "signup")
bursar.credits.set_user_plan(USER_ADA, "pro")
bursar.credits.add_credits(USER_ADA, Decimal("100.00"), entry_type="purchase", idempotency_key="buy")
print("ready")
```

--------------------------------

### Tier Function Usage

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/concepts/expressions.mdx

Example of tiered pricing logic where the function returns a rate based on the first threshold met.

```text
tier(input_tokens, 10000, 5, 100000, 10, 20)
# value < 10000   → 5
# value < 100000  → 10
# otherwise       → 20 (default)
```

--------------------------------

### Example JSON validation error output

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/13_cli_and_deployment.ipynb

Shows the structured error format returned when validation fails with the --json flag.

```json
{
  "valid": false,
  "errors": [
    {
      "type": "decimal_string",
      "loc": ["pricing", "rate_cards", "standard", "operations", "completion", "rules", 0, "charge", "sum", "components", 0, "per_unit", "rate"],
      "msg": "must be a base-10 decimal string",
      "input": 0.0025
    }
  ]
}
```

--------------------------------

### Initialize PostgresStore

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/guides/storage-backends.mdx

Construct a tenant-bound PostgresStore using the database URL and tenant identifier.

```python
store = PostgresStore(database_url, tenant_id=tenant_id)
```

```ts
const store = new PostgresStore({ postgres: databaseUrl, tenantId });
```

--------------------------------

### RTK Command Usage Examples

Source: https://github.com/zonastery/bursar/blob/main/AGENTS.md

Commonly used RTK-prefixed commands for Git, file operations, testing, building, and infrastructure management.

```bash
# Git (59-80% savings)
rtk git status          rtk git diff            rtk git log

# Files & Search (60-75% savings)
rtk ls <path>           rtk read <file>         rtk grep <pattern>
rtk find <pattern>      rtk diff <file>

# Test (90-99% savings) — shows failures only
rtk pytest tests/       rtk cargo test          rtk test <cmd>

# Build & Lint (80-90% savings) — shows errors only
rtk tsc                 rtk lint                rtk cargo build
rtk prettier --check    rtk mypy                rtk ruff check

# Analysis (70-90% savings)
rtk err <cmd>           rtk log <file>          rtk json <file>
rtk summary <cmd>       rtk deps                rtk env

# GitHub (26-87% savings)
rtk gh pr view <n>      rtk gh run list         rtk gh issue list

# Infrastructure (85% savings)
rtk docker ps           rtk kubectl get         rtk docker logs <c>

# Package managers (70-90% savings)
rtk pip list            rtk pnpm install        rtk npm run <script>
```

--------------------------------

### Initialize and calculate costs with PricingEngine

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/concepts/pricing.mdx

Constructs the engine from a configuration dictionary and calculates costs based on usage metrics and a specified rate card.

```python
from bursar.engine import PricingEngine
from bursar.metrics import UsageMetrics

engine = PricingEngine.from_dict(config)          # validates the whole config
cost = engine.calculate(
    UsageMetrics(
        operation="completion",
        measures={"input_tokens": 1000, "output_tokens": 500, "cache_read_tokens": 200},
        dimensions={"model": "gpt-4o"},
    ),
    rate_card="standard",
)
```

```ts
import { PricingEngine } from "@zonastery/bursar";

const engine = PricingEngine.fromDict(config);
const cost = engine.calculate(
  {
    operation: "completion",
    measures: {
      input_tokens: 1000,
      output_tokens: 500,
      cache_read_tokens: 200,
    },
    dimensions: { model: "gpt-4o" },
  },
  { rateCard: "standard" },
);
```

--------------------------------

### Initialize the Bursar environment

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/09_teams.ipynb

Sets up a temporary Postgres store and publishes the demo configuration to obtain a Bursar facade.

```python
import atexit
from shared import start_postgres_store, cleanup, base_config, publish_config, USER_ADA, USER_ALEX, USER_JAMAL
from decimal import Decimal
from bursar.metrics import UsageMetrics

store, pgdata = start_postgres_store()
atexit.register(cleanup, pgdata)
bursar = publish_config(store, base_config())
credits = bursar.credits
print("config published")
```

--------------------------------

### Development Commands

Source: https://github.com/zonastery/bursar/blob/main/python/README.md

Commands for setting up the development environment and running tests.

```bash
cd python
uv sync --group dev        # runtime + dev/test deps
uv run pytest              # full suite; integration tests need Postgres
ruff check src/ tests/
pyright src/
```

--------------------------------

### Initialize PricingEngine from dictionary

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/python-api/pricing-engine.mdx

Constructs an engine instance from a canonical configuration dictionary. Raises ConfigError if the configuration is invalid.

```python
from bursar import PricingEngine

engine = PricingEngine.from_dict(config_dict)
```

--------------------------------

### Initialize facade without billing store

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/12_subscriptions_and_auto_recharge.ipynb

Demonstrates initializing a facade using only publish_config, which results in disabled billing and commerce capabilities.

```python
plain = publish_config(store, base_config())
print("billing:", plain.billing)
print("commerce:", plain.commerce)
print("all done")
```

--------------------------------

### Initialize CreditEventEmitter and register handlers

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/11_events.ipynb

Sets up the credit store, initializes the emitter, and registers a recording function for various credit event types.

```python
import atexit
from shared import start_postgres_store, cleanup, base_config, publish_config, USER_ADA
from decimal import Decimal
from bursar import Bursar
from bursar.credits.events import CreditEventEmitter
from bursar.credits.service_types import ReserveOptions
from bursar.metrics import UsageMetrics

store, pgdata = start_postgres_store()
atexit.register(cleanup, pgdata)
publish_config(store, base_config())

emitter = CreditEventEmitter()
seen = []

def record(event):
    seen.append((event.type, event.data or {}))
    print(event.type, "-", event.data or {})

for event_type in [
    "credits.plan_changed",
    "credits.added",
    "credits.deducted",
    "credits.deduct_failed",
    "credits.refunded",
    "credits.refund_failed",
    "credits.reserved",
    "credits.reservation_released",
    "credits.quota_threshold",
]:
    emitter.on(event_type, record)

bursar = Bursar.create(credit_store=store, emitter=emitter)
credits = bursar.credits
bursar.accounts.on_account_created(USER_ADA, "acct_ada")
print("events facade ready")
```

--------------------------------

### Initialize PostgresStore

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/javascript-api/stores.mdx

Instantiate a PostgresStore by providing the database connection details and tenant scoping.

```ts
import { PostgresStore } from "@zonastery/bursar";

const store = new PostgresStore({
  postgres: databaseUrl,
  tenantId,
  connectionTimeoutMs: 10_000,
  statementTimeoutMs: 30_000,
  onPoolError: (error) => console.error("Bursar pool error", error),
});
```

--------------------------------

### Initialize and use PricingEngine

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/javascript-api/pricing-engine.mdx

Configures a PricingEngine with a standard rate card for token-based operations and demonstrates a cost calculation.

```typescript
import Decimal from "decimal.js";

const engine = PricingEngine.fromDict({
  version: 1,
  pricing: {
    operations: {
      completion: {
        measures: {
          input_tokens: { unit: "token" },
          output_tokens: { unit: "token" },
          cache_read_tokens: { unit: "token" },
        },
        dimensions: { model: { type: "string" } },
      },
    },
    rate_cards: {
      standard: {
        operations: {
          completion: {
            rules: [
              {
                when: {
                  model: { op: "in", values: ["gpt-4o", "gpt-4o-mini"] },
                },
                charge: {
                  type: "sum",
                  components: [
                    {
                      type: "per_unit",
                      measure: "input_tokens",
                      rate: "0.0025",
                      unit_size: "1000000",
                    },
                    {
                      type: "per_unit",
                      measure: "output_tokens",
                      rate: "0.0100",
                      unit_size: "1000000",
                    },
                    {
                      type: "per_unit",
                      measure: "cache_read_tokens",
                      rate: "0.00125",
                      unit_size: "1000000",
                    },
                  ],
                },
              },
            ],
            unmatched: {
              action: "charge",
              charge: {
                type: "expression",
                formula: "input_tokens * 0.005 + output_tokens * 0.015",
              },
            },
          },
        },
      },
    },
  },
  credits: {},
});

const cost = engine.calculate({
  operation: "completion",
  measures: { input_tokens: 2_000_000, output_tokens: 500_000 },
  dimensions: { model: "gpt-4o" },
});

// Exact decimals: 2,000,000 × 0.0025/M + 500,000 × 0.0100/M = 0.01
const expected = new Decimal("0.0025")
  .times(2)
  .plus(new Decimal("0.0100").times(0.5));
if (!cost.total.equals(expected)) {
  throw new Error(`unexpected total: ${cost.total.toString()}`);
}
console.log(cost.total.toString()); // "0.01"
```

--------------------------------

### Initialize PricingEngine from dictionary

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/javascript-api/pricing-engine.mdx

Constructs a new engine instance using a canonical configuration dictionary. Throws ConfigError if the configuration is invalid.

```typescript
import { PricingEngine } from "@zonastery/bursar";

const engine = PricingEngine.fromDict(configDict);
```

--------------------------------

### Inspect Configuration Top-Level Sections

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/01_first_pricing_config.ipynb

Loads the base configuration and prints the top-level keys to verify the document structure.

```python
from shared import base_config, start_postgres_store, cleanup, publish_config
from bursar.config import load_config_from_dict, ConfigError

config = base_config()
print("top-level sections:", sorted(config.keys()))
```

--------------------------------

### Initialize Bursar Postgres Store

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/00_why_bursar_and_setup.ipynb

Launches a throwaway Postgres cluster, runs migrations, and provisions a tenant for testing.

```python
# Everything in this series runs against a throwaway Postgres cluster.
# start_postgres_store() launches one, runs the bursar schema migrations,
# and provisions a tenant; the second return value is the data directory
# that must be cleaned up at the end of the notebook.
from decimal import Decimal

from shared import start_postgres_store, cleanup, base_config, publish_config, USER_ADA

store, pgdata = start_postgres_store()
print("store type:", type(store).__name__)
print("tenant id:", store.tenant_id)
```

--------------------------------

### Publish and Activate Pricing

Source: https://github.com/zonastery/bursar/blob/main/README.md

Activate the pricing configuration using the SDK facade.

```python
bursar.catalog.publish_and_activate(config)
```

```typescript
bursar.catalog.publishAndActivate(config);
```

--------------------------------

### Creating a Minimal Complete Store

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/14_custom_stores.ipynb

Shows how to dynamically generate a complete store implementation using stubs for all abstract methods, distinguishing between core contract errors and optional capability errors.

```python
# A minimal *complete* store: every abstract method is bound to a stub that
# raises NotImplementedError until this backend gains a real implementation
# (real stores replace the stubs with atomic SQL or RPC calls).
def _stub(name):
    def method(self, *args, **kwargs):
        raise NotImplementedError(f"{name}() is not implemented by MinimalStore")

    method.__name__ = name
    return method

MinimalStore = type(
    "MinimalStore",
    (CreditStore,),
    {name: _stub(name) for name in CreditStore.__abstractmethods__},
)
store = MinimalStore()

now = datetime.now(timezone.utc)

try:
    store.daily_spend(now, now)  # optional capability: default raises
except CapabilityNotSupportedError as exc:
    print("optional:", exc)

try:
    store.get_balance("user-ada")  # core contract: up to the store author
except NotImplementedError as exc:
    print("core:   ", exc)
```

--------------------------------

### Calculate execution jobs and batches

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/02_pricing_engine.ipynb

Shows how to bill for execution jobs and perform batch pricing calculations for multiple usage metrics simultaneously.

```python
execution = UsageMetrics(
    operation="execution",
    measures={"jobs": Decimal(3), "compute_seconds": Decimal(120)},
    dimensions={"model": "gpt-4o"},
)
print("3 jobs total:", engine.calculate(execution, rate_card="standard").total)

batch = engine.calculate_batch([completion, mini, execution], rate_card="standard")
print("batch totals:", [str(item.total) for item in batch])
```

--------------------------------

### PostgresStore

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/python-api/stores.mdx

Initializes a Postgres-backed credit store using psycopg2.

```APIDOC
## PostgresStore(database_url, tenant_id, max_pool_size=20, pool=None)

### Description
Connects to a Postgres database and manages credit transactions. Requires the `bursar[postgres]` extra.

### Parameters
- **database_url** (str) - Required - Postgres connection string.
- **tenant_id** (str | UUID) - Required - Scopes every transaction to one tenant.
- **max_pool_size** (int) - Optional - Upper bound of the internal ThreadedConnectionPool (default: 20).
- **pool** (ThreadedConnectionPool | None) - Optional - Reuse an existing pool instead of creating one.

### Methods
- **close()** - Drains the internal connection pool.
```

--------------------------------

### Initialize Bursar and manage credits

Source: https://github.com/zonastery/bursar/blob/main/javascript/README.md

Configure the PostgresStore and perform credit operations such as adding, deducting, and refunding credits, as well as paginating ledger entries.

```typescript
import { Bursar, PostgresStore } from "@zonastery/bursar";

const store = new PostgresStore({
  postgres: process.env.DATABASE_URL!,
  tenantId,
  connectionTimeoutMs: 10_000,
  statementTimeoutMs: 30_000,
  onPoolError: (error) => console.error("Bursar PostgreSQL pool error", error),
});
const bursar = new Bursar({ creditStore: store });

const grant = await bursar.credits.addCredits(userId, 500, {
  type: "purchase",
  idempotencyKey: "checkout:42",
});
const charge = await bursar.credits.deductCredits(userId, 20, {
  idempotencyKey: "job:42",
});
const refund = await bursar.credits.refundCredits(charge.entryId);

let page = await bursar.credits.listLedgerEntries(userId, { limit: 25 });
while (page.nextCursor) {
  page = await bursar.credits.listLedgerEntries(userId, {
    limit: 25,
    cursor: page.nextCursor,
  });
}
```

--------------------------------

### Initialize PostgresBillingStore

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/javascript-api/stores.mdx

Instantiate the PostgresBillingStore by providing the database connection string and tenant identifier.

```ts
import { PostgresBillingStore } from "@zonastery/bursar";

const billingStore = new PostgresBillingStore({
  postgres: databaseUrl,
  tenantId,
});
```

--------------------------------

### Initialize Bursar store and runtime

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/guides/multitenancy.mdx

Configure the SDK store and runtime with the required tenant ID for transaction-local isolation.

```python
from bursar import PostgresStore
from bursar.storage import BursarRuntimeOptions, create_bursar_runtime

store = PostgresStore(database_url, tenant_id=tenant_id)

runtime = create_bursar_runtime(
    BursarRuntimeOptions(
        postgres=database_url,
        tenant_id=tenant_id,
    )
)
```

```ts
import { PostgresStore } from "@zonastery/bursar";
import { createBursarRuntime } from "@zonastery/bursar/node";

const store = new PostgresStore({ postgres: databaseUrl, tenantId });

const runtime = await createBursarRuntime({
  postgres: databaseUrl,
  tenantId,
});
```

--------------------------------

### Create and Fund Account

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/quickstart.mdx

Registers a new account and adds credits using an idempotency key to ensure replay safety.

```python
from decimal import Decimal

account_id = "11111111-1111-4111-8111-111111111111"
bursar.accounts.on_account_created(
    account_id,
    event_key="signup:11111111",
)
grant = bursar.credits.add_credits(
    account_id,
    Decimal("100.000000"),
    entry_type="purchase",
    idempotency_key="purchase:quickstart:11111111",
)
print(grant.entry_id, grant.new_balance)
```

```typescript
const accountId = "11111111-1111-4111-8111-111111111111";
await bursar.accounts.onAccountCreated({
  accountId,
  eventKey: "signup:11111111",
});
const grant = await bursar.credits.addCredits(accountId, "100.000000", {
  type: "purchase",
  idempotencyKey: "purchase:quickstart:11111111",
});
console.log(grant.entryId, grant.newBalance);
```

--------------------------------

### Initialize Bursar facade

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/guides/credit-lifecycle.mdx

Configure and bind the Bursar facade using a Postgres store. Ensure the configuration is published before proceeding with credit operations.

```python
from bursar import Bursar, PostgresStore
from shared import USER_ADA, base_config, publish_config

bursar = publish_config(
    PostgresStore(database_url, tenant_id=tenant_id),
    base_config(),
)
user_id = USER_ADA
```

```ts
import { Bursar, PostgresStore } from "@zonastery/bursar";
import { USER_ADA, baseConfig, publishConfig } from "./shared";

const bursar = await publishConfig(
  new PostgresStore({ postgres: databaseUrl, tenantId }),
  baseConfig(),
);
const userId = USER_ADA;
```

--------------------------------

### Define topup offers

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/concepts/billing.mdx

Configure credit pack offers with quantity bounds and lot behavior settings.

```yaml
credits_10k:
  type: topup
  display_name: "10,000 Credits"
  price: { amount_minor: 500, currency: USD }
  providers:
    stripe: { type: stripe_price, price_id: price_credits_10k }
  credits_per_unit: "10000"
  quantity: { minimum: 1, maximum: 10, default: 1 }
  bucket: purchased
  lot_behavior: separate_lots
```

--------------------------------

### Manage configuration lifecycle

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/cli.mdx

Subcommands for validating, publishing, and listing immutable configuration versions. Requires BURSAR_TENANT_ID to be set.

```bash
bursar config validate ./pricing.yaml   # validate without applying (--json for CI)
bursar config set ./pricing.yaml         # publish + activate a new version (--label)
bursar config get                        # print the active version as JSON
bursar config list                       # list all versions (* = active)
bursar config activate 3                 # switch the active version
bursar config export 3                   # dump one version as JSON
bursar config diff 2 3                   # unified diff between two versions
bursar config schema                     # print the config JSON Schema
```

--------------------------------

### Development Commands

Source: https://github.com/zonastery/bursar/blob/main/javascript/README.md

Standard development workflow commands using Bun for dependency management, testing, and building.

```bash
cd javascript
bun ci                        # Bun 1.3.14; installs the committed bun.lock
bun run typecheck
bun run test                  # integration tests need Postgres (DATABASE_URL or testcontainer)
bun run lint
bun run build
```

--------------------------------

### Initialize PostgresBillingStore

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/python-api/stores.mdx

Initializes the billing store interface for managing commerce capabilities.

```python
from bursar import PostgresBillingStore

billing_store = PostgresBillingStore(database_url, tenant_id=tenant_id)
```

--------------------------------

### Provision and manage tenants

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/cli.mdx

Commands for creating tenants and updating their lifecycle status.

```bash
bursar tenant create acme \
  --id 018f7f5f-7b4a-7000-8000-000000000001 \
  --display-name "Acme"
```

```bash
bursar tenant status 018f7f5f-7b4a-7000-8000-000000000001 suspended
bursar tenant status 018f7f5f-7b4a-7000-8000-000000000001 active
```

```bash
export BURSAR_TENANT_ID=018f7f5f-7b4a-7000-8000-000000000001
bursar tenant bootstrap acme ./pricing.yaml \
  --display-name "Acme"
```

--------------------------------

### Configure Optional Storage Runtime

Source: https://github.com/zonastery/bursar/blob/main/python/README.md

Initialize the Bursar runtime with optional S3 and ClickHouse storage backends.

```python
from bursar.storage import BursarRuntimeOptions, create_bursar_runtime

runtime = create_bursar_runtime(
    BursarRuntimeOptions(
        postgres=os.environ["DATABASE_URL"],
        tenant_id=os.environ["BURSAR_TENANT_ID"],
    )
)
runtime.start()
bursar = runtime.bursar
```

--------------------------------

### Initialize Bursar with Dodo Provider

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/12_subscriptions_and_auto_recharge.ipynb

Configures the Bursar facade by replacing the default Stripe provider with a mock Dodo provider and setting initial commerce preferences.

```python
store, pgdata = start_postgres_store()
atexit.register(cleanup, pgdata)
config = base_config()
config["commerce"]["providers"]["dodo"] = {"type": "dodo"}
config["commerce"]["offers"]["pro_monthly"]["providers"]["dodo"] = {
    "type": "dodo_product", "product_id": "prod_pro_monthly",
}
config["commerce"]["offers"]["credits_10k"]["providers"]["dodo"] = {
    "type": "dodo_product", "product_id": "prod_credits_10k",
}
del config["commerce"]["providers"]["stripe"]
for offer in config["commerce"]["offers"].values():
    del offer["providers"]["stripe"]

publish_config(store, config, label="billing")

billing_store = PostgresBillingStore(store.database_url, tenant_id=store.tenant_id)

def mock_factory(ctx):
    return DemoMockPaymentProvider(sink=ctx.event_sink)

commerce_options = CommerceOptions(
    tenant_id=store.tenant_id,
    providers={"dodo": mock_factory},
    default_provider="dodo",
    preference_defaults={
        "auto_recharge": False,
        "overage_protection": True,
        "email_notifications": True,
        "usage_alerts": True,
        "invoice_reminders": False,
    },
)

bursar = Bursar.create(
    credit_store=store,
    billing_store=billing_store,
    commerce_options=commerce_options,
)
print("billing:", bursar.billing is not None)
print("commerce:", bursar.commerce is not None)
bursar.accounts.on_account_created(USER_ADA, "acct_ada")
```

--------------------------------

### Configure Bursar Runtime with Adapters

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/guides/storage-backends.mdx

Initialize the Bursar runtime with optional ClickHouse and S3 adapters using the composition root.

```python
from bursar.storage import BursarRuntimeOptions, BursarRuntimeStartOptions, create_bursar_runtime

runtime = create_bursar_runtime(
    BursarRuntimeOptions(
        postgres=database_url,
        tenant_id=tenant_id,
        clickhouse=clickhouse_options,
        s3=s3_options,
        outbox=outbox_options,
    )
)
runtime.start(BursarRuntimeStartOptions(load_catalog=True))
```

```ts
import { createBursarRuntime } from "@zonastery/bursar/node";

const runtime = await createBursarRuntime({
  postgres: databaseUrl,
  tenantId,
  clickhouse: clickhouseOptions,
  s3: s3Options,
  outbox: outboxOptions,
});
await runtime.start({ loadCatalog: true });
```

--------------------------------

### Run Integration Tests and Linting

Source: https://github.com/zonastery/bursar/blob/main/python/src/bursar/sql/README.md

Commands to execute integration tests and lint SQL files using sqlfluff from the package root.

```bash
gmake test-integration
uv run --with sqlfluff sqlfluff lint python/src/bursar/sql --dialect postgres
```

--------------------------------

### Manage Credits and Ledger

Source: https://github.com/zonastery/bursar/blob/main/python/README.md

Initialize the Postgres store and perform credit operations including adding, deducting, and refunding credits, as well as paginating ledger entries.

```python
from bursar import Bursar, PostgresStore

store = PostgresStore(database_url, tenant_id=tenant_id)
bursar = Bursar.create(credit_store=store)

grant = bursar.credits.add_credits(user_id, 500, entry_type="purchase", idempotency_key="checkout:42")
charge = bursar.credits.deduct_credits(user_id, 20, idempotency_key="job:42")
refund = bursar.credits.refund_credits(charge.entry_id)

page = bursar.credits.list_ledger_entries(user_id, limit=25)
while page.next_cursor is not None:
    page = bursar.credits.list_ledger_entries(user_id, limit=25, cursor=page.next_cursor)
```

--------------------------------

### Run documentation verification

Source: https://github.com/zonastery/bursar/blob/main/docs/README.md

Executes the full documentation gate to check formatting, TypeScript, and build integrity before pull requests.

```bash
npm run check
```

--------------------------------

### Manage Teams and Deduct Credits

Source: https://github.com/zonastery/bursar/blob/main/docs/docs/python-api/credit-manager.mdx

Demonstrates creating a team, adding a member, and deducting credits from a shared team pool using the facade.

```python
store.create_team(team_id, display_name="Acme")
store.add_team_member(team_id, user_id)
bursar.credits.deduct_team(
    team_id, user_id,
    UsageMetrics(operation="execution", measures={"jobs": 1}, dimensions={"model": "gpt-4o"}),
    idempotency_key="team:run:3",
)
```

--------------------------------

### Provision a new tenant

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/13_cli_and_deployment.ipynb

Creates a new tenant and returns its UUID. Use the --display-name flag to provide a human-readable name.

```bash
bursar tenant create acme --display-name "Acme Production"
# -> 3f6a2b7e-8c1d-4e9a-9f2b-7c0d5e1a3b4c
```

--------------------------------

### Compare configuration versions

Source: https://github.com/zonastery/bursar/blob/main/samples/python/notebooks/13_cli_and_deployment.ipynb

Use the diff command to view changes between two specific revisions in unified diff format.

```bash
bursar config diff 2 3
# --- v2
# +++ v3
# @@ ... @@
# -        "display_name": "Pro",
# +        "display_name": "Pro Tier",
```