@spacefast/common 0.0.26 → 0.2.1

package/dist/contracts/domains.js

@@ -1,12 +1,19 @@
 import { z } from "zod";
 import { AnyObjectSchema, baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema, DnsInstructionSchema, mutationEnvelope, requiredActionsSchema, } from "./common.js";
+import {} from "./enums.js";
 import { PrincipalRefSchema } from "./resources.js";
+/**
+ * Whether a name is the registrable domain itself or a hostname beneath one.
+ * Only the server can answer it — the Public Suffix List is what separates
+ * `example.co.uk` (apex) from `www.example.com` (hostname), and shipping the
+ * list to a browser costs more than the answer is worth.
+ */
+export const domainKindSchema = z.enum(["hostname", "apex"]);
 // ---------------------------------------------------------------------------
-// Domain resource (the platform spec). A canonical name
-// owned by a tenant-local principal, plus its registrar/DNS facets and THE
-// serving pointer/whole-host redirect intent.
+// Domain resource (the platform spec): a canonical name owned by a
+// tenant-local principal, plus its registrar/DNS facets and serving intent.
 // ---------------------------------------------------------------------------
-// Registration (who you pay) facet — present only on apex records.
+// Registration facet: who you pay.
 export const domainRegistrarFacetSchema = z.object({
     mode: z
         .enum(["stattic", "external"])
@@ -31,8 +38,8 @@ export const domainRegistrarFacetSchema = z.object({
         .optional()
         .describe("Whether outbound transfers are locked at the registrar."),
 });
-// DNS hosting (who answers queries) facet — present only on zone-cut-owning
-// records: the apex, or a hostname with verified NS delegation.
+// DNS hosting facet: who answers queries. Zone-cut-owning records are the
+// apex, or a hostname with verified NS delegation.
 export const domainDnsFacetSchema = z.object({
     mode: z
         .enum(["stattic", "external"])
@@ -172,8 +179,8 @@ export const domainRedirectTargetSchema = z
 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`.
+// 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,
@@ -181,7 +188,7 @@ export const domainRedirectSchema = z.object({
 export const DomainSchema = z.object({
     id: z.string().describe("Domain inventory record id (`dom_...`)."),
     tenantId: z.string().describe("Tenant that owns this record (`ten_...`)."),
-    principal: PrincipalRefSchema.describe("Tenant-local principal that owns this domain: a team in the main tenant, an external customer in platform integrations."),
+    principal: PrincipalRefSchema.describe("Tenant-local principal that owns this domain: a team in the main tenant, an external customer in partner integrations."),
     name: z
         .string()
         .describe("Canonical lowercase ASCII A-labels (IDNA2008/punycode), no trailing dot, no wildcard label."),
@@ -189,9 +196,7 @@ export const DomainSchema = z.object({
         .string()
         .optional()
         .describe("Read-only U-label form, present only when it differs from `name`."),
-    kind: z
-        .enum(["hostname", "apex"])
-        .describe("Derived field, never create input: `apex` if and only if `name` equals `derivedGroup`."),
+    kind: domainKindSchema.describe("Derived field, never create input: `apex` if and only if `name` equals `derivedGroup`."),
     wildcardEnabled: z
         .boolean()
         .describe("Whether wildcard hostnames can be derived from this record."),
@@ -257,23 +262,42 @@ export const spaceDomainSchema = z.discriminatedUnion("source", [
     spaceManagedDomainSchema,
     spaceCustomDomainSchema,
 ]);
+// A space's serving addresses are a bounded set the API returns whole; there is
+// no cursor to accept, so there is no `pagination` to advertise.
 export const spaceDomainListResponseSchema = z.object({
     data: z.array(spaceDomainSchema),
-    pagination: CursorPaginationSchema,
 });
-export const teamManagedDomainSchema = spaceManagedDomainSchema.extend({
+export const spaceDomainCreateRequestSchema = z
+    .object({
+    name: z
+        .string()
+        .trim()
+        .min(1)
+        .max(253)
+        .describe("Apex or concrete hostname to add and assign; the server canonicalizes it."),
+    primary: z
+        .boolean()
+        .default(false)
+        .describe("Whether this domain becomes the space's primary hostname."),
+})
+    .strict();
+// One item of `/v1/managed-domains`: a space's managed hostname plus the fields
+// that name its owning space. The `teamId` query only filters which spaces are
+// in scope, so this is not a team-shaped variant.
+export const managedDomainListItemSchema = spaceManagedDomainSchema.extend({
     spaceId: z.string().describe("Space that owns this managed hostname."),
     spaceSlug: z.string().describe("Current project slug for the owning space."),
     spaceTitle: z.string().describe("Current title for the owning space."),
 });
-export const teamManagedDomainListResponseSchema = z.object({
-    data: z.array(teamManagedDomainSchema),
-    pagination: CursorPaginationSchema,
+// Managed hostnames are derived from the caller's accessible spaces and
+// returned whole — `/v1/managed-domains` accepts no cursor, so it declares no
+// pagination.
+export const managedDomainListResponseSchema = z.object({
+    data: z.array(managedDomainListItemSchema),
 });
-// Pre-add advisory check. `canHost` mirrors the hosting provider's
-// hostability verdict: `false` often means the domain is blocklisted or
-// already attached to other provider infrastructure (which a later TXT
-// ownership proof can still claim), so clients warn — they never hard-block.
+// Pre-add advisory check. A `false` verdict usually means the domain is
+// blocklisted or attached to other provider infrastructure, which a later TXT
+// ownership proof can still claim, so clients warn instead of hard-blocking.
 export const domainPreflightQuerySchema = z.object({
     name: z
         .string()
@@ -281,6 +305,11 @@ export const domainPreflightQuerySchema = z.object({
         .min(1)
         .max(253)
         .describe("Apex or concrete hostname to preflight; canonicalized server-side."),
+    teamId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Team the domain would be added to. Defaults the same way `POST /v1/domains` does."),
 });
 export const domainPreflightSchema = z.object({
     name: z.string().describe("Canonical lowercase ASCII form of the requested hostname."),
@@ -288,6 +317,7 @@ export const domainPreflightSchema = z.object({
         .string()
         .optional()
         .describe("Read-only U-label form, present only when it differs from `name`."),
+    kind: domainKindSchema.describe("Whether the name is the registrable domain itself or a hostname under one. Decided server-side against the Public Suffix List, so `example.co.uk` is an apex and `www.example.com` is not."),
     canHost: z
         .boolean()
         .nullable()
@@ -310,19 +340,62 @@ export const domainCreateRequestSchema = z.object({
         .optional()
         .describe("Owning team. Defaults to the active team for sessions and the API key's team."),
 });
+// One PATCH, one intent. The strict branches keep metadata, assignment,
+// unassignment, and whole-host redirect on the domain resource without ever
+// accepting a partial or ambiguous combination.
+//
 // Facet modes are never PATCHable: `dns.mode` changes only via POST /dns and
-// `registrar.mode` only via POST /registration. The PATCHable surface is
-// `wildcardEnabled` (and future metadata) only.
-export const domainPatchSchema = z
+// `registrar.mode` only via POST /registration.
+const domainMetadataPatchSchema = z
     .object({
     wildcardEnabled: z
         .boolean()
-        .optional()
         .describe("Pass `true` to allow wildcard bindings under this domain record. Pass `false` to disallow them."),
 })
-    .refine((value) => Object.keys(value).length > 0, {
-    message: "At least one domain field is required.",
+    .strict();
+const domainAssignPatchSchema = z
+    .object({
+    spaceId: z.string().trim().min(1).describe("Space this hostname should select."),
+    primary: z.boolean().describe("Whether this domain becomes its Space's primary hostname."),
+    redirect: domainRedirectSchema
+        .nullable()
+        .optional()
+        .describe("Whole-host redirect target, or null to clear it."),
+})
+    .strict();
+const domainUnassignPatchSchema = z
+    .object({ spaceId: z.null().describe("Pass null to unassign the domain from its Space.") })
+    .strict();
+const domainRedirectPatchSchema = z
+    .object({
+    redirect: domainRedirectSchema
+        .nullable()
+        .describe("Whole-host redirect target, or null to clear it."),
+})
+    .strict();
+export const domainPatchSchema = z
+    .union([
+    domainMetadataPatchSchema,
+    domainAssignPatchSchema,
+    domainUnassignPatchSchema,
+    domainRedirectPatchSchema,
+])
+    .superRefine((value, context) => {
+    if ("redirect" in value && value.redirect && "primary" in value && value.primary) {
+        context.addIssue({
+            code: "custom",
+            path: ["primary"],
+            message: "A redirecting domain cannot be the Space's primary hostname.",
+        });
+    }
 });
+export function domainPatchIntent(body) {
+    if ("wildcardEnabled" in body)
+        return { kind: "metadata", body };
+    if (!("spaceId" in body))
+        return { kind: "redirect", body };
+    return body.spaceId === null ? { kind: "unassign" } : { kind: "assign", body };
+}
 // ---------------------------------------------------------------------------
 // Registrar facet routes (feature-flagged dev-only per charter D5).
 // ---------------------------------------------------------------------------
@@ -455,17 +528,14 @@ export const domainNameserverUpdateSchema = z.object({
         .max(13)
         .describe("Nameserver hostnames to delegate to (2-13)."),
 });
-// Facet modes change only here, never via PATCH. The response is the
-// post-mutation Domain plus an operation for callers watching the work item.
+// Facet modes change only here, never via PATCH.
 export const domainDnsModeRequestSchema = z.object({
     mode: z
         .enum(["stattic", "external"])
         .describe("Target DNS hosting mode. On `external` to `stattic`, the server snapshots observed records first."),
 });
-// The transition receipt rides inside `data` (envelope law: `{data}` plus
-// `operation` only): the post-mutation Domain plus the transition diagnostics
-// (import visibility limits on external→stattic, exported records to re-create
-// on stattic→external).
+// The transition receipt rides inside `data`; the envelope law allows `{data}`
+// plus `operation` only.
 export const domainDnsModeResponseSchema = mutationEnvelope(z.object({
     domain: DomainSchema.describe("The post-mutation Domain."),
     diagnostics: z
@@ -645,12 +715,8 @@ export const domainDnsProviderWriteStrategySchema = z.enum([
     "batch_transaction",
     "replace_all_record_sets",
 ]);
-// Hybrid DNS mode (both available at launch). `authoritative` = Spacefast hosts
-// the zone and answers queries (registrar_dns / stattic_nameservers backends);
-// `adapter` = Spacefast manages records on the user's existing DNS host through
-// that host's API (connected_provider) or only observes them and emits
-// instructions (unmanaged_external). Additive read-model label derived from
-// `managementKind`; it never changes how records are applied.
+// Additive read-model label derived from `managementKind` (see
+// `deriveDnsHybridMode`). It never changes how records are applied.
 export const domainDnsHybridModeSchema = z
     .enum(["authoritative", "adapter"])
     .describe("Whether Spacefast hosts the authoritative zone (`authoritative`) or manages/observes records on the user's existing DNS host (`adapter`).");
@@ -660,9 +726,7 @@ const DNS_MANAGEMENT_KINDS = [
     "registrar_dns",
     "stattic_nameservers",
 ];
-// Single source of truth mapping management kind -> hybrid mode. Spacefast-hosted
-// zones (registrar_dns, stattic_nameservers) are authoritative; provider and
-// external backends are adapter-mode.
+// Single source of truth mapping management kind to hybrid mode.
 export function deriveDnsHybridMode(managementKind) {
     return managementKind === "registrar_dns" || managementKind === "stattic_nameservers"
         ? "authoritative"
@@ -736,7 +800,13 @@ export const domainProviderConnectionStatusSchema = z.enum([
     "reconnect_required",
     "disabled",
 ]);
-export const domainDnsProviderSchema = z.enum([
+/**
+ * The DNS providers a Domain can name on the wire: the internal column
+ * vocabulary (`domainDnsProviderValues`) minus the two values that never leave
+ * the control plane — `none` (an unset column) and `dsapi` (our registrar's own
+ * DNS, which surfaces as `stattic`).
+ */
+export const DOMAIN_DNS_PROVIDERS = [
     "cloudflare",
     "vercel",
     "wpcom",
@@ -744,7 +814,8 @@ export const domainDnsProviderSchema = z.enum([
     "route53",
     "stattic",
     "manual",
-]);
+];
+export const domainDnsProviderSchema = z.enum(DOMAIN_DNS_PROVIDERS);
 export const domainProviderConnectionSchema = z.object({
     id: z.string().describe("Provider connection id (`dpc_...`)."),
     tenantId: z.string().describe("Tenant that owns this connection."),
@@ -816,19 +887,50 @@ export const domainProviderZoneAttachSchema = z.object({
     providerZoneId: z.string().min(1).max(255),
     providerZoneName: z.string().trim().min(1).max(255).optional(),
 });
-export const domainConnectDiscoverySchema = z.object({
-    supported: z.boolean(),
-    gated: z.boolean().optional(),
-    provider: z
-        .object({
-        urlSyncUX: z.string().url().optional(),
-        urlAPI: z.string().url().optional(),
-        urlControlPanel: z.string().url().optional(),
-        providerName: z.string().optional(),
-    })
-        .optional(),
-    checkedAt: z.string().datetime(),
+const domainConnectProviderSchema = z.object({
+    id: z.string().describe("DNS provider identifier returned by Domain Connect discovery."),
+    name: z.string().describe("DNS provider name returned by Domain Connect discovery."),
+    displayName: z.string().optional(),
+    controlPanelUrl: z.string().url().optional(),
 });
+const domainConnectUnavailableReasonSchema = z.enum([
+    "domain_not_bound",
+    "configuration_unsupported",
+    "discovery_not_advertised",
+    "discovery_ambiguous",
+    "settings_not_found",
+    "settings_invalid",
+    "sync_flow_unsupported",
+    "template_unsupported",
+    "provider_unavailable",
+    "signing_unavailable",
+]);
+export const domainConnectDiscoverySchema = z.discriminatedUnion("status", [
+    z.object({
+        status: z.literal("available"),
+        checkedAt: z.string().datetime(),
+        provider: domainConnectProviderSchema,
+        template: z.object({
+            providerId: z.string(),
+            serviceId: z.string(),
+            version: z.number().int().nullable(),
+        }),
+        applyUrl: z.string().url().describe("Signed DNS-provider approval URL."),
+    }),
+    z.object({
+        status: z.literal("unsupported"),
+        reason: domainConnectUnavailableReasonSchema,
+        checkedAt: z.string().datetime(),
+        provider: domainConnectProviderSchema.optional(),
+        gated: z.boolean().optional(),
+    }),
+    z.object({
+        status: z.literal("unavailable"),
+        reason: domainConnectUnavailableReasonSchema,
+        checkedAt: z.string().datetime(),
+        provider: domainConnectProviderSchema.optional(),
+    }),
+]);
 export const domainConnectDiscoveryResponseSchema = z.object({
     data: domainConnectDiscoverySchema,
 });
@@ -1127,8 +1229,7 @@ export const domainDnsRecordPatchSchema = domainDnsRecordPatchableFields
     message: "At least one DNS record field is required.",
 })
     .superRefine(requireMxSrvPriority);
-// Executed in exactly this order — deletes, patches, puts, posts — as one
-// atomic transaction; any failure rejects the whole batch with an RFC 6901
+// One atomic transaction. Any failure rejects the whole batch with an RFC 6901
 // JSON Pointer to the failing entry in the problem document's `pointer`.
 export const domainDnsRecordBatchSchema = z
     .object({
@@ -1226,3 +1327,13 @@ export const domainDiagnosticsResponseSchema = z.object({
         .array(domainHostnameDiagnosticsSchema)
         .describe("Per-hostname DNS and SSL connectivity diagnostics."),
 });
+export const domainSslRetrySchema = z.object({
+    requestedAt: z.string().datetime(),
+    retries: z.array(z.object({
+        hostname: z.string(),
+        queued: z.boolean(),
+        error: z.enum(["not_hosted_here"]).nullable(),
+    })),
+    hostnameDiagnostics: z.array(domainHostnameDiagnosticsSchema),
+});
+export const domainSslRetryResponseSchema = mutationEnvelope(domainSslRetrySchema);

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

@@ -2,9 +2,9 @@ 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.
+ * Recipient controls are independent from the mail category: a transactional
+ * notification can belong to a controllable topic, and essential auth mail has
+ * no topic at all.
  */
 export declare const emailPreferenceTopicValues: readonly ["system", "invites", "announcements", "offers"];
 export type EmailPreferenceTopic = (typeof emailPreferenceTopicValues)[number];

package/dist/contracts/email-preferences.js

@@ -1,8 +1,7 @@
 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).
+// The canonical category set; superadmin-emails.ts re-exports it. This file
+// must not import from other contracts: importing back from superadmin-emails
+// created a circular-init TDZ crash in dist.
 export const emailCategoryValues = [
     "transactional",
     "announcements",
@@ -11,9 +10,9 @@ export const emailCategoryValues = [
     "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.
+ * Recipient controls are independent from the mail category: a transactional
+ * notification can belong to a controllable topic, and essential auth mail has
+ * no topic at all.
  */
 export const emailPreferenceTopicValues = ["system", "invites", "announcements", "offers"];
 export const emailPreferenceTopicPolicy = {

package/dist/contracts/enums.d.ts

@@ -2,10 +2,10 @@ import { z } from "zod";
 export declare const spaceStatusValues: readonly ["provisioning", "active", "updating", "deleting", "failed"];
 export declare const spaceStatus: z.ZodEnum<{
     active: "active";
+    failed: "failed";
     provisioning: "provisioning";
     updating: "updating";
     deleting: "deleting";
-    failed: "failed";
 }>;
 export declare const spaceDisabledReasonCodeValues: readonly ["anonymous_expired", "abuse_takedown", "tenant_suspended", "site_suspended", "author_removed"];
 export declare const spaceDisabledReasonCode: z.ZodEnum<{
@@ -22,13 +22,17 @@ export declare const spaceTransferStatus: z.ZodEnum<{
     canceled: "canceled";
     expired: "expired";
 }>;
-export declare const tenantKindValues: readonly ["main", "platform", "partner", "internal"];
+export declare const tenantKindValues: readonly ["main", "partner", "internal"];
 export declare const tenantKind: z.ZodEnum<{
     internal: "internal";
     main: "main";
-    platform: "platform";
     partner: "partner";
 }>;
+export declare const tenantModeValues: readonly ["live", "test"];
+export declare const tenantMode: z.ZodEnum<{
+    live: "live";
+    test: "test";
+}>;
 export declare const tenantStatusValues: readonly ["active", "past_due", "suspended", "deleted"];
 export declare const tenantStatus: z.ZodEnum<{
     active: "active";
@@ -41,30 +45,13 @@ export declare const providerClientStatus: z.ZodEnum<{
     active: "active";
     disabled: "disabled";
 }>;
-export declare const siteKindValues: readonly ["static_runtime"];
-export declare const siteKind: z.ZodEnum<{
-    static_runtime: "static_runtime";
-}>;
-export declare const siteIsolationValues: readonly ["site", "space"];
-export declare const siteIsolation: z.ZodEnum<{
-    site: "site";
-    space: "space";
-}>;
-export declare const siteStatusValues: readonly ["ready_pool", "active", "provisioning", "degraded", "suspended", "deleted"];
-export declare const siteStatus: z.ZodEnum<{
-    active: "active";
-    provisioning: "provisioning";
-    suspended: "suspended";
-    deleted: "deleted";
-    ready_pool: "ready_pool";
-    degraded: "degraded";
-}>;
-export declare const poolSiteStatusValues: readonly ["provisioning", "ready_pool", "degraded", "retired"];
+export declare const poolSiteStatusValues: readonly ["provisioning", "ready_pool", "degraded", "retired", "cleanup_pending"];
 export declare const poolSiteStatus: z.ZodEnum<{
     provisioning: "provisioning";
     ready_pool: "ready_pool";
     degraded: "degraded";
     retired: "retired";
+    cleanup_pending: "cleanup_pending";
 }>;
 export declare const publishSourceKindValues: readonly ["direct_upload", "cli", "dashboard", "api", "git", "import", "agent", "build", "variable_update", "config_update"];
 export declare const publishSourceKind: z.ZodEnum<{
@@ -72,9 +59,9 @@ export declare const publishSourceKind: z.ZodEnum<{
     agent: "agent";
     api: "api";
     dashboard: "dashboard";
-    direct_upload: "direct_upload";
     cli: "cli";
     git: "git";
+    direct_upload: "direct_upload";
     import: "import";
     variable_update: "variable_update";
     config_update: "config_update";
@@ -112,10 +99,23 @@ export declare const buildStatus: z.ZodEnum<{
     skipped: "skipped";
 }>;
 export type BuildStatus = z.infer<typeof buildStatus>;
+/**
+ * The one authoritative "this build can still change on its own" set. Poll
+ * cadences, cancelability, activity checks and webhook re-enqueue gates all
+ * derive from it — never restate it.
+ */
+export declare const BUILD_IN_FLIGHT_STATUSES: readonly ["waiting_for_source", "uploading_source", "queued", "running"];
+/**
+ * Its complement: a build that has settled and will never move again.
+ * `skipped` is terminal — a build the runner decided not to run at all.
+ */
+export declare const BUILD_TERMINAL_STATUSES: ("failed" | "canceled" | "succeeded" | "skipped")[];
+export declare function buildIsInFlight(status: string): boolean;
+export declare function buildIsTerminal(status: string): boolean;
 export declare const diagnosticSeverity: z.ZodEnum<{
     info: "info";
-    error: "error";
     warning: "warning";
+    error: "error";
 }>;
 export declare const diagnosticProvider: z.ZodEnum<{
     registrar: "registrar";
@@ -127,6 +127,7 @@ export declare const domainOwnershipTypeValues: readonly ["external", "registere
 export declare const domainDnsModeValues: readonly ["external", "stattic_nameservers", "registrar_dns"];
 export declare const domainRegistrarProviderValues: readonly ["none", "dsapi", "manual"];
 export declare const domainDnsProviderValues: readonly ["none", "stattic", "route53", "cloudflare", "vercel", "wpcom", "pressable", "dsapi", "manual"];
+export type DomainDnsProviderValue = (typeof domainDnsProviderValues)[number];
 export declare const domainLifecycleStatusValues: readonly ["active", "pending_registration", "pending_transfer", "expired", "suspended", "redemption", "failed"];
 export declare const safetyCategoryValues: readonly ["csam", "malware", "phishing", "spam", "copyright", "fraud", "hateful_content", "extremism", "illegal_content", "privacy_violation", "compromised_account", "other_violation"];
 export declare const safetyCategory: z.ZodEnum<{
@@ -180,9 +181,8 @@ export declare const operationStatus: z.ZodEnum<{
 export type GitProvider = z.infer<typeof gitProvider>;
 export type PublishSourceKind = z.infer<typeof publishSourceKind>;
 export type PoolSiteStatus = z.infer<typeof poolSiteStatus>;
-export type SiteKind = z.infer<typeof siteKind>;
-export type SiteIsolation = z.infer<typeof siteIsolation>;
 export type TenantStatus = z.infer<typeof tenantStatus>;
+export type TenantMode = z.infer<typeof tenantMode>;
 export type OperationStatus = z.infer<typeof operationStatus>;
 export type SafetyCategory = z.infer<typeof safetyCategory>;
 export type SafetyResolutionReason = z.infer<typeof safetyResolutionReason>;