# estimate

> What something would cost a month before you make it: an app, its database and bucket, a repo, live editing.

Each charge comes back on its own line with the unit it's billed by, the unit price NoClick charges for it (what
the service costs NoClick, nothing added), the quantity a month and the dollars, priced for your account's plan.
Leave usage out and a modest default is assumed, and the line says so. Nothing is made or charged by asking.

```python
est = noclick.estimate([
    {"kind": "project", "runtime": "edge", "usage": {"requests": 100_000}},
    {"kind": "database", "engine": "sqlite"},
    {"kind": "bucket"},
])
print(f"${est.monthly_usd:.2f} a month")
```

## estimate

```typescript
function estimate(
  items: EstimateRequestItem[],
  options?: CallOptions,
): Promise<Estimate>
```

What `items` would cost a month, before you make any of them. Each item names its `kind`, its options (a
project's `runtime`, `region` and `framework`, a database's `engine`), an optional `name` of your own, and the
`usage` you expect a month by name (`Estimate.kinds()` lists each kind's). Usage you leave out is assumed from
the kind's defaults, and so is an option you leave out whose default changes a price (an edge app's `framework`
picks its build machine); every line a default decided says so (`assumed`). Prices are what each service costs
NoClick, nothing added, priced for your account's plan. Needs the `usage` scope; nothing is made, held or
charged. A kind, option or usage it can't price throws `InvalidRequest` naming the field.

    const est = await estimate([
      { kind: "project", runtime: "edge", usage: { requests: 100_000 } },
      { kind: "database", engine: "sqlite" },
      { kind: "bucket" },
    ]);
    for (const line of est.lines) {
      const note = line.assumed ? " (assumed)" : "";
      console.log(`${line.kind} ${line.charge}: ${line.quantity} ${line.unit} x $${line.unitUsd} = $${line.usd}${note}`);
    }
    console.log(`$${est.monthlyUsd.toFixed(2)} a month`);

Parameters:

- `items` (`EstimateRequestItem[]`, required)
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: An `Estimate`: `monthly_usd`, every charge in `lines` (its `unit`, `unit_usd`, `quantity` and
`usd`), the `items` each with its own total, and your `plan` with the usage it includes a month.
A kind, option or usage it can't price raises `noclick.InvalidRequest` naming the field.

Types:

