# gizai/account

the provider accounts of one owner, in the owner's own store: the accounts a person or an operator attaches to each kind of provider (gizlang/providers: an API key, a subscription sign-in, the Giz account or the address of a server), their health, and the rotation that gives each turn to an account that can answer. A model is named PROVIDER:MODEL ("codex:gpt-6-sol"). Its turn goes to the first ready account of the provider by priority; an account the provider refuses for its limit, its plan or its sign-in rests (until the limit resets, when the provider says when) and the next one answers. A desk keeps its own accounts (owner ""); a platform keeps its own (owner "") and each team's (owner the team's id) in one table, and every read names its owner (Store). This is the only module of gizai that imports gizmodel: the engines stay free of it.

```gizlang
import * as Account from "gizai/account";
```

## Types

### `Provider`

```gizlang
type Provider = Providers.Kind
```

A kind of provider (gizlang/providers): an account names one by its id.

### `Account`

```gizlang
type Account = { @Model.Key id: string; @Model.Min(0) owner: string; provider: string; @Model.MaxLength(80) label: string; @Model.Min(0) base: string; enabled: bool; priority: i64; rest: i64; streak: i64; @Model.Min(0) reason: string; used: i64; last: i64; @Model.Min(0) usage: string; checked: i64; }
```

An account of a provider, as the page shows it: its label, another address of its API ("" the provider's: a local
server, a proxy), whether it takes turns, its priority (lower answers first), until when (ms) it rests (0: ready) and
why it rests or last failed, the turns it answered and when it last did, and the provider's limits as it last
reported them ("5h 42% · week 13%") and when they were checked. What signs it in is its Credential.

- `id`: `string`
- `owner`: `string` — Whose account it is: "" the store's own (a desk, a platform), else a team's id.
- `provider`: `string`
- `label`: `string`
- `base`: `string`
- `enabled`: `bool`
- `priority`: `i64`
- `rest`: `i64`
- `streak`: `i64` — The refusals in a row since it last answered; each doubles its rest (OpenAi.restUntil).
- `reason`: `string`
- `used`: `i64`
- `last`: `i64`
- `usage`: `string`
- `checked`: `i64`

### `Credential`

```gizlang
type Credential = { @Model.Key @Model.Hidden id: string; @Model.Hidden @Model.Read("manager") @Model.Write("manager") @Model.Min(0) key: string; @Model.Hidden @Model.Read("manager") @Model.Write("manager") @Model.Min(0) refresh: string; @Model.Hidden @Model.Read("manager") @Model.Write("manager") expires: i64; @Model.Hidden @Model.Read("manager") @Model.Write("manager") @Model.Min(0) identity: string; }
```

What signs the account of the same id in; only the server reads it, no page shows it: its API key or access token,
its refresh token, when the access token expires (ms; 0: never) and the provider's account id (ChatGPT's).

- `id`: `string`
- `key`: `string`
- `refresh`: `string`
- `expires`: `i64`
- `identity`: `string`

### `Store`

```gizlang
type Store = { db: Data.Db; owner: string; }
```

The accounts of one owner in a store: every read and write names both, so no call reaches another owner's
accounts. `db` is the caller's own view of the store (a person's, under its policy; a server's).

- `db`: `M131.Db`
- `owner`: `string`

### `Added`

```gizlang
type Added = { provider: string; label: string; key: string; base: string; }
```

An account to add with a key or an address: its provider, label ("": numbered), key and address.

- `provider`: `string`
- `label`: `string`
- `key`: `string`
- `base`: `string`

### `Ready`

```gizlang
type Ready = { account: string; base: string; key: string; }
```

An account that can serve now: its id, its address ("" the provider's own) and its key ("" a server that asks
for none).

- `account`: `string`
- `base`: `string`
- `key`: `string`

### `Device`

```gizlang
type Device = { url: string; code: string; device: string; }
```

A ChatGPT device sign-in under way: the page the person opens, the code they enter there, and its id.

- `url`: `string`
- `code`: `string`
- `device`: `string`

### `Offer`

```gizlang
type Offer = { provider: Provider; model: Providers.Listed; }
```

A language model a provider lists: the provider and the model as its API lists it.

- `provider`: `gizlang_providers.Kind`
- `model`: `gizlang_providers.Listed`

## Functions

### `shapes`

```gizlang
function shapes(): Vec<Model.Shape>
```

The tables of the accounts: a store that keeps accounts installs them.

Effects: fail, read, write, console, io, alloc.

### `store`

```gizlang
function store(db: Data.Db, owner: string = ""): Store
```

