---
title: domainkit
description: Every namespace the package root exports, what each one owns, how the composed layer is built, and the failure shape every operation raises.
sidebar:
  label: domainkit
seo:
  title: DomainKit core API reference
---

The package root is one module per concept. A service module exposes `Service` (the tag) and
`Interface` (its shape); a value module exposes `Model` (the schema).

```ts
import { DnsRecord, DomainKit, Provision, Verify } from "domainkit";
```

Every namespace below is also its own subpath, for a package that emits declarations or wants a
narrow import: see [entry points](/docs/reference/entry-points#one-subpath-per-namespace).

{/* reference-inventory:start */}

## Lifecycle services

Each one is a `Service` tag, an `Interface`, a `layer`, and free accessors that read the service
from context (`Provision.plan(...)`). `Policy` values are `Context.Reference`s with defaults.

| Namespace   | Owns                                                                                                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Connect`   | `inspect`, `discover`, `zones`, `start`, `reconnect`, `complete`, `completeOutcome`, `attach`, `detach`, `disconnect`, `refresh`, `session`                                                 |
| `Provision` | `plan`, `approve`, `reject`, `apply`, `get`, `latest` over durable attempts, and `batch` over many at once                                                                                  |
| `Cleanup`   | The same verbs over a plan built from an apply receipt                                                                                                                                      |
| `Verify`    | `observe`, `attachEvidence`, `latest`, `summary`, `requirementKey`, `Observer` (`readinessChanged({ ownerId, domain, readiness, cause })`), `Policy`, and the evidence classes they produce |

## Host seams

| Namespace   | Owns                                                                             |
| ----------- | -------------------------------------------------------------------------------- |
| `Principal` | `{ ownerId, actorId }` per request; every Storage query is scoped by it          |
| `Storage`   | Every durable row, the row schemas, `layerMemory`, and `layerFromAsync`          |
| `Custody`   | Sealing credentials: `layer`, `layerConfig`, `layerFromAsync`, and `generateKey` |

## Providers

| Namespace    | Owns                                                                                     |
| ------------ | ---------------------------------------------------------------------------------------- |
| `Provider`   | `Definition`, `make`, `tokenAuth`, `Session`, `Dns`, `Target`, `Resolution`, `fromAsync` |
| `Providers`  | The registry of enabled definitions, built by `DomainKit.layer`                          |
| `Cloudflare` | `provider`, `AccountContext`, `TokenFields`, and the OAuth server metadata               |
| `Vercel`     | `provider`, `TeamContext`, and `TokenFields`                                             |

## Values

| Namespace    | Owns                                                                                                      |
| ------------ | --------------------------------------------------------------------------------------------------------- |
| `DomainName` | A normalized, IDN-aware hostname, its zone `candidates`, and `isWithin`                                   |
| `DnsRecord`  | Record constructors including `txt` and `spf`, `Model`, `Observed`, `Opaque`, `data`, `equals`, `sameSet` |
| `Plan`       | `Model`, the four operations, `writes`, `conflicts`, `isApplicable`, `renderInstructions`                 |
| `Approval`   | Consent bound to one plan digest and an explicit operation set                                            |
| `Receipt`    | What an apply actually wrote: `Applied`, `Skipped`, `Failed`, `applied`, `isComplete`                     |

## Everything else

| Namespace   | Owns                                                                             |
| ----------- | -------------------------------------------------------------------------------- |
| `DomainKit` | `layer`, `layerMemory`, `Error`, `ErrorCategory`, and `isError`                  |
| `Reason`    | The seventeen failure reasons and their union, `Reason.Model`                    |
| `Resolver`  | The public DNS pool: `layer` (Cloudflare and Google DoH), `layerWith`, `Outcome` |
| `VERSION`   | The installed package version, read from the package manifest                    |

{/* reference-inventory:end */}

## Composing the layer

`DomainKit.layer({ providers, resolver? })` provides every lifecycle service and requires `Storage`
and `Custody` beneath it. `DomainKit.layerMemory` adds the in-memory pair and a throwaway custody
key for tests and playgrounds.

<Snippet file="examples/storage/postgres.ts" region="wire" title="Composing the layer" />

## Failures

Every operation fails with `DomainKit.Error`. It carries one `Reason`, and `category`,
`isRetryable`, and `httpStatus` derive from it.

| Property      | Values                                                        |
| ------------- | ------------------------------------------------------------- |
| `reason`      | One member of `Reason.Model`                                  |
| `category`    | `request`, `auth`, `plan`, `provider`, `storage`, `internal`  |
| `isRetryable` | `true` for `Busy`, `ProviderUnavailable`, and `StorageFailed` |
| `httpStatus`  | The status `domainkit/server` answers with                    |

[Failure reasons](/docs/core/errors) lists every reason with its status and the next step.

## Completion outcomes

`Connect.completeOutcome({ continuationId, callbackUrl, provider? })` shares the completion lock,
exchange, persistence, and spending path with `Connect.complete`. Its `Connect.Completion` tagged
value is `Connected { started }`, `Cancelled { error }`, or `Failed { error, recovery }`.
`started` contains a connection and either an attachment or zone candidates; no redirect is produced.
`error` is the original `DomainKit.Error` for server-side handling. Do not send this value to a
browser: [Server callback outcomes](/docs/reference/server#callback-destinations) omit those errors
and storage rows.

The operation verifies the live continuation and its owner and actor inside the lock before
classifying callback parameters. `provider`, when supplied, also binds the stored flow to that
provider route. Invalid flows fail without an outcome; direct missing/expired reads retain
`NotFound`/`Expired`. `Connect.complete` returns the same `Started` result or original completion
error for ordinary callers. Neither operation spends cancellation or failure; persistence can be
partial, and `recovery: "inspect"` requires inspecting durable state before deciding whether to
restart. A provider code can be single-use even when the continuation is still live.