# PhoneNumber

> Phone numbers: a real number your agents answer and call from.

```python
[pick] = noclick.PhoneNumber.available(country="US", area_code="415", limit=1)
number = noclick.PhoneNumber.buy(pick, max_monthly_usd=5)
number.answer_with(host)                              # inbound calls reach this agent
call = number.call("+14155550100", goal="Confirm Friday's 3pm booking.").wait()
print(call.text)                                      # the transcript, one turn per line
```

Numbers in the countries NoClick sells in (`PhoneNumber.coverage()`), each at
its own price: billed monthly, and once when bought where its carrier charges
that; available on accounts with the phone feature (`noclick.NotAvailable`
otherwise). A number whose country asks for documents is bought with them
(`PhoneNumber.upload_document`, then `requirements=` on `buy`): the
carrier reviews them first, so `buy` returns a `PhoneNumberOrder` that
becomes the number once the carrier approves it. A number you keep with your own
phone provider is connected through that provider account
(`PhoneNumber.connect`), which bills it. Numbers have names
(`PhoneNumber.from_name`). The answering agent can transfer a call to a
person, a caller proven to be one of your users runs as that user,
`callers` says who gets through, calls both ways are listed, and a number can
record its calls. Invite-only beta: the agent texting the caller
(`answer_with(texts=True)`, under a `TextingRegistration` of your business
with the US carriers), porting numbers in (`PhoneNumber.port_in`) and moving
one away (`PhoneNumber.transfer_out`).

## PhoneNumber

```typescript
class PhoneNumber
```

A number you own. `release()` gives it back (billing stops).

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `name` | `string | null` | What your code calls it (null for one bought without a name). |
| `number` | `string` | The number in E.164 form. |
| `source` | `PhoneNumberSource | null` | Where it came from: `bought` or `connected` (`ported` is in invite-only beta). |
| `connection` | `string | null` | The phone provider connection a connected number runs through (its name; null otherwise). |
| `agentId` | `string | null` | The agent that answers inbound calls (null if none). |
| `transferTo` | `string | null` | Where the answering agent's `transfer_call` tool sends a call (null: no such tool). |
| `texts` | `boolean` | Invite-only beta. Whether the answering agent can text the caller (`send_text`). |
| `textsReady` | `boolean` | Invite-only beta. Whether the US carriers have taken the number onto your registration's campaign, so its texts go out. Until then the agent has no `send_text`. |
| `textsError` | `string | null` | Invite-only beta. Why the carriers didn't take the number onto the campaign, when they refused it. |
| `callers` | `PhoneCallers | null` | Who gets through: `anyone`, `users` or `owner`. |
| `recordCalls` | `boolean` | Whether its calls, both ways, are recorded. |
| `monthlyUsd` | `number | null` | What NoClick bills for it a month, in US dollars (null for a connected number, which its provider bills). |
| `userId` | `string | null` |  |
| `createdAt` | `Date | null` |  |
| `released` | `boolean` | Whether `release()` gave the number back, or `disconnect()` handed it back to its provider account. |

Types:

```typescript
/**
 * Where a number came from: `bought` through NoClick or `connected` (kept with your own phone provider
 * account, which bills it); `ported` (moved to NoClick from its carrier) is in invite-only beta.
 */
type PhoneNumberSource = "bought" | "connected" | "ported";

/**
 * Who gets through to a number: every caller, only your users, or only its owner (the number's own
 * user, or your account's owner), each a verified phone the carrier attests. It never changes who a
 * call runs as.
 */
type PhoneCallers = "anyone" | "users" | "owner";
```

### PhoneNumber.available

```typescript
static available(
  options?: CallOptions & {
    country?: string;
    type?: PhoneNumberType;
    areaCode?: string | number;
    locality?: string;
    region?: string;
    contains?: string;
    startsWith?: string;
    endsWith?: string;
    features?: "voice" | "voice_sms";
    limit?: number;;
  },
): Promise<AvailableNumber[]>
```

Numbers for sale in `country` (`US` by default) of `type` (`local` by default), narrowed by `areaCode`,
`locality` (a city), `region`, `contains` (digits, letters or `*` wildcards), `startsWith` and `endsWith`
(digits of the national number), and `features` (`voice`, or `voice_sms` for numbers that take texts
too). Each comes with its prices and what its country asks before it's sold.

Parameters:

- `options.country` (`string`)
- `options.type` (`PhoneNumberType`)
- `options.areaCode` (`string | number`)
- `options.locality` (`string`)
- `options.region` (`string`)
- `options.contains` (`string`)
- `options.startsWith` (`string`)
- `options.endsWith` (`string`)
- `options.features` (`"voice" | "voice_sms"`)
- `options.limit` (`number`): Return at most this many.
- `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: Up to `limit` numbers (10 by default, at most 30), each with its
`monthly_usd` and `upfront_usd`, the `locality` and `region` it's local
to, what it can do (`capabilities`), what its country asks before it's sold
(`requirements`) and whether it can text (`texting`).

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>;
}

/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";
```

### PhoneNumber.coverage

```typescript
static coverage(options?: CallOptions): Promise<NumberCoverage[]>
```

The countries numbers are for sale in, with the kinds of number sold in each. Right after a deploy, while that
is still being found out, the API answers 503 with `Retry-After`, which the client retries on its own.

Parameters:

- `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: A `noclick.NumberCoverage` per country: its ISO code, the kinds of number in stock
there (`types`), the kinds that can text (`texting_types`), the kinds bought with
documents the carrier reviews first (`documents_types`) and the kinds that ask a step
that can't be taken here (`steps_types`), which can't be bought through the API yet.

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>;
}
```

### PhoneNumber.places

```typescript
static places(
  country: string,
  options?: CallOptions & { type?: PhoneNumberType },
): Promise<NumberPlace[]>
```

Where in `country` numbers of `type` (`local` by default) are for sale: cities, or area codes in North America.

Parameters:

- `country` (`string`, required)
- `options.type` (`PhoneNumberType`)
- `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: A `noclick.NumberPlace` per place: its `kind` (`locality` or `area_code`),
its `value` and the `region` it's in. Empty where the carrier doesn't say.

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>;
}

/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";
```

### PhoneNumber.buy

```typescript
static buy(
  number: string | AvailableNumber,
  options: PhoneNumberBuyOptions & {
    address?: undefined;
    requirements?: undefined;
    holderOnFile?: false;
  },
): Promise<PhoneNumber>
static buy(
  number: string | AvailableNumber,
  options: PhoneNumberBuyOptions,
): Promise<PhoneNumber | PhoneNumberOrder>
```