The accounts of `owner` ("": the store's own) in `db`.

### `status`

```gizlang
function status(a: Account, now: i64): string
```

What an account is now: "off", "resting", "failing" (it last failed but may answer) or "ready".

### `said`

```gizlang
function said(a: Account, now: i64): string
```

What the page says of `a` at `now`: its status, and for a resting account when it is back.

Effects: fail, alloc.

### `accountsOf`

```gizlang
function accountsOf(at: Store, id: string): Vec<Account>
```

The accounts of provider `id` ("": all), by priority.

Effects: fail, read, write, console, io, alloc.

### `add`

```gizlang
function add(at: Store, input: Added): Account throws string
```

Adds the account `input` to the store's owner; a subscription signs in with its own flow (codexDevice).

Effects: fail, read, write, console, io, alloc.

### `attach`

```gizlang
function attach(at: Store, provider: string, label: string, key: string): Account throws string
```

Adds an account of a provider that a catalog names by its own id (`provider`: lower-case letters, digits, "-" and
"."; a gateway's routes name such providers, which need not be a kind of gizlang/providers) with its key.

Effects: fail, read, write, console, io, alloc.

### `readyOf`

```gizlang
function readyOf(at: Store, id: string, now: i64): Vec<Ready>
```

The owner's accounts of provider `id` that are on and do not rest at `now`, by priority, each with its key (a
subscription's token refreshed when it has expired). An account of a provider that signs in with a key serves only
with one; an account that is an address serves without.

Effects: fail, read, write, console, io, alloc.

### `keyOf`

```gizlang
function keyOf(at: Store, id: string, now: i64): string
```

The key of the owner's first account of provider `id` that serves at `now` with a key (readyOf); "" when the
owner has none.

Effects: fail, read, write, console, io, alloc.

### `hint`

```gizlang
function hint(at: Store, a: Account): string
```

The last four characters of the key of account `a` of the store's owner, to tell keys apart ("" a short key or
none): what a page may show of a key.

Effects: fail, read, write, console, io, alloc.

### `remove`

```gizlang
function remove(at: Store, a: Account): void throws string
```

Removes account `a` of the store's owner and what signs it in; another owner's account stays.

Effects: fail, read, write, console, io, alloc.

### `enable`

```gizlang
function enable(at: Store, a: Account, on: bool): void
```

Turns `a` on (ready at once) or off.

Effects: fail, read, write, console, io, alloc.

### `first`

```gizlang
function first(at: Store, a: Account): void
```

Makes `a` answer first among its provider's accounts.

Effects: fail, read, write, console, io, alloc.

### `codexDevice`

```gizlang
function codexDevice(): Device throws string
```

Starts a ChatGPT sign-in that needs no browser on this computer: the person opens `url` anywhere and enters `code`.

Effects: fail, read, write, console, io, alloc.

### `codexFinish`

```gizlang
function codexFinish(at: Store, d: Device, label: string): Account throws string
```

Ends the sign-in `d` once the person entered its code, and adds the account (labelled by its email when `label` is
""). Before they did, it fails with what to do; ask again after.

Effects: fail, read, write, console, io, alloc.

### `check`

```gizlang
function check(at: Store, pool: Http.Pool, a: Account): Account
```

Asks the provider how `a` stands and saves it: a subscription's limits (an account at its limit rests until the
limit resets), else whether its API answers. A failure is saved as its reason, never thrown.

Effects: fail, read, write, console, io, alloc.

### `offers`

```gizlang
function offers(at: Store, pool: Http.Pool): Vec<Offer>
```

The language models of the providers that have an account on: what the first ready account's API lists. A provider
that does not answer lists nothing.

Effects: fail, read, write, console, io, alloc.

### `signedIn`

```gizlang
function signedIn(at: Store): void throws string
```

Adds the account of each kind the Giz account signs in (GizStack) once there is a sign-in and no such account:
the sign-in alone makes its models usable.

Effects: fail, read, write, console, io, alloc.

### `model`

```gizlang
function model(at: Store, pool: Http.Pool, name: string): Option<Agent.Model>
```

The model that `name` (PROVIDER:MODEL) names on the accounts of its provider, through `pool`; none when the name
is not of a provider.

Effects: fail, alloc.

### `recheck`

```gizlang
function recheck(at: Store, a: Account): Account
```

Checks account `a` now.

Effects: fail, read, write, console, io, alloc.

### `checkAll`

```gizlang
function checkAll(at: Store): void
```

Checks every account that is on, at once.

Effects: fail, read, write, console, io, alloc.

### `adopt`

```gizlang
function adopt(at: Store): i64 throws string
```

Adds the sign-ins and keys this computer already holds, once each: CLIProxyAPI's (~/.cli-proxy-api), Codex's
(~/.codex/auth.json) and opencode's (~/.local/share/opencode/auth.json). Gives how many it added.

Effects: fail, read, write, console, io, alloc.

