domainkit 0.3.1 → 0.5.0

package/README.md

@@ -1,139 +1,72 @@
 # DomainKit
 
-DomainKit is a provider-independent TypeScript SDK for turning DNS requirements into reviewable,
-authorized provisioning plans. Products can connect customer domains without making one
-registrar's API or authorization model their architecture.
+Domain setup infrastructure for TypeScript SaaS applications.
 
-DomainKit is additive and fail-closed. It creates missing records, treats exact records as no-ops,
-reports incompatible state as a conflict, and never silently overwrites DNS. Every applied write is
-bound to an approved plan digest and recorded in a receipt that can authorize a separate cleanup.
+DomainKit turns DNS requirements into reviewable plans, requires explicit digest-bound
+authorization before writes, records applied changes in receipts, and uses those receipts to plan
+safe cleanup. It supports Cloudflare and Vercel without making either provider's API your product
+architecture.
 
-## Package shape
+## Install
 
-- `domainkit` — canonical Effect services, programs, schemas, and first-party providers;
-- `domainkit/promise` — secondary Promise facade for foreign runtime boundaries;
-- `domainkit/testing` — in-memory lifecycle capabilities and the provider conformance runner.
+```sh
+npm install domainkit effect@rc
+```
 
-The package is portable ESM built on Fetch, Web Crypto, and Web APIs. Effect is a peer dependency.
-Promise namespaces delegate to the Effect implementation rather than maintaining another planner,
-authorization engine, or verifier. There are no provider-specific subpaths: `Cloudflare` and
-`Vercel` are cohesive namespaces on each root.
+Node.js 24.10 or newer and Effect 4 are required.
 
 ## Plan, approve, and apply
 
 ```ts
+import { Digest, DnsRecord, DomainName, Provisioning } from "domainkit";
+import { InMemoryDnsProvider } from "domainkit/testing";
 import { Effect, Layer } from "effect";
-import { Digest, DnsProvider, Provisioning } from "domainkit";
-
-const program = Provisioning.create({
-  requirements,
-  target: Provisioning.Target.ExactZone({ zone: "example.com" }),
-}).pipe(
-  Effect.flatMap(({ plan }) =>
-    Provisioning.authorize(plan).pipe(
-      Effect.flatMap((authorization) => Provisioning.apply({ authorization, plan })),
-    ),
-  ),
-  Effect.provide(Layer.merge(Layer.succeed(DnsProvider.Service, provider), Digest.webCryptoLayer)),
-);
-```
-
-Promise consumers use the explicit secondary entry point at a JavaScript boundary:
 
-```ts
-import { Provisioning } from "domainkit/promise";
-
-const { plan } = await Provisioning.create({
-  provider,
-  requirements,
-  target: Provisioning.Target.ExactZone({ zone: "example.com" }),
+const requirement = DnsRecord.parse({
+  _tag: "CNAME",
+  metadata: {
+    ownership: "customer",
+    provenance: "product-onboarding",
+    purpose: "tracking",
+  },
+  name: "track.example.com",
+  policy: "exclusive",
+  target: "tracking.example.net",
+  ttl: 300,
 });
-```
-
-Use `DiscoverFromDomain` when the host has several authorized provider accounts. `ZoneDiscovery`
-checks the requested name and its parents, returns `Resolved`, `SelectionRequired`, or `NotFound`,
-and never guesses between ambiguous accounts.
-
-## Connect provider accounts
-
-`Connection.start` handles token and interactive provider methods. It returns either `Connected`
-or `Redirect`; `Connection.complete` consumes an interactive continuation exactly once. Cloudflare
-implements OAuth and token methods. Vercel implements its installation-code flow without
-mislabeling it as generic OAuth.
-
-After a host proves that an existing connected account owns another domain and obtains the owner's
-consent, `Connection.extend` adds that domain to the existing owner grant without repeating provider
-authentication. It preserves earlier domain grants and rejects cross-owner, expired, or revoking
-connections.
-
-Cloudflare can discover the selected account from a domain already visible to the credential, so a
-customer does not need to find or type an account ID. Vercel retains explicit personal or team
-context returned by the installation. Both contexts are versioned, non-secret values that can
-reconstruct the correct provider client later.
-
-Hosts provide one `AuthorizationLifecycle` repository for an authorization aggregate, its
-credential, and its owner bindings. SQL hosts can implement one transaction; split database and
-vault hosts can implement a recoverable saga behind the same interface. Interactive continuations
-remain separate, short-lived, one-time state. DomainKit does not choose a database, cache, vault,
-callback route, session model, consent UI, or audit system.
 
