Metadata-Version: 2.4
Name: allowance
Version: 0.1.0
Summary: CLI for Allowance approval and purchase workflows
Project-URL: Homepage, https://github.com/dasmer/allowance-cli
Project-URL: Repository, https://github.com/dasmer/allowance-cli
Project-URL: Issues, https://github.com/dasmer/allowance-cli/issues
Author: Allowance
License: MIT License
        
        Copyright (c) 2026 Allowance
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,allowance,cli,payments
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25.6.0
Requires-Dist: typer>=0.12.5
Description-Content-Type: text/markdown

# allowance

`allowance` is a human-first CLI for Allowance purchase workflows.

It uses an `ak_...` connection token at runtime and stores credentials in the OS keychain.
Runtime actions are token-scoped, so requests/allowances are visible to the token session that created them.

## Install

```bash
pipx install .
```

After publishing to PyPI:

```bash
pipx install allowance
```

Local development:

```bash
uv sync --dev
uv run allowance --help
```

## Publish to PyPI

This repo supports release publishing through GitHub Actions.

### One-time setup

1. Create a PyPI account for the maintainer/org.
2. Create a project-scoped API token in PyPI.
3. Add the token as a GitHub repository secret:
   - name: `PYPI_API_TOKEN`
   - value: `pypi-...`

### Release flow

1. Bump `version` in `pyproject.toml`.
2. Commit and push `main`.
3. Tag and push a version tag:

```bash
git tag v0.1.1
git push origin v0.1.1
```

4. GitHub Action `.github/workflows/publish-pypi.yml` runs:
   - lint/type/test
   - build wheels/sdist
   - publish to PyPI

After workflow success, users can install with:

```bash
pipx install allowance
```

## Fast Purchase Path (Recommended)

Use this flow for fastest agent and customer experience:

1. Authenticate once for the session.
2. Create a request with clear merchant + reason + cap amount.
3. Ask customer to approve immediately in app.
4. Poll until approved.
5. Issue card only when checkout is ready.
6. Complete checkout.
7. Report purchase outcome immediately (`success` or `failed`).
8. If failed and still active, re-issue and retry within policy limits.

Example:

```bash
allowance auth login --email you@example.com
allowance requests create --cents 5000 --merchant "Ticketmaster" --reason "2 tickets under $50"
allowance requests poll <request_id>
allowance cards issue <allowance_id> --expected-cents 4500
allowance cards report <allowance_id> <attempt_id> --status success --charged-cents 4380
```

## Auth

Login bootstraps via OTP, then mints and stores a connection token:

```bash
allowance auth login --email you@example.com
```

If already logged in, login exits with:

`Already logged in as <email>. Run allowance auth logout to switch accounts.`

Status command:

```bash
allowance auth status
```

Logout command (revokes remote token and clears keychain):

```bash
allowance auth logout
```

## Command Reference

All commands output JSON by default. Use `--pretty` for formatted JSON.

| Command | What It Does | Use When |
|---|---|---|
| `allowance auth login --email <email>` | Signs in via OTP bootstrap and stores token in keychain | Starting a session |
| `allowance auth status` | Shows whether CLI is logged in and which account/token prefix | Preflight checks |
| `allowance auth logout` | Revokes token and clears local credentials | End of session/security cleanup |
| `allowance requests create --cents ... --merchant ... --reason ... [--currency] [--expires-at]` | Creates a pending allowance request | You need user approval before spending |
| `allowance requests list` | Lists requests created by this token session | Find recent request IDs |
| `allowance requests get <request_id>` | Fetches full request detail | Inspect request state/details |
| `allowance requests poll <request_id>` | Returns current request status and `allowance_id` when approved | Waiting on user approval |
| `allowance requests cancel <request_id>` | Cancels a still-pending request | User changed mind / no longer needed |
| `allowance cards issue <allowance_id> --expected-cents <int>` | Issues checkout card for one purchase attempt | Approval exists and checkout is ready |
| `allowance cards attempts <allowance_id>` | Lists purchase attempts for that allowance | Audit/retry decisions |
| `allowance cards report <allowance_id> <attempt_id> --status success\\|failed ...` | Finalizes attempt result and updates allowance state | Immediately after checkout attempt |
| `allowance allowances list` | Lists allowances visible to current token | Find/manage active allowances |
| `allowance allowances get <allowance_id>` | Gets one allowance snapshot | Verify state/retry budget |
| `allowance allowances pause <allowance_id>` | Pauses spending on allowance | Temporary stop needed |
| `allowance allowances revoke <allowance_id>` | Permanently revokes allowance | Final stop / cleanup |

`allowance allowances unpause` is intentionally not exposed in this CLI.

## Agent + Customer Experience Guidelines

1. Request only when purchase intent and budget are clear.
2. Use merchant/reason text the customer can quickly recognize in approval UI.
3. After `requests create`, immediately provide request summary and ask customer to approve.
4. Poll with short intervals, but keep customer informed instead of silently looping.
5. Issue card only at the final checkout step to reduce stale credential windows.
6. Always call `cards report` right after checkout outcome.
7. Never echo PAN/CVV unless customer explicitly asks.

## Error Handling

| Status | Meaning | Typical Action |
|---|---|---|
| `401` | Auth invalid/expired | Re-login |
| `403` | Not allowed for this actor | Use correct actor/flow |
| `404` | Not found or out-of-scope token access | Verify IDs and token session |
| `409` | State conflict (not active, retry exhausted, etc.) | Inspect current resource state and adjust |
| `503` | Upstream issuer/provider unavailable | Retry later or fail gracefully |

## Global Flags

- `--api-base-url` to target another environment for one invocation
- `--pretty` for formatted JSON output

Example:

```bash
allowance --api-base-url http://127.0.0.1:8000 --pretty allowances list
```

## Configuration

- `ALLOWANCE_API_BASE_URL` (default: `https://allowance-api.fly.dev`)
- `ALLOWANCE_HTTP_TIMEOUT_SECONDS` (default: `20`)
- `ALLOWANCE_CLI_KEYCHAIN_SERVICE` (optional keychain namespace override)
- `ALLOWANCE_CLI_KEYCHAIN_ACCOUNT` (optional keychain account override)

## Tests

```bash
./scripts/test_unit.sh
./scripts/test_smoke.sh
./scripts/test_all.sh
```