Buy `number`; refused with `PriceExceeded` if it costs more than `maxMonthlyUsd` a month or
`maxUpfrontUsd` once (by default, the `upfrontUsd` an `AvailableNumber` showed; 0 for a number passed
as a string). A number whose country asks who holds it takes `address`, with a `phone` where a
requirement's `kind` is `contact`. One whose country asks for documents takes `requirements`: each
textual and document requirement's answer by its `id` (the text, or a `NumberDocument` from
`PhoneNumber.uploadDocument`); it resolves to a `PhoneNumberOrder` in the carrier's review (days,
sometimes), and nothing is charged until it completes. `name` is what your code calls it, unique among
its user's numbers (a taken one is a `Conflict` with `existingId`, before anything is bought).
`holderOnFile: true` files the holder profile on file in place of `address` and `requirements`.

Parameters:

- `number` (`string | AvailableNumber`, required)
- `options.maxMonthlyUsd` (`number`, required)
- `options.maxUpfrontUsd` (`number`)
- `options.country` (`string`)
- `options.type` (`PhoneNumberType`)
- `options.address` (`NumberHolder`)
- `options.requirements` (`Record<string, string | NumberDocument>`)
- `options.holderOnFile` (`boolean`): File the holder profile on file (`PhoneNumber.setHolderProfile`: yours, or inside `asUser` the user's) in place
of `address` and `requirements`, with the answers it holds that the number's country asks; with none on file it
throws `ActionRequired`.
- `options.name` (`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: The number, now yours. Its first month is charged now and it renews monthly
until you `release()` it. A number whose country asks for documents comes back
as a `noclick.PhoneNumberOrder` instead, in the carrier's review (days,
sometimes): nothing is charged until it completes, and `order.phone_number()`
is the number once it has.

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>;
}

/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";
```

### PhoneNumber.holderProfile

```typescript
static holderProfile(
  options?: { client?: NoClick; user?: UserRef | null },
): Promise<NumberHolderProfile | null>
```

The number holder profile on file: your account's, or with `user` (a `User` or your id for one) that user's.

Parameters:

- `options.user` (`UserRef | null`, default `null`): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: The profile, or `None` until one is filed.

Types:

```typescript
/** 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>;
}
```

### PhoneNumber.setHolderProfile

```typescript
static setHolderProfile(
  holder: NumberHolder | null,
  options?: {
    client?: NoClick;
    user?: UserRef | null;
    acceptedAt?: Date | string;
    requirements?: Record<string, string | NumberDocument>;
  },
): Promise<NumberHolderProfile | null>
```

File (or with `null` clear) the number holder profile: your account's, or with `user` that user's. `holder` is
who numbers are registered to where their country asks, `requirements` the answers to what those countries ask by
requirement id (the text, or a `NumberDocument`), and `acceptedAt` when the holder accepted having them filed with
the carrier in their name (required: only the person accepts it; your server records when they did). A purchase
files it with `PhoneNumber.buy(..., { holderOnFile: true })`.

Parameters:

- `holder` (`NumberHolder | null`, required)
- `options.acceptedAt` (`Date | string`)
- `options.requirements` (`Record<string, string | NumberDocument>`)
- `options.user` (`UserRef | null`, default `null`): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: The profile now on file (`None` once cleared).

Types:

```typescript
/** 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>;
}
```

### PhoneNumber.uploadDocument

```typescript
static uploadDocument(
  file: Uint8Array | ArrayBuffer | Blob,
  options: CallOptions & {
    requirement: string | NumberRequirement;
    country: string;
    type?: PhoneNumberType;
    filename: string;
  },
): Promise<NumberDocument>
```

Upload a document one of a number's requirements asks for (a requirement of `kind` `document` in
`country`'s numbers of `type`, `local` by default): a PDF, PNG or JPEG up to 20 MB. `requirement` is the
requirement or its `id`. The carrier holds the file; NoClick keeps only its name and what it's for.
Pass the result in `requirements` when you buy.

Parameters:

- `file` (`Uint8Array | ArrayBuffer | Blob`, required)
- `options.requirement` (`string | NumberRequirement`, required)
- `options.country` (`string`, required)
- `options.type` (`PhoneNumberType`, default `"local"`)
- `options.filename` (`string`, 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: A `noclick.NumberDocument` to pass in `requirements` when you buy. One no purchase
names within 25 minutes is gone; one a purchase named can be named again.

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>;
}

/**
 * One thing a number's country asks before it's sold: the holder's `address` or `contact` information, an
 * answer in text (`textual`: one of `values` where it lists them; `example` is the carrier's), a `document`,
 * or a `step` that can't be taken here.
 */
interface NumberRequirement {
  id: string;
  kind: "address" | "contact" | "textual" | "document" | "step";
  name: string;
  description: string;
  example: string;
  values: string[];
}

/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";
```

### PhoneNumber.connectable

```typescript
static connectable(
  connection: Connection | string,
  options?: CallOptions,
): Promise<ConnectableNumber[]>
```

The numbers (up to 1,000) in your phone provider account that `connection` (a `Connection` or its
name, connected with the account's own credentials; one holding a restricted API key throws
`InvalidRequest` naming `connection`) can route, each with its `label`, whether its calls go
somewhere today and, when it's already connected to NoClick, its `phoneNumberId` and `agentId`.

Parameters:

- `connection` (`Connection | string`, 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: Each number (up to 1,000) with its `label`, whether its calls go somewhere today
(`routed_elsewhere`), and, when it's already connected to NoClick, the number it's
connected as (`phone_number_id`) and the agent answering it (`agent_id`).

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>;
}
```

### PhoneNumber.connect

```typescript
static connect(
  number: string | ConnectableNumber,
  options: CallOptions & {
    connection: Connection | string;
    name?: string;
    recordCalls?: boolean;
  },
): Promise<PhoneNumber>
```

Connect `number`, which you keep with your own phone provider, through `connection` (its account,
connected with the account's own credentials: NoClick checks the provider's signed calls with the
account's secret, which a restricted key can't). NoClick remembers where its calls go today and
leaves them there until `answerWith` routes them to an agent; `disconnect()` puts them back. The
provider bills the number and its minutes; NoClick bills only what it adds (the agent's time on a
call). Inside `asUser` it's the user's number on the user's connection. A number already connected,
or one another NoClick workflow answers, throws `Conflict`; one on a SIP trunk, `InvalidRequest`.

Parameters:

- `number` (`string | ConnectableNumber`, required)
- `options.connection` (`Connection | string`, required)
- `options.name` (`string`)
- `options.recordCalls` (`boolean`)
- `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: The number, `source` `connected`, with no agent yet.

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>;
}
```

### PhoneNumber.portIn (invite-only beta)

```typescript
static portIn(
  numbers: string | string[],
  options: PortInOptions,
): Promise<PortRequest>
```

Invite-only beta. Port US local numbers in from their carrier, so they become NoClick
numbers: one, or several on one account at that carrier (one letter of authorization covers them).
`accountHolder` signs the letter on a NoClick page, branded like your other pages; the rest is how
the current carrier knows the account, as its bill shows it. Every number on the account moves unless
`remainingNumbers` names the ones that stay. Each number keeps working with its carrier until it moves
(moving it is free); then it's a NoClick number, billed monthly like a bought one
(`PriceExceeded`, nothing sent, above `maxMonthlyUsd`). A number you connected through your own
phone provider is disconnected first (`InvalidRequest` otherwise); for one kept with Twilio, the
account's name is "Twilio, Inc.", its number the last 8 characters of your Account SID, and the PIN
comes from Twilio's support. Resolves to a `PortRequest` whose `wait()` gives the `PhoneNumber`s.

Parameters:

- `numbers` (`string | string[]`, required)
- `options.accountHolder` (`Human | string`, required): The person authorized on the account, who signs the letter of authorization on a NoClick page: a `Human` with an email, or the email.
- `options.accountName` (`string`, required): The name on the account, often a business, not the signer.
- `options.serviceAddress` (`StreetAddress`, required)
- `options.accountNumber` (`string`, required)
- `options.maxMonthlyUsd` (`number`, required): The most each may cost a month once it's yours, in US dollars; above it `PriceExceeded`, and nothing is sent.
- `options.billingNumber` (`string`): The account's main number (the first number when omitted).
- `options.pin` (`string`): The account's PIN, or a mobile account's transfer PIN, where the carrier has one.
- `options.bill` (`Uint8Array`): A recent bill from the current carrier (PDF bytes), which some carriers ask for.
- `options.name` (`string`): What your code calls the number, when you port one.
- `options.requestedAt` (`Date | string`): When you'd like them to move; the carrier sets the dates, a few business days out at the earliest, and refuses one it doesn't allow.
- `options.remainingNumbers` (`string[]`): The account's numbers that stay with the carrier, when not all of them move; left out, every number on the
account moves. When the billing number moves, the first of them becomes the account's billing number.
- `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: The port request: an operation in `awaiting_human` until the account holder signs
(`sign_url`), then `submitted` and `scheduled` (its `step`), whose `.wait()`
gives the `PhoneNumber` objects once they've moved. They keep working with their carrier
until then.

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>;
}

/** Invite-only beta. A US address: a carrier account's service address, or a business's for its `TextingRegistration`. */
interface StreetAddress {
  street: string;
  street2?: string;
  city: string;
  /** The state, like `CA`. */
  region: string;
  postalCode: string;
}
```

### PhoneNumber.fromName

```typescript
static fromName(
  name: string,
  options?: CallOptions & {
    createIfMissing?: boolean;
    areaCode?: string | number;
    maxMonthlyUsd?: number;
    maxUpfrontUsd?: number;
    connect?: string;
    connection?: Connection | string;
    recordCalls?: boolean;;
  },
): PhoneNumber
```

A lazy reference to the number called `name` for the current (or given) user. A `recordCalls` you
pass is set on it every run. With `createIfMissing`, the first time it's used with none of that name,
NoClick buys a US local number in `areaCode` (any US one when omitted) for at most `maxMonthlyUsd` a
month and `maxUpfrontUsd` once, and names it, or with `connect` connects that number of yours through
`connection` instead; without it, a missing number throws `NotFound`. `areaCode` and the prices say
how to buy one, so they matter only then. The number itself never changes: an existing
number other than `connect` throws `Conflict` naming it.

Parameters:

- `name` (`string`, required)
- `options.createIfMissing` (`boolean`)
- `options.areaCode` (`string | number`)
- `options.maxMonthlyUsd` (`number`)
- `options.maxUpfrontUsd` (`number`)
- `options.connect` (`string`)
- `options.connection` (`Connection | string`, default `null`)
- `options.recordCalls` (`boolean`, default: unchanged)
- `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: A number that loads (or is bought, or has `record_calls` set) the first time it's used.
Nothing is sent yet.

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>;
}
```

### PhoneNumber.fromId

```typescript
static fromId(numberId: string, options?: CallOptions): PhoneNumber
```

A lazy reference to a number you own, by id.

Parameters:

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

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

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>;
}
```

### PhoneNumber.get

```typescript
static get(numberId: string, options?: CallOptions): Promise<PhoneNumber>
```

Load a number by id now; an unknown id, or one you released, raises `noclick.NotFound`.

Parameters:

- `numberId` (`string`, 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: The number, loaded.

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>;
}
```

### PhoneNumber.list

```typescript
static list(options?: ReadOptions & { limit?: number }): Promise<PhoneNumber[]>
```

The numbers you own, however you got them (bought here or in the NoClick app, or ported in): the current user's
inside `asUser`, or those `userFilter` covers. A number bought in the app is your account's own, with no `userId`
and no `name` until you give it one.

Parameters:

- `options.limit` (`number`): Return at most this many.
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `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: Every matching number, newest first, fetched page by page. Released numbers aren't listed.

Types:

```typescript
/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** 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>;
}

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