-Provider scope claims are not treated as proof. Each required capability carries `Declared`,
-`Introspected`, or `Exercised` evidence. Final-binding revocation is fail-closed: durable state
-remains retryable until the provider confirms revocation.
-
-## Observe DNS
-
-`Verification.observe` is the only verification operation. Public DNS is the default:
-
-```ts
-import { Effect } from "effect";
-import { DnsProvider, Verification } from "domainkit";
-
-const result = await Effect.runPromise(Verification.observe({ record }));
-```
-
-The default resolver pool queries Cloudflare and Google concurrently using RFC wire-format DNS over
-HTTPS and applies `AnyMatch`. Results preserve every named answer, negative response, timeout, and
-failure. Hosts can supply another resolver pool or choose tagged `AllMatch` and `Quorum` policies.
-
-Authoritative-provider observation is opt-in:
-
-```ts
-const result = await Verification.observe({
-  provider: Verification.Provider.Enabled({ zone }),
-  publicDns: Verification.PublicDns.Disabled(),
-  record,
-}).pipe(Effect.provideService(DnsProvider.Service, provider), Effect.runPromise);
+const program = Effect.gen(function* () {
+  const { plan } = yield* Provisioning.create({
+    requirements: [requirement],
+    target: Provisioning.Target.ExactZone({
+      zone: DomainName.parse("example.com"),
+    }),
+  });
+  const authorization = yield* Provisioning.authorize(plan);
+  return yield* Provisioning.apply({ authorization, plan });
+}).pipe(Effect.provide(Layer.merge(InMemoryDnsProvider.layer(), Digest.webCryptoLayer)));
 ```
 
-When both sources are requested, both must match for `Verified`. Every result is exhaustive and
-tagged as `NotObserved`, `Pending`, `Mismatch`, `Unavailable`, or `Verified`.
+Planning is additive and fail-closed: exact records become no-ops, missing records become creates,
+and incompatible state becomes a conflict. DomainKit never silently overwrites DNS.
 
-## Implement a DNS provider
+## Public entry points
 
-Implement the narrow `DnsProvider` contract exported from `domainkit`. Then
-run the deterministic offline contract exported from `domainkit/testing`:
+- `domainkit` — canonical Effect services, schemas, plans, providers, and verification;
+- `domainkit/promise` — Promise adapters for foreign-runtime boundaries;
+- `domainkit/testing` — in-memory services and provider conformance helpers.
 
-```ts
-import { Effect } from "effect";
-import { DomainName } from "domainkit";
-import { ProviderConformance } from "domainkit/testing";
-
-const report = await Effect.runPromise(
-  ProviderConformance.run({
-    makeProvider: ProviderConformance.fromAsync(() => makeFreshPromiseProvider()),
-    zone: DomainName.parse("example.com"),
-  }),
-);
-```
+Provider credentials, OAuth state, durable connections, plans, receipts, authorization, and audit
+history remain owned by your application. DomainKit supplies the domain model and operations, not a
+hosted control plane.
 
-The contract covers complete readback across provider pages, exact no-op, conflict, create, stale
-plans, partial receipts, and receipt-bound cleanup. First-party providers run the same contract and
-credential-gated live profiles against disposable records.
+## Learn more
 
-Schemas own external and persisted parsing; Effect `Data` values own in-process configuration and
-control flow. See [the architecture decisions](docs/adr/README.md),
-[provider behavior](docs/providers.md), and [runnable examples](examples/).
+- [Executable quickstart](https://github.com/AryaLabsHQ/domainkit/blob/main/packages/domainkit/examples/effect/quickstart.ts)
+- [Architecture decisions](https://github.com/AryaLabsHQ/domainkit/tree/main/docs/adr)
+- [Provider behavior](https://github.com/AryaLabsHQ/domainkit/blob/main/docs/providers.md)
+- [Examples](https://github.com/AryaLabsHQ/domainkit/tree/main/packages/domainkit/examples)
+- [Issues](https://github.com/AryaLabsHQ/domainkit/issues)
 
 ## License