@builder.io/ai-utils 0.84.0 → 0.85.0-dev.202607231533.14c8ab346

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.84.0",
+  "version": "0.85.0-dev.202607231533.14c8ab346",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/acl-schema.d.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+export declare const PermissionSchema: z.ZodEnum<{
+    list: "list";
+    read: "read";
+    write: "write";
+}>;
+export type Permission = z.infer<typeof PermissionSchema>;
+export declare const AclEntrySchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>;
+    resource: z.ZodString;
+    permissions: z.ZodArray<z.ZodEnum<{
+        list: "list";
+        read: "read";
+        write: "write";
+    }>>;
+    description: z.ZodOptional<z.ZodString>;
+    principals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type AclEntry = z.infer<typeof AclEntrySchema>;
+export declare const AclPolicySchema: z.ZodObject<{
+    secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    entries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        action: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+        }>;
+        resource: z.ZodString;
+        permissions: z.ZodArray<z.ZodEnum<{
+            list: "list";
+            read: "read";
+            write: "write";
+        }>>;
+        description: z.ZodOptional<z.ZodString>;
+        principals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    denyDescription: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AclPolicy = z.infer<typeof AclPolicySchema>;
+export declare const AclDenialSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "command-allowlist": "command-allowlist";
+        "command-security": "command-security";
+        "file-access": "file-access";
+    }>;
+    reason: z.ZodEnum<{
+        "deny-pattern-matched": "deny-pattern-matched";
+        "no-allow-match": "no-allow-match";
+        "security-policy": "security-policy";
+        "shell-metacharacter": "shell-metacharacter";
+    }>;
+    resource: z.ZodString;
+    command: z.ZodOptional<z.ZodString>;
+    permission: z.ZodOptional<z.ZodEnum<{
+        list: "list";
+        read: "read";
+        write: "write";
+    }>>;
+    policy: z.ZodOptional<z.ZodString>;
+    matchedPattern: z.ZodOptional<z.ZodString>;
+    matchedEntry: z.ZodOptional<z.ZodObject<{
+        action: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+        }>;
+        resource: z.ZodString;
+        permissions: z.ZodArray<z.ZodEnum<{
+            list: "list";
+            read: "read";
+            write: "write";
+        }>>;
+        description: z.ZodOptional<z.ZodString>;
+        principals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type AclDenial = z.infer<typeof AclDenialSchema>;
+export interface AccessResult {
+    allowed: boolean;
+    message: string;
+    matchedEntry?: AclEntry;
+    matchedPattern?: string;
+    reason?: "deny-pattern-matched" | "no-allow-match";
+    requestedResource?: string;
+    requestedPermission?: Permission;
+}

package/src/acl-schema.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+export const PermissionSchema = z
+    .enum(["read", "write", "list"])
+    .meta({ title: "Permission" });
+// One ACL rule
+export const AclEntrySchema = z
+    .object({
+    action: z
+        .enum(["allow", "deny"])
+        .meta({ description: "whether this rule allows or denies access" }),
+    resource: z
+        .string()
+        .meta({ description: "what — supports glob patterns like /files/*.txt" }),
+    permissions: z
+        .array(PermissionSchema)
+        .meta({ description: "actions this rule applies to" }),
+    description: z.string().optional().meta({
+        description: "custom message, in deny case, this is the error message. This will override denyDescription on AclPolicy if defined.",
+    }),
+    principals: z.array(z.string()).optional().meta({
+        description: "array of teams/roles this rule applies to (e.g., ['developer', 'admin'])",
+    }),
+})
+    .meta({ title: "AclEntry" });
+// A full ACL policy is just a list of rules
+export const AclPolicySchema = z
+    .object({
+    secrets: z.array(z.string()).optional(),
+    entries: z.array(AclEntrySchema).optional(),
+    denyDescription: z.string().optional().meta({
+        description: "Default message to use when a resource is denied access",
+    }),
+})
+    .meta({ title: "AclPolicy" });
+// Structured description of an ACL/policy denial. Travels with the tool result
+// so internal tools can show admins exactly which rule blocked a command/file,
+// and both UIs can render a distinct "blocked, did not run" treatment.
+export const AclDenialSchema = z
+    .object({
+    kind: z
+        .enum(["command-security", "command-allowlist", "file-access"])
+        .meta({ description: "which gate produced the denial" }),
+    reason: z
+        .enum([
+        "security-policy",
+        "deny-pattern-matched",
+        "no-allow-match",
+        "shell-metacharacter",
+    ])
+        .meta({ description: "why the denial happened" }),
+    resource: z.string().meta({
+        description: "the file path or command that was blocked",
+    }),
+    command: z.string().optional().meta({
+        description: "the full command, when the denial is command-related",
+    }),
+    permission: PermissionSchema.optional().meta({
+        description: "the requested permission, for file-access denials",
+    }),
+    policy: z.string().optional().meta({
+        description: "named security policy that matched, when applicable",
+    }),
+    matchedPattern: z.string().optional().meta({
+        description: "the glob/pattern that matched the resource or command",
+    }),
+    matchedEntry: AclEntrySchema.optional().meta({
+        description: "the full ACL entry that matched, for file-access denials",
+    }),
+    message: z.string().meta({ description: "human-readable explanation" }),
+})
+    .meta({ title: "AclDenial" });

