@builder.io/ai-utils 0.91.1 → 0.92.0

package/src/projects.js

@@ -25,6 +25,16 @@ export function getGitProviderFromUrl(url) {
         return "unknown";
     }
 }
+export const GIT_PROVIDERS = [
+    "github",
+    "selfHostedGithub",
+    "bitbucket",
+    "gitlab",
+    "azure",
+    "internalHost",
+    "custom",
+];
+export const GitProviderSchema = z.enum(GIT_PROVIDERS);
 export const EXAMPLE_REPOS = [
     "steve8708/mui-vite",
     "steve8708/carbon-vite",
@@ -970,6 +980,14 @@ export const ProjectHostingBuildConfigSchema = z.object({
     buildOutputDir: z.string().optional(),
     nodeVersion: z.string().optional(),
 });
+/**
+ * Who pays for AI usage on a project's published site.
+ *
+ * `undefined` is reserved for headless publishes that never reach
+ * `POST /projects/hosting/ai-usage`: it is the signal that makes the publish
+ * step fire, so every interactive path writes a value, `"skip"` included.
+ */
+export const AiPaymentModeSchema = z.enum(["builder-credits", "byok", "skip"]);
 /**
  * Hosting configuration for a project, stored at `projects/{projectId}.hosting`.
  */
@@ -1015,6 +1033,8 @@ export const ProjectHostingSchema = z.object({
     lastDeployId: z.string().optional(),
     lastDeployAt: z.number().optional(),
     lastDeployStatus: DeployStatusSchema.optional(),
+    /** Kubernetes branch route currently serving; absent means the default route. */
+    publishedBranchId: z.string().optional(),
     /** Git commit currently live at the project's hosting URL (set on go-live). */
     publishedCommit: z.string().optional(),
     autoDeploy: z
@@ -1042,6 +1062,24 @@ export const ProjectHostingSchema = z.object({
     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.",
     }),
+    /**
+     * Who pays for AI usage on the published site. Written only by
+     * `POST /projects/hosting/ai-usage`, which gates on `fusionHostingPublish`;
+     * deliberately kept out of {@link PROJECT_UPDATABLE_HOSTING_FIELDS_MASK} so
+     * the generic `PATCH` (gated on `modifyProjectSettings`) cannot write it.
+     */
+    aiPaymentMode: AiPaymentModeSchema.optional().meta({
+        description: "Who pays for AI usage on the published site. Absent means the first-publish step has never run for this project.",
+    }),
+    /**
+     * When a hosting field that is baked into the deployed site last changed
+     * (env vars, build config, AI payment mode). Compared against
+     * `lastDeployAt` to decide whether the live site is stale: server-side so a
+     * change made in one browser session is visible in every other.
+     */
+    configUpdatedAt: z.number().optional().meta({
+        description: "Epoch ms of the last change to a hosting field that requires a redeploy. Compare against `lastDeployAt`.",
+    }),
 });
 /**
  * Mask of the hosting sub-fields a client may write via `PATCH`. Everything
@@ -1052,7 +1090,7 @@ export const ProjectHostingSchema = z.object({
  * new field added to `ProjectHostingSchema` must be opted *in* to be writable,
  * so the default for anything we add later is "not client-writable".
  */
-const PROJECT_UPDATABLE_HOSTING_FIELDS_MASK = {
+export const PROJECT_UPDATABLE_HOSTING_FIELDS_MASK = {
     enabled: true,
     buildConfig: true,
     environment: true,
@@ -1184,6 +1222,18 @@ export const DeploySchema = z.object({
     devBranchId: z.string().optional().meta({
         description: "Fusion dev branch's id (unset if we are deploying project default branch)",
     }),
+    supersededRouteBranchId: z.string().nullable().optional().meta({
+        description: "Prior published route awaiting cleanup after a branch switch; null identifies the default route.",
+    }),
+    supersededRouteResourceVersions: z
+        .object({
+        route: z.string().optional(),
+        handshake: z.string().optional(),
+    })
+        .optional()
+        .meta({
+        description: "Kubernetes versions that fence deletion of the superseded route resources.",
+    }),
     status: DeployStatusSchema,
     netlifyDeployId: z.string().optional(),
     url: z.string().optional(),
@@ -1461,6 +1511,92 @@ export const DeleteHostingRequestSchema = z.object({
 export const DeleteHostingResponseSchema = z.object({
     success: z.literal(true),
 });
+// ---------------------------------------------------------------------------
+// AI usage (who pays for AI on the published site)
+// ---------------------------------------------------------------------------
+/** Query for `GET /projects/hosting/ai-usage`. */
+export const GetHostingAiUsageRequestSchema = z.object({
+    projectId: z.string().min(1),
+});
+/**
+ * Status of the published site's gateway token. Recomputed from the
+ * authoritative PAT doc on every read; the plaintext token is never included.
+ */
+export const HostingAiUsageTokenStatusSchema = z.object({
+    active: z.boolean(),
+    lastUsed: z.number().optional(),
+    createdBy: z.string().optional(),
+});
+export const GetHostingAiUsageResponseSchema = z.object({
+    /**
+     * Whether the project has ever been deployed. Server-derived from
+     * `hosting.netlifySiteId`, which the client can never see.
+     */
+    hasEverPublished: z.boolean(),
+    aiPaymentMode: AiPaymentModeSchema.optional(),
+    /**
+     * Whether `"builder-credits"` can be honoured for this project: the LD flag
+     * AND a `coreVersion` floor at or above the minimum supporting release.
+     * Per-project, because core is pinned in the project's own lockfile.
+     */
+    coreSupportsGateway: z.boolean(),
+    token: HostingAiUsageTokenStatusSchema.nullable(),
+});
+/** Providers a customer may bring their own key for. */
+export const AiUsageByokProviderSchema = z.enum(["anthropic", "openai"]);
+/**
+ * Body for `POST /projects/hosting/ai-usage`.
+ *
+ * Deliberately closed (`strictObject`): this route is gated on
+ * `fusionHostingPublish` rather than `modifyProjectSettings`, so the request
+ * shape is the only thing stopping it becoming a general prod-env write
+ * primitive. The handler builds the env entries itself from `provider`,
+ * `apiKey` and `baseUrl` — an env var *name* is never caller-supplied.
+ */
+export const SetHostingAiUsageRequestSchema = z.strictObject({
+    projectId: z.string().min(1),
+    mode: AiPaymentModeSchema,
+    provider: AiUsageByokProviderSchema.optional(),
+    apiKey: z.string().min(1).optional(),
+    // https only: this value is written into a published site's prod env as
+    // `OPENAI_BASE_URL`, so an `http://` endpoint would send the customer's
+    // provider key and every prompt in plaintext from the deployed site.
+    baseUrl: z
+        .url()
+        .refine((value) => value.startsWith("https://"), {
+        message: "baseUrl must use https",
+    })
+        .optional(),
+});
+export const SetHostingAiUsageResponseSchema = z.object({
+    aiPaymentMode: AiPaymentModeSchema,
+    /**
+     * `hosting.configUpdatedAt` after the write — compare against
+     * `hosting.lastDeployAt` to decide whether a redeploy is needed. Absent when
+     * the write changed nothing deploy-relevant (e.g. re-selecting the current
+     * mode), which is exactly the case where no redeploy is needed.
+     */
+    configUpdatedAt: z.number().optional(),
+});
+/** Body for `POST /projects/hosting/ai-usage/revoke`. */
+export const RevokeHostingAiTokenRequestSchema = z.strictObject({
+    projectId: z.string().min(1),
+});
+export const RevokeHostingAiTokenResponseSchema = z.object({
+    success: z.literal(true),
+});
+/**
+ * The three prod env vars the AI-usage endpoint owns. The write path sets only
+ * these; every non-`byok` mode deletes exactly these. Without the delete, a
+ * BYOK→credits switch is a silent no-op — the stale provider key keeps winning
+ * the framework's engine auto-detection, and the gateway injection gate keys on
+ * its absence.
+ */
+export const AI_USAGE_MANAGED_PROD_ENV_KEYS = [
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+];
 export const GetDeploysRequestSchema = z.object({
     projectId: z.string(),
     deployId: z.string().optional(),
@@ -1703,3 +1839,69 @@ export const EnsureMainBranchExistsOptionsSchema = z.object({
         description: "Branch whose head ref seeds the main branch when it doesn't exist yet. No-op for non-internalHost projects.",
     }),
 });
+/**
+ * `settings.environmentVariables` is stored with **plaintext** secret values;
+ * secrets are masked before this shape leaves ai-services, same as
+ * `Project.settings`.
+ */
+export const ProjectTemplateSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    ownerId: z.string(),
+    description: z.string(),
+    repoFullName: z.string(),
+    repoProvider: GitProviderSchema,
+    repoUrl: z.string(),
+    repoPrivate: z.boolean(),
+    screenshot: z.string().nullish(),
+    order: z.number(),
+    hidden: z.boolean(),
+    isDefault: z.boolean(),
+    createdDate: z.string(),
+    updatedAt: z.string(),
+    createdBy: z.string(),
+    lastUpdateBy: z.string(),
+    sourceProjectId: z.string(),
+    sourceBranchName: z.string(),
+    settings: ProjectSettingsSchema.partial(),
+    hosting: ProjectHostingSchema.optional(),
+});
+/**
+ * The id, ownership, audit, and source fields are server-assigned, so they can't
+ * be overridden here.
+ *
+ * A masked-secret placeholder in `settings.environmentVariables` keeps the
+ * source project's real value, so a client that never saw a secret can still
+ * round-trip it.
+ */
+export const ProjectTemplateOverridesSchema = z.object({
+    ...ProjectTemplateSchema.omit({
+        id: true,
+        ownerId: true,
+        createdDate: true,
+        updatedAt: true,
+        createdBy: true,
+        lastUpdateBy: true,
+        sourceProjectId: true,
+        sourceBranchName: true,
+    }).partial().shape,
+    hosting: ProjectHostingExternalSchema.optional(),
+});
+export const CreateProjectTemplateFromProjectOptionsSchema = z.object({
+    sourceProjectId: z.string().min(1).meta({
+        description: "Project whose settings, repo fields, and hosting config seed the template.",
+    }),
+    sourceBranchName: z.string().min(1).meta({
+        description: "Branch of the source project that projects created from this template are seeded from.",
+    }),
+    overrides: ProjectTemplateOverridesSchema.optional().meta({
+        description: "Fields to override on top of the values copied from the source project.",
+    }),
+});
+/**
+ * Deliberately minimal: the stored template carries plaintext secret env values,
+ * so nothing beyond the identity of the new template goes back to the caller.
+ */
+export const CreateProjectTemplateFromProjectResponseSchema = z.object({
+    template: ProjectTemplateSchema.pick({ id: true, name: true }),
+});

package/src/projects.test.js

@@ -1,5 +1,16 @@
 import { describe, expect, it } from "vitest";
-import { AGENT_NATIVE_STARTER_REPO, matchesAgentNativeStarter, } from "./projects";
+import { AGENT_NATIVE_STARTER_REPO, matchesAgentNativeStarter, ProjectHostingExternalSchema, ProjectHostingSchema, } from "./projects";
+describe("project hosting schemas", () => {
+    it("accepts the canonical published branch route", () => {
+        expect(ProjectHostingSchema.parse({ publishedBranchId: "branch-live" })).toEqual({ publishedBranchId: "branch-live" });
+    });
+    it("does not allow clients to write the canonical published branch route", () => {
+        expect(ProjectHostingExternalSchema.parse({
+            enabled: true,
+            publishedBranchId: "branch-client",
+        })).toEqual({ enabled: true });
+    });
+});
 describe("matchesAgentNativeStarter", () => {
     it("matches when repoName is the starter", () => {
         expect(matchesAgentNativeStarter({ repoName: AGENT_NATIVE_STARTER_REPO })).toBe(true);