```typescript
/** One thing to estimate: its `kind`, its options, and the usage you expect a month by name. */
interface EstimateRequestItem {
  /** `project` (an app), `durable_objects` (an app's), `database`, `bucket`, `repo` or `live_editing`. */
  kind: string;
  /** Your own label for it, said back with its lines. */
  name?: string;
  /** A project's: `edge` (the default) or `container`. */
  runtime?: "edge" | "container";
  /** A database's: `sqlite` (the default) or `postgres`. */
  engine?: "sqlite" | "postgres";
  /** Where a project (or its Durable Objects) would run; omitted, where a new one of yours would go. */
  region?: string;
  /** A project's framework, as `Project.create` takes it: `nextjs` builds on a bigger machine. */
  framework?: string;
  /** What you expect a month, by the kind's usage names (`Estimate.kinds()` lists them); the rest is assumed. */
  usage?: Record<string, number>;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

## Estimate

```typescript
class Estimate
```

What the items would cost a month: a usage-based estimate, priced for your account's plan.

| Attribute | Type | Description |
| --- | --- | --- |
| `monthlyUsd` | `number` |  |
| `estimated` | `boolean` | Always true: these charges are by usage, so what's charged is what's used. |
| `items` | `EstimateItem[]` |  |
| `lines` | `EstimateLine[]` | Every item's lines, in order. |
| `plan` | `JsonObject | null` | Your account's plan, as `GET /v1/status` names it (null for a key acting for one of your users). |
| `includedUsdPerMonth` | `number | null` | The usage the plan includes a month, in dollars, which every charge to the account draws from (null without a plan). `plan` says whether a day's share of it is capped too. |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

### Estimate.kinds

```typescript
static kinds(
  options?: CallOptions & { region?: string },
): Promise<EstimateKind[]>
```

What `estimate` takes: each kind and variant, the usage it's priced by with the default assumed for any you
leave out, and each charge's unit price. A container app's prices depend on its `region` (default: where a new
app of yours would go). Needs the `usage` scope.

    for (const kind of await Estimate.kinds()) {
      console.log(kind.kind, kind.options, kind.usage.map((u) => `${u.name}=${u.default}`));
    }

Parameters:

- `options.region` (`string`)
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: Each `EstimateKind`: its `kind` and `options` (a project's `runtime`, a database's `engine`),
its `usage` fields with their defaults, and its `prices`.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

## EstimateItem

```typescript
interface EstimateItem
```

One thing you asked about, priced: its options, the usage it was priced at, and its lines.

| Attribute | Type | Description |
| --- | --- | --- |
| `kind` | `string` |  |
| `label` | `string` | For people, e.g. `App on the edge`. |
| `name` | `string | null` |  |
| `options` | `JsonObject` | What it was priced as: a project's `runtime`, `region` and `framework`, a database's `engine`. |
| `usage` | `Record<string, number>` | Every usage it was priced at, by name: what you gave and the defaults for the rest. |
| `assumed` | `string[]` | The usage names you left out, and the options you left out whose default changes a price. |
| `monthlyUsd` | `number` |  |
| `lines` | `EstimateLine[]` |  |
| `notIncluded` | `string[]` | What its meters also charge that no usage here prices (an app's calls to AI, say), in words. |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## EstimateLine

```typescript
interface EstimateLine
```

One charge of an estimate: what is billed, by which unit, at what price, and how much of it a month.

| Attribute | Type | Description |
| --- | --- | --- |
| `kind` | `string` | The kind of the item it's for: `project`, `durable_objects`, `database`, `bucket`, `repo` or `live_editing`. |
| `item` | `string | null` | The `name` you gave the item, if any. |
| `charge` | `string` | Which charge it is, e.g. `front_door`, `rows_written` or `storage`. |
| `description` | `string` | What it charges for, in words. |
| `unit` | `string` | The unit it's billed by, e.g. `million requests` or `GB-month`. |
| `unitUsd` | `number` | The price of one `unit`, in US dollars. |
| `quantity` | `number` | How many units a month. |
| `usd` | `number` | What it would cost your account a month, in US dollars. |
| `assumed` | `boolean` | Whether a default decided it: its `quantity` came from usage you left out, or its price from an option you left out (an edge app's `framework`, a container's `region`). |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## EstimateKind

```typescript
interface EstimateKind
```

Something an estimate takes: the usage it's priced by and the charges it makes.

| Attribute | Type | Description |
| --- | --- | --- |
| `kind` | `string` | What `kind` an item names; a project and a database come in variants (`options`). |
| `label` | `string` |  |
| `description` | `string` |  |
| `options` | `JsonObject` | What this variant is priced as: a project's `runtime` and `region`, a database's `engine`. |
| `usage` | `EstimateUsageField[]` |  |
| `prices` | `EstimatePrice[]` |  |
| `notIncluded` | `string[]` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

## EstimateUsageField

```typescript
interface EstimateUsageField
```

A usage a kind takes: what it counts, and the default assumed when you leave it out.

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `string` |  |
| `unit` | `string` |  |
| `description` | `string` |  |
| `default` | `number` |  |
| `most` | `number | null` | The most it can be (a share is at most 1), else null. |

## EstimatePrice

```typescript
interface EstimatePrice
```

A charge a kind makes, at its unit price.

| Attribute | Type | Description |
| --- | --- | --- |
| `charge` | `string` |  |
| `description` | `string` |  |
| `unit` | `string` |  |
| `unitUsd` | `number` |  |
| `usageFields` | `string[]` | The usage names its quantity comes from. |
