# gizlang:signin

the giz.ai sign-in that `giz auth login` saves, shared by the command line and gizai's "giz:" models: the credentials file, the OAuth device exchange, and the model API of a signed-in account.

```gizlang
import * as Signin from "gizlang:signin";
```

## Types

### `Failure`

```gizlang
type Failure = { message: string; hint: string; status: i64; code: string; }
```

Why a giz.ai account request failed: the message, a hint of what to do, the HTTP status (0: none) and the OAuth
error code.

- `message`: `string`
- `hint`: `string`
- `status`: `i64`
- `code`: `string`

### `Auth`

```gizlang
type Auth = { token: string; base: string; }
```

A bearer token and the giz.ai address it is for.

- `token`: `string`
- `base`: `string`

### `Reply`

```gizlang
type Reply = { status: i64; headers: Vec<Http.Header>; body: bytes; }
```

An HTTP answer read whole.

- `status`: `i64`
- `headers`: `Vec<gizlang_http.Header>`
- `body`: `bytes`

### `Listed`

```gizlang
type Listed = { id: string; kind: string; tools: bool; context: i64; }
```

A model an API lists: its id, its type ("language" for a chat model; "" when the API does not say) and whether it
takes tools ("tools" in its supported_parameters; true when the API does not say), and its context window in tokens
(0: the API does not say).

- `id`: `string`
- `kind`: `string`
- `tools`: `bool`
- `context`: `i64`

## Functions

### `send`

```gizlang
function send(sys: System, method: string, url: string, headers: Vec<Http.Header>, body: bytes): Result<Reply, Failure>
```

METHOD URL with HEADERS and BODY, its answer read whole.

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

### `postForm`

```gizlang
function postForm(sys: System, url: string, names: Vec<string>, values: Vec<string>): Result<Reply, Failure>
```

POST URL with the form NAMES = VALUES.

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

### `trimmedUrl`

```gizlang
function trimmedUrl(url: string): string
```

URL without its trailing slashes.

Effects: fail.

### `credentialsPath`

```gizlang
function credentialsPath(sys: System): string
```

The credentials file: GIZ_CONFIG, else ~/.config/giz/credentials.json.

Effects: fail, io.

### `readCredentials`

```gizlang
function readCredentials(sys: System): Result<Option<JsonValue>, Failure>
```

The saved sign-in; none when there is no file.

Effects: fail, io.

### `lockCredentials`

```gizlang
function lockCredentials(sys: System): Result<bool, Failure>
```

proper-lockfile's lock, which the JavaScript CLI 2.0 takes too: the directory FILE.lock, stale after 10 s.

Effects: fail, io.

### `unlockCredentials`

```gizlang
function unlockCredentials(sys: System): void
```

Removes the lock on the credentials file that the last `lockCredentials` took.

Effects: fail, io.

### `writeCredentials`

```gizlang
function writeCredentials(sys: System, config: Option<JsonValue>): Result<bool, Failure>
```

Saves CONFIG (owner-only), or removes the file for none.

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

### `discovery`

```gizlang
function discovery(sys: System, base: string): Result<JsonValue, Failure>
```

The OAuth server metadata of BASE.

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

### `exchange`

```gizlang
function exchange(sys: System, base: string, meta: JsonValue, resource: string, names: Vec<string>, values: Vec<string>, config: JsonValue): Result<JsonValue, Failure>
```

CONFIG after a token grant (NAMES = VALUES) for RESOURCE, as CLI 2.0's exchangeToken records it.

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

### `gizBase`

```gizlang
function gizBase(sys: System, computer: bool): string
```

The giz.ai address to use: GIZ_URL, else the saved sign-in's, else (with COMPUTER) the Computer identity's, else
giz.ai.

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

### `credentials`

```gizlang
function credentials(sys: System, base: string, rejected: string): Result<Auth, Failure>
```

The bearer for BASE: GIZ_TOKEN, else the saved sign-in (refreshed under the lock when it is expired or REJECTED), else
the Computer's identity.

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

### `gizstackToken`

```gizlang
function gizstackToken(sys: System): Result<Option<string>, string>
```

GizStack's access token from the saved giz.ai sign-in: the refresh token's grant for https://gizstack.com, kept until a
minute before it expires. None without a sign-in.

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

### `computerIdentity`

```gizlang
function computerIdentity(sys: System): Result<Option<Auth>, Failure>
```

The Computer's own identity, asked of the identity socket (never a path from options or the environment); none outside
a Giz Computer.

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

### `gizApi`

```gizlang
function gizApi(sys: System, base: string, pool: Http.Pool): ModelApi throws string
```

giz.ai's OpenAI-compatible API (BASE/v1) with the account's bearer, refreshed when it has expired; through POOL.

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

### `listModels`

```gizlang
function listModels(c: ModelApi): Vec<Listed> throws string
```

The models `c` offers (GET /models), in its order.

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

### `signedIn`

```gizlang
function signedIn(sys: System): bool
```

Whether a giz.ai account is at hand: GIZ_TOKEN, or a sign-in `giz auth login` saved.

Effects: fail, io.

## Constants

### `GIZ_URL`

```gizlang
const GIZ_URL = "https://www.giz.ai"
```

giz.ai's address when neither GIZ_URL nor a sign-in names one.

### `GIZ_CLIENT`

```gizlang
const GIZ_CLIENT = "giz-cli"
```

The OAuth client of `giz auth login`.

### `GIZSTACK`

```gizlang
const GIZSTACK = "https://gizstack.com"
```

GizStack, whose access token comes from the same giz.ai sign-in.