tooig 0.1.4

Interactive framework for tooig developer program

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
2. Installation
3. Setup walkthrough
4. Authentication
5. Build authorization
6. SDK installation
7. Credential storage
8. Configuration
9. Developer API
10. Local database replica
11. Security model
12. Troubleshooting
13. 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

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:

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:

npx @tooig/setup developer

Global installation is also supported:

npm install --global @tooig/setup
tooig developer

GitHub Packages with pnpm

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

pnpm dlx @tooig/setup developer

or:

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:

tooig developer --no-open

Authentication

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

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:

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:

https://developer.tooig.com/api

Override it for local development:

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:

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.