### PhoneNumber.listPage

```typescript
static listPage(options?: ReadOptions & PageOptions): Promise<Page<PhoneNumber>>
```

One page of numbers; pass `nextCursor` back as `cursor`.

Parameters:

- `options.cursor` (`string | null`): The `next_cursor` of the page before; omit it for the first page.
- `options.limit` (`number`): Return at most this many.
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `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: A page whose `data` holds the numbers and whose `next_cursor` is `None` on the last page.

Types:

```typescript
/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** 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>;
}

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

### PhoneNumber.release

```typescript
release(): Promise<void>
```

Give the number back; it stops ringing and billing. A connected number throws `Conflict`: `disconnect()` it.

### PhoneNumber.disconnect

```typescript
disconnect(): Promise<void>
```

Hand a connected number back to its provider account: NoClick takes it off its agent, puts back
where its calls went before, and it leaves your list. A bought number throws `Conflict`: `release()` it.

### PhoneNumber.update

```typescript
update(changes: { name?: string | null; recordCalls?: boolean }): Promise<this>
```

Rename it (`name: null` removes its name; one another of its user's numbers has is a `Conflict`),
or start or stop recording its calls from the next call (both sides in one file; the caller hears
that the call is recorded before the agent speaks).

Parameters:

- `changes` (`{ name?: string | null; recordCalls?: boolean }`, required)

Returns: This number, updated. A field you leave out is unchanged.

### PhoneNumber.answerWith

```typescript
answerWith(agent: Agent | string, options?: AnswerWithOptions): Promise<this>
```

Route inbound calls to `agent`, an agent on the `sdk` harness, whose tools and connections work
during a call as in a message; one on a coding harness can't answer calls (`NotAvailable`). Calling it again replaces the whole setup: an option left out goes
back to its default.

Parameters:

- `agent` (`Agent | string`, required)
- `options.transferTo` (`string | Human`): Gives the agent a `transfer_call` tool that hands the caller to this number (E.164) or `Human`
with a `phone`, once the agent has said so; who picks up hears why first, and a transfer nobody
picks up comes back to the agent, which is told.
- `options.texts` (`boolean`, invite-only beta): Invite-only beta. Gives the agent a `send_text` tool that texts the caller, and only the
caller (a link, a confirmation, an address), after asking and hearing a yes. Each text is signed
with your brand (`Harbor Dental: ...`), the first to a caller says how to opt out, and a caller who
texted STOP is never texted again. Texting from a US local number needs your business registered
with the US carriers (`TextingRegistration`); until that's approved this throws `ActionRequired`
naming it, and a number that can't text (one kept with your own phone provider, a toll-free one)
throws `NotAvailable`. Until texting ships it throws `NotAvailable`.
- `options.callers` (`PhoneCallers`, default `"anyone"`): Who gets through: `anyone` (the default), `users` (only a caller whose
number is a user's verified phone, attested by the carrier) or `owner` (only the number's own
user, or your account's owner). On an account number such a user's call runs as them under every
setting; a user's own number runs every call as that user.
- `options.conversation` (`string`): The agent's conversation each call lands in, a template over `{caller}` and `{number}`:
`"owner"` puts every call in the same conversation as `agent.message(..., { conversation: "owner" })`.
Omitted, each caller has a conversation of their own on the number.

Returns: This number, with `agent_id` naming the agent that now answers it.

Types:

```typescript
/**
 * Who gets through to a number: every caller, only your users, or only its owner (the number's own
 * user, or your account's owner), each a verified phone the carrier attests. It never changes who a
 * call runs as.
 */
type PhoneCallers = "anyone" | "users" | "owner";
```

### PhoneNumber.call

```typescript
call(
  to: string,
  options: { goal: string; agent?: Agent | string },
): Promise<Operation<PhoneCall>>
```

Call `to` with the number's answering agent working toward `goal` (`agent`, if given, must
be that agent). `wait()` resolves to the `PhoneCall` with its transcript at hang-up.

Parameters:

- `to` (`string`, required)
- `options.goal` (`string`, required)
- `options.agent` (`Agent | string`)

Returns: An operation whose `.wait()` gives the `PhoneCall` at hang-up, with its
transcript, `status` (`completed` or `not_connected`), length and cost.

### PhoneNumber.getCall

```typescript
static getCall(
  call: string | Operation<unknown>,
  options?: CallOptions,
): Promise<PhoneCall>
```

One call as it stands, read live while it goes (`call` is its id, or the operation `number.call()` returned):
its `status`, when it was `answeredAt`, what was said so far turn by turn (`lines`), who ended it (`endedBy`)
and, once it has ended, its `transcript`. An unknown call throws `NotFound`.

Parameters:

- `call` (`string | Operation<unknown>`, 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: The `noclick.PhoneCall`: its `status`, when it was `answered_at`, what was said so
far turn by turn (`lines`), who ended it (`ended_by`) and, once it has ended, its
`transcript`. An unknown call raises `noclick.NotFound`.

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>;
}
```

### PhoneNumber.hangUp

```typescript
static hangUp(
  call: string | Operation<unknown>,
  options?: CallOptions,
): Promise<PhoneCall>
```

Hang up a call the number placed, ringing or live: the agent says goodbye and the call ends (a ringing one is
cancelled). `call` is its id, or the operation `number.call()` returned. Resolves to the call as it stands; it
ends a moment later with `endedBy` `hang_up`, and its operation settles with the transcript as at any hang-up.
A call that already ended throws `Conflict`; one the number answered throws `NotAvailable`.

Parameters:

- `call` (`string | Operation<unknown>`, 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: The `noclick.PhoneCall` as it stands. It ends a moment later with `ended_by`
`hang_up`, and its operation settles with the transcript as at any hang-up. A call
that already ended raises `noclick.Conflict`; one the number answered raises
`noclick.NotAvailable`.

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>;
}
```

### PhoneNumber.calls

```typescript
calls(
  options?: {
    direction?: "inbound" | "outbound";
    since?: Date | string;
    limit?: number;
  },
): Promise<PhoneCall[]>
```

The calls on this number, newest first: the calls it answered with the ones it placed. `direction`
keeps one kind, `since` those that started at or after it, and `limit` the newest that many.

Parameters:

- `options.direction` (`"inbound" | "outbound"`)
- `options.since` (`Date | string`)
- `options.limit` (`number`): Return at most this many.

Returns: The matching calls, each with its `direction` and its transcript once it has
ended (and `recording_url` when the number records its calls).

### PhoneNumber.textMessages (invite-only beta)

```typescript
textMessages(
  options?: {
    direction?: "inbound" | "outbound";
    since?: Date | string;
    limit?: number;
  },
): Promise<PhoneText[]>
```

Invite-only beta. The texts its answering agent sent callers (`send_text`) and the texts the
number received, newest first. A reply doesn't wake the agent: read it here, or take
`phone.text.received` events. `direction` keeps one kind, `since` those at or after it.

Parameters:

- `options.direction` (`"inbound" | "outbound"`)
- `options.since` (`Date | string`)
- `options.limit` (`number`): Return at most this many.

Returns: The matching texts, each with its `direction`, `text`, `status` and cost.

### PhoneNumber.transferOut (invite-only beta)

```typescript
transferOut(): Promise<TransferOut>
```

Invite-only beta. Move the number to another carrier: what that carrier asks for (the account
it's on, whose account and billing numbers are the number itself, and a transfer PIN for it). Another carrier may take the number for 30 days from now; a
request outside that window, or quoting another PIN, is refused, so nobody takes it without you.
Once it moves, it leaves your numbers and its billing stops.

Returns: The transfer's details, with its `pin` and `expires_at`.

## AvailableNumber

```typescript
interface AvailableNumber
```

A number you can buy: `PhoneNumber.buy(available, { maxMonthlyUsd })`. `monthlyUsd` it costs a month and
`upfrontUsd` once, when it's bought. `texting`: `registration` (a US local number, which texts under
your business's US carrier registration), `unavailable` (texting from its country, or from a toll-free
number, isn't available yet) or `none` (it can't text).

| Attribute | Type | Description |
| --- | --- | --- |
| `number` | `string` |  |
| `monthlyUsd` | `number | null` |  |
| `locality` | `string | null` |  |
| `region` | `string | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `country` | `string` |  |
| `type` | `PhoneNumberType` |  |
| `upfrontUsd` | `number | null` |  |
| `capabilities` | `string[]` |  |
| `requirements` | `NumberRequirements` |  |
| `texting` | `"registration" | "unavailable" | "none"` |  |

Types:

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

/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";

/**
 * What a number's country asks before it's sold: `none`, `address` (pass `address` to `buy`), `documents`
 * (pass `requirements` to `buy` too, uploading each document with `PhoneNumber.uploadDocument`; the carrier
 * reviews them before the number is yours) or `steps` (it can't be bought through the API yet).
 */
interface NumberRequirements {
  needs: "none" | "address" | "documents" | "steps";
  items: NumberRequirement[];
}

/**
 * One thing a number's country asks before it's sold: the holder's `address` or `contact` information, an
 * answer in text (`textual`: one of `values` where it lists them; `example` is the carrier's), a `document`,
 * or a `step` that can't be taken here.
 */
interface NumberRequirement {
  id: string;
  kind: "address" | "contact" | "textual" | "document" | "step";
  name: string;
  description: string;
  example: string;
  values: string[];
}
```

## PhoneCall

```typescript
interface PhoneCall
```

One call on a number, answered (`direction` `inbound`) or placed (`outbound`). `transcript` is filled
in at hang-up; `text` reads it as lines. `PhoneNumber.getCall` reads one while it goes, with what was
said so far (`lines`).

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string | null` |  |
| `direction` | `string | null` |  |
| `to` | `string | null` |  |
| `fromNumber` | `string | null` |  |
| `status` | `string | null` | `calling` while it runs; ends `completed`, `not_connected`, `refused` (turned away by `callers`), `failed` or `lost`. |
| `goal` | `string | null` |  |
| `agentId` | `string | null` |  |
| `transcript` | `TranscriptTurn[]` |  |
| `seconds` | `number | null` |  |
| `costUsd` | `number | null` | What the call was charged, as your usage shows it (null until it has ended and its charge is recorded, or when it never connected). |
| `error` | `string | null` |  |
| `createdAt` | `Date | null` |  |
| `endedAt` | `Date | null` |  |
| `userId` | `string | null` | The user the call ran as: on an account number, a caller proven to be one of your users (their verified phone, attested by the carrier), whatever the number's `callers`; on a user's number, its user. |
| `recordingUrl` | `string | null` | A signed link to the recording (both sides, one file), valid for an hour from when you read the call; null unless the number records its calls, or once the recording is deleted. |
| `transfer` | `{ to: string; status: string; seconds?: number } | null` | Where the agent handed the caller (`to`) and whether they picked up (`status`, `seconds`); null if nobody was. |
| `answeredAt` | `Date | null` | When the call reached the agent's voice: a placed call's person picked up (null while it rings, and for a call nobody answered). |
| `endedBy` | `"hang_up" | null` | `hang_up` when `PhoneNumber.hangUp` ended it; null when the other end, the agent or the call's limit did, and while it goes. |
| `lines` | `CallLine[]` | What was said so far, turn by turn, as `PhoneNumber.getCall` reads a call while it goes; empty in a number's `calls()`. |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |
| `text` | `string` | The transcript as `role: text` lines. |

Types:

```typescript
interface TranscriptTurn {
  /** `assistant` (the agent) or `user` (the other party). */
  role: string;
  text: string;
  /** Seconds into the call. */
  at: number | null;
}

/** One line said on a call, as a person reads its turns: the other party (`them`) or the agent's voice (`agent`). */
interface CallLine {
  /** The turn it was said in, counted from the call's start. */
  turn: number;
  who: "them" | "agent";
  text: string;
}

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

## ConnectableNumber

```typescript
interface ConnectableNumber
```

A number in your phone provider account, from `PhoneNumber.connectable`: connect it with
`PhoneNumber.connect(connectable, { connection })`.

| Attribute | Type | Description |
| --- | --- | --- |
| `number` | `string` |  |
| `label` | `string | null` | The provider account's own name for it. |
| `routedElsewhere` | `boolean` | Its calls go somewhere today (a URL, an application, a SIP trunk): answering it takes them over, and `disconnect()` puts that back. |
| `phoneNumberId` | `string | null` | The NoClick number it's already connected as (null when it isn't); connecting it again throws `Conflict`. |
| `agentId` | `string | null` | The agent answering it, when it's already connected (null otherwise). |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

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