package/src/events.d.ts

@@ -598,6 +598,8 @@ export type BotMentionGitHubInternalPrV1 = FusionEventVariant<"bot.mention.githu
     /** Numeric GitHub comment ID (for reaction / reply threading) */
     commentNumericId?: number;
     commentType: "issue" | "pr";
+    /** Whether the normal bot-mention pipeline should post successful agent text. */
+    postSuccessResultComment?: boolean;
     /** GitHub Enterprise hostname, if applicable */
     hostname?: string;
     /** For review comments: the comment being replied to */
@@ -1300,7 +1302,34 @@ export declare const McpPrototypePulledV1: {
     eventName: "mcp.prototype.pulled";
     version: "1";
 };
-export type FusionEvent = ClientDevtoolsSessionStartedEvent | ClientDevtoolsSessionIdleEventV1 | ClientDevtoolsToolCallRequestV1 | ClientDevtoolsToolCallV1 | ClientDevtoolsToolResultV1 | ClientDevtoolsBuildMigratedV1 | ClientDevtoolsBuildCompletedV1 | ClientDevtoolsBuildUploadedV1 | ClientDevtoolsBuildFailedV1 | FusionProjectCreatedV1 | SetupAgentCompletedV1 | GitPrMergedV1 | GitPrCreatedV1 | GitPrClosedV1 | ForceSetupAgentV1 | ClawMessageSentV1 | CodegenCompletionV1 | CodegenUserPromptV1 | GitWebhooksRegisterV1 | FusionProjectSettingsUpdatedV1 | VideoRecordingCompletedV1 | TimelineRecordingReadyV1 | FusionBranchCreatedV1 | FusionContainerStartedV1 | FusionContainerFailedV1 | FusionBranchFailedV1 | BotMentionGitHubExternalPrV1 | BotMentionGitHubInternalPrV1 | BotMentionGitLabPrV1 | BotMentionBitbucketPrV1 | BotMentionAzurePrV1 | ReviewSubmittedV1 | PrReviewRequestedV1 | FigmaDecodeJobV1 | ProjectSnapshotRefreshV1 | ProjectSnapshotCapturedV1 | ProjectSnapshotCreatedV1 | ProjectSnapshotFailedV1 | ProjectSnapshotReadyCheckV1 | ProjectSnapshotPodWatchV1 | McpPrototypePulledV1;
+export type HostingCustomDomainCertCheckV1 = FusionEventVariant<"hosting.custom-domain.cert-check", {
+    domain: string;
+    projectId: string;
+    certId: string;
+    attemptId: string;
+    startedAtMs: number;
+    timeoutMs: number;
+}, {
+    projectId: string;
+}, 1>;
+export declare const HostingCustomDomainCertCheckV1: {
+    eventName: "hosting.custom-domain.cert-check";
+    version: "1";
+};
+export type HostingCustomDomainDelegationCheckV1 = FusionEventVariant<"hosting.custom-domain.delegation-check", {
+    domain: string;
+    projectId: string;
+    attemptId: string;
+    startedAtMs: number;
+    timeoutMs: number;
+}, {
+    projectId: string;
+}, 1>;
+export declare const HostingCustomDomainDelegationCheckV1: {
+    eventName: "hosting.custom-domain.delegation-check";
+    version: "1";
+};
+export type FusionEvent = ClientDevtoolsSessionStartedEvent | ClientDevtoolsSessionIdleEventV1 | ClientDevtoolsToolCallRequestV1 | ClientDevtoolsToolCallV1 | ClientDevtoolsToolResultV1 | ClientDevtoolsBuildMigratedV1 | ClientDevtoolsBuildCompletedV1 | ClientDevtoolsBuildUploadedV1 | ClientDevtoolsBuildFailedV1 | FusionProjectCreatedV1 | SetupAgentCompletedV1 | GitPrMergedV1 | GitPrCreatedV1 | GitPrClosedV1 | ForceSetupAgentV1 | ClawMessageSentV1 | CodegenCompletionV1 | CodegenUserPromptV1 | GitWebhooksRegisterV1 | FusionProjectSettingsUpdatedV1 | VideoRecordingCompletedV1 | TimelineRecordingReadyV1 | FusionBranchCreatedV1 | FusionContainerStartedV1 | FusionContainerFailedV1 | FusionBranchFailedV1 | BotMentionGitHubExternalPrV1 | BotMentionGitHubInternalPrV1 | BotMentionGitLabPrV1 | BotMentionBitbucketPrV1 | BotMentionAzurePrV1 | ReviewSubmittedV1 | PrReviewRequestedV1 | FigmaDecodeJobV1 | ProjectSnapshotRefreshV1 | ProjectSnapshotCapturedV1 | ProjectSnapshotCreatedV1 | ProjectSnapshotFailedV1 | ProjectSnapshotReadyCheckV1 | ProjectSnapshotPodWatchV1 | McpPrototypePulledV1 | HostingCustomDomainCertCheckV1 | HostingCustomDomainDelegationCheckV1;
 export interface ModelPermissionRequiredEvent {
     type: "assistant.model.permission.required";
     data: {

package/src/events.js

@@ -162,3 +162,11 @@ export const McpPrototypePulledV1 = {
     eventName: "mcp.prototype.pulled",
     version: "1",
 };
+export const HostingCustomDomainCertCheckV1 = {
+    eventName: "hosting.custom-domain.cert-check",
+    version: "1",
+};
+export const HostingCustomDomainDelegationCheckV1 = {
+    eventName: "hosting.custom-domain.delegation-check",
+    version: "1",
+};

package/src/projects.d.ts

@@ -1490,9 +1490,16 @@ export declare const ProjectHostingSchema: z.ZodObject<{
         uploading: "uploading";
     }>>;
     publishedCommit: z.ZodOptional<z.ZodString>;
-    customDomain: z.ZodOptional<z.ZodString>;
-    customDomainVerified: z.ZodOptional<z.ZodBoolean>;
     autoDeploy: z.ZodOptional<z.ZodBoolean>;
+    unpublishTrigger: z.ZodOptional<z.ZodEnum<{
+        system: "system";
+        user: "user";
+    }>>;
+    systemUnpublishReason: z.ZodOptional<z.ZodEnum<{
+        "bandwidth-cap": "bandwidth-cap";
+        "web-request-cap": "web-request-cap";
+    }>>;
+    domainIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type ProjectHosting = z.infer<typeof ProjectHostingSchema>;
 /**
@@ -1550,6 +1557,36 @@ export declare const HostingSlugSchema: z.ZodObject<{
     createdBy: z.ZodString;
 }, z.core.$strip>;
 export type HostingSlug = z.infer<typeof HostingSlugSchema>;
+/**
+ * Per-Neon-project charged-through watermarks inside a space's hosting usage
+ * snapshot. Storage folds root + child branch bytes-month into one field.
+ */
+export declare const HostingNeonProjectUsageSchema: z.ZodObject<{
+    computeUnitSecondsChargedThrough: z.ZodNumber;
+    storageBytesMonthChargedThrough: z.ZodNumber;
+    transferBytesChargedThrough: z.ZodNumber;
+}, z.core.$strip>;
+export type HostingNeonProjectUsage = z.infer<typeof HostingNeonProjectUsageSchema>;
+/**
+ * Reconciler idempotency watermark for a space's Netlify + Neon hosting costs,
+ * stored at `hostingUsageSnapshots/{spaceId}`. Netlify is one account-level
+ * scalar; Neon is a per-project map. `freeDeployCount` gates the free 5/mo
+ * deploy cap (cost itself is inside Netlify's partner_account_usage total).
+ */
+export declare const HostingUsageSnapshotSchema: z.ZodObject<{
+    ownerId: z.ZodString;
+    periodKey: z.ZodString;
+    netlifyConsumptionCycleStart: z.ZodString;
+    netlifyCreditsChargedThrough: z.ZodNumber;
+    neonByProject: z.ZodRecord<z.ZodString, z.ZodObject<{
+        computeUnitSecondsChargedThrough: z.ZodNumber;
+        storageBytesMonthChargedThrough: z.ZodNumber;
+        transferBytesChargedThrough: z.ZodNumber;
+    }, z.core.$strip>>;
+    freeDeployCount: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type HostingUsageSnapshot = z.infer<typeof HostingUsageSnapshotSchema>;
 /**
  * Deploy lease lock with fencing token, stored at
  * `hosting-locks/{projectId}__{checkoutBranch}` (the key uses the resolved ref
@@ -1711,6 +1748,143 @@ export declare const GetDeploysResponseSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type GetDeploysResponse = z.infer<typeof GetDeploysResponseSchema>;
+export declare const HostingDomainStatusSchema: z.ZodEnum<{
+    active: "active";
+    failed: "failed";
+    pending: "pending";
+    provisioning: "provisioning";
+    verifying: "verifying";
+}>;
+export type HostingDomainStatus = z.infer<typeof HostingDomainStatusSchema>;
+export declare const HostingDomainKindSchema: z.ZodEnum<{
+    apex: "apex";
+    subdomain: "subdomain";
+}>;
+export type HostingDomainKind = z.infer<typeof HostingDomainKindSchema>;
+/**
+ * Custom domain record. The same shape backs two Firestore collections:
+ *
+ * - Lock doc `hosting-domains/{domain}` is the single exclusive owner. It
+ *   exists only once a project reaches `provisioning`/`active` (cert + route
+ *   created, DNS ownership proven) and is the cross-project serialization
+ *   point serving/deploy/unpublish read to answer "is this verified?".
+ *   `certId`/`certMapEntryName`/`httpRouteName`/`verifiedAt` are only ever
+ *   populated here.
+ * - Claim subdoc `hosting-domains/{domain}/claims/{projectId}` is a
+ *   non-exclusive, per-project verification attempt (`pending`/`verifying`/
+ *   `failed`). Multiple projects can hold a claim on the same domain at once;
+ *   whoever proves DNS ownership first wins the lock and the losers are swept
+ *   to `failed`.
+ *
+ * The normalized domain is the doc key — global uniqueness comes for free.
+ */
+export declare const HostingDomainSchema: z.ZodObject<{
+    domain: z.ZodString;
+    kind: z.ZodEnum<{
+        apex: "apex";
+        subdomain: "subdomain";
+    }>;
+    projectId: z.ZodString;
+    ownerId: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        failed: "failed";
+        pending: "pending";
+        provisioning: "provisioning";
+        verifying: "verifying";
+    }>;
+    dnsAuthId: z.ZodString;
+    delegationTarget: z.ZodString;
+    trafficTarget: z.ZodOptional<z.ZodString>;
+    certId: z.ZodOptional<z.ZodString>;
+    certMapEntryName: z.ZodOptional<z.ZodString>;
+    httpRouteName: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    pendingSince: z.ZodNumber;
+    verifyingSince: z.ZodOptional<z.ZodNumber>;
+    attemptId: z.ZodOptional<z.ZodString>;
+    verifiedAt: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodString>;
+    failedStep: z.ZodOptional<z.ZodEnum<{
+        dns: "dns";
+        https: "https";
+    }>>;
+    routeError: z.ZodOptional<z.ZodString>;
+    routeErrorAt: z.ZodOptional<z.ZodNumber>;
+    createdBy: z.ZodString;
+}, z.core.$strip>;
+export type HostingDomain = z.infer<typeof HostingDomainSchema>;
+export declare const AddDomainRequestSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    domain: z.ZodString;
+}, z.core.$strip>;
+export type AddDomainRequest = z.infer<typeof AddDomainRequestSchema>;
+export declare const AddDomainResponseSchema: z.ZodObject<{
+    domain: z.ZodString;
+    kind: z.ZodEnum<{
+        apex: "apex";
+        subdomain: "subdomain";
+    }>;
+    records: z.ZodObject<{
+        traffic: z.ZodObject<{
+            recordType: z.ZodEnum<{
+                A: "A";
+                CNAME: "CNAME";
+            }>;
+            name: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>;
+        validation: z.ZodObject<{
+            recordType: z.ZodEnum<{
+                A: "A";
+                CNAME: "CNAME";
+            }>;
+            name: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type AddDomainResponse = z.infer<typeof AddDomainResponseSchema>;
+export declare const VerifyDomainRequestSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    domain: z.ZodString;
+}, z.core.$strip>;
+export type VerifyDomainRequest = z.infer<typeof VerifyDomainRequestSchema>;
+export declare const VerifyDomainResponseSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        active: "active";
+        failed: "failed";
+        pending: "pending";
+        provisioning: "provisioning";
+        verifying: "verifying";
+    }>;
+}, z.core.$strip>;
+export type VerifyDomainResponse = z.infer<typeof VerifyDomainResponseSchema>;
+export declare const RemoveDomainRequestSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    domain: z.ZodString;
+}, z.core.$strip>;
+export type RemoveDomainRequest = z.infer<typeof RemoveDomainRequestSchema>;
+export declare const RemoveDomainResponseSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type RemoveDomainResponse = z.infer<typeof RemoveDomainResponseSchema>;
+export declare const RepairDomainRequestSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    domain: z.ZodString;
+}, z.core.$strip>;
+export type RepairDomainRequest = z.infer<typeof RepairDomainRequestSchema>;
+export declare const RepairDomainResponseSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        active: "active";
+        failed: "failed";
+        pending: "pending";
+        provisioning: "provisioning";
+        verifying: "verifying";
+    }>;
+    routeError: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RepairDomainResponse = z.infer<typeof RepairDomainResponseSchema>;
 export declare const CloneProjectOptionsSchema: z.ZodObject<{
     sourceProjectId: z.ZodString;
     sourceBranchName: z.ZodDefault<z.ZodString>;

package/src/projects.js

@@ -324,12 +324,33 @@ export const ProjectHostingSchema = z.object({
     lastDeployStatus: DeployStatusSchema.optional(),
     /** Git commit currently live at the project's hosting URL (set on go-live). */
     publishedCommit: z.string().optional(),
-    customDomain: z.string().optional(),
-    customDomainVerified: z.boolean().optional(),
     autoDeploy: z
         .boolean()
         .optional()
         .meta({ description: "auto-deploy on push/merge" }),
+    /**
+     * Who last drove the site into `publishStatus: "unpublished"`. Absent is
+     * treated as `"user"`. `"system"` means free-tier usage-cap enforcement took
+     * the site down (deleted the HTTPRoute, kept the Netlify site) and the
+     * reconciler **may** auto-restore it — routing-only, no rebuild — once the cap
+     * clears. `"user"` (or absent) means the user unpublished, so the reconciler
+     * must leave it down. The publish/unpublish hosting lock keeps this honest:
+     * whichever operation wins the lock is the one that writes `publishStatus`
+     * and this field, so they never disagree.
+     */
+    unpublishTrigger: z.enum(["system", "user"]).optional().meta({
+        description: "Who last unpublished the site. Absent === user. 'system' lets the reconciler auto-restore a usage-cap takedown; 'user' does not.",
+    }),
+    /**
+     * Why the system unpublished the site. Set iff `unpublishTrigger === "system"`;
+     * drives the projects-grid "suspended" card and takedown observability.
+     */
+    systemUnpublishReason: z
+        .enum(["bandwidth-cap", "web-request-cap"])
+        .optional(),
+    domainIds: z.array(z.string()).optional().meta({
+        description: "Doc keys (normalized domains) in `hosting-domains` attached to this project. The domain docs are the source of truth; this is only the back-pointer.",
+    }),
 });
 /**
  * Canonical "is this project hostable" predicate. Keys off the explicit
@@ -410,6 +431,42 @@ export const HostingSlugSchema = z.object({
         description: "user ID of the user who first clicked Publish on the project",
     }),
 });
+/**
+ * Per-Neon-project charged-through watermarks inside a space's hosting usage
+ * snapshot. Storage folds root + child branch bytes-month into one field.
+ */
+export const HostingNeonProjectUsageSchema = z.object({
+    computeUnitSecondsChargedThrough: z.number(),
+    storageBytesMonthChargedThrough: z.number().meta({
+        description: "root + child branch bytes-month already billed",
+    }),
+    transferBytesChargedThrough: z.number().meta({
+        description: "public network transfer bytes already billed",
+    }),
+});
+/**
+ * Reconciler idempotency watermark for a space's Netlify + Neon hosting costs,
+ * stored at `hostingUsageSnapshots/{spaceId}`. Netlify is one account-level
+ * scalar; Neon is a per-project map. `freeDeployCount` gates the free 5/mo
+ * deploy cap (cost itself is inside Netlify's partner_account_usage total).
+ */
+export const HostingUsageSnapshotSchema = z.object({
+    ownerId: z.string(),
+    periodKey: z.string().meta({
+        description: "Builder billing cycle; resets the Neon watermarks",
+    }),
+    netlifyConsumptionCycleStart: z.string().meta({
+        description: "Netlify consumption_cycle_start_date; watermark resets when this advances",
+    }),
+    netlifyCreditsChargedThrough: z.number().meta({
+        description: "Netlify credits already billed this Netlify cycle",
+    }),
+    neonByProject: z.record(z.string(), HostingNeonProjectUsageSchema),
+    freeDeployCount: z.number().meta({
+        description: "Deploys this Builder cycle, for the free 5/mo cap",
+    }),
+    updatedAt: z.number(),
+});
 /**
  * Deploy lease lock with fencing token, stored at
  * `hosting-locks/{projectId}__{checkoutBranch}` (the key uses the resolved ref
@@ -615,6 +672,116 @@ export const GetDeploysRequestSchema = z.object({
 export const GetDeploysResponseSchema = z.object({
     deploys: z.array(DeployListItemSchema),
 });
+export const HostingDomainStatusSchema = z.enum([
+    "pending",
+    "verifying",
+    "provisioning",
+    "active",
+    "failed",
+]);
+export const HostingDomainKindSchema = z.enum(["apex", "subdomain"]);
+/**
+ * Custom domain record. The same shape backs two Firestore collections:
+ *
+ * - Lock doc `hosting-domains/{domain}` is the single exclusive owner. It
+ *   exists only once a project reaches `provisioning`/`active` (cert + route
+ *   created, DNS ownership proven) and is the cross-project serialization
+ *   point serving/deploy/unpublish read to answer "is this verified?".
+ *   `certId`/`certMapEntryName`/`httpRouteName`/`verifiedAt` are only ever
+ *   populated here.
+ * - Claim subdoc `hosting-domains/{domain}/claims/{projectId}` is a
+ *   non-exclusive, per-project verification attempt (`pending`/`verifying`/
+ *   `failed`). Multiple projects can hold a claim on the same domain at once;
+ *   whoever proves DNS ownership first wins the lock and the losers are swept
+ *   to `failed`.
+ *
+ * The normalized domain is the doc key — global uniqueness comes for free.
+ */
+export const HostingDomainSchema = z.object({
+    domain: z
+        .string()
+        .meta({ description: "Doc key — normalized (punycode) domain." }),
+    kind: HostingDomainKindSchema,
+    projectId: z.string(),
+    ownerId: z.string(),
+    status: HostingDomainStatusSchema,
+    dnsAuthId: z
+        .string()
+        .meta({ description: "GCP DNS authorization resource name." }),
+    delegationTarget: z.string().meta({
+        description: "_acme-challenge CNAME value the customer must add.",
+    }),
+    trafficTarget: z.string().optional().meta({
+        description: "The traffic record value: ALB anycast IP for apex domains, `cname.builder.cloud` for subdomains. Persisted so the UI can reconstruct both DNS records after page reload.",
+    }),
+    certId: z
+        .string()
+        .optional()
+        .meta({ description: "Certificate Manager cert resource name." }),
+    certMapEntryName: z.string().optional(),
+    httpRouteName: z.string().optional(),
+    createdAt: z.number(),
+    pendingSince: z.number().meta({
+        description: "TTL anchor: set on entering `pending`, re-stamped on `failed`→`pending`.",
+    }),
+    verifyingSince: z.number().optional().meta({
+        description: "Set when the delegation-check poll loop starts (on entering `verifying`). Used for the poll timeout and UI. Cleared on promotion to `provisioning` or on failure.",
+    }),
+    attemptId: z.string().optional().meta({
+        description: "Per-verify-attempt nonce, set on entering `verifying`. Delegation-check polls whose attemptId no longer matches are stale (a newer retry superseded them) and stop early.",
+    }),
+    verifiedAt: z.number().optional(),
+    error: z.string().optional(),
+    failedStep: z.enum(["dns", "https"]).optional().meta({
+        description: "Which setup step failed, set alongside `status: failed` so the UI can attribute the failure. `dns` = delegation verification, `https` = cert/route provisioning.",
+    }),
+    routeError: z.string().optional().meta({
+        description: "Non-fatal health signal on an otherwise verified (`provisioning`/`active`) domain: set when re-creating the Envoy HTTPRoute failed on republish, so the site's cert is valid but the custom domain has no live route (bare 404). `status` stays `active`; this drives a degraded banner + Fix action. Cleared once the route is recreated.",
+    }),
+    routeErrorAt: z.number().optional().meta({
+        description: "When `routeError` was last set.",
+    }),
+    createdBy: z.string(),
+});
+export const AddDomainRequestSchema = z.object({
+    projectId: z.string(),
+    domain: z.string(),
+});
+const DnsRecordSchema = z.object({
+    recordType: z.enum(["A", "CNAME"]),
+    name: z.string(),
+    value: z.string(),
+});
+export const AddDomainResponseSchema = z.object({
+    domain: z.string(),
+    kind: HostingDomainKindSchema,
+    records: z.object({
+        traffic: DnsRecordSchema,
+        validation: DnsRecordSchema,
+    }),
+});
+export const VerifyDomainRequestSchema = z.object({
+    projectId: z.string(),
+    domain: z.string(),
+});
+export const VerifyDomainResponseSchema = z.object({
+    status: HostingDomainStatusSchema,
+});
+export const RemoveDomainRequestSchema = z.object({
+    projectId: z.string(),
+    domain: z.string(),
+});
+export const RemoveDomainResponseSchema = z.object({
+    success: z.literal(true),
+});
+export const RepairDomainRequestSchema = z.object({
+    projectId: z.string(),
+    domain: z.string(),
+});
+export const RepairDomainResponseSchema = z.object({
+    status: HostingDomainStatusSchema,
+    routeError: z.string().optional(),
+});
 export const CloneProjectOptionsSchema = z.object({
     sourceProjectId: z.string().min(1).meta({
         description: "Project to clone from.",

package/src/vpc-peering.d.ts

@@ -0,0 +1,49 @@
+/** Fields common to all VPC connectivity types. */
+interface VpcConnectionBase {
+    id: string;
+    ownerId: string;
+    type: string;
+    gcpRegion: string;
+    customerDnsServers: string[];
+    proxyIp: string;
+    enabled: boolean;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Traditional VPC Peering via bridge VPC. */
+export interface VpcGcpPeering extends VpcConnectionBase {
+    type: "gcp-peering";
+    gcpProjectId: string;
+    gcpNetworkName: string;
+    bridgeCidr: string;
+    importCustomRoutes: boolean;
+}
+/**
+ * PSC Network Attachment — customer creates the network attachment in their VPC,
+ * our proxy VM connects to it via a PSC interface on nic1.
+ * No bridge VPC or bridge CIDR needed on our side.
+ */
+export interface VpcGcpNetworkAttachment extends VpcConnectionBase {
+    type: "gcp-network-attachment";
+    gcpProjectId: string;
+    networkAttachmentName: string;
+}
+/** Discriminated union of all VPC connectivity types. */
+export type VpcPeering = VpcGcpPeering | VpcGcpNetworkAttachment;
+export interface CreateVpcGcpPeeringParams {
+    type: "gcp-peering";
+    gcpRegion: string;
+    gcpProjectId: string;
+    gcpNetworkName: string;
+    bridgeCidr: string;
+    customerDnsServers: string[];
+    importCustomRoutes?: boolean;
+}
+export interface CreateVpcGcpNetworkAttachmentParams {
+    type: "gcp-network-attachment";
+    gcpProjectId: string;
+    networkAttachmentName: string;
+    customerDnsServers: string[];
+}
+export type CreateVpcPeeringParams = CreateVpcGcpPeeringParams | CreateVpcGcpNetworkAttachmentParams;
+export {};

package/src/vpc-peering.js

@@ -0,0 +1 @@
+export {};