Metadata-Version: 2.4
Name: tooig
Version: 0.1.4
Summary: Interactive framework for tooig developer program
Project-URL: Documentation, https://developer.tooig.com/get_started
Project-URL: Issues, https://github.com/tooig/developer/issues
Project-URL: Repository, https://github.com/tooig/developer
Author-email: "Tooig, Inc" <tooighq@gmail.com>
License: MIT
Keywords: cli,developer,nineth,tooig
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: platformdirs<5,>=4.2
Requires-Dist: questionary<3,>=2.1
Requires-Dist: rich<15,>=13.9
Requires-Dist: typer<1,>=0.15
Description-Content-Type: text/markdown

# Tooig Setup CLI

`tooig` initializes a Tooig developer account and build. The Python package is
published to PyPI as `tooig`; the Node.js package is published to GitHub
Packages as `@tooig/setup`. Both clients implement the same authentication,
authorization, credential-storage, and SDK-installation flow.

## Table of contents

1. [Requirements](#requirements)
2. [Installation](#installation)
3. [Setup walkthrough](#setup-walkthrough)
4. [Authentication](#authentication)
5. [Build authorization](#build-authorization)
6. [SDK installation](#sdk-installation)
7. [Credential storage](#credential-storage)
8. [Configuration](#configuration)
9. [Developer API](#developer-api)
10. [Local database replica](#local-database-replica)
11. [Security model](#security-model)
12. [Troubleshooting](#troubleshooting)
13. [Release process](#release-process)

## Requirements

- Python 3.10 or newer for the PyPI package.
- Node.js 20 or newer for the GitHub package.
- A GitHub token with package read access when installing `@tooig/setup`.

## Installation

### PyPI

```console
python -m pip install --upgrade tooig
tooig developer
```

### GitHub Packages with npm or npx

GitHub's npm registry only accepts scoped packages. Map the `@tooig` scope to
GitHub Packages before `npm`, `npx`, or `pnpm` tries to resolve the package:

```console
npm config set @tooig:registry https://npm.pkg.github.com
npm login --scope=@tooig --auth-type=legacy --registry=https://npm.pkg.github.com
```

Use a GitHub personal access token with package read permission as the login
password. Then run the CLI directly:

```console
npx @tooig/setup developer
```

Global installation is also supported:

```console
npm install --global @tooig/setup
tooig developer
```

### GitHub Packages with pnpm

The same npm scope and authentication configuration is used by pnpm:

```console
pnpm dlx @tooig/setup developer
```

or:

```console
pnpm add --global @tooig/setup
tooig developer
```

Do not use `npx install --g`; that is not an npm installation command.

## Setup walkthrough

Run `tooig developer` or `npx @tooig/setup developer`. The CLI:

1. Prompts for the local part of `{name}@developer.tooig.com`.
2. Offers **Sign in** or **Create developer account**.
3. Reads the password without echoing it.
4. Authenticates and obtains a short-lived login token.
5. Offers signed browser authorization or entry of an existing API key.
6. Validates and stores the resulting API key.
7. Offers `nineth` or `bridge (nineth-bridge)`.
8. Installs the selected SDK using pip, npm, or pnpm.
9. Prints <https://developer.tooig.com/get_started>.

For a headless machine, prevent the browser from opening and use the printed
link on another trusted device:

```console
tooig developer --no-open
```

## Authentication

The email prompt fixes the trusted domain and accepts only the name portion:

```text
email: [name]@developer.tooig.com
```

Names are normalized to lowercase. New passwords must be at least 12
characters. Password prompts are hidden, and passwords and login tokens are
held in memory only.

The API rejects other email domains, duplicate accounts, weak passwords, and
incorrect sign-ins. Successful login returns a short-lived signed access token
and the developer profile.

## Build authorization

### Browser authorization

The CLI calls `POST /developer/authorizations`. The server stores a hash of a
signed five-minute request and returns an origin-checked URL:

```text
https://developer.tooig.com/{authorization-id}?token={signed-request}
```

After the developer approves the request, the CLI polls the same authorization
record. The resulting API key is signed by the service and remains retrievable
only until the five-minute authorization expires. The
database stores its hash, prefix, status, expiry, owner, and optional project,
but never stores the plaintext key.

### Existing API key

Select **Use an existing API key**. Input remains hidden. The CLI calls the
session endpoint and saves the key only when the service verifies its signature,
expiry, owner record, and revocation status.

## SDK installation

| CLI ecosystem | Selection | Command performed |
| --- | --- | --- |
| PyPI | `nineth` | `python -m pip install --upgrade nineth` |
| PyPI | `bridge` | `python -m pip install --upgrade nineth-bridge` |
| npm | `nineth` | `npm install nineth` |
| npm | `bridge` | `npm install nineth-bridge` |
| pnpm | `nineth` | `pnpm add nineth` |
| pnpm | `bridge` | `pnpm add nineth-bridge` |

The Node.js client detects pnpm from `npm_config_user_agent`; other Node.js
invocations use npm. Package commands are executed as argument arrays from a
fixed allowlist, never through interpolated shell text.

## Credential storage

Both clients use the same versioned JSON document:

| Platform | Default location |
| --- | --- |
| Windows | `%APPDATA%\\tooig\\credentials.json` |
| macOS | `~/Library/Application Support/tooig/credentials.json` |
| Linux | `${XDG_CONFIG_HOME:-~/.config}/tooig/credentials.json` |

The file contains the developer email, API URL, and API key. It never contains
the password or login token. Writes use a temporary file and atomic rename. On
POSIX, directories use mode `0700` and files use `0600`. The clients reject a
symlinked credential target.

## Configuration

The default API is:

```text
https://developer.tooig.com/api
```

Override it for local development:

```console
tooig developer --api-url http://localhost:8000/api
```

`TOOIG_API_URL` provides the equivalent environment setting. Non-loopback API
URLs must use HTTPS and cannot contain embedded credentials.

## Developer API

All endpoints are relative to the API base URL.

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `POST` | `/auth/signup` | Create a developer account. |
| `POST` | `/auth/login` | Return a short-lived access token. |
| `GET` | `/auth/session` | Validate a login token or developer API key. |
| `POST` | `/developer/projects` | Register a build and selected SDK. |
| `GET` | `/developer/projects` | List the developer's projects. |
| `POST` | `/developer/projects/{id}/api-keys` | Issue a project API key. |
| `DELETE` | `/developer/projects/{id}/api-keys/{key}` | Revoke a key. |
| `POST` | `/developer/authorizations` | Start signed browser authorization. |
| `POST` | `/developer/authorizations/{id}/approve` | Approve the signed request. |
| `GET` | `/developer/authorizations/{id}` | Poll authorization status. |
| `POST` | `/compute/consume` | Record idempotent compute use. |
| `GET` | `/compute/usage` | List compute usage. |
| `GET` | `/payment/transactions` | List payment ledger entries. |

Projects and API keys are always owner-scoped. Compute entries can bind both a
project and the API key that incurred the cost. Balance changes, provider
payments, and compute usage use independent reference fields for idempotency and
auditability.

## Local database replica

Tests use a SQLite replica defined by `program/utility/local_schema.sql`; they do
not connect to Supabase. It models developer accounts, projects, hashed keys,
authorizations, balances, billing settings, balance ledgers, compute usage, and
payment transactions.

The production contract remains in `program/utility/supabase/schema.sql`, with
foreign keys, indexes, update triggers, row-level security, and owner policies.
Schema validation during development parses the SQL but does not apply it to a
remote project.

## Security model

- HTTPS is mandatory except for loopback development.
- Password and secret prompts do not echo input.
- Passwords are never stored by the CLI.
- API-key plaintext is returned only at issue time; persistence uses a hash.
- Signed keys are checked for expiry and revocation on every authenticated use.
- Browser requests expire after five minutes and are bound to the developer.
- Compute and payment writes are idempotent and auditable.
- Flutterwave webhook signatures are verified before ledger mutation.
- Full card numbers and CVVs are not written to Tooig payment records.
- Installer package names are selected from a fixed allowlist.
- Credential writes are atomic and symlink-resistant.

Protect the credential file with operating-system access controls and disk
encryption. Revoke a key immediately after device or credential compromise.

## Troubleshooting

### `@tooig/setup` resolves against registry.npmjs.org

Configure the scope before using npx:

```console
npm config set @tooig:registry https://npm.pkg.github.com
```

### GitHub Packages returns 401 or 403

Run the scoped `npm login` command again with a token that is permitted to read
the package. Check package visibility and organization access when single sign-on
is enforced.

### PowerShell blocks `npm.ps1`

Use `npm.cmd` or `npx.cmd` in a restricted PowerShell session, or use an
execution policy approved by your organization.

### Browser authorization cannot open a window

Run with `--no-open`, then open the displayed URL on a trusted device. The CLI
continues polling until approval or expiry.

## Release process

The first recognized dispatch token controls the release:

| Dispatch | Version bump | Repository release | SDK package publish |
| --- | --- | --- | --- |
| `build:` | Major | Yes | No |
| `feat:` | Minor | Yes | No |
| `chore:` | Patch | Yes | No |
| `build(sdk):` | Major | Yes | PyPI and GitHub Packages |
| `feat(sdk):` | Minor | Yes | PyPI and GitHub Packages |
| `chore(sdk):` | Patch | Yes | PyPI and GitHub Packages |

An SDK release keeps the Python and Node.js package versions equal. Repository
tags use `vX.Y.Z`; package tags use `tooig-vX.Y.Z`.

GitHub Actions publishes `@tooig/setup` to `https://npm.pkg.github.com` with the
workflow `GITHUB_TOKEN` and `packages: write`. PyPI uses Trusted Publishing with
`id-token: write`; no npmjs token is used.

Release notes are date-based:

- Repository: `.github/release_notes/build-{mm-dd-yyyy}.md`
- SDK: `.github/release_notes/tooig/build-{mm-dd-yyyy}.md`

The workflow resolves the Lagos calendar date and fails before publishing if the
required note is missing. Multiple same-day releases update that day's file.