## PortRequest (invite-only beta)

```typescript
class PortRequest extends Operation
```

Invite-only beta. Numbers moving to NoClick from their carrier on one letter of
authorization: the operation `PhoneNumber.portIn` returns. It waits in `awaiting_human` until the
account holder signs the letter at `signUrl`, then runs (`step` `submitted`, then `scheduled` once
the carrier has given every number its date, `portAt` the latest) and resolves to the `PhoneNumber`s
(`source` `ported`) once they've moved. A rejection fails it with the carrier's reason:
`InvalidRequest` whose `field` names what didn't match its records (`account_name`,
`account_holder`, `service_address`, `account_number`, `billing_number`, `pin`, `numbers`,
`remaining_numbers`, `bill` or `requested_at`); `retry` sends corrected details. `cancel()` works until the carrier has committed to
a date. The numbers keep working with their carrier until they move.

| Attribute | Type | Description |
| --- | --- | --- |
| `number` | `string | null` | The first number on the letter, in E.164 form. |
| `numbers` | `PortRequestNumber[]` | Each number on the letter, with its own `status` and `portAt`: a carrier can move them on different days. |
| `portAt` | `Date | null` | When the last number moves, once every one is `scheduled`. |
| `monthlyUsd` | `number | null` | What each number costs a month once it's yours, in US dollars. |
| `signUrl` | `string | null` | While `awaiting_human`: the page where the account holder signs (it's emailed to them too). |

Types:

```typescript
/** Invite-only beta. One number on a port's letter of authorization: a carrier can move them on different days. */
interface PortRequestNumber {
  number: string;
  /** `draft`, `submitted`, `scheduled`, `rejected` or `ported`. */
  status: string | null;
  portAt: Date | null;
}
```

### PortRequest.list

```typescript
static list(
  options?: KindScopedFilters & { limit?: number },
): Promise<PortRequest[]>
```

Port requests (kind `phone.port_in`), newest first; takes `Operation.list`'s filters except `kind`.

Parameters:

- `options.limit` (`number`): Return at most this many.
- `options.client` (`NoClick`)
- `options.user` (`UserOption`): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.status` (`OperationStatus | "live" | readonly (OperationStatus | "live")[]`): Statuses, or `"live"` for every non-terminal one.
- `options.agent` (`string | ApiObject`): An `Agent` or agent id.
- `options.statusNot` (`OperationStatus | readonly OperationStatus[]`)
- `options.key` (`string`): The requesting key: its id or its prefix (`nk_live_ab12`).
- `options.createdAfter` (`Date | string`)
- `options.createdBefore` (`Date | string`)
- `options.updatedAfter` (`Date | string`): Rows changed since (for polling).
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).

Returns: Every matching port request (or the first `limit`), each with its `numbers`,
`step`, `port_at` and `sign_url`.

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>;
}

type OperationStatus =
  | "queued" | "running" | "awaiting_human"
  | "succeeded" | "failed" | "canceled" | "expired";

/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;
```

### PortRequest.listPage

```typescript
static listPage(
  options?: KindScopedFilters & PageOptions,
): Promise<Page<PortRequest>>
```

One page of port requests; pass `nextCursor` back as `cursor`.

Parameters:

- `options.cursor` (`string | null`): The `next_cursor` of the page before; omit it for the first page.
- `options.limit` (`number`): Return at most this many.
- `options.client` (`NoClick`)
- `options.user` (`UserOption`): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.status` (`OperationStatus | "live" | readonly (OperationStatus | "live")[]`): Statuses, or `"live"` for every non-terminal one.
- `options.agent` (`string | ApiObject`): An `Agent` or agent id.
- `options.statusNot` (`OperationStatus | readonly OperationStatus[]`)
- `options.key` (`string`): The requesting key: its id or its prefix (`nk_live_ab12`).
- `options.createdAfter` (`Date | string`)
- `options.createdBefore` (`Date | string`)
- `options.updatedAfter` (`Date | string`): Rows changed since (for polling).
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).

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

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>;
}

type OperationStatus =
  | "queued" | "running" | "awaiting_human"
  | "succeeded" | "failed" | "canceled" | "expired";

/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;
```

### PortRequest.retry

```typescript
retry(corrections?: Partial<PortDetails>): Promise<PortRequest>
```

Send a port the carrier refused again with corrected details, for the numbers that haven't moved; a
detail you leave out keeps what it had. A change to what the letter says (the account holder, the
account's name, the service address, the account or billing number), or a refusal of the name it
was signed with, asks the account holder to sign again; a new `pin`, `bill`, `requestedAt` or
`remainingNumbers` goes straight back. Resolves to a new `PortRequest` for the same numbers.

Parameters:

- `corrections` (`Partial<PortDetails>`)

Returns: A new port request for the same numbers, waiting as `port_in`'s does.

Types:

```typescript
/**
 * Invite-only beta. How the current carrier knows the numbers' account, as its bill shows it,
 * for `PhoneNumber.portIn`.
 */
interface PortDetails {
  /** The person authorized on the account, who signs the letter of authorization on a NoClick page: a `Human` with an email, or the email. */
  accountHolder: Human | string;
  /** The name on the account, often a business, not the signer. */
  accountName: string;
  serviceAddress: StreetAddress;
  accountNumber: string;
  /** The account's main number (the first number when omitted). */
  billingNumber?: string;
  /** The account's PIN, or a mobile account's transfer PIN, where the carrier has one. */
  pin?: string;
  /** A recent bill from the current carrier (PDF bytes), which some carriers ask for. */
  bill?: Uint8Array;
  /** When you'd like them to move; the carrier sets the dates, a few business days out at the earliest, and refuses one it doesn't allow. */
  requestedAt?: Date | string;
  /**
   * The account's numbers that stay with the carrier, when not all of them move; left out, every number on the
   * account moves. When the billing number moves, the first of them becomes the account's billing number.
   */
  remainingNumbers?: string[];
}

/** Invite-only beta. A US address: a carrier account's service address, or a business's for its `TextingRegistration`. */
interface StreetAddress {
  street: string;
  street2?: string;
  city: string;
  /** The state, like `CA`. */
  region: string;
  postalCode: string;
}
```

### PortRequest.portFromId

```typescript
static portFromId(operationId: string, options?: CallOptions): PortRequest
```

A lazy reference to a port by operation id: resume it anywhere (`Operation.fromId` gives a plain operation).

Parameters:

- `operationId` (`string`, required)
- `options.client` (`NoClick`)
- `options.user` (`UserOption`): `undefined` = the ambient user (`asUser`), `null` = the account itself.

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>;
}
```

## TextingRegistration (invite-only beta)

```typescript
class TextingRegistration
```

Invite-only beta. Your business registered with the US carriers, which texting from a US
number needs: the brand the carriers' registry verifies, and the campaign NoClick writes for it (a
voice agent texting a caller one thing they asked for, after a spoken yes). One per scope: your
account's, or one of your users' (a user's own number texts under its user's registration when there
is one, else the account's). Review takes days to weeks; `status` follows it: `pending`,
`awaiting_human` (its contact must answer the registry: a public company's verification email, or a
sole proprietor's texted code, sent back with `verify`), `in_review`, then `approved`, `rejected`
(`statusReason`, and `fields` names the facts to correct with `update`) or `suspended`. `delete()`
stops texting and its monthly fee.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `status` | `string | null` | `pending`, `awaiting_human`, `in_review`, `approved`, `rejected` or `suspended`. |
| `statusReason` | `string | null` | The reviewer's words, when it refused or suspended it. |
| `fields` | `string[]` | The facts a refusal named, to correct with `update`. |
| `legalName` | `string | null` |  |
| `brandName` | `string | null` | What its texts are signed with: `Harbor Dental: ...`. |
| `entityType` | `string | null` |  |
| `industry` | `string | null` |  |
| `website` | `string | null` |  |
| `taxId` | `string | null` | The EIN, its last four digits shown. |
| `privacyUrl` | `string | null` |  |
| `termsUrl` | `string | null` |  |
| `setupUsd` | `number | null` | Charged once, as the registry charges it: the brand when registered, the campaign's review and first months when it opens. |
| `monthlyUsd` | `number | null` | The campaign's monthly fee, after its first months. |
| `segmentUsd` | `number | null` | What a text costs a segment (160 characters), sent or received, before the other person's network fee, which is charged as reported. |
| `userId` | `string | null` |  |
| `approvedAt` | `Date | null` |  |
| `createdAt` | `Date | null` |  |

### TextingRegistration.create

```typescript
static create(
  options: TextingRegistrationDetails & CallOptions,
): Promise<TextingRegistration>
```

Register the business with the US carriers, as the legal entity on its tax records. Resolves to the
registration, `pending`; its brand's fee is charged now. A scope that has one throws `Conflict` with
its `existingId`.

Parameters:

- `options.legalName` (`string`, required): The legal entity as its tax records name it.
- `options.entityType` (`"private_company" | "public_company" | "nonprofit" | "government" | "sole_proprietor"`, required)
- `options.industry` (`string`, required): One of the registry's (`healthcare`, `retail`, `professional`, ...).
- `options.address` (`StreetAddress`, required): Its US address.
- `options.website` (`string`, required): `website`, `privacyUrl` and `termsUrl` are pages anyone can open; the privacy policy must say phone numbers aren't shared.
- `options.contact` (`TextingContact`, required)
- `options.privacyUrl` (`string`, required)
- `options.termsUrl` (`string`, required)
- `options.maxSetupUsd` (`number`, required): Refused (`PriceExceeded`, nothing registered) above this once, in US dollars.
- `options.maxMonthlyUsd` (`number`, required): Refused (`PriceExceeded`, nothing registered) above this a month, in US dollars.
- `options.taxId` (`string`): Its EIN (none for a sole proprietor).
- `options.brandName` (`string`): What texts are signed with (the legal name when omitted).
- `options.stock` (`{ symbol: string; exchange: string }`): A public company's listing.
- `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: The registration, `pending`; its brand's fee is charged now. A scope that has one
raises `noclick.Conflict` with its `existing_id`.

Types:

```typescript
/** Invite-only beta. A US address: a carrier account's service address, or a business's for its `TextingRegistration`. */
interface StreetAddress {
  street: string;
  street2?: string;
  city: string;
  /** The state, like `CA`. */
  region: string;
  postalCode: string;
}

/** Invite-only beta. The person the carriers' registry contacts: your business's own, never NoClick's. */
interface TextingContact {
  name: string;
  email: string;
  phone: string;
}

/** `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>;
}
```

### TextingRegistration.fromId

```typescript
static fromId(
  registrationId: string,
  options?: CallOptions,
): TextingRegistration
```

A lazy reference to a registration by id.

Parameters:

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

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

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>;
}
```

