# Project

> Projects: a repo deployed to a URL, with what the running app needs.

```python
repo = noclick.Repo.from_name("booking", create_if_missing=True)
app = noclick.Project.from_name("booking", repo=repo, create_if_missing=True)
app.bind("DB", noclick.Database.from_name("booking-db", create_if_missing=True))
app.secrets.set("MAPS_API_KEY", "...")
deployment = app.deploy().wait()
print(deployment.url)   # https://booking.noclick.site
```

A deploy of the production branch goes live at `app.url`; any other branch
gets a preview URL of its own. Bindings, secrets and schedules apply from the
next deployment.

Inside the running app, `noclick.Project.current()` is the app itself, signed
in by its deployment (no key in the app's code), and the whole client acts as a
key of the app's user: `app.database("DB")` reaches what it's bound to,
`noclick.Agent.from_name(..., create_if_missing=True)` makes what it needs,
`app.ai` and `app.agent("SUPPORT")` think and talk as the app, and
`app.verify_request(...)` checks a scheduled request. What the app spends
counts toward its `budget_usd_per_month` ($10 unless set) and its user's cap.

## noclick.Project

```python
class Project
```

An app: a repo deployed to a URL. `Project.from_name("booking", repo=repo, create_if_missing=True)` is lazy; `app.deploy()` builds and
ships it.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` |  |
| `name` | `str` |  |
| `url` | `str` | Its production URL (`https://<name>.noclick.site` until a domain serves it). |
| `hostname` | `str` | Its own name under NoClick's user-sites domain (`booking.noclick.site`), which never changes (NoClick moves only an app it publishes, when it's renamed where it was published from). |
| `repo_id` | `str | None` | None for an app NoClick publishes (`published`). |
| `published` | `bool` | NoClick publishes its files itself (an automation's interface): it has no repo, and deploys when it's published again from there. |
| `workflow` | `dict[str, Any] | None` | `{id, name, step}` of the automation it was published from (None for every other app): `step` is the interface it serves, for a key that reads workflows (None for any other), which renaming or unpublishing one of several takes: `workflow.build(publish={"action": "unpublish", "step": step})`. |
| `runtime` | `str` | `auto` (each deployment runs where its commit says: `Deployment.runtime`), `edge` (JavaScript frameworks and files) or `container` (any server, in any language). |
| `framework` | `str | None` | On `edge`: `nextjs`, `remix`, `astro`, `vite` or `static`; on `container`: `python`, `node` or `docker` (the repo's own Dockerfile); under `auto` either, which names its runtime. Detected at each build when None. |
| `production_branch` | `str` | The branch whose deploys go live (the repo's default). |
| `domain_names` | `list[str]` | The live hostnames of the domains serving it, oldest first; `domains()` loads the domains. |
| `deploy_on_push` | `str` | What a push to its repo deploys by itself: `off` (only `deploy()` deploys), `production` (a push to the production branch deploys it) or `all` (any other branch's push deploys a preview too). |
| `preview_resources` | `str` | `branch`: each preview branch gets its own copy of every resource its code names, made the first time it writes to one (until then it reads production's), so preview data never reaches production; `shared`: previews use production's resources. New apps start with `branch`. |
| `preview_access` | `str` | Who opens its previews: `public` (every app's unless set: anyone with a preview's URL, while search engines are told not to list it) or `link` (only a link NoClick signs, from `preview_link()` or a preview's deploy, until `revoke_preview_links()`; anyone else is told it's private). Production is always public. `link` is refused for an app whose previews run in containers until NoClick turns on front-door-only containers, since a container answers at its own address too. |
| `preview_public_paths` | `list[str]` | With `preview_access` `link`, the paths of a preview that stay open to anyone (`/auth/callback` exactly, or everything under `/api/webhooks/*`): what calls a preview without a person's browser, such as a webhook's sender or an OAuth provider's redirect. Empty unless set. |
| `budget_usd_per_month` | `float | None` | The most it may spend in a calendar month, in US dollars: $10 unless its maker set another. An app with code always has one; None only for an app NoClick publishes. |
| `check_paths` | `list[str | dict[str, Any]]` | What a `Deployment.check()` asks when it names no paths, what a promote checks where the release serves and then at production's URL, and what a deploy of code asks once it's live: each a page's path (`/pricing`), loaded in a browser, or what a plain request for a path must answer (`{"path": "/api/health", "status": 200}`, with `"json": True` for a JSON body). Empty: promotes aren't checked, and a deploy asks only the home page. |
| `region` | `str | None` | The region its server code is placed near (`noclick.regions()`), fixed when it was created. |
| `live_editing` | `bool` | Whether it's edited live (`app.live`): each edit swaps into the pages its owner has open, and deploys when the session ends. On from its first production release for an app live editing can run. |
| `live_editing_set_by` | `str | None` | Who set `live_editing` last: `owner` (set with `update`, which NoClick never turns back on), `noclick` (its default), or None while nobody has. |
| `badge` | `bool` | Whether its production pages carry the "Built with NoClick" link: while its paying account's plan keeps NoClick's branding. |
| `badge_corner` | `str` | The corner of its pages the badge sits in, where it carries one: `bottom-right` unless set with `update` (`bottom-left`, `top-right` or `top-left`). |
| `container` | `ProjectContainer` | How each of its instances runs in a container (`cpu`, `memory`, `min_instances`, `max_instances`, `cpu_always`, `request_timeout_s`), and what its warm instances cost a month with nothing calling it (`idle_usd_per_month`, with a `note` in words). Set with `create` or `update`: each release runs at the settings it was released with, but production keeps `min_instances` warm as it stands. |
| `user_id` | `str | None` |  |
| `created_at` | `Any` |  |
| `production` | `Deployment | None` | The deployment serving `url` (None before the first production deploy). |
| `repo` | `Repo | None` | The repo it deploys from (None for an app NoClick publishes). |
| `secrets` | `ProjectSecrets` | Its secrets: `app.secrets.set("MAPS_API_KEY", "...")`. |
| `settings` | `ProjectSettings` | Its plain settings: `app.settings.set("PUBLIC_BASE_URL", "...")`. |
| `email` | `ProjectEmail` | Transactional email from the app. |
| `payments` | `ProjectPayments` | Payments into an account the owner claims. |
| `sign_in` | `ProjectSignIn` | Sign-in for the app's own users. |
| `ai` | `ProjectAI` | `noclick.AI` acting as the app, from its own code: `app.ai.chat(...)`. |
| `live` | `ProjectLive` | Its live editing session: `app.live.start()`. |

### Project.create

```python
noclick.Project.create(
    name, *, repo=None, runtime=None, framework=None, production_branch=None,
    budget_usd_per_month=None, region=None, deploy_on_push=None,
    preview_resources=None, check_paths=None, container=None, allow_existing=False,
    user=..., client=None
) -> Project
```

Create a project called `name` (unique per user; a duplicate
raises `noclick.Conflict` with `existing_id`, or with `allow_existing=True`
returns the project already there, as it is: nothing about it changes) that deploys `repo`
(a `noclick.Repo` or its id). Without `repo` a new, empty repo of
the same name is created for it. `runtime` is `auto` unless given:
each deployment runs where its commit says, on the edge (a wrangler
config naming its entry, a JavaScript framework, or only files: server
code in isolates, static files served from everywhere) or in a
container that scales to zero (a Dockerfile, or a server in another
language: Flask, Django, Go, or a Node server with a `start` script),
and the deployment says which and why. `edge` or `container` pins
it there whatever the commit has. `framework` is detected from the
repo at each build when omitted: on `edge` `nextjs`, `remix`,
`astro`, `vite` or `static`; on `container` `docker` (the
repo's own Dockerfile), else `python` or `node`.
`production_branch` is the repo's default branch.
`deploy_on_push` (`off` unless given) makes a push deploy by itself:
`production` deploys a push to the production branch, `all` a push
to any other branch too, as a preview.
`budget_usd_per_month` caps what the app may spend in a calendar month:
its hosting and builds, its calls to what it's bound to, its email, its AI
and the agent turns it starts, all of which count toward its user's cap too.
Every app gets one: $10 unless you pass another (an agent making a site sets
one that fits it). At it the app's paid calls stop and its pages keep serving;
at twice it its pages pause.
`region` (`noclick.regions()`) places its server code near that region,
for good: put it with the database it binds (`region=db.region`), so its
queries stay short. Without one, your account's default region, else
`us-east`. Its static files are served from everywhere. It says where the
code runs, not where data stays: that's the database's and bucket's region.
`preview_resources` is `branch` unless given: each preview branch gets
its own copy of every database, bucket, dict and queue its code reaches,
made at its first write, so a preview never changes production's data
(`shared`: previews use production's). `check_paths` (up to 10) are
what a deploy of code asks once it's live, what a promote checks and what
`Deployment.check()` asks when it names none: each a page's path
(`/pricing`), loaded in a browser, or what a plain request for a path
must answer (`{"path": "/api/health", "status": 200}`, with
`"json": True` for a JSON body), as `update()` takes them.
`container` sizes each instance of its releases in a container, by
name: `cpu` (vCPUs, 1 unless given), `memory` (MiB, 512),
`min_instances` kept running while production serves it whether or
not anything calls it (0), `max_instances` (10), `cpu_always` (CPU
between requests too, for a bot or a worker: each instance billed from
start to stop) and `request_timeout_s` (300); `ProjectContainer`
says each one's bounds. A setting out of bounds raises
`noclick.InvalidRequest` naming it (`container.memory`), and so
do warm instances whose cost alone passes the budget
(`container.min_instances`, with their `idle_usd_per_month`).

Parameters:

- `name` (`str`, required)
- `repo` (`Any`, default `None`)
- `runtime` (`str | None`, default `None`)
- `framework` (`str | None`, default `None`)
- `production_branch` (`str | None`, default `None`)
- `budget_usd_per_month` (`float | None`, default `None`)
- `region` (`str | None`, default `None`)
- `deploy_on_push` (`str | None`, default `None`)
- `preview_resources` (`str | None`, default `None`)
- `check_paths` (`Sequence[str | Mapping[str, Any]] | None`, default `None`)
- `container` (`Mapping[str, Any] | ProjectContainer | None`, default `None`)
- `allow_existing` (`bool`, default `False`)
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `Project` The new project, loaded. Nothing is deployed until `deploy()`.

Usage:

Deploy code you already committed:

```python
repo = noclick.Repo.from_name("booking")
app = noclick.Project.create("booking", repo=repo)
print(app.url)   # https://booking.noclick.site
```

Inside `as_user` the app is that user's, and what it spends counts toward their cap
and its own budget:

```python
with noclick.as_user("acme"):
    app = noclick.Project.create("status-page", framework="astro", budget_usd_per_month=10)
```

Check its API, not only its home page, at every deploy and promote:

```python
app = noclick.Project.create(
    "booking", repo=repo, preview_resources="branch",
    check_paths=["/", {"path": "/api/health", "status": 200}],
)
```

Run a Discord bot that stays connected with nothing calling it: one instance kept running, its CPU
on between requests:

```python
bot = noclick.Project.create(
    "standup-bot", repo=repo, runtime="container",
    container={"cpu_always": True, "min_instances": 1},
)
print(bot.container.idle_usd_per_month, bot.container.note)
```

### Project.from_name

```python
noclick.Project.from_name(
    name, *, repo=None, create_if_missing=False, runtime=None, framework=None,
    production_branch=None, budget_usd_per_month=..., region=None, deploy_on_push=None,
    preview_resources=None, check_paths=None, user=..., client=None
) -> Project
```

A lazy reference to the project called `name` in the current (or
given) user. Given fields, it gets the project and sets the ones you pass, on every run: an
existing project whose repo, runtime, framework, production branch, budget,
`deploy_on_push`, `preview_resources` or `check_paths` differ gets yours.
`create_if_missing=True` creates it with the fields `Project.create` takes when there's
none; without it, a missing project raises `noclick.NotFound`. A field you leave out is
never changed; an app with code always has a budget, so
`budget_usd_per_month=None` raises `noclick.InvalidRequest`.
`region` is fixed once it's created: an existing app in another region
raises `noclick.Conflict` naming its `region`. Each run with fields is a write: set
them in a setup script or at deploy, and take the bare `from_name` in the app's handlers.

Parameters:

- `name` (`str`, required)
- `repo` (`Any`, default `None`)
- `create_if_missing` (`bool`, default `False`)
- `runtime` (`str | None`, default `None`)
- `framework` (`str | None`, default `None`)
- `production_branch` (`str | None`, default `None`)
- `budget_usd_per_month` (`Any`, default: unchanged)
- `region` (`str | None`, default `None`)
- `deploy_on_push` (`str | None`, default `None`)
- `preview_resources` (`str | None`, default `None`)
- `check_paths` (`Sequence[str | Mapping[str, Any]] | None`, default `None`)
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `Project` A project that loads (or is created, or has your fields set) the first time it's used.
Nothing is sent yet.

Usage:

Refer to an app by name:

```python
app = noclick.Project.from_name("booking")
print(app.url, app.production)
```

Or get it, creating it if it's missing, and set its fields. The same lines set it up the
first time and deploy it every time after:

```python
repo = noclick.Repo.from_name("booking", create_if_missing=True)
app = noclick.Project.from_name("booking", repo=repo, budget_usd_per_month=25, create_if_missing=True)
app.deploy().wait()
```

### Project.current

```python
noclick.Project.current(*, client=None) -> Project
```

The app this code runs in, from inside a deployment. NoClick puts the
deployment's own credential in its environment (`NOCLICK_DEPLOYMENT_TOKEN`), so
the app's code holds no key, and the whole client (`noclick.Agent`,
`noclick.Database`, `noclick.AI`, ...) acts as a key of the app's user, attributed
to the app. Outside a deployment it raises `noclick.Unauthenticated`; pass
`client=` to act with a key of your own instead. Python runs in an app on the
`container` runtime; an `edge` app's code uses the TypeScript client's
`Project.current()`.

What its code makes (an agent, a database, a sandbox) or buys (a phone number, a domain)
is the app's own. Its user's other resources it reads and uses but never changes or
deletes (on one bound to the app, it may clear its data), and it never reaches another
app, another user, or what another app's code made. It never mints or revokes keys,
sets a cap or budget (its own included), changes policy, answers approvals, accepts
terms for a person, or reads secrets' values or raw tokens: those raise
`noclick.PermissionDenied`. It talks to agents in threads of its own (`agent`), and
never to one holding the `noclick` tool. The app's code decides who may make it do
what: policy doesn't judge its calls (an agent it messages still runs under its policy).

What the app does is billed to your account, attributed to the app and its user, and
counts toward the app's `budget_usd_per_month` and its user's cap: what its code
spends, what it buys (each renewal in the month it renews) and what bills after its
request (its numbers' calls and texts, its automations' runs, its MCP servers, channels,
machines and cards). A purchase must fit what's left of the budget, and one in a
person's name raises `noclick.ApprovalRequired` until they approve it. Once the budget
or the cap is used up the app keeps serving and reading its data, but its paid calls
(writes, email, `app.ai`, agent turns) raise `noclick.SpendCapExceeded` naming the
app; catch it and serve the page without them.

Parameters:

- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `Project` The app, loaded on first use. Nothing is sent yet.

Usage:

In a request handler of a deployed app, read what the app is bound to by name:

```python
app = noclick.Project.current()
db = app.database("DB")
rows = db.query("select id, starts_at from bookings where day = ?", ["2026-10-02"])
app.email.send(to="ana@example.com", subject="Your booking", text="See you Friday at 3pm.")
```

Make what it needs as it goes, which is the app's own from then on:

```python
noclick.Project.current()
helper = noclick.Agent.from_name("helper", instructions="Answer in French.", tools=["search"],
                                 create_if_missing=True)
print(helper.message("Bonjour !", conversation="visitor-91c2").text)
```

### Project.from_id

```python
noclick.Project.from_id(project_id, *, client=None, user=...) -> Project
```

A lazy reference to a project by id.

Parameters:

- `project_id` (`str`, required)
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: `Project` A project that loads the first time you read a field. Nothing is sent yet.

Usage:

```python
app = noclick.Project.from_id("2b7e9c4a-6f1d-4a3b-8e5c-0d9f7a1b3c52")
op = app.deploy()
```

### Project.get

```python
noclick.Project.get(project_id, *, user=..., client=None) -> Project
```

Load a project by id now; an unknown id raises `noclick.NotFound`.

Parameters:

- `project_id` (`str`, required)
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `Project` The project, loaded, with its `production` deployment.

Usage:

```python
app = noclick.Project.get("2b7e9c4a-6f1d-4a3b-8e5c-0d9f7a1b3c52")
print(app.name, app.url, app.framework)
```

### Project.list

```python
noclick.Project.list(
    *, limit=None, user_filter=None, user=..., client=None
) -> list[Project]
```

The current user's projects (the account's own outside `as_user`, or those `user_filter` covers).

Parameters:

- `limit` (`int | None`, default `None`): Return at most this many.
- `user_filter` (`Any`, default `None`): Which users a read covers: `noclick.ALL_USERS`, `noclick.NO_USER`, a `User`, or your id for one. It filters without acting as that user.
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `list[Project]` Every matching project, newest first, fetched page by page, each with its `production` deployment.

Usage:

```python
for app in noclick.Project.list(user_filter=noclick.ALL_USERS):
    live = app.production
    print(app.name, app.url, live.status if live else "not deployed")
```

### Project.list_page

```python
noclick.Project.list_page(
    *, cursor=None, limit=None, user_filter=None, user=..., client=None
) -> Page
```

One page of projects; pass `next_cursor` back as `cursor`.

Parameters:

- `cursor` (`str | None`, default `None`): The `next_cursor` of the page before; omit it for the first page.
- `limit` (`int | None`, default `None`): Return at most this many.
- `user_filter` (`Any`, default `None`): Which users a read covers: `noclick.ALL_USERS`, `noclick.NO_USER`, a `User`, or your id for one. It filters without acting as that user.
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `Page` A page whose `data` holds the projects and whose `next_cursor` is `None` on the last page.

Usage:

```python
page = noclick.Project.list_page(limit=50)
while True:
    for app in page.data:
        print(app.name, app.url)
    if page.next_cursor is None:
        break
    page = noclick.Project.list_page(limit=50, cursor=page.next_cursor)
```

### Project.analytics_summary

```python
noclick.Project.analytics_summary(
    *, period='7d', tz=None, user_filter=None, user=..., client=None
) -> AnalyticsSummary
```

Every app's requests over the last `period` (`24h`, `7d` or `30d`) and how many failed, in one
read however many apps there are: each production site's, over the same window `analytics` reads, its days
starting in `tz` (UTC when omitted). Which apps: the current user's, or those `user_filter` covers, as
`list`. Requests, not visitors.

Parameters:

- `period` (`str`, default `'7d'`)
- `tz` (`str | None`, default `None`)
- `user_filter` (`Any`, default `None`): Which users a read covers: `noclick.ALL_USERS`, `noclick.NO_USER`, a `User`, or your id for one. It filters without acting as that user.
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `AnalyticsSummary` Its `AnalyticsSummary`: one line per app, newest first.

Usage:

Each app's week, busiest first:

```python
week = noclick.Project.analytics_summary(tz="Europe/Paris")
for line in sorted(week.apps, key=lambda a: a.requests, reverse=True):
    print(line.project_id, line.requests, line.errors)
```

### Project.update

```python
app.update(
    *, repo=..., runtime=..., framework=..., production_branch=...,
    budget_usd_per_month=..., deploy_on_push=..., preview_resources=...,
    check_paths=..., live_editing=..., badge_corner=..., preview_access=...,
    preview_public_paths=..., container=...
) -> Project
```

Change the `repo` it deploys (a `noclick.Repo` or its id), its `runtime`
(`auto`, `edge` or `container`), its `framework`, its `production_branch`, its
`budget_usd_per_month`, what a push deploys (`deploy_on_push`: `off`,
`production` or `all`), what deploys, promotes and checks ask (`check_paths`, up
to 10: a page's path, loaded in a browser, or what a plain request for a path must
answer, `{"path": "/api/health", "status": 200}` or `{"path": ..., "json": True}`;
`[]` stops checking promotes), whether previews get their own
resources (`preview_resources`: `branch` or `shared`), whether it's edited live
(`live_editing`, see `app.live`), the corner its badge sits in (`badge_corner`:
`bottom-right`, `bottom-left`, `top-right` or `top-left`, away from a chat's composer
or a corner button, say), or who opens its previews (`preview_access`: `public` or
`link`, the paths a private preview leaves open in `preview_public_paths`; production
is always public; while NoClick's front door doesn't keep previews private yet the answer's
`raw["notes"]` say so), or how each of its instances runs in a container (`container`:
a mapping of `cpu`, `memory`, `min_instances`, `max_instances`, `cpu_always` and
`request_timeout_s`, where a setting left out keeps its value, or another app's
`container`; `container=None` sets every one back to its default; `ProjectContainer`
says each one's bounds). A new repo, runtime, framework, branch or container settings apply
from the next release (a deploy, or for container settings a promote of what production
serves; the answer's `raw["notes"]` say so), and what's live keeps serving as it runs until
then; the rest apply at once, `container`'s `min_instances` included. A container
setting out of bounds raises `noclick.InvalidRequest` naming it (`container.memory`),
and so do warm instances whose cost alone passes the app's budget
(`container.min_instances`, with their `idle_usd_per_month`). An app with code always has a budget: `budget_usd_per_month=None`
raises `noclick.InvalidRequest` (only an app NoClick publishes may have none). Its user's
cap still applies either way. Pinning a runtime the app's framework doesn't run on raises
`noclick.InvalidRequest`: change the framework with it.

Parameters:

- `repo` (`Any`, default: unchanged)
- `runtime` (`Any`, default: unchanged)
- `framework` (`Any`, default: unchanged)
- `production_branch` (`Any`, default: unchanged)
- `budget_usd_per_month` (`Any`, default: unchanged)
- `deploy_on_push` (`Any`, default: unchanged)
- `preview_resources` (`Any`, default: unchanged)
- `check_paths` (`Any`, default: unchanged)
- `live_editing` (`Any`, default: unchanged)
- `badge_corner` (`Any`, default: unchanged)
- `preview_access` (`Any`, default: unchanged)
- `preview_public_paths` (`Any`, default: unchanged)
- `container` (`Any`, default: unchanged)

Returns: `Project` This app, updated. A field you leave out is unchanged.

Usage:

Give an app a budget of its own, so it can't spend all of its user's cap:

```python
app = noclick.Project.from_name("booking", user="user_42")
app.update(budget_usd_per_month=25)
```

Lift it for the rest of the month after a busy launch:

```python
app = noclick.Project.from_name("booking", user="user_42")
if app.usage().limited_by == "project":
    app.update(budget_usd_per_month=50)
```

Deploy every push to the production branch from now on:

```python
app = noclick.Project.from_name("booking")
app.update(deploy_on_push="production")
```

Promote only releases whose home and booking pages load cleanly, and whose API answers:

```python
app = noclick.Project.from_name("booking")
app.update(check_paths=["/", "/book", {"path": "/api/bookings", "status": 200, "json": True}])
```

Give an app made before branched previews its own copies per branch, so a preview's
writes never reach production's data:

```python
app = noclick.Project.from_name("booking")
app.update(preview_resources="branch")
```

Edit a Vite site live, each change showing in the page its owner has open: it takes an app of
your account's own whose previews get their own data (`noclick.Conflict` says what else to change):

```python
app = noclick.Project.from_name("larkspur")
app.update(live_editing=True)
print(app.live_editing, app.live.start().enter_url)
```

Let an app made before `auto` run each commit where it says (its next deploy of a
Dockerfile runs in a container):

```python
app = noclick.Project.from_name("booking")
app.update(runtime="auto", framework=None)
deployment = app.deploy().wait()
print(deployment.runtime, deployment.runtime_reason)
```

Keep the badge clear of a chat's composer in the bottom-right corner:

```python
app = noclick.Project.from_name("inbox")
app.update(badge_corner="top-right")
```

Make an app's previews private, its Stripe webhook still reaching them, and hand its owner the link:

```python
app = noclick.Project.from_name("booking")
app.update(preview_access="link", preview_public_paths=["/api/webhooks/*"])
print(app.preview_link(branch="new-form").url)
```

Give an app that loads a model at start more room, then deploy to run at it:

```python
app = noclick.Project.from_name("transcriber")
app.update(container={"cpu": 2, "memory": 4096})
app.deploy().wait()
```

Keep a bot connected with nothing calling it, seeing what that costs before it's live:

```python
bot = noclick.Project.from_name("standup-bot")
bot.update(container={"cpu_always": True, "min_instances": 1})
print(bot.container.idle_usd_per_month, bot.raw["notes"])
```

Put every setting back to its default:

```python
noclick.Project.from_name("standup-bot").update(container=None)
```

### Project.deploy

```python
app.deploy(*, branch=None, commit=None) -> Operation
```

Build and deploy `branch` (the production branch when omitted) at
its head, or at `commit`. A deploy of the production branch goes live
at `url` once it's ready; any other branch is a preview with a URL of
its own. Every release is asked for its home page (its scripts and
stylesheets too) and the app's `check_paths` as soon as its URL
serves it: one that answers wrong stays live, the deployment's
`warning` says what answered and its `next_step` what to fix.
When its static files answer every path asked, its code is asked at a
path no file answers too; `code_unchecked` says when nothing asked
could reach its code. A preview of an app whose
`preview_resources` is `branch` says what it writes to in
`preview_data`.

Parameters:

- `branch` (`str | None`, default `None`)
- `commit` (`str | None`, default `None`)

Returns: `Operation` An operation whose `.wait()` gives the `Deployment`, `ready`, with its `warning`,
`next_step`, `code_unchecked` and `preview_data`. A failed build raises `noclick.OperationFailed`, whose
`deployment_id` names the deployment to read the build log of.

Usage:

Deploy production and wait for it:

```python
app = noclick.Project.from_name("booking")
deployment = app.deploy().wait()
print(deployment.url, deployment.commit)
if deployment.warning:
    print(deployment.warning, deployment.next_step)   # live, but not working
```

Deploy a branch as a preview, and read the build log when it fails:

```python
app = noclick.Project.from_name("booking")
try:
    preview = app.deploy(branch="new-form").wait()
    print(preview.url)   # https://new-form--booking.noclick.site
except noclick.OperationFailed as failed:
    for line in noclick.Deployment.from_id(failed.deployment_id).logs(kind="build"):
        print(line.message)
```

### Project.deployments

```python
app.deployments(*, branch=None, limit=20) -> list[Deployment]
```

Its deployments, newest first, of every branch or of `branch`.

Parameters:

- `branch` (`str | None`, default `None`)
- `limit` (`int | None`, default `20`): Return at most this many.

Returns: `list[Deployment]` Up to `limit` deployments (20 by default; `None` for all), fetched page by page.

Usage:

```python
app = noclick.Project.from_name("booking")
for deployment in app.deployments(limit=10):
    print(deployment.branch, deployment.status, deployment.production, deployment.url)
```

### Project.preview_link

```python
app.preview_link(*, branch=None, expires_in=None) -> PreviewLink
```

Make a link that opens a preview of the app (`branch`'s, else the newest serving) to whoever holds it,
for `expires_in` seconds (7 days unless given; 5 minutes to 30 days). It's what to hand people when the
app's `preview_access` is `link`. It lasts until it expires, or until `revoke_preview_links()` stops
every link made before.

Parameters:

- `branch` (`str | None`, default `None`)
- `expires_in` (`int | None`, default `None`)

Returns: `PreviewLink` The `PreviewLink`. No preview serving (or one of the production branch, always public) raises
`noclick.NotFound` (`noclick.InvalidRequest`), saying what to deploy.

Usage:

```python
app = noclick.Project.from_name("booking")
link = app.preview_link(branch="new-form", expires_in=24 * 3600)
print(link.url, link.expires_at)
```

### Project.revoke_preview_links

```python
app.revoke_preview_links() -> Project
```

Stop every link to the app's previews made before now, and the cookie each left in a browser: within 30
seconds none of them opens a preview, while links made after (`preview_link()`, a preview's deploy) open
them as before. For a link that reached someone who shouldn't have it. On an app whose previews are public
their URLs still open them, which `raw["notes"]` says.

Returns: `Project` This app, as it is then.

Usage:

```python
app = noclick.Project.from_name("booking")
app.revoke_preview_links()
print(app.preview_link(branch="new-form").url)   # a fresh link for the people who should keep it
```

### Project.rollback

```python
app.rollback(*, to) -> Operation
```

Serve an earlier deployment (a `Deployment` or its id, still
`ready`) at `url` again, without rebuilding: released again with
production's settings and secrets as they are now, then live within a
minute. The same as `to.promote()`. It covers the app's last 10
production deployments; an older one is built again from its commit.

Parameters:

- `to` (`Deployment | str`, required)

Returns: `Operation` An operation whose `.wait()` gives that deployment (or, past the window, the one built
from its commit), now `production`.

Usage:

Go back to the production deployment before the current one:

```python
app = noclick.Project.from_name("booking")
previous = [d for d in app.deployments(branch=app.production_branch) if d.status == "ready" and not d.production][0]
app.rollback(to=previous).wait()
```

### Project.bind

```python
app.bind(name, resource, *, kind=None) -> Binding
```

Give the app `resource` under `name`: a `noclick.Database`,
`Bucket`, `Connection`, `Dict`, `Queue`, `Secret` or `Agent`, or its id
with `kind` (`database`, `bucket`, `connection`, `dict`, `queue`,
`secret` or `agent`). The running app reads it
from its environment by that name. Binding a name again replaces what it
pointed at; it takes effect at the next deployment. An agent is the app's
user's own or one of your account's, and the app talks to it as itself (see
`agent`).

A `Secret` reaches the app as one variable per key, each under the key's own
name, and `name` only lists it. The app's environment holds a name once, so
a key that another bound secret holds, or that another binding, the app's own
`secrets` or `settings` or NoClick sets, raises `noclick.Conflict`; a secret
that gains such a key after it's bound fails the next deployment the same way.

Parameters:

- `name` (`str`, required)
- `resource` (`Any`, required)
- `kind` (`str | None`, default `None`)

Returns: `Binding` The binding, naming the resource.

Usage:

Give the app its database, its files and the owner's CRM:

```python
app = noclick.Project.from_name("booking")
app.bind("DB", noclick.Database.from_name("booking-db", create_if_missing=True))
app.bind("FILES", noclick.Bucket.from_name("uploads", create_if_missing=True))
app.bind("CRM", noclick.Connection.from_name("hubspot"))
app.deploy()
```

Give it an agent to answer its visitors:

```python
app = noclick.Project.from_name("booking")
app.bind("SUPPORT", noclick.Agent.from_name("support"))
app.deploy()
```

With an id, say what it is:

```python
app = noclick.Project.from_name("booking")
app.bind("DB", "5c2e8a1f-3b7d-4e9a-a6c4-8d1f0e2b3a79", kind="database")
```

### Project.bindings

```python
app.bindings() -> list[Binding]
```

What the app is given, by name.

Returns: `list[Binding]` Each binding with the resource it names.

Usage:

```python
app = noclick.Project.from_name("booking")
for binding in app.bindings():
    print(binding.name, binding.kind, binding.resource_name)   # DB database booking-db
```

### Project.unbind

```python
app.unbind(name) -> None
```

Take `name` away from the app at the next deployment. The resource itself is kept.

Parameters:

- `name` (`str`, required)

Usage:

```python
app = noclick.Project.from_name("booking")
app.unbind("CRM")
```

### Project.database

```python
app.database(name) -> Database
```

The database bound to the app as `name`, from the app's own code
(`Project.current()`) or yours.

Parameters:

- `name` (`str`, required)

Returns: `Database` The `noclick.Database`; a name bound to something else raises `noclick.InvalidRequest`,
an unbound one `noclick.NotFound`.

Usage:

```python
app = noclick.Project.current()
bookings = app.database("DB").query("select count(*) as n from bookings")
print(bookings.rows[0]["n"])
```

### Project.bucket

```python
app.bucket(name) -> Bucket
```

The bucket bound to the app as `name`.

Parameters:

- `name` (`str`, required)

Returns: `Bucket` The `noclick.Bucket`.

Usage:

```python
app = noclick.Project.current()
files = app.bucket("FILES")
files.put("invoices/1042.pdf", b"%PDF-...")
```

### Project.dict

```python
app.dict(name) -> Dict
```

The dict bound to the app as `name`.

Parameters:

- `name` (`str`, required)

Returns: `Dict` The `noclick.Dict`.

Usage:

```python
app = noclick.Project.current()
sessions = app.dict("SESSIONS")
sessions.put("sess_91c2", {"user": "ana"}, ttl_s=3600)
```

### Project.queue

```python
app.queue(name) -> Queue
```

The queue bound to the app as `name`.

Parameters:

- `name` (`str`, required)

Returns: `Queue` The `noclick.Queue`.

Usage:

```python
app = noclick.Project.current()
app.queue("JOBS").put({"booking": 1042, "send": "reminder"})
```

### Project.connection

```python
app.connection(name) -> Connection
```

The connection bound to the app as `name`: the app runs its operations as the
account that connected it.

Parameters:

- `name` (`str`, required)

Returns: `Connection` The `noclick.Connection`.

Usage:

```python
app = noclick.Project.current()
crm = app.connection("CRM")
crm.run("create_contact", {"email": "ana@example.com"})
```

### Project.agent

```python
app.agent(name) -> Agent
```

The agent bound to the app as `name`. From the app's own code it acts as the app:
`message`, `send` and `ask` start turns in the app's own conversations, and
`history` and `conversations` read only those. A key the app passes (its visitor's
id, say) always names a thread of the app's: `visitor-91c2` from the app is
`app:<app id>:visitor-91c2` to your own code, which reads those threads, and no other
app reaches them. The agent's policy still judges its tool calls, and its turns are
billed like any turn, attributed to the app: to the agent's budget, the app's and its
user's cap. Anything else (`update`, `delete`, its triggers, memory, wake-ups or
children) raises `noclick.PermissionDenied` from the app, unless its code made the
agent. A preview's code talks to it in threads of the preview's own
(`app-preview:<app id>:<key>`), its tools answering from a simulated world; no app's
code talks to an agent that holds the `noclick` tool.

Parameters:

- `name` (`str`, required)

Returns: `Agent` The `noclick.Agent`.

Usage:

Answer a visitor in a thread of their own, and degrade once the money runs out:

```python
app = noclick.Project.current()
support = app.agent("SUPPORT")
try:
    reply = support.message("Can I move my booking to Saturday?", conversation="visitor-91c2")
    print(reply.text)
except (noclick.SpendCapExceeded, noclick.PaymentRequired):
    print("Chat is resting for now. Email help@acmebooking.com and we'll answer today.")
```

### Project.verify_request

```python
app.verify_request(body, headers, *, tolerance_s=300) -> None
```

Check that a request to the app came from NoClick (one of its schedules or
subscriptions): `body` is the raw body exactly as it arrived, `headers` its
headers. Every request NoClick makes to the app carries a
`NoClick-Signature` header (`t=<unix seconds>,v1=<hex>`, HMAC-SHA256 of
`"<t>.<body>"`) keyed with the app's signing secret, which NoClick sets in the
deployment's environment as `NOCLICK_SIGNING_SECRET`. It sends nothing.

Raises `noclick.WebhookSignatureError` when the header is missing or malformed, the
timestamp is more than `tolerance_s` from now, or the signature doesn't match; answer
such a request 401.

Parameters:

- `body` (`bytes | str`, required)
- `headers` (`Mapping[str, Any]`, required)
- `tolerance_s` (`int`, default `300`)

Usage:

In a Flask route a schedule calls, in an app on the `container` runtime:

```python
from flask import Flask, request

server = Flask(__name__)

@server.post("/jobs/reminders")
def reminders():
    app = noclick.Project.current()
    try:
        app.verify_request(request.get_data(), request.headers)
    except noclick.WebhookSignatureError:
        return "", 401
    return "", 204
```

### Project.schedule

```python
app.schedule(cron, *, path, name=None) -> Schedule
```

POST `path` on the app on every tick of `cron` (a
`noclick.Cron`). A schedule is keyed by `name` (the path when
omitted), so calling this again with the same one updates it rather
than adding another. Each request carries a signed `NoClick-Signature`
header, so the app can refuse anyone else.

Parameters:

- `cron` (`Cron`, required)
- `path` (`str`, required)
- `name` (`str | None`, default `None`)

Returns: `Schedule` The schedule, `active`, with its `next_run`.

Usage:

Send reminders at 9am New York time on weekdays:

```python
app = noclick.Project.from_name("booking")
reminders = app.schedule(noclick.Cron("0 9 * * 1-5", tz="America/New_York"), path="/jobs/reminders")
print(reminders.next_run)
```

Two schedules on one path need names:

```python
app = noclick.Project.from_name("booking")
app.schedule(noclick.Cron("0 * * * *"), path="/jobs/sync", name="hourly-sync")
app.schedule(noclick.Cron("0 3 * * 0"), path="/jobs/sync", name="weekly-full-sync")
```

### Project.schedules

```python
app.schedules() -> list[Schedule]
```

Its schedules.

Returns: `list[Schedule]` Each schedule with its `status`, `next_run` and how its `last_run` went.

Usage:

```python
app = noclick.Project.from_name("booking")
for schedule in app.schedules():
    print(schedule.cron, schedule.tz, schedule.path, schedule.status, schedule.last_status)
```

### Project.durable_objects

```python
app.durable_objects() -> DurableObjectClasses
```

Its Durable Object classes in every environment, production's first.

Returns: `DurableObjectClasses` Each class with how many objects it has and what they store; `unread` names a figure the host
couldn't report.

Usage:

```python
app = noclick.Project.from_name("chat")
for room in app.durable_objects():
    print(room.name, room.environment, room.objects_count, room.stored_bytes, room.status)
```

### Project.subscribe

```python
app.subscribe(source, *, path) -> Subscription
```

POST each of a connection's app events to `path` on the app, signed as its
schedules' calls are, so the app runs its own pipeline with no agent in between.
`source` is a `noclick.OnEvent` (a connection of the app's own scope, one of its
integration's events, its filters). The body is JSON: `{object: "app_event", id, subscription_id, connection, integration, event, text, thread, data, test, created_at}`, where `data` is the event as the integration sent it, `text` the
same in words and `thread` the conversation it belongs to (a WhatsApp chat, a Slack
thread). Check it with `verify_request`, answer 2xx within 10 seconds (do slow work
after answering), and key on `id`: an event the app didn't take is sent again, the
same body, for three days. Up to 20 an app; one whose connection isn't connected yet
is `error` until it is.

Parameters:

- `source` (`Any`, required)
- `path` (`str`, required)

Returns: `Subscription` The subscription, with its `path`.

Usage:

Every WhatsApp message to the app's own route, from its own code:

```python
whatsapp = noclick.Connection.from_name("whatsapp", integration="whatsapp")
app = noclick.Project.current()
app.subscribe(noclick.OnEvent(whatsapp, "receive_message"), path="/hooks/whatsapp")
```

### Project.subscriptions

```python
app.subscriptions() -> list[Subscription]
```

Its subscriptions, oldest first.

Returns: `list[Subscription]` Each `noclick.Subscription` with its `source`, `path` and `status`.

Usage:

```python
app = noclick.Project.from_name("booking")
for subscription in app.subscriptions():
    print(subscription.source["event"], subscription.path, subscription.status)
```

### Project.add_domain

```python
app.add_domain(name) -> Domain
```

Serve the app at the domain `name` too. A domain you bought through
NoClick is pointed at it at once, at its name and `www`; one owned elsewhere
is connected and waits in `pending_dns` until its records are set (`records`
lists them). Each name is live once its certificate is issued.

A subdomain of a domain your account holds (`ana.acmebooking.com` under the account's
`acmebooking.com`) can serve any project, a user's included, so each user's app gets an
address of yours; only a key acting for the whole account (not a user session or a key
pinned to a user) may hand one out. Under a bought domain the record is written for you;
under a connected one connected with `wildcard=True` it needs no record of its own and
is live within minutes, and otherwise `records` lists the one to add.

Parameters:

- `name` (`str`, required)

Returns: `Domain` The `noclick.Domain`, with its `status`.

Usage:

Serve the app at a domain you own:

```python
app = noclick.Project.from_name("booking")
domain = app.add_domain("book.acme.com")
print(domain.status)   # pending_dns until the records are set
for record in domain.records:
    print(record.type, record.name, record.value)
```

Give a user's app a subdomain of your account's domain:

```python
ana_app = noclick.Project.from_name("store", user="user_42")
domain = ana_app.add_domain("ana.acmebooking.com")
print(domain.status)   # active: the account bought acmebooking.com through NoClick
```

### Project.domains

```python
app.domains() -> list[Domain]
```

The domains that serve the app.

Returns: `list[Domain]` Each `noclick.Domain` with its `status`.

Usage:

```python
app = noclick.Project.from_name("booking")
for domain in app.domains():
    print(domain.name, domain.status)
```

### Project.remove_domain

```python
app.remove_domain(name) -> None
```

Stop serving the app at `name` (a bare domain's `www` too). The domain itself is
kept: a bought one stays yours, and one connected for the app stays connected until you
delete it. A name that doesn't serve the app raises `noclick.NotFound`.

Parameters:

- `name` (`str`, required)

Usage:

```python
app = noclick.Project.from_name("booking")
app.remove_domain("book.acme.com")
```

### Project.logs

```python
app.logs(
    *, since=None, level=None, deployment=None, limit=100, environment='all'
) -> LogLines
```

What the app printed while serving, oldest first: the last `limit`
lines (at most 1,000), or with `since` (a timezone-aware
`datetime`) the first `limit` after it. `level` keeps `warn` or
`error` lines only; `deployment` one deployment's; `environment`
(`production` or `preview`) one environment's. A request's lines are
never cut apart. Lines are kept 7 days, and take up to a minute to show
after a request writes them.

Parameters:

- `since` (`str | datetime | None`, default `None`)
- `level` (`str | None`, default `None`)
- `deployment` (`Deployment | str | None`, default `None`)
- `limit` (`int`, default `100`): Return at most this many.
- `environment` (`str`, default `'all'`)

Returns: `LogLines` The lines, with `delay_s`: how long a line can take to show, so an empty read may only be early.
Pass the last one's `at` as `since` to read on from there.

Usage:

The errors of the last hour:

```python
from datetime import datetime, timedelta, timezone

app = noclick.Project.from_name("booking")
an_hour_ago = datetime.now(timezone.utc) - timedelta(hours=1)
for line in app.logs(since=an_hour_ago, level="error"):
    print(line.at, line.message)
```

Follow the log, a page at a time:

```python
app = noclick.Project.from_name("booking")
lines = app.logs(limit=50)
while lines:
    for line in lines:
        print(line.message)
    lines = app.logs(since=lines[-1].at, limit=50)
```

### Project.analytics

```python
app.analytics(*, period='7d', environment='production', tz=None) -> ProjectAnalytics
```

How the app's traffic went over the last `period` (`24h`, `7d` or `30d`): its requests each hour
(`24h`) or day, starting in `tz` (an IANA time zone; UTC when omitted), how many failed, the totals
against the same length of time before, by status, how long answers took to begin and the busiest paths.
`environment`: its production site (`production`), its previews (`preview`) or both (`all`).

It counts every request the app's sites answered, its static files and API calls included, people's and
bots' alike: requests, not visitors.

Parameters:

- `period` (`str`, default `'7d'`)
- `environment` (`str`, default `'production'`)
- `tz` (`str | None`, default `None`)

Returns: `ProjectAnalytics` Its `ProjectAnalytics`, read from NoClick's record of each request.

Usage:

How the site is doing this week, against last week:

```python
app = noclick.Project.from_name("booking")
week = app.analytics(tz="Europe/Paris")
print(week.requests, week.previous_requests, week.error_rate, week.p95_ms)
for day in week.series:
    print(day.at.date(), day.requests, day.errors)
for page in week.top_paths:
    print(page.path, page.requests)
```

The last 24 hours, hour by hour:

```python
for hour in app.analytics(period="24h").series:
    print(hour.at, hour.requests)
```

### Project.usage

```python
app.usage() -> ProjectUsage
```

What the app has spent this month, against its budget: everything it cost in
`usd` (hosting and builds, its calls to what it's bound to, its email, its AI and its
agent turns), split `by_type`, and `limited_by`, what refuses its paid calls now.

Returns: `ProjectUsage` Requests served, compute in `cpu_ms`, `usd` and its `budget_usd`, what refuses its paid
calls (`limited_by`), and the `period_start` it counts from.

Usage:

Show the app's spend against its budget:

```python
app = noclick.Project.from_name("booking")
used = app.usage()
print(used.requests, used.cpu_ms, f"${used.usd:.2f}")
if used.budget_usd is not None:
    print(f"${used.usd:.2f} of ${used.budget_usd:.2f}", used.by_type)
```

Find out why its paid calls fail:

```python
app = noclick.Project.from_name("booking")
if app.usage().limited_by == "user":
    print("Its user reached their monthly cap.")
```

### Project.export

```python
app.export() -> Operation
```

Package everything the app is, to run it elsewhere: its code as a
git bundle, `apps/<name>.json` with its settings, bindings and secret
names (never values), and each database, bucket, dict and queue it binds,
each in its own export's format. To put the code on GitHub, use the
repo's `export_to_github`.

Returns: `Operation` An operation whose `.wait()` gives an `noclick.ExportBundle`.

Usage:

```python
app = noclick.Project.from_name("booking")
bundle = app.export().wait()
print(bundle.url)
for item in bundle.contents:
    print(item.kind, item.name, item.detail)
```

### Project.delete

```python
app.delete(*, delete_data=False) -> TrashItem
```

Delete the app: it goes offline within seconds and to the trash,
restorable for 30 days with everything it had (its releases,
settings, secrets, bindings, schedules and domains), served again
with no build. Its name is free meanwhile. The repo and every bound
database and bucket are kept, unless `delete_data=True` moves the
repo to the trash too, with each database and bucket no other app
binds.

Parameters:

- `delete_data` (`bool`, default `False`)

Returns: `TrashItem` Its `TrashItem`: `restore()` serves it again where it was.

Usage:

Delete the app and keep its data:

```python
app = noclick.Project.from_name("status-page", user="acme")
item = app.delete()
```

Or delete what only it used as well, then change your mind:

```python
item = noclick.Project.from_name("scratch").delete(delete_data=True)
item.restore()
```

### Project.unpublish

```python
app.unpublish() -> TrashItem
```

Take down an app NoClick publishes (`published`), to the trash: its page's key stops working and every
address it answers at stops at once. For 30 days no other app takes its address, and `restore()` (or
publishing its automation's interface again) serves it where it was with the same key; then, or when the
item is purged, it's deleted for good. Only the account's own key or session can: a key acting for one of
your users gets `noclick.NotFound`.

Returns: `TrashItem` Its `TrashItem`: `restore()` puts it back live.

Usage:

Take down the pages whose automation is gone:

```python
for app in noclick.Project.list():
    if app.published and app.workflow is None:
        app.unpublish()
```

Or take one down, then change your mind:

```python
item = noclick.Project.from_name("bakery").unpublish()
item.restore()
```

## noclick.Deployment

```python
class Deployment
```

One build of a project at one commit. `status` goes `queued`,
`building`, then `ready` (serving at `url`), `failed` (`error`
says why) or `canceled`. `production` is True for the one serving the
project's own URL.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` |  |
| `project_id` | `str` |  |
| `branch` | `str` |  |
| `commit` | `str | None` | The sha it was built from. |
| `commit_message` | `str | None` |  |
| `status` | `str` |  |
| `url` | `str | None` | Where this deployment serves (a preview URL unless it's production). |
| `production` | `bool` |  |
| `environment` | `str` | `production` for a deploy of the production branch, `preview` for any other: whose secrets it was built with. A promoted preview keeps `preview` and serves with production's secrets. |
| `started_by` | `str` | `deploy` (a `deploy()`, or promoting a retired one) or `push` (the app deploys on push, see `Project.deploy_on_push`). |
| `error` | `str | None` | Why the build failed, or why a push couldn't deploy, in one line (None unless `failed`). |
| `failure` | `str | None` | Whose its failure is (None unless `failed`): `app` (its code, settings or config), `limit` (one of the app's limits: the build's time or memory, the size of its source or output) or `platform`, NoClick's own, which changing the app won't fix and which isn't charged. |
| `platform_error` | `bool` | True when it failed on NoClick's side (`failure` is `platform`): don't change the app to work around it; tell whoever it's for, with `error_id`. |
| `error_id` | `str | None` | The id NoClick's team finds a failure of its own by (None unless `platform_error`). |
| `fix` | `dict[str, str] | None` | What fixes a failure when it's a known change to the app (None otherwise). Today only `{"kind": "next_upgrade", "found": <the Next.js it asks for>, "needed": <a release that builds>}`: its `next_step` says how to upgrade it, or to hand it to the app's coding agent. |
| `runtime` | `str | None` | Where it runs: `edge` or `container`, chosen when its build starts (None until then). |
| `runtime_reason` | `str | None` | Why it runs there, in words: the app's pinned runtime, or what its commit has, its own scripts named (`the app's own Dockerfile describes its server, built as it's written`). |
| `created_at` | `Any` |  |
| `ready_at` | `Any` |  |
| `last_check` | `dict[str, Any] | None` | Its latest check, in short: `{operation_id, passed, url, checked_at, paths: [{path, ok, status, problem}]}`, with `code_unchecked` when its code never ran (None before its first). The check's operation has the whole of it; a promote's check is kept here too. |
| `serves` | `dict[str, str | None] | None` | Each URL it answers now: `{"production": <the app's URL, or None>, "preview": <its branch's preview URL, or None>}`. A promoted preview serves both, while its `environment` stays the one it was built for. |
| `warning` | `str | None` | On the deployment a deploy's or a promote's (a rollback's) `wait()` gives: it went live, but its home page didn't load as a visitor's browser would (an answer other than 2xx, a redirect to another site, a script or stylesheet it names that doesn't load as one), another page answered 500 or more, one of the app's `check_paths` answered other than it asks, or nothing answered, with the error the app logged then. A site of files with no `index.html` gets one too, though it may mean to serve only its files. It stays live (nothing is rolled back): `next_step` says what to fix. None when everything asked answered as asked, and on a deployment read later. |
| `next_step` | `str | None` | On the deployment a deploy's or a promote's `wait()` gives, beside its `warning`: what to fix, then deploy again. None otherwise. |
| `code_unchecked` | `str | None` | On the deployment a deploy's or a promote's `wait()` gives: its static files answered every path asked, so its server code never ran, and a broken API would pass unseen. Add a route its code answers to the app's `check_paths` as a request entry (`{"path": "/api/health", "status": 200}`). None otherwise. |
| `parked` | `list[str] | None` | On the deployment a rollback's `wait()` gives: the Durable Object classes production's objects have that this release is from before, parked rather than dropped. Their objects keep their data and answer that they're parked until a release that exports them serves production again, which takes them back. None otherwise. |
| `rebuilt` | `str | None` | On the deployment a promote of one past the rollback window gives: that one's release was no longer kept, so its commit was built again with the app's settings and secrets as they are now, as this deployment. None otherwise. |
| `settings_changed` | `str | None` | On the deployment a promote's (a rollback's) `wait()` gives: the app's settings changed since this release was built, named, so what its build read of them (a `VITE_` or `NEXT_PUBLIC_` value it put in its pages) is still as it was then; deploying production again builds with them. None otherwise. |
| `preview_link` | `str | None` | On the deployment a preview's deploy gives, when the app's `preview_access` is `link`: the link that opens the preview (its `url` with a token NoClick signed, good for 7 days), which is what to hand people; anyone else opening the preview is told it's private. None otherwise (`app.preview_link()` makes one any time). |
| `preview_data` | `str | None` | On the deployment a preview's deploy gives, when the app's `preview_resources` is `branch`: what the preview writes to (its own copies of what its code reaches, made at its first write), when the copies go to the trash, and that promoting never carries them to production. None for production, and for an app whose previews use production's resources. |
| `variables` | `dict[str, list[str]] | None` | The names each of its releases was given in its environment, by the environment it was released to (`{"production": [...], "preview": [...]}`): the app's settings and secrets, its bindings, a container's `DATABASE_URL` and NoClick's own. Never a value. |
| `databases` | `list[dict[str, Any]] | None` | On the deployment a container's deploy's or promote's (a rollback's) `wait()` gives, when the app binds databases: `{binding, engine, variable}` each. `variable` names where a Postgres database's connection URL reached the app (`DATABASE_URL`, or `<binding>_URL` when it binds several or sets `DATABASE_URL` itself), a login of the release's own that lasts as long as the release; a SQLite one has none (`variable` None), and its `note` says the code reaches it through the SDK. None otherwise. |

### Deployment.from_id

```python
noclick.Deployment.from_id(deployment_id, *, client=None, user=...) -> Deployment
```

A lazy reference to a deployment by id.

Parameters:

- `deployment_id` (`str`, required)
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: `Deployment` A deployment that loads the first time you read a field. Nothing is sent yet.

Usage:

```python
deployment = noclick.Deployment.from_id("0d6c2f8e-4b1a-4e97-a3c5-7f8e9d0c1b2a")
for line in deployment.logs(kind="build"):
    print(line.message)
```

### Deployment.get

```python
noclick.Deployment.get(deployment_id, *, user=..., client=None) -> Deployment
```

Load a deployment by id now; an unknown id raises `noclick.NotFound`.

Parameters:

- `deployment_id` (`str`, required)
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `Deployment` The deployment, loaded.

Usage:

```python
deployment = noclick.Deployment.get("0d6c2f8e-4b1a-4e97-a3c5-7f8e9d0c1b2a")
print(deployment.status, deployment.url, deployment.error)
```

### Deployment.logs

```python
deployment.logs(*, kind='build', limit=None, level=None, environment='all') -> LogLines
```

Its build output (`kind="build"`) or what it printed while
serving (`kind="runtime"`), oldest first. Of runtime lines, `level`
keeps `warn` or `error` lines only and `environment`
(`production` or `preview`) one environment's: a promoted preview
writes in both. A request's lines are never cut apart.

Parameters:

- `kind` (`str`, default `'build'`)
- `limit` (`int | None`, default `None`): Return at most this many.
- `level` (`str | None`, default `None`)
- `environment` (`str`, default `'all'`)

Returns: `LogLines` The lines, or the last `limit` of them, with `delay_s`: how long a runtime line can take to show.
A build keeps every line; runtime lines are kept 7 days.

Usage:

Find out why a build failed:

```python
deployment = noclick.Deployment.get("0d6c2f8e-4b1a-4e97-a3c5-7f8e9d0c1b2a")
if deployment.status == "failed":
    for line in deployment.logs(kind="build"):
        print(line.at, line.level, line.message)
```

Read the last errors a preview printed, each with the request it was in:

```python
preview = noclick.Deployment.from_id("0d6c2f8e-4b1a-4e97-a3c5-7f8e9d0c1b2a")
tail = preview.logs(kind="runtime", level="error", environment="preview", limit=20)
for line in tail:
    print(line.request_id, line.status, line.message)
if not tail:
    print(f"Nothing yet: a line takes up to {tail.delay_s}s to show.")
```

### Deployment.cancel

```python
deployment.cancel() -> Deployment
```

Stop a deployment that's still `queued` or `building`; one that
already finished is left as it is.

Returns: `Deployment` This deployment, `canceled` unless it had already finished.

Usage:

```python
deployment = noclick.Deployment.get("0d6c2f8e-4b1a-4e97-a3c5-7f8e9d0c1b2a")
deployment.cancel()
print(deployment.status)   # canceled
```

### Deployment.check

```python
deployment.check(
    paths=None, *, review=None, wait_for=None, settle_ms=None, headers=None,
    cookies=None
) -> Operation
```

Check up to 10 `paths` of this `ready` deployment where it serves (its preview URL, or the app's
URL when it's production), one after another. A path given as a string is a page, loaded in a browser:
its HTTP status, load time, console errors and a screenshot, kept as a file the chat shows. One given as
`{"path": "/api/health", "status": 200}` is what a plain request for it must answer (that status; else
any below 400), with `"json": True` for a JSON body: no browser, no screenshot. A page the app's files
serve never runs its code, so name the code's routes as requests. Without `paths`, the app's
`check_paths` (else its home page). A deployment no URL serves now can't be checked
(`noclick.Conflict`). The browser is billed at its provider's price, by the second.

`review` has a model look at the screenshots too, in one call billed at its price:
`{"brief": ...}` says what the site is for (who it's for and the idea it's built on), `"facts"` gives
the owner's own words about the business, and `"rubric": "app"` judges screens people use (their task,
forms, states, density, tap targets) instead of a site people read (`"site"`, the default). A page its
scripts draw after it loads is judged once an element matching the CSS selector `wait_for` shows (up to
20 seconds after it loads; one it never shows on fails), and `settle_ms` (1,000 unless given, at most
10,000) is how long each page is watched before its screenshot, its console errors until then counting.

A page behind a sign-in is checked signed in: `headers` (an `Authorization` header, say) go with each
request to the deployment's own address, never to another site, and `cookies` (each `{"name", "value", "path"}`, the path `/` unless given) are set on that address alone, httpOnly, and sent with
the request entries their path covers. They're secrets: sealed until the check runs, then dropped, never
in its result, its log or its operation.

Parameters:

- `paths` (`Sequence[str | Mapping[str, Any]] | None`, default `None`)
- `review` (`Mapping[str, Any] | None`, default `None`)
- `wait_for` (`str | None`, default `None`)
- `settle_ms` (`int | None`, default `None`)
- `headers` (`Mapping[str, str] | None`, default `None`)
- `cookies` (`Sequence[Mapping[str, str]] | None`, default `None`)

Returns: `Operation` An operation whose `.wait()` gives a `DeploymentCheck`; `passed` is False when a path failed
(`PathCheck.problem` says why), and its `review` has the model's scores and issues.

Usage:

Check the pages you changed before you say they work:

```python
preview = noclick.Project.from_name("booking").deploy(branch="new-form").wait()
checked = preview.check(["/", "/book"]).wait()
for page in checked.paths:
    print(page.path, page.status, page.problem, page.screenshot["url"])
    for error in page.console_errors:
        print("  ", error["kind"], error["message"])
```

Check the API the page calls, and have a model review the page:

```python
checked = preview.check(
    ["/", {"path": "/api/bookings", "status": 200, "json": True}],
    review={"brief": "A booking page for Le Comptoir, a bistro in Lyon"},
).wait()
print(checked.passed, checked.code_unchecked)
print(checked.review.scores, [issue["fix"] for issue in checked.review.issues])
```

Check a screen behind the app's sign-in, once it has drawn:

```python
checked = preview.check(
    ["/library"], wait_for="main#docs", cookies=[{"name": "session", "value": session_token}],
    review={"brief": "A study library for one pilot", "rubric": "app"},
).wait()
```

### Deployment.requests

```python
deployment.requests(*, since=None) -> RequestOutcomes
```

How the requests this deployment served went since `since` (a timezone-aware datetime; the last 24
hours when omitted, at most 7 days back): how many, by status, the error rate and the slowest routes.

Parameters:

- `since` (`str | datetime | None`, default `None`)

Returns: `RequestOutcomes` Its `RequestOutcomes`, read from NoClick's record of each request it answered, files included.

Usage:

See whether a release is failing in production:

```python
app = noclick.Project.from_name("booking")
outcomes = app.production.requests()
print(outcomes.requests, outcomes.error_rate, outcomes.by_status)
for route in outcomes.slowest_routes:
    print(route.method, route.path, route.p95_ms)
```

### Deployment.promote

```python
deployment.promote(*, force=False) -> Operation
```

Make this `ready` deployment the project's production one: its
URL starts serving this build within a minute. Promoting an older
production deployment is a rollback. Either way it's released again,
without a build, with production's settings, secrets and bindings as
they are now, so a key revoked since never comes back with it. Once
production serves it, its home page and the app's `check_paths` are
asked as a deploy asks them: the deployment's `warning` says what
answered wrong (it stays live). A rollback to a release from before one
of the app's Durable Object classes parks the class (`parked`).

An app with `check_paths` checks the deployment first (`check()`)
and doesn't promote one that fails: the operation fails with the check
in its error, and production keeps serving. `force=True` promotes it
without the check. Before production switches, the databases the app
binds are bookmarked: undoing the promote (`Operation.undo()`) puts
them back as they were, with the release before, taking out what was
written to them since and keeping it in the trash for 30 days as a
database copy each. The operation's `undo_rewinds` says that before
you undo, and the undo's result says it again (`warning`), with each
copy and how it goes back (`copies`).

Rollback covers the app's last 10 production deployments, and each
branch's newest preview for 30 days. One older than that was retired:
promoting it builds its commit again, checked as a promote is, and the
operation (`project.deploy`) gives the new deployment, whose
`rebuilt` says so.

Parameters:

- `force` (`bool`, default `False`)

Returns: `Operation` An operation whose `.wait()` gives this deployment (or, past the window, the one built
from its commit), now `production`.

Usage:

Put a preview live once you've checked it:

```python
app = noclick.Project.from_name("booking")
preview = app.deploy(branch="new-form").wait()
print(preview.url)   # check it here first
preview.promote().wait()
```

Take it back, data included, if it goes wrong:

```python
promoted = preview.promote()
promoted.wait()
promoted.undo()
```

## noclick.Schedule

```python
class Schedule
```

A project's cron job: NoClick POSTs `path` on the app on every tick
of `cron` (read in `tz`). When 5 runs in a row fail the same way over
at least 30 minutes it pauses itself (`status` `paused`,
`paused_reason` says why) until you `resume()` it.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` |  |
| `project_id` | `str` |  |
| `name` | `str` | What keys it within the project (the path unless you named it). |
| `cron` | `str` | The five-field cron expression. |
| `tz` | `str` |  |
| `path` | `str` |  |
| `status` | `str` | `active` or `paused`. |
| `paused_reason` | `str | None` |  |
| `next_run` | `Any` |  |
| `last_run` | `Any` |  |
| `last_status` | `str | None` | How the last run went: `succeeded` (a 2xx answer) or `failed` (None before the first). |
| `last_error` | `str | None` | Why the last run failed, in one line (`Answered 500.`); None after a success. |
| `created_at` | `Any` |  |

### Schedule.from_id

```python
noclick.Schedule.from_id(schedule_id, *, client=None, user=...) -> Schedule
```

A lazy reference to a schedule by id.

Parameters:

- `schedule_id` (`str`, required)
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).

Returns: `Schedule` A schedule that loads the first time you read a field. Nothing is sent yet.

Usage:

```python
schedule = noclick.Schedule.from_id("6a1f3c9e-2d4b-4e8a-b7c0-5d9e8f1a2b3c")
schedule.pause()
```

### Schedule.get

```python
noclick.Schedule.get(schedule_id, *, user=..., client=None) -> Schedule
```

Load a schedule by id now; an unknown id raises `noclick.NotFound`.

Parameters:

- `schedule_id` (`str`, required)
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `Schedule` The schedule, loaded.

Usage:

```python
schedule = noclick.Schedule.get("6a1f3c9e-2d4b-4e8a-b7c0-5d9e8f1a2b3c")
print(schedule.cron, schedule.tz, schedule.next_run, schedule.last_status)
```

### Schedule.pause

```python
schedule.pause() -> Schedule
```

Stop firing until `resume()`.

Returns: `Schedule` This schedule, `paused`.

Usage:

```python
schedule = noclick.Schedule.get("6a1f3c9e-2d4b-4e8a-b7c0-5d9e8f1a2b3c")
schedule.pause()
```

### Schedule.resume

```python
schedule.resume() -> Schedule
```

Fire again from the next tick, clearing `paused_reason`.

Returns: `Schedule` This schedule, `active`, with its `next_run`.

Usage:

Fix what made it fail, then resume it:

```python
app = noclick.Project.from_name("booking")
for schedule in app.schedules():
    if schedule.status == "paused":
        print(schedule.path, schedule.paused_reason)
        schedule.resume()
```

### Schedule.run_now

```python
schedule.run_now() -> Schedule
```

Call its path once now, outside the cron, and wait for the answer
(at most 30 seconds). A paused schedule runs too, and stays paused.

Returns: `Schedule` This schedule, with `last_run` and `last_status` from that call.

Usage:

```python
schedule = noclick.Schedule.get("6a1f3c9e-2d4b-4e8a-b7c0-5d9e8f1a2b3c")
schedule.run_now()
print(schedule.last_status)   # succeeded
```

### Schedule.delete

```python
schedule.delete() -> None
```

Delete the schedule; it stops firing.

Usage:

```python
schedule = noclick.Schedule.from_id("6a1f3c9e-2d4b-4e8a-b7c0-5d9e8f1a2b3c")
schedule.delete()
```

## noclick.DurableObjectClass

```python
class DurableObjectClass
```

One of an app's Durable Object classes in one environment (production's, or a preview branch's): its
`name`, the `binding` its code reaches it by, how many `objects` it has (`objects_more` when there were
more than were counted) and what they store (`stored_bytes`, the latest the host reported; None when it
couldn't be read). `status` is `trashed` while it's in the trash, `parked` while no release that serves
exports it (a rollback to a release from before it, or a live edit's release that added it and never went live),
and `stopped` while its environment's objects
are stopped (`stopped_for`: the app in the trash, or past its hard spending limit), their data kept. Its
objects' data is reached only by the app's own code.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` |  |
| `project_id` | `str` |  |
| `name` | `str` |  |
| `binding` | `str | None` | The name the app's code reaches it by (`env.ROOM`). |
| `environment` | `str` | `production` or `preview`. |
| `branch` | `str | None` | A preview's branch; None in production. |
| `status` | `str` | `live`, `trashed` while it's in the trash, `parked` (kept behind a stub, its data kept, while no release that serves exports it), or `stopped` (its environment's objects stopped, its data kept). |
| `stopped_for` | `str | None` | Why its objects are stopped: `trash`, or `budget` (the app past its hard spending limit); None when they run. |
| `objects_count` | `int | None` | How many objects it has; None when the host couldn't say. |
| `objects_more` | `bool` | More objects than were counted. |
| `stored_bytes` | `int | None` |  |
| `added_by_deployment_id` | `str | None` |  |
| `created_at` | `Any` |  |
| `parked_at` | `Any` |  |
| `trashed_at` | `Any` |  |
| `trash_id` | `str | None` | Its entry in the trash while it's there. |
| `restorable_until` | `Any` |  |

### DurableObjectClass.objects

```python
durable_object_class.objects(*, limit=100, cursor=None) -> Page[DurableObjectInstance]
```

A page of its objects, as the host lists them.

Parameters:

- `limit` (`int`, default `100`): Return at most this many.
- `cursor` (`str | None`, default `None`): The `next_cursor` of the page before; omit it for the first page.

Returns: `Page[DurableObjectInstance]` A page of `DurableObjectInstance`; pass `next_cursor` as `cursor` for the next.

Usage:

```python
app = noclick.Project.from_name("chat")
room = next(c for c in app.durable_objects() if c.name == "Room")
page = room.objects()
print([o.id for o in page.data if o.has_stored_data])
```

### DurableObjectClass.delete

```python
durable_object_class.delete() -> TrashItem
```

Move the class to the trash for 30 days: its objects and their data are kept, and every request and alarm
reaching it is refused meanwhile. A key from code, an agent or an MCP connection gets
`noclick.ApprovalRequired`: the account's owner approves it from the link NoClick sends them. Restore it
from the trash to have it back; a release that deletes the class (`deleted_classes`) deploys once it's
there.

Returns: `TrashItem` The trash entry, with `restore()`.

Usage:

```python
app = noclick.Project.from_name("chat")
old = next(c for c in app.durable_objects() if c.name == "OldRoom")
item = old.delete()
item.restore()   # changed your mind
```

## noclick.DurableObjectClasses

```python
class DurableObjectClasses(list[DurableObjectClass])
```

An app's classes; `unread` names a figure the host couldn't report this time (`stored_bytes` or
`objects`), left None on each class rather than shown as nothing; `cost` is what the app's Durable Objects
were charged this month, every environment's together (`{"usd", "period_start"}`; None with no classes).

| Attribute | Type | Description |
| --- | --- | --- |
| `unread` | `list[str]` |  |
| `cost` | `dict[str, Any] | None` |  |

## noclick.DurableObjectInstance

```python
class DurableObjectInstance
```

One object of a Durable Object class, as its host lists it: its `id` and whether it holds data. What it
stores is reached only by the app's own code.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` |  |
| `has_stored_data` | `bool` |  |

## noclick.ProjectSecrets

```python
class ProjectSecrets
```

`app.secrets`: values the running app reads from its environment by
name, set for production deployments, previews or both. Values are
write-only; nothing reads one back. An app's environment holds 128 values
in all, NoClick's own and each bound secret's included.

### ProjectSecrets.set

```python
app.secrets.set(name, value, *, environment='all') -> None
```

Set the secret `name` (letters, digits and `_`, starting with a
letter) to `value` (at most 5 KB), replacing any value it had, for
`environment`: `production` (deploys of the production branch, and
what's promoted), `preview` (every other branch) or `all`. It
reaches the app at the next deployment. Keep a larger value in a bound
`noclick.Secret` or bucket the app reads.

Parameters:

- `name` (`str`, required)
- `value` (`str`, required)
- `environment` (`str`, default `'all'`)

Usage:

The same key everywhere:

```python
app = noclick.Project.from_name("booking")
app.secrets.set("MAPS_API_KEY", "...")
app.deploy()
```

A live key in production and a test key in previews:

```python
app = noclick.Project.from_name("booking")
app.secrets.set("STRIPE_KEY", "sk_live_...", environment="production")
app.secrets.set("STRIPE_KEY", "sk_test_...", environment="preview")
```

### ProjectSecrets.list

```python
app.secrets.list(*, environment='all') -> dict[str, datetime]
```

The project's secrets by name, never their values: those set for
`environment` (`production`, `preview` or `all`).

Parameters:

- `environment` (`str`, default `'all'`)

Returns: `dict[str, datetime]` Each secret's name mapped to when its value was last set.

Usage:

```python
app = noclick.Project.from_name("booking")
for name, updated_at in app.secrets.list(environment="preview").items():
    print(name, updated_at)
```

### ProjectSecrets.delete

```python
app.secrets.delete(name, *, environment='all') -> None
```

Delete the secret `name` from `environment` (`all` by default);
the app stops seeing it at the next deployment. A name that isn't set
there raises `noclick.NotFound`.

Parameters:

- `name` (`str`, required)
- `environment` (`str`, default `'all'`)

Usage:

```python
app = noclick.Project.from_name("booking")
app.secrets.delete("MAPS_API_KEY")
```

### ProjectSecrets.versions

```python
app.secrets.versions(name, *, environment='all') -> list[Version]
```

What `name` held before each change or deletion of the last 30 days, newest first, in
`environment` (`production`, `preview` or `all`), never the values.

Parameters:

- `name` (`str`, required)
- `environment` (`str`, default `'all'`)

Returns: `list[Version]` Each earlier version, with its `environment`.

Usage:

```python
app = noclick.Project.from_name("booking")
for version in app.secrets.versions("STRIPE_KEY", environment="production"):
    print(version.op, version.replaced_at)
```

### ProjectSecrets.restore

```python
app.secrets.restore(name, version) -> None
```

Set `name` back to `version`'s value in its environment (deleted since, it's back). It reaches the
app at the next deployment.

Parameters:

- `name` (`str`, required)
- `version` (`Any`, required)

Usage:

Undo deleting a secret:

```python
app = noclick.Project.from_name("booking")
app.secrets.delete("MAPS_API_KEY")
app.secrets.restore("MAPS_API_KEY", app.secrets.versions("MAPS_API_KEY")[0])
```

## noclick.ProjectSettings

```python
class ProjectSettings
```

`app.settings`: plain values the running app reads from its environment by
name, such as a feature flag or a public URL. Unlike `app.secrets` they read back,
and they show in the console; put anything sensitive in `app.secrets`.

### ProjectSettings.set

```python
project_settings.set(name, value) -> None
```

Set `name` (letters, digits and `_`, starting with a letter; not a secret's
name) to `value` (at most 4 KB). It reaches the app at the next deployment.

Parameters:

- `name` (`str`, required)
- `value` (`str`, required)

Usage:

```python
app = noclick.Project.from_name("booking")
app.settings.set("PUBLIC_BASE_URL", "https://book.acme.com")
app.deploy()
```

### ProjectSettings.list

```python
project_settings.list() -> dict[str, str]
```

The project's settings and their values.

Returns: `dict[str, str]` Each setting's name mapped to its value.

Usage:

```python
app = noclick.Project.from_name("booking")
for name, value in app.settings.list().items():
    print(name, value)
```

### ProjectSettings.delete

```python
project_settings.delete(name) -> None
```

Delete the setting `name`; the app stops seeing it at the next deployment.
A name that isn't set raises `noclick.NotFound`.

Parameters:

- `name` (`str`, required)

Usage:

```python
app = noclick.Project.from_name("booking")
app.settings.delete("PUBLIC_BASE_URL")
```

### ProjectSettings.versions

```python
project_settings.versions(name) -> list[Version]
```

What `name` held before each change or deletion of the last 30 days, newest first, with each
`value`.

Parameters:

- `name` (`str`, required)

Returns: `list[Version]` Each earlier version.

Usage:

```python
app = noclick.Project.from_name("booking")
print([v.value for v in app.settings.versions("PUBLIC_BASE_URL")])
```

### ProjectSettings.restore

```python
project_settings.restore(name, version) -> str
```

Set `name` back to `version`'s value (deleted since, it's back). It reaches the app at the next
deployment.

Parameters:

- `name` (`str`, required)
- `version` (`Any`, required)

Returns: `str` The value it holds again.

Usage:

```python
app = noclick.Project.from_name("booking")
app.settings.restore("PUBLIC_BASE_URL", app.settings.versions("PUBLIC_BASE_URL")[0])
```

## noclick.ProjectAI

```python
class ProjectAI
```

`app.ai`: `noclick.AI` acting as the app, from the app's own code
(`Project.current()`). Every call is billed to your account and attributed to the app
and its user: it counts toward the app's `budget_usd_per_month` and its user's cap, and
raises `noclick.SpendCapExceeded` once either is used up (`noclick.PaymentRequired`
once your account's balance is). Only the app acts as the app: on a project reached with
your own key, each call raises `noclick.InvalidRequest` (use `noclick.AI` there,
inside `as_user` for the app's user).

| Attribute | Type | Description |
| --- | --- | --- |
| `base_url` | `str` | The OpenAI-compatible endpoint, for an OpenAI client in the app's code; pair it with `headers()`, which carry the deployment's credential. |

### ProjectAI.chat

```python
app.ai.chat(
    messages, *, model=None, max_tokens=None, temperature=None, response_format=None,
    tools=None, tool_choice=None, reasoning_effort=None, conversation=None
) -> ChatReply
```

`noclick.AI.chat` as the app, with the same arguments. `model="agent:<name>"`
reaches only an agent bound to the app, in the app's own conversations.

Parameters:

- `messages` (`str | Sequence[Any]`, required)
- `model` (`str | None`, default `None`)
- `max_tokens` (`int | None`, default `None`)
- `temperature` (`float | None`, default `None`)
- `response_format` (`dict[str, Any] | None`, default `None`)
- `tools` (`Sequence[dict[str, Any]] | None`, default `None`)
- `tool_choice` (`str | dict[str, Any] | None`, default `None`)
- `reasoning_effort` (`str | None`, default `None`)
- `conversation` (`str | None`, default `None`)

Returns: `ChatReply` The answer: its `text`, the `message` to append, and what it cost.

Usage:

Summarize a review in a request handler:

```python
app = noclick.Project.current()
reply = app.ai.chat("Summarize in one line: the class was great but the room was cold.")
print(reply.text)
```

Serve the page without the summary once the app's budget is used up:

```python
app = noclick.Project.current()
try:
    summary = app.ai.chat("Summarize in one line: the class was great but the room was cold.").text
except (noclick.SpendCapExceeded, noclick.PaymentRequired):
    summary = None
```

### ProjectAI.embed

```python
app.ai.embed(texts, *, model=None, dimensions=None) -> Embeddings
```

`noclick.AI.embed` as the app.

Parameters:

- `texts` (`str | Sequence[str]`, required)
- `model` (`str | None`, default `None`)
- `dimensions` (`int | None`, default `None`)

Returns: `Embeddings` One vector per text, in order, with their length and what the call cost.

Usage:

```python
app = noclick.Project.current()
[vector] = app.ai.embed("Yoga for beginners on Saturday mornings").vectors
classes = app.database("DB").query(
    "select id, title from classes order by embedding <=> cast(? as halfvec) limit 5", [vector])
```

### ProjectAI.image

```python
app.ai.image(prompt, *, model=None, size=None, images=None) -> GeneratedImage
```

`noclick.AI.image` as the app.

Parameters:

- `prompt` (`str`, required)
- `model` (`str | None`, default `None`)
- `size` (`str | None`, default `None`)
- `images` (`Sequence[str] | None`, default `None`)

Returns: `GeneratedImage` The image: a signed `url` that lasts 24 hours, its size and what it cost.

Usage:

```python
app = noclick.Project.current()
image = app.ai.image("A sunlit yoga studio, watercolor", size="1024x1024")
print(image.url, image.cost_usd)
```

### ProjectAI.transcribe

```python
app.ai.transcribe(audio, *, model=None, language=None, speakers=False) -> Transcript
```

`noclick.AI.transcribe` as the app: an `https` URL to a recording, or its bytes.

Parameters:

- `audio` (`str | bytes`, required)
- `model` (`str | None`, default `None`)
- `language` (`str | None`, default `None`)
- `speakers` (`bool | Sequence[str]`, default `False`)

Returns: `Transcript` The transcript: its `text`, timed `segments`, the `language` and how long the audio was.

Usage:

```python
app = noclick.Project.current()
words = app.ai.transcribe("https://booking.noclick.site/uploads/voicemail-1042.m4a", language="en")
print(words.text)
```

### ProjectAI.models

```python
app.ai.models(*, kind=None) -> list[AIModel]
```

The models the app can call, as `noclick.AI.models` lists them; `kind="agent"`
lists the agents bound to it.

Parameters:

- `kind` (`str | None`, default `None`)

Returns: `list[AIModel]` Every matching model with its prices in US dollars, the default of each kind first.

Usage:

```python
app = noclick.Project.current()
for m in app.ai.models(kind="chat"):
    print(m.id, m.input_usd_per_token, m.output_usd_per_token)
```

### ProjectAI.headers

```python
app.ai.headers() -> dict[str, str]
```

The headers an OpenAI client in the app's code sends to `base_url`: the
deployment's credential as the bearer, so every call is the app's.

Returns: `dict[str, str]` `Authorization`.

Usage:

Code written for OpenAI's client works as the app:

```python
from openai import OpenAI

app = noclick.Project.current()
gpt = OpenAI(base_url=app.ai.base_url, api_key="-", default_headers=app.ai.headers())
answer = gpt.chat.completions.create(
    model="openrouter/anthropic/claude-sonnet-4.6", messages=[{"role": "user", "content": "Hi"}])
```

## noclick.Binding

```python
class Binding
```

A resource the running app reads by `name`: a `database`, `bucket`, `dict`,
`queue`, `secret`, `connection` or `agent` (`kind`), with its `resource_id`
and `resource_name`.

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `str` |  |
| `kind` | `str` |  |
| `resource_id` | `str` |  |
| `resource_name` | `str | None` |  |
| `variables` | `list[str]` | The variables the app's code reads it as from its next deployment: its `name`, or for a secret each of its keys under the key's own name (`name` only lists it). |
| `created_at` | `Any` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.LogLine

```python
class LogLine
```

One line an app printed, or its build did: when (`at`), its `level`
(`info`, `warn` or `error`), the `message`, and the deployment it came from.
A line written while serving also names its `environment` (`production` or
`preview`) and the request it was written in (`request_id`, shared by that
request's lines); the host's own line for a request carries the `status` it
answered (0 when it never did).

| Attribute | Type | Description |
| --- | --- | --- |
| `at` | `Any` |  |
| `level` | `str` |  |
| `message` | `str` |  |
| `deployment_id` | `str | None` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |
| `environment` | `str | None` |  |
| `request_id` | `str | None` |  |
| `status` | `int | None` |  |

## noclick.LogLines

```python
class LogLines(list[LogLine])
```

The lines a log read returns, oldest first: a list of `LogLine`, with how long a line can take to show.

| Attribute | Type | Description |
| --- | --- | --- |
| `delay_s` | `int | None` | Up to how many seconds a line takes to show after a request writes it (the host's logs lag its requests): a read that's empty, or misses a request just made, may only be early. None for a build's log, which is kept whole as it's written. |

## noclick.ProjectUsage

```python
class ProjectUsage
```

What an app spent this month so far, against its budget: `requests` served,
`cpu_ms` of compute, everything it cost in `usd`, and the `period_start` it
counts from.

| Attribute | Type | Description |
| --- | --- | --- |
| `requests` | `int` |  |
| `cpu_ms` | `int` |  |
| `usd` | `float` | Everything the app spent: hosting, builds, its calls to what it's bound to, its email, its AI and its agent turns. |
| `period_start` | `Any` |  |
| `budget_usd` | `float | None` | Its `budget_usd_per_month` (None without one). |
| `limited_by` | `str | None` | What refuses its paid calls now: `project` (its budget is used up), `user` (its user's cap is) or `account` (your account's balance is); None while they go through. |
| `by_type` | `dict[str, float]` | `usd` split by the spend types of `Usage.series(group_by="type")`: `apps`, `ai`, `model_tokens`, ... |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.DeploymentCheck

```python
class DeploymentCheck
```

What `Deployment.check()` saw where the deployment serves (`url`): `passed` when every path did,
each path's `PathCheck`, and what it cost (`cost_usd`: the browser at its provider's price by the second,
and the review's model call).

| Attribute | Type | Description |
| --- | --- | --- |
| `deployment_id` | `str` |  |
| `url` | `str` |  |
| `passed` | `bool` |  |
| `paths` | `list[PathCheck]` |  |
| `checked_at` | `Any` |  |
| `cost_usd` | `float` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |
| `review` | `CheckReview | None` | The review of its screenshots, when the check asked for one (`review=`). |
| `code_unchecked` | `str | None` | Set when every path passed but the release's static files answered each of them, so the app's server code never ran: a broken API behind a working home page passes such a check. Name a route its code answers as a request entry (`{"path": "/api/health", "status": 200}`) to check the code too. |

## noclick.PathCheck

```python
class PathCheck
```

One path a check asked: a page, loaded in a browser, or a request entry of the check's paths, asked with a
plain request (`expected` says what it had to answer). Where it ended (`url`), its HTTP `status`, how long
it took (`load_ms`, None when it didn't load or answer within 30 seconds), and of a page its `title`, the
errors its console showed and a `screenshot`. `ok` is False when a page answered 400 or more, didn't load, a
script threw and nothing caught it, what the check waits for (`wait_for`) never showed, or a picture it shows
doesn't (`broken_images`), and when a request entry answered other than it asks; `problem` says which. Other
console errors are reported without failing it.

| Attribute | Type | Description |
| --- | --- | --- |
| `path` | `str` |  |
| `url` | `str` |  |
| `ok` | `bool` |  |
| `problem` | `str | None` |  |
| `status` | `int | None` |  |
| `load_ms` | `int | None` |  |
| `title` | `str | None` |  |
| `console_errors` | `list[dict[str, str]]` | Each `{"kind", "message"}`: `exception` (uncaught), `console` (`console.error`) or `browser` (a file that failed to load, ...). |
| `screenshot` | `dict[str, Any] | None` | The screenshot, an account file the chat shows: `{"id", "name", "url", "mime_type", ...}` (None when the page couldn't be opened at all, and for a request entry). |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |
| `broken_images` | `list[str]` | The pictures the page shows that a browser can't (a missing file, or text committed in an image's place), each the site's own path (its URL when it's elsewhere); any fails the path. |
| `undeliverable_emails` | `list[str]` | Each address the page shows (a `mailto:` link or its text) whose domain takes no mail (no MX record), reported without failing it. |
| `expected` | `dict[str, Any] | None` | A request entry's `{"status", "json"}`, as far as it asks them (`{}`: any status below 400); None for a page. |

## noclick.CheckReview

```python
class CheckReview
```

What a model made of a check's screenshots (`Deployment.check(review=...)`), against NoClick's design
rubric for a site or an app: each criterion's score from 1 to 5 (under 4 a defect), the issues to fix, most
important first, and of a site the `claims` its pages make that neither its brief nor the owner's words give.
`passed` is True when every score is 4 or more. A review that couldn't answer has its `error` instead, and
leaves the check as it was.

| Attribute | Type | Description |
| --- | --- | --- |
| `model` | `str` | The model that looked. |
| `passed` | `bool | None` | None when the review couldn't answer (`error` says why). |
| `scores` | `dict[str, int]` | Each criterion's score, 1-5: a site's `belongs`, `first_screen`, `type`, `colour`, `images`, `phone`, `finish` and `generated`; an app's `task`, `forms`, `states`, `density`, `touch`, `type`, `navigation` and `finish`. |
| `issues` | `list[dict[str, str]]` | Each `{"where", "what", "fix"}`, the most important first. |
| `claims` | `list[dict[str, str]]` | A site's facts on its pages (a name, number, price, hour, quote) that neither the brief nor the owner's words give, each `{"where", "what"}`: listed, never scored. Empty for an app. |
| `error` | `str | None` |  |
| `cost_usd` | `float` | What the model's call cost, counted in the check's `cost_usd` too. |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.RequestOutcomes

```python
class RequestOutcomes
```

How the requests a deployment served between `since` and `until` went: how many, by HTTP status
(`by_status`: `{"200": 120, "500": 2, "none": 1}`, `none` for one never answered), the `errors` (an
answer of 500 or more, or none) and their `error_rate`, and the `slowest_routes` by their 95th-percentile
time. `sampled`: there were more than the 2,000 newest it read, or the record of a very busy app is a
sample, each request in it counted for the ones it stands for.

| Attribute | Type | Description |
| --- | --- | --- |
| `requests` | `int` |  |
| `errors` | `int` |  |
| `error_rate` | `float | None` |  |
| `by_status` | `dict[str, int]` |  |
| `slowest_routes` | `list[RouteTiming]` |  |
| `sampled` | `bool` |  |
| `since` | `Any` |  |
| `until` | `Any` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.RouteTiming

```python
class RouteTiming
```

One route's requests: how many, how many failed (`errors`), and their times in milliseconds.

| Attribute | Type | Description |
| --- | --- | --- |
| `method` | `str` |  |
| `path` | `str` |  |
| `requests` | `int` |  |
| `errors` | `int` |  |
| `p50_ms` | `float` |  |
| `p95_ms` | `float` |  |
| `max_ms` | `float` |  |

## noclick.ProjectAnalytics

```python
class ProjectAnalytics
```

How an app's traffic went over a `period` (`24h`, `7d` or `30d`, from `since` up to `until`):
the `requests` its sites answered and the `errors` among them (an answer of 500 or more, or none) with their
`error_rate`, `by_status` (`{"200": 1180, "404": 21, "none": 1}`), how long answers took to begin
(`p50_ms`, `p95_ms`), each `interval`'s (`hour` or `day`, starting in `tz`) in `series`, the
busiest `top_paths`, and the same length of time just before `since` (`previous_requests`,
`previous_errors`) to compare with. Counted from NoClick's record of every request, its files and API calls
included: requests, not visitors. `by_source` says who made them as their user agents say: `browser` (a
person's browser, or a program that says it's one) and `automated` (curl, an HTTP library, a headless browser,
a crawler), and `unknown` for any recorded before NoClick told them apart. NoClick's own checks of the app are
in no figure but `noclick_requests`. `sampled`: a very busy app's record is a sample, each request in it
counted for the ones it stands for.

| Attribute | Type | Description |
| --- | --- | --- |
| `period` | `str` |  |
| `environment` | `str` |  |
| `interval` | `str` |  |
| `tz` | `str` |  |
| `since` | `Any` |  |
| `until` | `Any` |  |
| `requests` | `int` |  |
| `errors` | `int` |  |
| `error_rate` | `float | None` |  |
| `by_status` | `dict[str, int]` |  |
| `p50_ms` | `float | None` |  |
| `p95_ms` | `float | None` |  |
| `series` | `list[TrafficInterval]` |  |
| `top_paths` | `list[PathTraffic]` |  |
| `previous_requests` | `int` |  |
| `previous_errors` | `int` |  |
| `sampled` | `bool` |  |
| `by_source` | `dict[str, int]` |  |
| `noclick_requests` | `int` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.TrafficInterval

```python
class TrafficInterval
```

One hour or day of an app's traffic: the `requests` from `at` on, and how many of them failed
(`errors`: an answer of 500 or more, or none).

| Attribute | Type | Description |
| --- | --- | --- |
| `at` | `Any` |  |
| `requests` | `int` |  |
| `errors` | `int` |  |

## noclick.PathTraffic

```python
class PathTraffic
```

One of an app's busiest paths: its requests, how many failed, their 95th-percentile time in milliseconds,
and how many of them a browser made (`browser_requests`).

| Attribute | Type | Description |
| --- | --- | --- |
| `path` | `str` |  |
| `requests` | `int` |  |
| `errors` | `int` |  |
| `p95_ms` | `float | None` |  |
| `browser_requests` | `int` |  |

## noclick.AnalyticsSummary

```python
class AnalyticsSummary
```

Every app's requests over a `period` (from `since` up to `until`, days starting in `tz`), read at once:
`apps` newest first, an app nobody reached at 0. `of(app)` is one app's. Requests, not visitors, NoClick's
own checks left out. `sampled`: a very busy app's record is a sample, each request in it counted for the ones it
stands for.

| Attribute | Type | Description |
| --- | --- | --- |
| `period` | `str` |  |
| `tz` | `str` |  |
| `since` | `Any` |  |
| `until` | `Any` |  |
| `apps` | `list[AppRequests]` |  |
| `sampled` | `bool` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

### AnalyticsSummary.of

```python
analytics_summary.of(app) -> AppRequests
```

One app's line in the summary.

Parameters:

- `app` (`Any`, required)

Returns: `AppRequests` The `AppRequests` of `app` (a `Project` or its id); one the summary didn't cover reads as 0.

Usage:

```python
week = noclick.Project.analytics_summary()
app = noclick.Project.from_name("booking")
print(week.of(app).requests, week.of(app).errors)
```

## noclick.AppRequests

```python
class AppRequests
```

One app's requests to its production site over a summary's period, how many failed and how many a browser
made; NoClick's own checks of it are in none of them but `noclick_requests`.

| Attribute | Type | Description |
| --- | --- | --- |
| `project_id` | `str` |  |
| `requests` | `int` |  |
| `errors` | `int` |  |
| `browser_requests` | `int` |  |
| `noclick_requests` | `int` |  |

## noclick.PreviewLink

```python
class PreviewLink
```

A link that opens a preview of an app to whoever holds it, until `expires_at`: the preview's address
carrying a token NoClick signed for it. The browser that opens it keeps a cookie for that preview alone. On an app
whose `preview_access` is `link` it's the only way in (but for its `preview_public_paths`); on a public
app's preview the address alone opens it too.

| Attribute | Type | Description |
| --- | --- | --- |
| `url` | `str` |  |
| `branch` | `str` |  |
| `preview_url` | `str` | The preview's own address, which tells anyone without the link that it's private. |
| `preview_access` | `str` | `public` or `link`: the app's `preview_access` when the link was made. |
| `expires_at` | `Any` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.ProjectContainer

```python
class ProjectContainer
```

How each instance of an app runs in a container, and what its warm instances cost: the `cpu` and
`memory` each instance gets, how many are kept running (`min_instances`) and how many it may grow to
(`max_instances`), whether its CPU runs between requests too (`cpu_always`), and how long a request may take
(`request_timeout_s`). Changed with `update(container=...)`, `min_instances` applies at once, to the release
production serves; the rest from the app's next release (a deploy, or a promote). An app on the edge has them
too: they size its releases in a container.

| Attribute | Type | Description |
| --- | --- | --- |
| `cpu` | `float` | vCPUs per instance: 0.5 to 8 (1, 2, 4, 6 or 8; under 1 in steps of 0.01, where each instance answers one request at a time). 1 unless set. |
| `memory` | `int` | Memory per instance, in MiB, from 512: up to 1024 under 1 vCPU, 4096 at 1, 8192 at 2, 2048 to 16384 at 4, 4096 to 24576 at 6 and 4096 to 32768 at 8. 512 unless set. |
| `min_instances` | `int` | Instances kept running while production serves it, whether or not anything calls it, so no request waits for one to start: 0 to 3. 0 unless set. |
| `max_instances` | `int` | The most instances it runs at once: 1 to 10. 10 unless set. |
| `cpu_always` | `bool` | Whether its CPU runs between requests too, for work that goes on without one (a bot, a queue worker, a loop): each instance is then billed from start to stop. Takes 1 vCPU or more. False unless set. |
| `request_timeout_s` | `int` | How long a request may take, in seconds: 1 to 3600. 300 unless set. |
| `idle_usd_per_month` | `float` | What its warm instances cost a month with nothing calling it, in US dollars, at the price where it runs: 0 with none kept warm. |
| `note` | `str | None` | What its settings cost or change beyond each request, in a sentence: the instances kept warm and their price, that under 1 vCPU each instance answers one request at a time, or that an app pinned to the edge doesn't use them. None when there's nothing to say. |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.ProjectEmail

```python
class ProjectEmail
```

`app.email`: transactional email from the app's own address (receipts, booking
confirmations), rate-capped and charged per recipient; a high bounce or complaint rate
pauses sending. One-time sign-in codes go through `send_code`, on a lane of their own.
Newsletters and announcements go through `broadcast`, on a stream of their own, so they
never hold up a receipt.

Usage:

```python
app = noclick.Project.from_name("booking")
email = app.email   # this app's noclick.ProjectEmail
email.enable(domain="acmebooking.com", from_address="bookings@acmebooking.com")
email.send(to="ana@example.com", subject="Your booking", text="See you Friday at 3pm.")
```

### ProjectEmail.enable

```python
app.email.enable(
    *, domain=None, from_address=None, from_name=None, postal_address=None
) -> EmailSetup
```

Turn email on for the app, or change what you pass (the rest keeps its value).
Without a `domain` the app sends from its default address
(`noreply@booking.noclick.site`). With one (a `Domain` or its name), mail goes from
`from_address` on it, `noreply@<domain>` unless you pass one, and broadcasts go from
the same name on its `news.` subdomain, so their reputation stays apart from receipts'.
The first call answers `pending` while NoClick sets up the app's sending (what it
sends meanwhile goes out once that's done). A domain bought through NoClick gets its
DNS records written for it and turns `active` within minutes; any other is connected
for you, and `records` lists what to add at its DNS host (within seconds of this call).

`domain` may also be a subdomain of a domain your account holds
(`mail.ana.acmebooking.com` under the account's `acmebooking.com`), for any
project, a user's included; only a key acting for the whole account may choose one.
Its records are written for you under a bought domain, and listed in `records` under
a connected one. `postal_address` is the address every broadcast's footer carries,
as the law asks of bulk mail; `broadcast` needs one.

Parameters:

- `domain` (`Any`, default `None`)
- `from_address` (`str | None`, default `None`)
- `from_name` (`str | None`, default `None`)
- `postal_address` (`str | None`, default `None`)

Returns: `EmailSetup` The setup: `active` when the app can send now, `pending` while NoClick sets up
its sending (what it sends meanwhile goes out once that's done), or `pending_dns`
while the domain's `records` aren't seen yet.

Usage:

Send from your own domain:

```python
app = noclick.Project.from_name("booking")
setup = app.email.enable(domain="acmebooking.com", from_address="bookings@acmebooking.com", from_name="Acme Booking")
print(setup.status, setup.from_address)
```

A domain hosted elsewhere waits for its DNS records:

```python
app = noclick.Project.from_name("booking")
setup = app.email.enable(domain="acme.test")
for record in setup.records:
    print(record.type, record.name, record.value)
```

### ProjectEmail.status

```python
app.email.status() -> EmailSetup
```

Read how the app sends email, checking the domain's DNS records again.

Returns: `EmailSetup` The current setup; `status` is `off` if email was never enabled.

Usage:

```python
app = noclick.Project.from_name("booking")
setup = app.email.status()
if setup.status == "pending_dns":
    print("Still waiting for", [record.name for record in setup.records])
```

### ProjectEmail.send

```python
app.email.send(
    to, subject, *, text=None, html=None, reply_to=None, time_sensitive=False,
    idempotency_key=None
) -> SentEmail
```

Send one message to `to` (an address, or a list of up to 10 that each
receive it) with a `text` body, an `html` one, or both. Email must be
`active`, or `pending` (the message waits and goes once sending is set up):
`noclick.ActionRequired` while the domain's records are pending,
`noclick.RateLimited` past the daily limit.

While the account can't pay (out of funds, or at a spend cap) the message is
`held`, sent and charged once it can, so a form never fails on it. A message
only worth getting now (a magic link, a password reset) passes
`time_sensitive=True` and is refused instead (`noclick.PaymentRequired`).

Parameters:

- `to` (`str | Sequence[str]`, required)
- `subject` (`str`, required)
- `text` (`str | None`, default `None`)
- `html` (`str | None`, default `None`)
- `reply_to` (`str | None`, default `None`)
- `time_sensitive` (`bool`, default `False`)
- `idempotency_key` (`str | None`, default `None`): Makes a retried create safe: the same key returns the first result. Generated when omitted.

Returns: `SentEmail` The message as accepted, usually `queued` (`held` while the account can't
pay); `messages()` shows whether it was delivered.

Usage:

Pass an `idempotency_key` so a retried request can't send twice:

```python
app = noclick.Project.from_name("booking")
sent = app.email.send(
    to="ana@example.com",
    subject="Your booking is confirmed",
    text="See you Friday at 3pm.",
    html="<p>See you <b>Friday at 3pm</b>.</p>",
    idempotency_key="booking-1042-confirmation",
)
print(sent.id, sent.status)
```

### ProjectEmail.send_code

```python
app.email.send_code(
    to, code, *, purpose='sign_in', expires_in_s=None, idempotency_key=None
) -> SentEmail
```

Send a one-time `code` (4-12 letters and digits) to `to`, in a short message NoClick
writes in the app's name: `purpose` `sign_in` or `verify_email`, and `expires_in_s`
said in it when you pass one. Codes have a daily limit of their own, apart from
`daily_limit`, so a new app's sign-ins never wait on its other mail; one address gets at
most 5 codes in 15 minutes (`noclick.RateLimited`). Each is charged as one message.
`app.sign_in` sends its codes this way.

Parameters:

- `to` (`str`, required)
- `code` (`str`, required)
- `purpose` (`str`, default `'sign_in'`)
- `expires_in_s` (`int | None`, default `None`)
- `idempotency_key` (`str | None`, default `None`): Makes a retried create safe: the same key returns the first result. Generated when omitted.

Returns: `SentEmail` The message, `kind` `code`; its subject names the purpose, never the code.

Usage:

```python
app = noclick.Project.current()
app.email.send_code("ana@example.com", "482913", expires_in_s=300)
```

### ProjectEmail.messages

```python
app.email.messages(*, to=None, limit=50, environment=None) -> list[SentEmail]
```

The messages the app sent, newest first; `to` keeps those sent to one address, and
`environment` (`production` or `preview`) those its production or its previews sent.

A preview's code reaches only the account's own people, so `environment="preview"` is
its outbox: each message names the recipients it kept in `captured`, with the `text`
and `html` it would have sent.

Parameters:

- `to` (`str | None`, default `None`)
- `limit` (`int | None`, default `50`): Return at most this many.
- `environment` (`str | None`, default `None`)

Returns: `list[SentEmail]` Up to `limit` messages (50 unless you say; `None` reads them all), each with
its delivery `status`, whether it was `opened` and why it `bounced`.

Usage:

```python
app = noclick.Project.from_name("booking")
for message in app.email.messages(to="ana@example.com", limit=10):
    print(message.at, message.subject, message.status, message.opened)
for kept in app.email.messages(environment="preview"):
    print(kept.captured, kept.subject, kept.text)
```

### ProjectEmail.broadcast

```python
app.email.broadcast(
    to, subject, *, idempotency_key, text=None, html=None, reply_to=None
) -> Operation
```

Send one message to many people who asked for it: a newsletter, an announcement.
`to` holds up to 50,000 addresses, and listing them says each one opted in to mail
from the app. Anyone who unsubscribed from its broadcasts (until they opt in again and you
`resubscribe` them), bounced or marked one as spam is skipped. It goes out on a bulk
stream of its own, under `broadcast_daily_limit`, from `broadcast_from_address` on the
domain's `news.` subdomain, so a campaign's complaints never pause the app's transactional
mail. It needs a domain of the app's own (`noclick.ActionRequired` on the default sender).
Every message carries its recipient's own `List-Unsubscribe` header, with one-click
unsubscribe, and a footer with an unsubscribe link and the `postal_address` from
`enable()` (`noclick.ActionRequired` until there is one). Unsubscribing stops
broadcasts, never receipts. It goes out at the pace mail can be sent, so a large one takes
minutes.

`idempotency_key` names the broadcast: sending again with the same key sends nothing
new, so a job that crashes halfway can simply run again.

Parameters:

- `to` (`Sequence[str]`, required)
- `subject` (`str`, required)
- `idempotency_key` (`str`, required): Makes a retried create safe: the same key returns the first result. Generated when omitted.
- `text` (`str | None`, default `None`)
- `html` (`str | None`, default `None`)
- `reply_to` (`str | None`, default `None`)

Returns: `Operation` An operation whose `.wait()` gives the `Broadcast`: how many it was sent to and who
was skipped, and why.

Usage:

```python
app = noclick.Project.from_name("booking")
subscribers = [row["email"] for row in app.database("DB").query("select email from subscribers")]
result = app.email.broadcast(
    subscribers, "What's new at Acme Booking",
    html="<h1>Group bookings are here</h1><p>Book for up to 12 people at once.</p>",
    idempotency_key="newsletter-2026-10",
).wait()
print(result.sent, len(result.skipped))
```

### ProjectEmail.resubscribe

```python
app.email.resubscribe(address) -> bool
```

Lift `address`'s unsubscribe from the app's broadcasts, once they've asked for them
again and confirmed it: a click on a link you emailed that address, as when they first
subscribed. Mail after an unsubscribe is spam unless the person opted in again, so call it
only on a confirmed opt-in. A bounce or a spam complaint isn't lifted.

Parameters:

- `address` (`str`, required)

Returns: `bool` `True` if the address was unsubscribed and now gets broadcasts again, `False` if it
wasn't unsubscribed.

Usage:

```python
app = noclick.Project.from_name("newsletter")
# Ana clicked the confirmation link you emailed her after she signed up again.
if app.email.resubscribe("ana@example.com"):
    print("Ana gets the newsletter again")
```

## noclick.EmailSetup

```python
class EmailSetup
```

How an app sends email: the sender, its domain's DNS records and whether it can send.
`status` is `off` (never enabled), `pending` (NoClick is setting up the app's sending,
usually within a minute; mail sent meanwhile goes out once it's set up, and `pending_reason`
says why when setting it up failed), `pending_dns` (the domain's records aren't seen yet: a
domain bought through NoClick gets them written and turns `active` within minutes),
`active`, or `paused` (too many bounces or spam complaints; `paused_reason` says which:
`bounce_rate`, `complaint_rate`, `mailbox_provider_feedback` or `blocklisted`).
Broadcasts go out apart, from the domain's `news.` subdomain, with a status of their own.

| Attribute | Type | Description |
| --- | --- | --- |
| `status` | `str` |  |
| `from_address` | `str | None` | The address mail goes out from, like `bookings@acmebooking.com`. |
| `from_name` | `str | None` | The display name recipients see, like `Acme Booking`. |
| `domain` | `str | None` | The sending domain; `None` while the app uses its default sender. |
| `records` | `list[DnsRecord]` | What DNS must hold for mail to send and land: DKIM and a bounce subdomain (MX and SPF) for the domain and for its `news.` subdomain, and a recommended DMARC policy. |
| `daily_limit` | `int | None` | How many messages the app may send a day; it grows as its mail keeps landing. |
| `sent_today` | `int | None` | How many it has sent since midnight UTC. |
| `paused_reason` | `str | None` |  |
| `pending_reason` | `str | None` | Why the app's sending isn't set up yet, once setting it up failed (NoClick keeps trying); else `None`. |
| `postal_address` | `str | None` | The postal address every broadcast's footer carries (`None` until you give one). |
| `broadcast_daily_limit` | `int | None` | How many recipients its broadcasts may reach a day, apart from `daily_limit`. |
| `broadcast_status` | `str` | `needs_domain` (the default sender doesn't send broadcasts), `pending`, `pending_dns`, `active` or `paused`. |
| `broadcast_from_address` | `str | None` | The address broadcasts go out from, on the `news.` subdomain: `bookings@news.acmebooking.com`. |
| `broadcast_sent_today` | `int | None` | How many broadcast recipients it has sent to since midnight UTC. |
| `broadcast_paused_reason` | `str | None` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |
| `can_send` | `bool` | Whether `send` goes out now (`status` is `active`). |

## noclick.SentEmail

```python
class SentEmail
```

One message an app sent. `status` is `held` (kept while the account can't pay: sent
and charged once it can, or `failed` after 3 days, never charged), `queued`, `sent` (on its
way to the recipient's server), `delivered`, `bounced`, `complained` (marked as spam:
best-effort, since some mailbox providers, Gmail among them, report no single complaint) or `failed`;
`error` says why a message bounced or failed. Sent to several recipients, it shows the
worst any met (a bounce, a complaint), else how far the slowest got.

A preview's code reaches only the account's own people (its owner and the members of the
owner's workspaces): every other copy is kept, never sent or charged, and named in
`captured`; a message whose every copy was kept is `captured`, with the `text` and
`html` it would have sent. `messages(environment="preview")` is the preview's outbox.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` |  |
| `to` | `list[str]` |  |
| `subject` | `str | None` |  |
| `status` | `str` |  |
| `opened` | `bool | None` | Whether the recipient opened it, as far as can be told: privacy proxies open some mail on the reader's behalf. `None` for a message with no HTML, or a sign-in code, which aren't tracked. |
| `bounced` | `bool` |  |
| `error` | `str | None` |  |
| `at` | `Any` | When it was sent. |
| `kind` | `str` | `message` (`send`), `code` (`send_code`) or `broadcast`. |
| `environment` | `str` | Where the code that sent it runs: `production` or `preview`. |
| `captured` | `list[str]` | The recipients a preview kept rather than sent to. |
| `text` | `str | None` | What a kept message would have said; `None` once a message went out. |
| `html` | `str | None` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.Broadcast

```python
class Broadcast
```

One broadcast an app sent: how many recipients it was `sent` to, and those it
`skipped`, each `{to, reason}` with `reason` `unsubscribed`, `bounced`,
`complained` or `invalid`. Each message's delivery shows in `app.email.messages()`.
From a preview, only the account's own people get it: `captured` counts the copies kept.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` |  |
| `subject` | `str | None` |  |
| `sent` | `int` |  |
| `skipped` | `list[dict[str, Any]]` |  |
| `captured` | `int` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.ProjectPayments

```python
class ProjectPayments
```

`app.payments`: take payments in the app without a payments account of your own.
NoClick opens a test account for the app and puts its keys in the app's secrets; the
owner claims it to take real money.

Usage:

```python
app = noclick.Project.from_name("booking")
payments = app.payments   # this app's noclick.ProjectPayments
setup = payments.enable(country="US")
print(setup.mode, setup.claim_url)
```

### ProjectPayments.enable

```python
app.payments.enable(
    *, country=None, owner_email=None, business_name=None
) -> PaymentsSetup
```

Open a test payments account for the app and put its keys in the app's secrets
(for production and previews). `country` is where the owner's business is: required
the first time, since the account can only ever be in that country (`noclick.NotAvailable`,
listing the countries, for one the processor doesn't serve). `owner_email` is who the
processor reminds before an unclaimed test account expires (your NoClick account's email
unless you pass one); `business_name` prefills the claim (the app's name unless you pass one).

Calling it again returns the same account, with its webhook endpoint following the app's
URL. After `test_expires_at` passes unclaimed, it opens a fresh test account with new
keys and no data, and the app must deploy again; once the owner has reinstalled NoClick's
payments app on a `disconnected` account, it reconnects it.

Parameters:

- `country` (`str | None`, default `None`)
- `owner_email` (`str | None`, default `None`)
- `business_name` (`str | None`, default `None`)

Returns: `PaymentsSetup` The setup in `test` mode, with the `claim_url` to send the owner.

Usage:

```python
app = noclick.Project.from_name("booking")
setup = app.payments.enable(country="US")
print(setup.secrets)   # read these in the app's code
print("Claim it before", setup.test_expires_at, setup.claim_url)
```

### ProjectPayments.status

```python
app.payments.status() -> PaymentsSetup
```

Read where the app's payments stand.

Returns: `PaymentsSetup` The current setup; `mode` moves from `test` to `claimed` to `live`. `processor`
is there even while `off`, so an app's payment code can be written before `enable()`.

Usage:

```python
app = noclick.Project.from_name("booking")
if app.payments.status().mode == "live":
    app.deploy()   # production picks up the live keys

processor = noclick.Project.from_name("booking").payments.status().processor   # before enable()
```

## noclick.PaymentsSetup

```python
class PaymentsSetup
```

Where an app's payments go. `mode` is `off` (never enabled), `test` (a test
account that takes test cards, waiting to be claimed), `claimed` (the owner claimed it and
is finishing the steps `claim_step` names), `live` (live keys are in the app's production
secrets and the account can take payments) or `disconnected` (the owner removed NoClick's
payments app or its keys). Money goes straight to the owner's account; NoClick takes no cut.

| Attribute | Type | Description |
| --- | --- | --- |
| `mode` | `str` |  |
| `claim_step` | `str | None` | While claiming: `claim` (send the owner `claim_url`), `application` (the owner gives the payment processor their business details), `install` (the owner installs NoClick's payments app on their live account) or `verification` (the processor is verifying the business). |
| `next_step` | `str | None` | What to do now, in a sentence. |
| `claim_url` | `str | None` | Where the owner claims the account: a NoClick link that always sends them to their next step, working until `test_expires_at` (`None` once live). |
| `test_expires_at` | `Any` | When the test account and its test data are deleted unless it's claimed (60 days after `enable()`); after that `enable()` opens a fresh one, with new keys. |
| `dashboard_url` | `str | None` | The owner's own dashboard at the payment processor, once claimed. |
| `secrets` | `list[str]` | The project secrets that hold the account's keys. Production gets the live keys once `live`; preview deployments keep the test keys, so a preview never takes a real payment. |
| `processor` | `str | None` | Which payment processor apps are paid through, by the name its own client library goes by, so the app's code can pick the library that reads `secrets`. It's the same for every app, so `status()` reports it even while `off`, and code can be written before `enable()`. |
| `country` | `str | None` | Where the business is (ISO 3166-1 alpha-2), fixed when the account was opened. |
| `webhook_url` | `str | None` | Where the processor delivers the account's events, signed with `PAYMENTS_WEBHOOK_SECRET`: the app's `/api/payments/webhook` on its production URL. |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.ProjectSignIn

```python
class ProjectSignIn
```

`app.sign_in`: accounts for the app's own users. Enabling it commits sign-in code
into the app's repo, where you can read and change it, and keeps the users in the app's
bound database.

Usage:

```python
app = noclick.Project.from_name("booking")
sign_in = app.sign_in   # this app's noclick.ProjectSignIn
setup = sign_in.enable(providers=["email", "google"]).wait()
print(setup.commit, setup.managed_providers)
```

### ProjectSignIn.enable

```python
app.sign_in.enable(
    providers, *, own_credentials=None, users_table='users', database=None,
    branch=None, deploy=True
) -> Operation
```

Add sign-in with `providers` (`email`, `google`, `apple`, `microsoft`,
`github`) to the app: commit the code for its framework to `branch` (the repo's default
branch unless you pass one), create `users_table` and the tables it needs in its bound
database and deploy. Calling it again with another list changes the providers.

`google`, `apple` and `microsoft` sign in through NoClick, with nothing to set up at
the provider: its screen names NoClick. To show your own name there instead, list `google`
or `microsoft` in `own_credentials` and set its client's id and secret as the app's
secrets (`SignInSetup.missing_secrets` names them, `callback_urls` where to register it);
`apple` signs in only through NoClick, and `github` only with your own client. Omitted,
each provider keeps how it signs in now: one on your own client stays there.

The app needs a bound database (`noclick.ActionRequired` otherwise; `database` names
the binding when it has several). It works on `nextjs`, `remix` and `astro` apps, and
on a `static` site as it is: a worker in front of its files answers sign-in, and its pages
include `/auth.js` (`noclick.NotAvailable` for a client-only `vite` app, or a site that
already runs its own worker). `email` sends its codes through `app.email.send_code`, which
is enabled with the default sender if it isn't yet.

A file the change would replace that holds edits of yours is never overwritten: the change
goes on a branch of its own (`SignInSetup.branch`, with a preview to review), and naming
a `branch` whose files hold edits raises `noclick.Conflict` naming them.

`deploy=False` sets it up (its secrets and tables) and commits its code without
deploying: it goes live with the branch's next deploy, so you can commit changes of your
own beside it first.

Parameters:

- `providers` (`Sequence[str]`, required)
- `own_credentials` (`Sequence[str] | None`, default `None`)
- `users_table` (`str`, default `'users'`)
- `database` (`str | None`, default `None`)
- `branch` (`str | None`, default `None`)
- `deploy` (`bool`, default `True`)

Returns: `Operation` An operation whose `wait()` gives the `SignInSetup` once the code is
committed and deployed (committed alone with `deploy=False`).

Usage:

Add it straight to production:

```python
app = noclick.Project.from_name("booking")
setup = app.sign_in.enable(providers=["email", "google"]).wait()
print(setup.managed_providers)   # ['google']: nothing to set up
```

With your own Google client, to show your name on Google's screen:

```python
app = noclick.Project.from_name("booking")
setup = app.sign_in.enable(providers=["email", "google"], own_credentials=["google"]).wait()
print(setup.callback_urls, setup.missing_secrets)
```

Or on a branch, to review the commit on its preview deployment first:

```python
app = noclick.Project.from_name("booking")
op = app.sign_in.enable(providers=["email"], branch="add-sign-in")
print(op.wait().commit)
```

Commit it without deploying, to ship it with your own changes in one deploy:

```python
app = noclick.Project.from_name("booking")
app.sign_in.enable(providers=["email"], deploy=False).wait()
app.repo.commit({"app/routes/_index.tsx": page}, message="Show who's signed in")
app.deploy().wait()
```

### ProjectSignIn.upgrade

```python
app.sign_in.upgrade(*, branch=None, deploy=True) -> Operation
```

Move the app's sign-in code to the library version NoClick ships now (`update_available`),
with the same providers: the same commit, migrate and deploy as `enable`, and the same care
for files you edited (`deploy=False` commits it without deploying, as `enable` takes it).
Security fixes come this way; NoClick tells you of one with the
`project.sign_in.update_available` event and never pushes it to production by itself.

Parameters:

- `branch` (`str | None`, default `None`)
- `deploy` (`bool`, default `True`)

Returns: `Operation` An operation whose `wait()` gives the `SignInSetup`.

Usage:

```python
app = noclick.Project.from_name("booking")
if app.sign_in.status().update_available:
    print(app.sign_in.upgrade(branch="sign-in-update").wait().commit)
```

### ProjectSignIn.status

```python
app.sign_in.status() -> SignInSetup
```

Read the app's sign-in: its providers, where its users are kept, and what it still needs.

Returns: `SignInSetup` The current setup; `status` is `off` if sign-in was never enabled.

Usage:

```python
app = noclick.Project.from_name("booking")
setup = app.sign_in.status()
print(setup.status, setup.providers, setup.tables, setup.library, setup.version)
```

## noclick.SignInSetup

```python
class SignInSetup
```

An app's sign-in. `status` is `off`, `installing` (a change is being committed and
deployed), `active` or `failed` (the first change failed; `error` says why: a later
change that fails leaves sign-in `active` as it was, with `error`). The code lives in the
app's repo and the users in `users_table` of the app's own database.

| Attribute | Type | Description |
| --- | --- | --- |
| `status` | `str` |  |
| `providers` | `list[str]` | `email` (a one-time code by email), `google`, `apple`, `microsoft`, `github`. |
| `managed_providers` | `list[str]` | The providers that sign in through NoClick, with nothing to set up at the provider (its screen names NoClick). The rest of `providers` but `email` use your own client there. |
| `users_table` | `str | None` |  |
| `tables` | `list[str]` | Every table sign-in keeps in the database: `users_table` first, then its sessions, the accounts people sign in with, the pending codes and its rate limits. |
| `database` | `str | None` | The binding of the database the users are kept in. |
| `library` | `str` | The open-source library the code is written with, and its version, so code written against the app's sign-in uses the right calls. |
| `version` | `str | None` |  |
| `update_available` | `str | None` | A newer version NoClick ships (`upgrade()` moves to it), else `None`. |
| `commit` | `str | None` | The commit that added or last changed sign-in. |
| `branch` | `str | None` | Where that commit went when it wasn't the production branch: the one you passed, or the one NoClick made because files it would change hold edits of yours (`edited_files`). |
| `edited_files` | `list[str]` |  |
| `callback_urls` | `dict[str, str]` | Where each provider on your own client sends people back to; register it with that provider. They're on the app's own NoClick address, so adding a domain doesn't change them. |
| `missing_secrets` | `list[str]` | Project secrets a provider on your own client still needs (`GOOGLE_CLIENT_ID`, ...); it works once they're set. |
| `secrets` | `list[str]` | The secrets NoClick writes itself and never shows: `AUTH_SECRET`, `AUTH_URL`, `AUTH_PROXY_SECRET`, and the app's client of NoClick's sign-in (`NOCLICK_SIGN_IN_CLIENT_ID`, `NOCLICK_SIGN_IN_CLIENT_SECRET`) while any provider signs in through NoClick. |
| `error` | `dict[str, Any] | None` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.ProjectLive

```python
class ProjectLive
```

`app.live`: edit the app in a live session. The site runs on a Vite dev server with its code checked out at
`/site`; each change swaps into the pages its owner has open (a game keeps running, a form keeps what was
typed), and the session's end deploys what was edited, only once its build and check pass. It's for your
account's own apps built with Vite (6 to 8), or of files whose package.json builds nothing or that have none,
whose previews get their own data (`preview_resources="branch"`), with `live_editing` on: such an app has it
on from its first production release (`app.update(live_editing=True)` for one released before). The container
is billed by the minute at what it costs NoClick.

Usage:

```python
app = noclick.Project.from_name("larkspur")
live = app.live   # this app's noclick.ProjectLive
session = live.start()
print(session.state, session.enter_url)
```

### ProjectLive.status

```python
project_live.status() -> LiveStatus
```

Read whether the app is edited live, whether it can be, and its session.

Returns: `LiveStatus` The app's switch and whether it's supported, its open session (else its last one) and the agents'
conversations editing it.

Usage:

```python
app = noclick.Project.from_name("larkspur")
status = app.live.status()
if not status.supported:
    print(status.unsupported_reason)
elif status.session and status.session.open:
    print(status.session.state, status.session.viewers, status.session.edits.hot)
```

### ProjectLive.start

```python
project_live.start(*, wait=False, refresh_data=False, limits=None) -> LiveSession
```

Start the app's live session, or return the one that's open. A session reads the `noclick-live`
branch (production's branch at the first one), and its code writes to copies of the app's data, not
production's: `refresh_data=True` makes them again from production's. It answers while the session
starts (`state` `warming`); `wait=True` waits for it to be live, up to 60 seconds, and answers it
as it stands then: a first start in a place can take a few minutes, so a session can still come back
`warming`. `status()` reads it again.

`limits` shortens the session's timers, in seconds (a session's timers can only be shortened):
`idle_grace_s` (60: no page open and no command, before it's `idle`), `idle_end_s` (600: idle
before it ends), `max_quiet_with_viewers_s` (14,400: pages open but no command), `max_session_s`
(43,200) and `hold_warming_s` (30: how long a page waits for a starting session before it shows that
it's starting).

An account has at most 3 sessions open, and 24 session-hours a day. A start is refused while your
account can't pay for it (`noclick.PaymentRequired`) or the app's budget is spent
(`noclick.SpendCapExceeded`), and for an app live editing can't run (`noclick.Conflict`, whose
`readiness` says what to change).

Parameters:

- `wait` (`bool`, default `False`)
- `refresh_data` (`bool`, default `False`)
- `limits` (`Mapping[str, int] | None`, default `None`)

Returns: `LiveSession` The session, with its `enter_url`: a link that opens the app in live mode, for 2 hours. Its
`state` is `warming` while it starts, `wait=True` or not.

Usage:

Start a session and send its owner the link:

```python
app = noclick.Project.from_name("larkspur")
session = app.live.start()
print(session.enter_url)
```

Start one that ends a minute after its last command, and wait until it's live:

```python
import time

app = noclick.Project.from_name("larkspur")
session = app.live.start(wait=True, limits={"idle_grace_s": 30, "idle_end_s": 30})
while session.state == "warming":
    time.sleep(5)
    session = app.live.status().session or session
print(session.state, session.limits)
```

### ProjectLive.exec

```python
project_live.exec(
    command, *, background=False, timeout_s=90
) -> LiveExecResult | Operation
```

Run a bash command in the session's container, in the site's working tree (`/site`), starting a
session when none is open, and wait for it: `timeout_s` is 90 by default, and at most 90. A file the
command writes is committed to the `noclick-live` branch by itself, and swaps into the open pages: the
result says how, per batch of files it changed (`vite`). A non-zero exit is a result, not an exception.

A command answers within its request, so one sent while the session is still starting (a first start
in a place can take a few minutes) or deploying what was edited doesn't run: it raises
`noclick.Conflict`, whose `state` is `warming` or `ending`. `background=True` returns an
`Operation` at once instead, which waits for a starting session, then runs the command with
`timeout_s` up to 600: for a command longer than a request allows (an install, a test run), or the
first one of a session. An account runs at most 4 background commands at once. Cancelling one stops
its wait, not a command already sent.

Parameters:

- `command` (`str`, required)
- `background` (`bool`, default `False`)
- `timeout_s` (`int`, default `90`)

Returns: `LiveExecResult | Operation` What it printed (`stdout` and `stderr`), its `exit_code`, and a `LiveEdit` per batch of
files it changed: `hot`, `reload`, `error` or `none`. With `background=True`, an
`Operation` at once, whose `wait()` gives that result.

Usage:

Edit a file, then read what the open pages did with it:

```python
app = noclick.Project.from_name("larkspur")
result = app.live.exec("sed -i 's/Score/Points/' src/render.js")
for edit in result.vite:
    print(edit.outcome, edit.files, edit.applied)
    if edit.outcome == "reload":
        print("reloaded:", edit.reload["reason"], edit.reload["chain"])
    elif edit.outcome == "error":
        print(edit.error["message"], edit.error["file"])
```

Install a dependency, which takes longer than a request allows, in the background:

```python
app = noclick.Project.from_name("larkspur")
installed = app.live.exec("npm install canvas-confetti", background=True, timeout_s=300).wait()
print(installed.ok, installed.stderr)
```

### ProjectLive.edits

```python
project_live.edits(*, after=0, limit=50) -> LiveEdits
```

What Vite did with each edit of the app's newest session after `after` (a sequence number), oldest
first: edits made by commands and by agents attached to it alike.

Parameters:

- `after` (`int`, default `0`)
- `limit` (`int`, default `50`): Return at most this many.

Returns: `LiveEdits` Up to `limit` edits (at most 200), with `last_seq` to read the next ones after. Empty when no
session has run.

Usage:

```python
app = noclick.Project.from_name("larkspur")
seen = 0
edits = app.live.edits(after=seen)
for edit in edits:
    print(edit.seq, edit.outcome, edit.files)
seen = edits.last_seq
```

### ProjectLive.enter_link

```python
project_live.enter_link() -> LiveEnterLink
```

Make a link that opens the app in live mode (`start()` returns one too). Whoever opens it sees the
session's dev server at the app's own URL, on that device, for 12 hours, and can change nothing; everyone
else sees production.

Returns: `LiveEnterLink` The link, which works any number of times for 2 hours.

Usage:

```python
app = noclick.Project.from_name("larkspur")
link = app.live.enter_link()
print(link.url, link.expires_at)
```

### ProjectLive.end

```python
project_live.end(*, deploy=True) -> Operation
```

End the app's live session now (it also ends on its own, about 11 minutes after the last page closed
and the last command ran). What it edited is committed, built and checked where production serves, and
only then deployed; a build or check that fails leaves production as it was, and the edits stay on the
`noclick-live` branch for the next session. `deploy=False` stops it without deploying. A session still
starting is stopped.

Parameters:

- `deploy` (`bool`, default `True`)

Returns: `Operation` An operation whose `.wait()` gives the `LiveEnd`. A build or check that failed raises
`noclick.OperationFailed`, saying why.

Usage:

```python
app = noclick.Project.from_name("larkspur")
ended = app.live.end().wait()
print(ended.outcome, ended.deployment_id)
```

## noclick.LiveStatus

```python
class LiveStatus
```

Whether an app is edited live, whether it can be, and its session.

| Attribute | Type | Description |
| --- | --- | --- |
| `enabled` | `bool` | The app's `live_editing` switch. |
| `supported` | `bool` | Whether the app can be edited live, as far as is known without reading its code. |
| `unsupported_reason` | `str | None` | Why it can't, when it can't. |
| `session` | `LiveSession | None` | Its open session, else its last one (None before its first). |
| `attached` | `list[dict[str, str | None]]` | The agents' conversations editing it: `[{"agent_id", "conversation"}]`. |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.LiveSession

```python
class LiveSession
```

An app's live session: its site on a dev server, with its code checked out in `workdir`. `state` goes
`warming` (starting; `phase` says where), `live`, `idle` (no page open and no command for a minute),
`ending` (building, checking and deploying what was edited), then `ended` (`release` says how) or
`failed` (`error` says why).

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` |  |
| `project_id` | `str` |  |
| `state` | `str` |  |
| `phase` | `str | None` |  |
| `mode` | `str` | `vite` (over its package.json: its own Vite, or NoClick's for files whose package.json builds nothing) or `plain` (NoClick's Vite over a site of only files). |
| `url` | `str | None` | The app's own URL, where the pages open in live mode show the session. |
| `enter_url` | `str | None` | A link that opens the app in live mode, on the session a `start()` returns (None otherwise). |
| `workdir` | `str` | Where the site's code is checked out in the session's container. |
| `viewers` | `dict[str, int]` | The pages open in live mode: `{"connected": ..., "visible": ...}`. |
| `edits` | `LiveEditCounts` |  |
| `data` | `list[LiveDataCopy]` | What the session's code writes to instead of production's data. |
| `readiness` | `dict[str, Any] | None` | What keeps an edit from swapping in place: `{"ready", "mode", "reasons": [{"code", "detail"}]}`. |
| `git` | `dict[str, Any] | None` | The session's branch, `noclick-live`: `{"branch", "head", "pushed", "dirty", "state", "conflict"}`. |
| `limits` | `dict[str, int] | None` | The timers in force, in seconds (`idle_end_s`, `max_session_s`, ...), when the session reported them. |
| `started_at` | `Any` |  |
| `live_at` | `Any` |  |
| `ended_at` | `Any` |  |
| `end_reason` | `str | None` | Why it ended: `api` (`end()`), `idle`, `max_quiet`, `max_session`, `switch_off`, ... |
| `error` | `dict[str, Any] | None` | `{"code", "message"}` once it failed, or once its end couldn't deploy. |
| `release` | `dict[str, Any] | None` | How its end went: `{"outcome", "deployment_id", "script"}`, `outcome` `deployed`, `deploy_failed`, `no_changes` or `stopped`. |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |
| `open` | `bool` | Whether the session is still open (`warming`, `live`, `idle` or `ending`). |

## noclick.LiveEditCounts

```python
class LiveEditCounts
```

How a session's edits went so far: how many, and how many swapped in place (`hot`), reloaded the page
(`reload`) or didn't compile (`error`).

| Attribute | Type | Description |
| --- | --- | --- |
| `count` | `int` |  |
| `hot` | `int` |  |
| `reload` | `int` |  |
| `error` | `int` |  |
| `last_seq` | `int` | The newest edit's sequence number: `app.live.edits(after=...)` reads the ones after it. |

## noclick.LiveDataCopy

```python
class LiveDataCopy
```

One resource the app binds that a session's code reaches a copy of, never production's.

| Attribute | Type | Description |
| --- | --- | --- |
| `kind` | `str` | `database`, `bucket`, `dict` or `queue`. |
| `name` | `str` | The binding's name. |
| `production_id` | `str` |  |
| `copy_id` | `str | None` | The copy's id, once the session's first write made it (None until then: it reads production's). |
| `with_data` | `bool` | Whether the copy starts with production's data. |
| `note` | `str | None` | What the copy holds, in a sentence. |

## noclick.LiveEdit

```python
class LiveEdit
```

What Vite did with one batch of changed files in the open pages. `outcome` is `hot` (swapped in place;
`applied` counts the pages that took it), `reload` (the page reloaded and lost its state; `reload` says
why), `error` (it doesn't compile, and the page shows Vite's error overlay; `error` says where) or `none`
(nothing imports the files).

| Attribute | Type | Description |
| --- | --- | --- |
| `seq` | `int` | Its sequence number in the session. |
| `files` | `list[str]` |  |
| `outcome` | `str` |  |
| `clients` | `int` | How many pages were open. |
| `reload` | `dict[str, Any] | None` | `{"path", "triggeredBy", "reason", "chain"}`: `reason` is `no-boundary`, `html`, `config`, `dependency`, `server-restart` or `other`, and `chain` the imports from the changed file up to the page. |
| `error` | `dict[str, Any] | None` | `{"message", "file", "loc": {"line", "column"}, "frame"}`. |
| `applied` | `dict[str, Any] | None` | `{"ok", "failed", "errors"}`: the pages that applied the swap, and what threw as it ran. |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.LiveEdits

```python
class LiveEdits(list[LiveEdit])
```

The edits a read returns, oldest first: a list of `LiveEdit`, with where the next read starts.

| Attribute | Type | Description |
| --- | --- | --- |
| `last_seq` | `int` | The sequence number to pass as `after` to read the edits after these. |

## noclick.LiveExecResult

```python
class LiveExecResult
```

What a command run in a live session printed and how it exited (a non-zero `exit_code` is a result, not an
error), with what Vite did in the open pages with each file it changed.

| Attribute | Type | Description |
| --- | --- | --- |
| `stdout` | `str` |  |
| `stderr` | `str` |  |
| `exit_code` | `int | None` |  |
| `timed_out` | `bool` | Whether it ran past its `timeout_s` and was stopped. |
| `ms` | `int` | How long it ran, in milliseconds. |
| `vite` | `list[LiveEdit]` | A record per batch of files the command changed; empty when it changed none. |
| `earlier` | `list[LiveEdit]` | Edits made outside the command since the one before, when there were any. |
| `note` | `str | None` |  |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |
| `ok` | `bool` | Whether the command exited 0. |

## noclick.LiveEnterLink

```python
class LiveEnterLink
```

A link that opens the app in live mode on whatever device opens it.

| Attribute | Type | Description |
| --- | --- | --- |
| `url` | `str` |  |
| `expires_at` | `Any` | When the link stops working (2 hours after it was made); it works any number of times until then. |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |

## noclick.LiveEnd

```python
class LiveEnd
```

How a live session's end went. `outcome` is `deployed` (what was edited serves at the app's URL, as
`deployment_id`), `no_changes` (nothing was edited), `stopped` (it ended without deploying) or `aborted`
(an edit came in as it ended, and the session is live again). A build or check that failed fails the operation
instead, leaving production as it was.

| Attribute | Type | Description |
| --- | --- | --- |
| `outcome` | `str` |  |
| `session_id` | `str | None` |  |
| `deployment_id` | `str | None` | The production deployment it released (None unless `deployed`). |
| `main_behind` | `bool` | It deployed, but the production branch couldn't be moved to its commit; the next session's start merges it. |
| `raw` | `dict[str, Any]` | The response JSON exactly as the API sent it. |
