@spacefast/common 0.0.11 → 0.0.13

package/dist/contracts/domains.js

@@ -2,10 +2,9 @@ import { z } from "zod";
 import { AnyObjectSchema, baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema, DnsInstructionSchema, mutationEnvelope, requiredActionsSchema, } from "./common.js";
 import { PrincipalRefSchema } from "./resources.js";
 // ---------------------------------------------------------------------------
-// Domain resource (internal-docs/platform.md L2387-2431). Pure inventory: a
-// canonical name owned by a tenant-local principal, plus the registrar/dns
-// facets where they apply and the verification read-model. Routing intent
-// lives on DomainBinding, provider assignment on SiteDomainAssignment.
+// Domain resource (internal-docs/platform.md L2387-2431). A canonical name
+// owned by a tenant-local principal, plus its registrar/DNS facets and THE
+// serving pointer/whole-host redirect intent.
 // ---------------------------------------------------------------------------
 // Registration (who you pay) facet — present only on apex records.
 export const domainRegistrarFacetSchema = z.object({
@@ -159,6 +158,26 @@ export const domainHintSchema = z.object({
     providerRequestId: z.string().optional(),
     expiresAt: z.string().datetime().optional(),
 });
+export const domainRedirectTargetSchema = z
+    .union([
+    z.object({
+        url: z.string().url().describe("Absolute URL to redirect to."),
+    }),
+    z.object({
+        spaceId: z.string().min(1).describe("Space to redirect to (`spc_...`)."),
+        path: z.string().max(255).optional().describe("Path on the target space."),
+    }),
+])
+    .describe("Redirect destination: an absolute URL, or a space (optionally with a path).");
+export const domainRedirectStatusSchema = z
+    .union([z.literal(301), z.literal(302), z.literal(307), z.literal(308)])
+    .describe("HTTP redirect status; defaults to 308.");
+// A domain either serves its Space or redirects away from it — whole-host
+// only. Path-level routing belongs in the serving Space's `_redirects`.
+export const domainRedirectSchema = z.object({
+    to: domainRedirectTargetSchema,
+    status: domainRedirectStatusSchema,
+});
 export const DomainSchema = z.object({
     id: z.string().describe("Domain inventory record id (`dom_...`)."),
     tenantId: z.string().describe("Tenant that owns this record (`ten_...`)."),
@@ -175,7 +194,17 @@ export const DomainSchema = z.object({
         .describe("Derived, never create input: `apex` iff `name` equals `derivedGroup`."),
     wildcardEnabled: z
         .boolean()
-        .describe("Whether wildcard bindings may be created under this record."),
+        .describe("Whether wildcard hostnames may be derived from this record."),
+    spaceId: z
+        .string()
+        .nullable()
+        .describe("Space this hostname selects (`spc_...`), or null when the record is inventory only. One Space per hostname; a Space may hold many domains."),
+    primary: z
+        .boolean()
+        .describe("Whether this domain is its Space's primary hostname (feeds `liveUrl`)."),
+    redirect: domainRedirectSchema
+        .optional()
+        .describe("Whole-host redirect target; present only on redirecting domains."),
     derivedGroup: z
         .string()
         .describe("PSL registrable domain of `name`; server-computed, never client-supplied."),
@@ -205,7 +234,7 @@ export const spaceCustomDomainSchema = DomainSchema.extend({
     managed: z.literal(false),
     deletable: z.literal(true),
     assignable: z.literal(true),
-    primary: z.boolean().describe("Whether this custom domain binding is the space's primary URL."),
+    primary: z.boolean().describe("Whether this custom domain is the space's primary URL."),
 });
 export const spaceManagedDomainSchema = z.object({
     id: z.string().describe("Stable managed row id derived from the default hostname row."),
@@ -268,299 +297,6 @@ export const domainPatchSchema = z
     message: "At least one domain field is required.",
 });
 // ---------------------------------------------------------------------------
-// DomainBinding (internal-docs/platform.md L2466-2498): a discriminated union
-// on `mode` — serve a space, redirect, or proxy an upstream.
-// ---------------------------------------------------------------------------
-// DomainBindingDiagnostic (L2508-2510): the shared Diagnostic shape plus a
-// binding-specific suggested `action`.
-export const domainBindingDiagnosticSchema = baseDiagnosticSchema.extend({
-    action: z
-        .enum(["add_dns", "wait", "verify", "confirm_move", "remove_conflict", "contact_support"])
-        .optional()
-        .describe("Suggested next step to resolve this binding diagnostic."),
-});
-export const domainBindingConflictSchema = z.object({
-    id: z.string().describe("Stable conflict id, passed back in activation `confirm`."),
-    scope: z
-        .enum(["same_space", "same_principal", "same_tenant", "external"])
-        .describe("Who holds the overlapping claim, relative to the caller."),
-    hostname: z.string().describe("Hostname both claims target."),
-    pathPrefix: z.string().optional().describe("Conflicting path scope, when path-based."),
-    existingBindingId: z.string().optional().describe("The incumbent binding, when visible."),
-    resolution: z
-        .enum([
-        "activate_moves_existing",
-        "choose_different_path",
-        "verify_to_takeover",
-        "cannot_resolve",
-    ])
-        .optional()
-        .describe("How this conflict can be resolved."),
-});
-export const domainBindingStatusSchema = z
-    .enum(["draft", "pending", "blocked", "activating", "active", "failed", "deleted"])
-    .describe("Binding lifecycle status; the binding is the pollable resource for activation.");
-const domainBindingBaseFields = {
-    id: z.string().describe("Domain binding id (`dbn_...`)."),
-    tenantId: z.string().describe("Tenant the binding belongs to (`ten_...`)."),
-    domainId: z.string().describe("Domain inventory record this binding routes (`dom_...`)."),
-    siteDomainAssignmentId: z
-        .string()
-        .nullable()
-        .describe("Provider assignment serving this hostname, once linked (`sda_...`)."),
-    hostname: z.string().describe("Hostname this binding claims (copied from the domain)."),
-    pathPrefix: z
-        .string()
-        .nullable()
-        .describe("Path scope like `/docs`; null claims the whole host. More specific paths win."),
-    wildcard: z
-        .boolean()
-        .describe("Whether this binding captures subdomains (requires domain wildcardEnabled)."),
-    status: domainBindingStatusSchema,
-    diagnostics: z
-        .array(domainBindingDiagnosticSchema)
-        .describe("Structured diagnostics with stable codes and suggested actions."),
-    requiredActions: requiredActionsSchema,
-    conflicts: z
-        .array(domainBindingConflictSchema)
-        .describe("Unresolved overlapping claims; conflicts block instead of dead-ending."),
-    providerState: AnyObjectSchema.describe("Raw provider-side state, for diagnostics only."),
-    createdAt: z.string().datetime().describe("When the binding was created."),
-    updatedAt: z.string().datetime().describe("When the binding last changed."),
-};
-export const domainBindingRedirectTargetSchema = z
-    .union([
-    z.object({
-        url: z.string().url().describe("Absolute URL to redirect to."),
-    }),
-    z.object({
-        spaceId: z.string().min(1).describe("Space to redirect to (`spc_...`)."),
-        path: z.string().max(255).optional().describe("Path on the target space."),
-    }),
-])
-    .describe("Redirect destination: an absolute URL, or a space (optionally with a path).");
-export const domainBindingRedirectStatusSchema = z
-    .union([z.literal(301), z.literal(302), z.literal(307), z.literal(308)])
-    .describe("HTTP redirect status; defaults to 308.");
-export const domainBindingSchema = z.discriminatedUnion("mode", [
-    z.object({
-        ...domainBindingBaseFields,
-        mode: z.literal("serve").describe("Serve a space's content on this hostname/path."),
-        spaceId: z.string().describe("Space served by this binding (`spc_...`)."),
-        channel: z.string().describe('Channel served on this hostname; defaults to "live".'),
-        primary: z
-            .boolean()
-            .describe("One primary hostname per space; the primary binding feeds `liveUrl`."),
-    }),
-    z.object({
-        ...domainBindingBaseFields,
-        mode: z.literal("redirect").describe("Redirect requests to a URL or another space."),
-        to: domainBindingRedirectTargetSchema,
-        redirectStatus: domainBindingRedirectStatusSchema,
-    }),
-    z.object({
-        ...domainBindingBaseFields,
-        mode: z.literal("proxy").describe("Proxy requests to an external upstream."),
-        upstream: z.object({
-            url: z.string().url().describe("Absolute upstream URL requests are proxied to."),
-        }),
-    }),
-]);
-function requireBindingModeFields(value, ctx) {
-    if (value.mode === "redirect" && value.to === undefined) {
-        ctx.addIssue({ code: "custom", path: ["to"], message: "Redirect bindings require `to`." });
-    }
-    if (value.mode === "proxy" && value.upstream === undefined) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["upstream"],
-            message: "Proxy bindings require `upstream`.",
-        });
-    }
-    if (value.mode !== "redirect" && (value.to !== undefined || value.redirectStatus !== undefined)) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["to"],
-            message: "`to`/`redirectStatus` apply only to redirect bindings.",
-        });
-    }
-    if (value.mode !== "proxy" && value.upstream !== undefined) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["upstream"],
-            message: "`upstream` applies only to proxy bindings.",
-        });
-    }
-    if (value.mode === "serve" || value.mode === undefined) {
-        return;
-    }
-    if (value.channel !== undefined || value.primary !== undefined) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["channel"],
-            message: "`channel`/`primary` apply only to serve bindings.",
-        });
-    }
-}
-// One POST end to end (charter D5): pass `hostname` and the Domain inventory
-// record is auto-created for the space's principal — no separate create-domain
-// step. Pass `domainId` to bind an existing inventory record instead.
-export const domainBindingCreateSchema = z
-    .object({
-    domainId: z
-        .string()
-        .min(1)
-        .optional()
-        .describe("Existing domain inventory record to bind (`dom_...`)."),
-    hostname: z
-        .string()
-        .trim()
-        .min(1)
-        .max(253)
-        .optional()
-        .describe("Hostname to bind. Auto-creates the Domain inventory record for the space's team when none exists."),
-    spaceId: z
-        .string()
-        .min(1)
-        .describe("Space this hostname is anchored to: the serve target, or for redirect/proxy bindings the space whose site serves the hostname."),
-    mode: z
-        .enum(["serve", "redirect", "proxy"])
-        .default("serve")
-        .describe("Routing intent: serve a space, redirect, or proxy an upstream."),
-    pathPrefix: z
-        .string()
-        .trim()
-        .max(255)
-        .nullable()
-        .optional()
-        .describe("Path scope like `/docs`; omit to claim the whole host."),
-    wildcard: z
-        .boolean()
-        .optional()
-        .describe("Capture subdomains too (requires domain wildcardEnabled)."),
-    channel: z
-        .string()
-        .trim()
-        .min(1)
-        .max(64)
-        .optional()
-        .describe('Channel to serve (serve mode); defaults to "live".'),
-    primary: z
-        .boolean()
-        .optional()
-        .describe("Make this the space's primary hostname (serve mode)."),
-    to: domainBindingRedirectTargetSchema.optional(),
-    redirectStatus: domainBindingRedirectStatusSchema.optional(),
-    upstream: z
-        .object({ url: z.string().url().describe("Absolute upstream URL.") })
-        .optional()
-        .describe("Proxy upstream (proxy mode)."),
-})
-    .superRefine((value, ctx) => {
-    if (!value.domainId && !value.hostname) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["hostname"],
-            message: "Pass `hostname` (auto-creates the domain) or `domainId`.",
-        });
-    }
-    if (value.domainId && value.hostname) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["domainId"],
-            message: "Pass either `domainId` or `hostname`, not both.",
-        });
-    }
-    requireBindingModeFields(value, ctx);
-});
-export const domainBindingPatchSchema = z
-    .object({
-    mode: z
-        .enum(["serve", "redirect", "proxy"])
-        .optional()
-        .describe("Switch the routing intent; the new mode's fields are required alongside."),
-    pathPrefix: z.string().trim().max(255).nullable().optional().describe("New path scope."),
-    wildcard: z.boolean().optional().describe("Toggle subdomain capture."),
-    channel: z.string().trim().min(1).max(64).optional().describe("Channel to serve (serve mode)."),
-    primary: z
-        .boolean()
-        .optional()
-        .describe("Promote to the space's primary hostname (serve mode)."),
-    to: domainBindingRedirectTargetSchema.optional(),
-    redirectStatus: domainBindingRedirectStatusSchema.optional(),
-    upstream: z
-        .object({ url: z.string().url().describe("Absolute upstream URL.") })
-        .optional()
-        .describe("Proxy upstream (proxy mode)."),
-})
-    .superRefine((value, ctx) => {
-    if (Object.keys(value).length === 0) {
-        ctx.addIssue({ code: "custom", message: "At least one binding field is required." });
-    }
-    if (value.mode !== undefined) {
-        requireBindingModeFields(value, ctx);
-    }
-});
-// Binding activation is asynchronous; the binding is the pollable status
-// resource. `confirm` carries conflict ids whose `confirm_move` resolution the
-// caller accepts — activation performs the move (no public move API).
-export const domainBindingActivateSchema = z.object({
-    confirm: z
-        .array(z.string())
-        .default([])
-        .describe("Conflict ids whose `activate_moves_existing` resolution the caller confirms."),
-});
-// Activation is asynchronous: the binding is the pollable status resource and
-// `operation` tracks the work item (standard mutation envelope).
-export const domainBindingActivateResponseSchema = mutationEnvelope(domainBindingSchema);
-export const domainBindingListResponseSchema = z.object({
-    data: z.array(domainBindingSchema),
-    pagination: CursorPaginationSchema,
-});
-export const domainBindingListQuerySchema = cursorListQuerySchema;
-// ---------------------------------------------------------------------------
-// SiteDomainAssignment (internal-docs/platform.md L2445-2464): provider
-// assignment of a hostname to a unified site. Mostly provider state managed by
-// bindings; POST/DELETE exist as the canonical explicit mutation surface.
-// ---------------------------------------------------------------------------
-export const siteDomainAssignmentSchema = z.object({
-    id: z.string().describe("Site domain assignment id (`sda_...`)."),
-    tenantId: z.string().describe("Tenant the assignment belongs to (`ten_...`)."),
-    domainId: z.string().describe("Domain inventory record this hostname belongs to (`dom_...`)."),
-    siteId: z.string().nullable().describe("Unified site (`site_...`) the hostname is assigned to."),
-    hostname: z.string().describe("Hostname assigned at the provider."),
-    status: z
-        .enum([
-        "unassigned",
-        "pending_provider",
-        "pending_dns",
-        "pending_ssl",
-        "active",
-        "blocked",
-        "failed",
-    ])
-        .describe("Provider assignment status; the assignment is pollable during activation."),
-    dnsInstructions: z
-        .array(DnsInstructionSchema)
-        .describe("DNS records required for this hostname to route and verify."),
-    providerState: AnyObjectSchema.describe("Raw provider-side state, for diagnostics only."),
-    diagnostics: z
-        .array(baseDiagnosticSchema)
-        .describe("Structured assignment diagnostics with stable codes."),
-    createdAt: z.string().datetime().describe("When the assignment was created."),
-    updatedAt: z.string().datetime().describe("When the assignment last changed."),
-});
-export const siteDomainAssignmentCreateSchema = z.object({
-    spaceId: z
-        .string()
-        .min(1)
-        .describe("Space whose site this domain's hostname is assigned to (`spc_...`)."),
-});
-export const siteDomainAssignmentListResponseSchema = z.object({
-    data: z.array(siteDomainAssignmentSchema),
-    pagination: CursorPaginationSchema,
-});
-// ---------------------------------------------------------------------------
 // Registrar facet routes (feature-flagged dev-only per charter D5).
 // ---------------------------------------------------------------------------
 export const domainRegistrationSchema = z.object({
@@ -1414,13 +1150,15 @@ export const domainHostnameDiagnosticsSchema = z.object({
         .describe("Provider IPs the hostname should point at."),
     verificationCode: z.string().nullable().describe("Expected TXT verification value."),
     dnsInstructions: z
-        .array(AnyObjectSchema)
+        .array(DnsInstructionSchema)
         .default([])
         .describe("DNS records required for this hostname."),
     dns: z.object({
         observedAt: z.string().datetime(),
         expectedTxtValue: z.string().nullable(),
-        pointsToProvider: z.boolean().describe("Whether observed A records point at the provider."),
+        pointsToProvider: z
+            .boolean()
+            .describe("Whether every provider-supported address family points at the provider."),
         proxyDetected: z.boolean().nullable().describe("Whether observed A records look proxied."),
         txtVerified: z.boolean().nullable().describe("Whether the verification TXT is observed."),
         hasAaaaRecords: z.boolean(),

package/dist/contracts/email-preferences.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+export declare const emailCategoryValues: readonly ["transactional", "announcements", "offers", "system", "invites"];
+export type EmailCategory = (typeof emailCategoryValues)[number];
+/**
+ * Recipient controls are deliberately independent from the mail category.
+ * A transactional notification can still belong to a controllable topic,
+ * while essential authentication mail has no topic at all.
+ */
+export declare const emailPreferenceTopicValues: readonly ["system", "invites", "announcements", "offers"];
+export type EmailPreferenceTopic = (typeof emailPreferenceTopicValues)[number];
+export declare const emailPreferenceTopicPolicy: {
+    readonly system: {
+        readonly subscribedByDefault: true;
+        readonly reportAbuse: false;
+    };
+    readonly invites: {
+        readonly subscribedByDefault: true;
+        readonly reportAbuse: true;
+    };
+    readonly announcements: {
+        readonly subscribedByDefault: true;
+        readonly reportAbuse: false;
+    };
+    readonly offers: {
+        readonly subscribedByDefault: false;
+        readonly reportAbuse: false;
+    };
+};
+export declare const emailPreferenceSourceValues: readonly ["one_click", "landing", "dashboard", "ses_subscription", "admin"];
+export declare const emailPreferencesSchema: z.ZodObject<{
+    system: z.ZodBoolean;
+    invites: z.ZodBoolean;
+    announcements: z.ZodBoolean;
+    offers: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const emailPreferencesUpdateSchema: z.ZodObject<{
+    system: z.ZodOptional<z.ZodBoolean>;
+    invites: z.ZodOptional<z.ZodBoolean>;
+    announcements: z.ZodOptional<z.ZodBoolean>;
+    offers: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type EmailPreferences = z.infer<typeof emailPreferencesSchema>;
+export type EmailPreferencesUpdate = z.infer<typeof emailPreferencesUpdateSchema>;
+export declare const emailSuppressionReasonValues: readonly ["complaint", "hard_bounce", "manual"];
+export type EmailSuppressionReason = (typeof emailSuppressionReasonValues)[number];
+export declare const emailSuppressionStrength: {
+    readonly complaint: 1;
+    readonly hard_bounce: 2;
+    readonly manual: 3;
+};

package/dist/contracts/email-preferences.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+// The canonical category set. superadmin-emails.ts re-exports this as
+// superadminEmailCategoryValues — email-preferences must stay import-free
+// within contracts (it is the foundational email contract; importing back
+// from superadmin-emails created a circular-init TDZ crash in dist).
+export const emailCategoryValues = [
+    "transactional",
+    "announcements",
+    "offers",
+    "system",
+    "invites",
+];
+/**
+ * Recipient controls are deliberately independent from the mail category.
+ * A transactional notification can still belong to a controllable topic,
+ * while essential authentication mail has no topic at all.
+ */
+export const emailPreferenceTopicValues = ["system", "invites", "announcements", "offers"];
+export const emailPreferenceTopicPolicy = {
+    system: { subscribedByDefault: true, reportAbuse: false },
+    invites: { subscribedByDefault: true, reportAbuse: true },
+    announcements: { subscribedByDefault: true, reportAbuse: false },
+    offers: { subscribedByDefault: false, reportAbuse: false },
+};
+export const emailPreferenceSourceValues = [
+    "one_click",
+    "landing",
+    "dashboard",
+    "ses_subscription",
+    "admin",
+];
+export const emailPreferencesSchema = z.object({
+    system: z.boolean(),
+    invites: z.boolean(),
+    announcements: z.boolean(),
+    offers: z.boolean(),
+});
+export const emailPreferencesUpdateSchema = emailPreferencesSchema.partial();
+export const emailSuppressionReasonValues = ["complaint", "hard_bounce", "manual"];
+export const emailSuppressionStrength = {
+    complaint: 1,
+    hard_bounce: 2,
+    manual: 3,
+};

package/dist/contracts/enums.d.ts

@@ -8,17 +8,15 @@ export declare const spaceStatus: z.ZodEnum<{
     deleting: "deleting";
     failed: "failed";
 }>;
-export declare const spaceDisabledReasonCodeValues: readonly ["anonymous_expired", "abuse_takedown", "tenant_suspended", "site_suspended", "visit_cap_exceeded"];
+export declare const spaceDisabledReasonCodeValues: readonly ["anonymous_expired", "abuse_takedown", "tenant_suspended", "site_suspended"];
 export declare const spaceDisabledReasonCode: z.ZodEnum<{
     anonymous_expired: "anonymous_expired";
     abuse_takedown: "abuse_takedown";
     tenant_suspended: "tenant_suspended";
     site_suspended: "site_suspended";
-    visit_cap_exceeded: "visit_cap_exceeded";
 }>;
-export declare const spaceTransferStatusValues: readonly ["pending_confirmation", "confirming_domains", "moving", "completed", "canceled", "expired"];
+export declare const spaceTransferStatusValues: readonly ["pending_confirmation", "confirming_domains", "completed", "canceled", "expired"];
 export declare const spaceTransferStatus: z.ZodEnum<{
-    moving: "moving";
     pending_confirmation: "pending_confirmation";
     confirming_domains: "confirming_domains";
     completed: "completed";
@@ -125,8 +123,8 @@ export declare const buildStatus: z.ZodEnum<{
 }>;
 export declare const diagnosticSeverity: z.ZodEnum<{
     info: "info";
-    warning: "warning";
     error: "error";
+    warning: "warning";
 }>;
 export declare const diagnosticProvider: z.ZodEnum<{
     registrar: "registrar";

package/dist/contracts/enums.js

@@ -11,18 +11,14 @@ export const spaceStatusValues = [
     "failed",
 ];
 export const spaceStatus = z.enum(spaceStatusValues);
-// Serving-axis disable reasons (internal-docs/platform.md "Space"): exactly
-// these five. Confirmed scan takedowns use `abuse_takedown`; infected state and
-// claim invalidation are explicit enforcement effects, not reason metadata.
-// `visit_cap_exceeded` is the anonymous visit-quota pause
-// (ANONYMOUS_PUBLISH_CAPS.maxLifetimeViews): recoverable, the claim token stays
-// intact, and claiming the space restores serving.
+// Serving-axis disable reasons (internal-docs/platform.md "Space"). Confirmed
+// scan takedowns use `abuse_takedown`; infected state and claim invalidation
+// are explicit enforcement effects, not reason metadata.
 export const spaceDisabledReasonCodeValues = [
     "anonymous_expired",
     "abuse_takedown",
     "tenant_suspended",
     "site_suspended",
-    "visit_cap_exceeded",
 ];
 export const spaceDisabledReasonCode = z.enum(spaceDisabledReasonCodeValues);
 // SpaceTransfer status machine (internal-docs/platform.md "Transfer
@@ -34,7 +30,6 @@ export const spaceDisabledReasonCode = z.enum(spaceDisabledReasonCodeValues);
 export const spaceTransferStatusValues = [
     "pending_confirmation",
     "confirming_domains",
-    "moving",
     "completed",
     "canceled",
     "expired",