### TextingRegistration.get

```typescript
static get(
  registrationId: string,
  options?: CallOptions,
): Promise<TextingRegistration>
```

Load a registration by id now; an unknown or deleted one throws `NotFound`.

Parameters:

- `registrationId` (`string`, 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: The registration, loaded.

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>;
}
```

### TextingRegistration.list

```typescript
static list(
  options?: ReadOptions & { limit?: number },
): Promise<TextingRegistration[]>
```

The registrations of the current user (or, without one, the account's), or those `userFilter` covers, newest first.

Parameters:

- `options.limit` (`number`): Return at most this many.
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `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: Every matching registration, newest first. Deleted ones aren't listed.

Types:

```typescript
/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** 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>;
}

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

### TextingRegistration.update

```typescript
update(corrections: Partial<TextingRegistrationDetails>): Promise<this>
```

Resubmit a refused registration (or one waiting on its contact) with corrected facts; a fact you
leave out keeps what it had. A corrected `privacyUrl` or `termsUrl` opens a new campaign, whose
review and first months are charged again. Resolves to this registration, back in review.

Parameters:

- `corrections` (`Partial<TextingRegistrationDetails>`, required)

Returns: This registration, back in review.

Types:

```typescript
/** Invite-only beta. What `TextingRegistration.create` takes; `update` takes any of them. */
interface TextingRegistrationDetails {
  /** The legal entity as its tax records name it. */
  legalName: string;
  entityType: "private_company" | "public_company" | "nonprofit" | "government" | "sole_proprietor";
  /** One of the registry's (`healthcare`, `retail`, `professional`, ...). */
  industry: string;
  /** Its US address. */
  address: StreetAddress;
  /** `website`, `privacyUrl` and `termsUrl` are pages anyone can open; the privacy policy must say phone numbers aren't shared. */
  website: string;
  contact: TextingContact;
  privacyUrl: string;
  termsUrl: string;
  /** Refused (`PriceExceeded`, nothing registered) above this once, in US dollars. */
  maxSetupUsd: number;
  /** Refused (`PriceExceeded`, nothing registered) above this a month, in US dollars. */
  maxMonthlyUsd: number;
  /** Its EIN (none for a sole proprietor). */
  taxId?: string;
  /** What texts are signed with (the legal name when omitted). */
  brandName?: string;
  /** A public company's listing. */
  stock?: { symbol: string; exchange: string };
}

