domainkit 0.15.0 → 0.16.0

package/dist/types/Storage.d.ts

@@ -130,6 +130,94 @@ declare const Attempt_base: Schema.Class<Attempt, Schema.Struct<{
 /** One durable plan -> approval -> receipt lifecycle. */
 export declare class Attempt extends Attempt_base {
 }
+export declare const BatchId: Schema.brand<Schema.String, "@domainkit/BatchId">;
+export type BatchId = typeof BatchId.Type;
+/**
+ * Where a batch stands, recomputed from its items' attempts after every transition.
+ *
+ * `planning` while any item is still without a plan, `planned` once every item carries one,
+ * `approved` once the principal bound the batch digest, then the apply states. `partial` and
+ * `failed` are resumable; `complete` and `rejected` are terminal and leave the unfinished index.
+ */
+export declare const BatchStatus: Schema.Literals<readonly ["planning", "planned", "approved", "applying", "complete", "partial", "failed", "rejected"]>;
+export type BatchStatus = typeof BatchStatus.Type;
+/** Who bound the batch to its digest, and when. The digest itself is `Batch.digest`. */
+export declare const BatchApproval: Schema.Struct<{
+    readonly actorId: Schema.String;
+    readonly at: Schema.DateTimeUtcFromString;
+}>;
+export type BatchApproval = typeof BatchApproval.Type;
+declare const Batch_base: Schema.Class<Batch, Schema.Struct<{
+    readonly id: Schema.brand<Schema.String, "@domainkit/BatchId">;
+    readonly ownerId: Schema.String;
+    readonly kind: Schema.Literals<readonly ["provisioning", "cleanup"]>;
+    readonly status: Schema.Literals<readonly ["planning", "planned", "approved", "applying", "complete", "partial", "failed", "rejected"]>;
+    /** SHA-256 over the items' `attachmentId:planDigest` pairs, bound at approval. */
+    readonly digest: Schema.NullOr<Schema.brand<Schema.String, "@domainkit/Digest">>;
+    readonly approval: Schema.NullOr<Schema.Struct<{
+        readonly actorId: Schema.String;
+        readonly at: Schema.DateTimeUtcFromString;
+    }>>;
+    readonly rejection: Schema.NullOr<Schema.Struct<{
+        readonly actorId: Schema.String;
+        readonly reason: Schema.NullOr<Schema.String>;
+        readonly at: Schema.DateTimeUtcFromString;
+    }>>;
+    /** Unique per owner: a replayed create returns the batch this key already made. */
+    readonly idempotencyKey: Schema.String;
+    readonly createdBy: Schema.String;
+    readonly createdAt: Schema.DateTimeUtcFromString;
+    readonly updatedAt: Schema.DateTimeUtcFromString;
+    /** When the batch reached `complete` or `rejected`; null while it still owes a move. */
+    readonly completedAt: Schema.NullOr<Schema.DateTimeUtcFromString>;
+}>, {}>;
+/**
+ * Many domains planned together, approved once, and applied with bounded concurrency.
+ *
+ * The batch owns the aggregate's own state only: its digest, who approved or declined it, and the
+ * status recomputed from its items. Every plan, approval, receipt, lease, and failure stays on the
+ * attempt an item points at, so nothing is stored twice.
+ */
+export declare class Batch extends Batch_base {
+}
+declare const BatchItem_base: Schema.Class<BatchItem, Schema.Struct<{
+    readonly batchId: Schema.brand<Schema.String, "@domainkit/BatchId">;
+    readonly attachmentId: Schema.String;
+    /** The item's place in the batch, as `create` received it. */
+    readonly position: Schema.Number;
+    readonly attemptId: Schema.NullOr<Schema.brand<Schema.String, "@domainkit/PlanId">>;
+    readonly planFailure: Schema.NullOr<Schema.String>;
+}>, {}>;
+/**
+ * One domain's place in a batch: a pointer to the attachment and to the attempt carrying its plan.
+ *
+ * `attemptId` is null until the item is planned, and `planFailure` carries why the last planning
+ * pass stopped, cleared the moment a plan lands.
+ */
+export declare class BatchItem extends BatchItem_base {
+}
+/**
+ * The status a batch holds, given whether it was approved or declined and where each item's
+ * attempt stands. `null` names an item that has no plan yet.
+ *
+ * Both `Storage` implementations recompute the stored status through this after every transition,
+ * so the owner-scoped unfinished index never disagrees with the attempts it summarizes.
+ */
+export declare const batchStatusOf: (input: {
+    readonly approved: boolean;
+    readonly rejected: boolean;
+    readonly items: ReadonlyArray<AttemptStatus | null>;
+}) => BatchStatus;
+/** A batch with its items, in `position` order. Every batch read returns one. */
+export interface BatchAggregate {
+    readonly batch: Batch;
+    readonly items: ReadonlyArray<BatchItem>;
+}
+/** One item's attempt approval, as `batches.approve` writes it beside the batch's own. */
+export interface BatchItemApproval {
+    readonly attachmentId: string;
+    readonly approval: Approval.Model;
+}
 export declare const RequirementStatus: Schema.Literals<readonly ["satisfied", "missing", "mismatch", "unknown"]>;
 export type RequirementStatus = typeof RequirementStatus.Type;
 export declare const Overall: Schema.Literals<readonly ["ready", "pending", "failed"]>;
@@ -247,6 +335,72 @@ export interface Interface {
         readonly complete: (id: Plan.PlanId, receipt: Receipt.Model) => Fx<Attempt>;
         readonly fail: (id: Plan.PlanId, message: string) => Fx<Attempt>;
     };
+    /**
+     * The batch aggregate: many attempts planned together and approved once.
+     *
+     * Every transition runs in one transaction over the locked batch row and leaves `status`
+     * recomputed from the items' attempts, so the owner-scoped unfinished index never disagrees
+     * with the attempts it summarizes.
+     */
+    readonly batches: {
+        /**
+         * Insert the batch and one item per attachment, or return the batch this owner already
+         * created under `idempotencyKey`. A replay ignores `attachmentIds` and returns what is
+         * stored, which is what makes a retried create safe.
+         */
+        readonly create: (input: {
+            readonly kind: Plan.Kind;
+            readonly idempotencyKey: string;
+            /** One item per attachment, in order; empty or duplicated fails `InvalidInput`. */
+            readonly attachmentIds: ReadonlyArray<string>;
+        }) => Fx<BatchAggregate>;
+        readonly get: (id: BatchId) => Fx<BatchAggregate>;
+        /**
+         * The batch this owner created under `idempotencyKey`, if any.
+         *
+         * What a caller reads before it validates a create's payload, so a retried request answers
+         * with the batch the first one made whatever the retry now says.
+         */
+        readonly byIdempotencyKey: (key: string) => Fx<Option.Option<BatchAggregate>>;
+        /** Every batch that has not reached `complete` or `rejected`, most recently touched first. */
+        readonly listUnfinished: () => Fx<ReadonlyArray<BatchAggregate>>;
+        /**
+         * Point an item at the attempt that now carries its plan and clear its plan failure.
+         *
+         * Fails `Stale` unless the batch is still `planning` or `planned`. That check is the fence a
+         * planner still in flight hits when the principal declines the batch underneath it, so plan
+         * state never lands on a rejected aggregate.
+         */
+        readonly recordItemPlan: (id: BatchId, attachmentId: string, attemptId: Plan.PlanId) => Fx<BatchAggregate>;
+        /** Record why an item could not be planned; the batch stays `planning`. Same fence. */
+        readonly recordItemPlanFailure: (id: BatchId, attachmentId: string, message: string) => Fx<BatchAggregate>;
+        /**
+         * Bind the batch to `digest` and approve every item's attempt in the same transaction, so a
+         * batch is never approved without the per-attempt approvals `attempts.apply` needs.
+         *
+         * Fails `Stale` unless the batch is `planned` and every item still points at the attempt its
+         * approval names. Approving an approved batch under the same digest returns it unchanged; a
+         * different digest fails `Stale`.
+         */
+        readonly approve: (id: BatchId, input: {
+            readonly digest: Plan.Digest;
+            readonly actorId: string;
+            /** One per item, covering every item in the batch. */
+            readonly approvals: ReadonlyArray<BatchItemApproval>;
+        }) => Fx<BatchAggregate>;
+        /**
+         * Decline the batch and every planned attempt under it, in one transaction. Terminal.
+         *
+         * Rejecting again returns the batch unchanged; a batch that reached `approved` or later
+         * fails `Stale`.
+         */
+        readonly reject: (id: BatchId, input: {
+            readonly actorId: string;
+            readonly reason: string | null;
+        }) => Fx<BatchAggregate>;
+        /** Recompute the stored status from the items' attempts, after applying moved them. */
+        readonly refresh: (id: BatchId) => Fx<BatchAggregate>;
+    };
     readonly readiness: {
         /** One row per (owner, domain); `attachmentId`, when set, must exist for the owner. */
         readonly put: (readiness: Readiness) => Fx<void>;
@@ -334,6 +488,28 @@ export interface AsyncInterface {
         readonly complete: (principal: Principal.Interface, id: Plan.PlanId, receipt: Receipt.Model) => Promise<Attempt>;
         readonly fail: (principal: Principal.Interface, id: Plan.PlanId, message: string) => Promise<Attempt>;
     };
+    readonly batches: {
+        readonly create: (principal: Principal.Interface, input: {
+            readonly kind: Plan.Kind;
+            readonly idempotencyKey: string;
+            readonly attachmentIds: ReadonlyArray<string>;
+        }) => Promise<BatchAggregate>;
+        readonly get: (principal: Principal.Interface, id: BatchId) => Promise<BatchAggregate>;
+        readonly byIdempotencyKey: (principal: Principal.Interface, key: string) => Promise<BatchAggregate | null>;
+        readonly listUnfinished: (principal: Principal.Interface) => Promise<ReadonlyArray<BatchAggregate>>;
+        readonly recordItemPlan: (principal: Principal.Interface, id: BatchId, attachmentId: string, attemptId: Plan.PlanId) => Promise<BatchAggregate>;
+        readonly recordItemPlanFailure: (principal: Principal.Interface, id: BatchId, attachmentId: string, message: string) => Promise<BatchAggregate>;
+        readonly approve: (principal: Principal.Interface, id: BatchId, input: {
+            readonly digest: Plan.Digest;
+            readonly actorId: string;
+            readonly approvals: ReadonlyArray<BatchItemApproval>;
+        }) => Promise<BatchAggregate>;
+        readonly reject: (principal: Principal.Interface, id: BatchId, input: {
+            readonly actorId: string;
+            readonly reason: string | null;
+        }) => Promise<BatchAggregate>;
+        readonly refresh: (principal: Principal.Interface, id: BatchId) => Promise<BatchAggregate>;
+    };
     readonly readiness: {
         readonly put: (principal: Principal.Interface, readiness: Readiness) => Promise<void>;
         readonly get: (principal: Principal.Interface, domain: string) => Promise<Readiness | null>;

package/dist/types/internal/attempts.d.ts

@@ -29,6 +29,7 @@ export declare const make: (storage: Storage.Interface, connect: Connect.Interfa
         readonly sourceReceiptId: Receipt.ReceiptId | null;
     }) => Fx<Plan.Model>;
     approve: (plan: Plan.Model | Plan.PlanId, options?: ApproveOptions) => Fx<Approval.Model>;
+    draftApproval: (attempt: Storage.Attempt, options?: ApproveOptions) => Fx<Approval.Model>;
     reject: (plan: Plan.Model | Plan.PlanId, options?: {
         readonly reason?: string;
     }) => Fx<Storage.Attempt>;

package/dist/types/internal/error.d.ts

@@ -7,7 +7,7 @@ import { Effect, Schema } from "effect";
 import * as Reason from "../Reason.ts";
 export type Category = "request" | "auth" | "plan" | "provider" | "storage" | "internal";
 declare const DomainKitError_base: Schema.Class<DomainKitError, Schema.TaggedStruct<"DomainKitError", {
-    readonly reason: Schema.suspend<Schema.Union<readonly [typeof Reason.InvalidInput, typeof Reason.Unauthenticated, typeof Reason.Forbidden, typeof Reason.NotFound, typeof Reason.Conflict, typeof Reason.Stale, typeof Reason.Expired, typeof Reason.Busy, typeof Reason.ProviderRejected, typeof Reason.ProviderUnavailable, typeof Reason.ProviderConflict, typeof Reason.Unsupported, typeof Reason.Reconnect, typeof Reason.StorageFailed, typeof Reason.CryptoFailed, typeof Reason.ResolverFailed]>>;
+    readonly reason: Schema.suspend<Schema.Union<readonly [typeof Reason.InvalidInput, typeof Reason.Unauthenticated, typeof Reason.Forbidden, typeof Reason.NotFound, typeof Reason.Conflict, typeof Reason.Stale, typeof Reason.BatchStale, typeof Reason.Expired, typeof Reason.Busy, typeof Reason.ProviderRejected, typeof Reason.ProviderUnavailable, typeof Reason.ProviderConflict, typeof Reason.Unsupported, typeof Reason.Reconnect, typeof Reason.StorageFailed, typeof Reason.CryptoFailed, typeof Reason.ResolverFailed]>>;
 }>, import("effect/Cause").YieldableError>;
 export declare class DomainKitError extends DomainKitError_base {
     get category(): Category;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domainkit",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Build reviewable DNS plans for custom domains in TypeScript",
   "keywords": [
     "custom-domains",