/** Invite-only beta. A US address: a carrier account's service address, or a business's for its `TextingRegistration`. */
interface StreetAddress {
  street: string;
  street2?: string;
  city: string;
  /** The state, like `CA`. */
  region: string;
  postalCode: string;
}

/** Invite-only beta. The person the carriers' registry contacts: your business's own, never NoClick's. */
interface TextingContact {
  name: string;
  email: string;
  phone: string;
}
```

### TextingRegistration.verify

```typescript
verify(code: string): Promise<this>
```

A sole proprietor's contact sends back the code the registry texted them (`InvalidRequest` naming `code` when it's wrong or expired).

Parameters:

- `code` (`string`, required)

Returns: This registration, its contact verified.

### TextingRegistration.delete

```typescript
delete(): Promise<void>
```

Stop texting under it: its numbers stop texting, its campaign closes and its monthly fee ends.

## PhoneText (invite-only beta)

```typescript
interface PhoneText
```

Invite-only beta. A text a number's agent sent a caller (`direction` `outbound`) or one the
number received (`inbound`).

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string | null` |  |
| `direction` | `string | null` |  |
| `fromNumber` | `string | null` |  |
| `to` | `string | null` |  |
| `text` | `string | null` |  |
| `keyword` | `string | null` | `stop`, `start` or `help` when a received text was one: STOP stops texts to its sender, START lets them through again, and both are answered in your business's name. |
| `status` | `string | null` | `sent`, then `delivered` or `failed`, for one sent; `received` for one received. |
| `segments` | `number | null` |  |
| `costUsd` | `number | null` | What it was charged: its segments, and the other person's network fee once it's reported (a network may charge to send a text, to receive one, or both). |
| `callId` | `string | null` |  |
| `error` | `string | null` |  |
| `createdAt` | `Date | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

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

## TransferOut (invite-only beta)

```typescript
class TransferOut
```

Invite-only beta. What the carrier you're moving a number to asks for, from
`number.transferOut()`: the account the number is on (its name, its account and billing numbers, which are
the number itself, and its service address) and a transfer `pin` for this number, good until `expiresAt`.
Until then another carrier may take the number; after it, a request is refused. Printing it never shows the
PIN.

| Attribute | Type | Description |
| --- | --- | --- |
| `phoneNumberId` | `string | null` |  |
| `number` | `string | null` |  |
| `accountName` | `string | null` |  |
| `accountNumber` | `string | null` |  |
| `pin` | `string | null` |  |
| `serviceAddress` | `string | null` |  |
| `expiresAt` | `Date | null` |  |
| `billingNumber` | `string | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

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

## NumberHolder

```typescript
interface NumberHolder
```

Who a number is registered to, for a country that asks who holds it (a requirement's `kind` is `address` or
`contact`).

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `string` | First and last name. |
| `street` | `string` |  |
| `city` | `string` |  |
| `postalCode` | `string` |  |
| `country` | `string` | ISO alpha-2. |
| `businessName` | `string` |  |
| `street2` | `string` |  |
| `region` | `string` | State, province or county, where the country has one. |
| `phone` | `string` | A number to contact them on, in E.164; required where one of the requirements' `kind` is `contact`. |

## NumberHolderProfile

```typescript
interface NumberHolderProfile
```

The number holder profile on file (`PhoneNumber.setHolderProfile`): who your numbers (or a user's) are registered to
where their country asks, the answers to what those countries ask by requirement id, and when the holder accepted
having them filed in their name. A purchase files it with `holderOnFile: true`; where your approval settings make
`person_filing` standing, an app's code buying a number that files it runs with no one asked.

| Attribute | Type | Description |
| --- | --- | --- |
| `holder` | `NumberHolder` |  |
| `requirements` | `Record<string, string>` |  |
| `acceptedAt` | `Date | null` |  |
| `userId` | `string | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

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

## NumberCoverage

```typescript
interface NumberCoverage
```

A country numbers are for sale in, the kinds in stock there, the kinds that can text, the kinds bought with
documents the carrier reviews first (`documentsTypes`) and the kinds that ask a step that can't be taken here
(`stepsTypes`: these can't be bought through the API yet).

| Attribute | Type | Description |
| --- | --- | --- |
| `country` | `string` |  |
| `types` | `PhoneNumberType[]` |  |
| `textingTypes` | `PhoneNumberType[]` |  |
| `documentsTypes` | `PhoneNumberType[]` |  |
| `stepsTypes` | `PhoneNumberType[]` |  |

Types:

```typescript
/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";
```

## NumberPlace

```typescript
interface NumberPlace
```

A place numbers of a kind are for sale in: a city, or an area code in North America.

| Attribute | Type | Description |
| --- | --- | --- |
| `kind` | `"locality" | "area_code"` |  |
| `value` | `string` |  |
| `region` | `string` |  |

## NumberDocument

```typescript
interface NumberDocument
```

A document you uploaded for one of a number's requirements (`PhoneNumber.uploadDocument`): pass it, or its
`id`, in `requirements` when you buy. The carrier holds the file; NoClick keeps its name and what it's for.
One no purchase names within 25 minutes is gone; one a purchase named can be named again.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `requirementId` | `string` |  |
| `requirementName` | `string` |  |
| `filename` | `string` |  |
| `uploadedAt` | `Date | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

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

## PhoneNumberOrder

```typescript
class PhoneNumberOrder
```

A number ordered while the carrier reviews the documents filed for it (`PhoneNumber.buy` of a number whose
country asks for them). Nothing is yours, or charged, until it completes: `status` is `in_review`,
`rejected` (the carrier sent it back: `reason` says why; `resubmit` corrections before `deadline`),
`completed` (`phoneNumber()` is the number) or `failed` (it ended without the number; nothing was charged).

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `number` | `string` | The number ordered, in E.164 form. |
| `country` | `string | null` |  |
| `type` | `PhoneNumberType | null` |  |
| `status` | `"in_review" | "rejected" | "completed" | "failed"` | `in_review`, `rejected`, `completed` or `failed`. |
| `reason` | `string | null` | The carrier's words when it sent the order back or ended it (null otherwise). |
| `deadline` | `Date | null` | When a sent-back order must be corrected by. |
| `monthlyUsd` | `number | null` | What the number costs a month, once it's yours. |
| `upfrontUsd` | `number | null` | What it costs once, charged when the order completes. |
| `phoneNumberId` | `string | null` | The number, once the order completed. |
| `requirements` | `NumberRequirements | null` | While it's open: what its country asks, which a `resubmit` answers. |
| `createdAt` | `Date | null` |  |
| `updatedAt` | `Date | null` |  |

Types:

```typescript
/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";

/**
 * What a number's country asks before it's sold: `none`, `address` (pass `address` to `buy`), `documents`
 * (pass `requirements` to `buy` too, uploading each document with `PhoneNumber.uploadDocument`; the carrier
 * reviews them before the number is yours) or `steps` (it can't be bought through the API yet).
 */
interface NumberRequirements {
  needs: "none" | "address" | "documents" | "steps";
  items: NumberRequirement[];
}

/**
 * One thing a number's country asks before it's sold: the holder's `address` or `contact` information, an
 * answer in text (`textual`: one of `values` where it lists them; `example` is the carrier's), a `document`,
 * or a `step` that can't be taken here.
 */
interface NumberRequirement {
  id: string;
  kind: "address" | "contact" | "textual" | "document" | "step";
  name: string;
  description: string;
  example: string;
  values: string[];
}
```

### PhoneNumberOrder.retrieve

```typescript
static retrieve(
  orderId: string,
  options?: CallOptions,
): Promise<PhoneNumberOrder>
```

Load an order by id now; an unknown id throws `NotFound`.

Parameters:

- `orderId` (`string`, 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: The order, as it stands.

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>;
}
```

### PhoneNumberOrder.resubmit

```typescript
resubmit(
  options?: {
    address?: NumberHolder;
    requirements?: Record<string, string | NumberDocument>;
  },
): Promise<this>
```

File corrected answers for an order the carrier sent back (`status` `rejected`), for its review again:
`address` and `requirements` as `PhoneNumber.buy` takes them. Any other order throws `Conflict`.

Parameters:

- `options.address` (`NumberHolder`)
- `options.requirements` (`Record<string, string | NumberDocument>`)

Returns: This order, `in_review` again.

### PhoneNumberOrder.phoneNumber

```typescript
phoneNumber(): Promise<PhoneNumber>
```

The number, once the order completed; `Conflict` while it hasn't (`refresh()` first).

Returns: The `noclick.PhoneNumber` the order became.
