@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/git.d.ts

@@ -96,16 +96,16 @@ export declare const gitConnectionCreateSchema: z.ZodPipe<z.ZodObject<{
     autoDeployProduction: z.ZodDefault<z.ZodBoolean>;
     autoDeployPreviews: z.ZodDefault<z.ZodBoolean>;
     buildSettings: z.ZodOptional<z.ZodObject<{
-        rootDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        installDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        installCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        buildCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        outputDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        ignoredBuildCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        frameworkPreset: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        platformPreset: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-        timeoutSeconds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        buildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        outputDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        ignoredBuildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        frameworkPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        platformPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodBoolean>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodTransform<{
     productionBranch: string;
@@ -163,16 +163,16 @@ export declare const gitConnectionPatchSchema: z.ZodObject<{
     autoDeployProduction: z.ZodOptional<z.ZodBoolean>;
     autoDeployPreviews: z.ZodOptional<z.ZodBoolean>;
     buildSettings: z.ZodOptional<z.ZodObject<{
-        rootDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        installDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        installCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        buildCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        outputDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        ignoredBuildCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        frameworkPreset: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        platformPreset: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-        timeoutSeconds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        buildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        outputDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        ignoredBuildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        frameworkPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        platformPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodBoolean>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const gitConnectionAnalyzeSchema: z.ZodObject<{
@@ -249,7 +249,13 @@ export declare const githubInstallationSchema: z.ZodObject<{
     htmlUrl: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export declare const githubInstallationsResponseSchema: z.ZodObject<{
-    appConfigured: z.ZodBoolean;
+    readiness: z.ZodObject<{
+        canAuthorize: z.ZodBoolean;
+        canInstall: z.ZodBoolean;
+        webhookReady: z.ZodBoolean;
+        codeStorageReady: z.ZodBoolean;
+        ready: z.ZodBoolean;
+    }, z.core.$strip>;
     installUrl: z.ZodNullable<z.ZodString>;
     installations: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -258,18 +264,6 @@ export declare const githubInstallationsResponseSchema: z.ZodObject<{
         htmlUrl: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export declare const githubInstallationClaimSchema: z.ZodObject<{
-    installationId: z.ZodString;
-    state: z.ZodString;
-}, z.core.$strip>;
-export declare const githubInstallationClaimResponseSchema: z.ZodObject<{
-    installation: z.ZodObject<{
-        id: z.ZodString;
-        accountLogin: z.ZodString;
-        accountType: z.ZodNullable<z.ZodString>;
-        htmlUrl: z.ZodNullable<z.ZodString>;
-    }, z.core.$strip>;
-}, z.core.$strip>;
 export declare const githubRepositorySchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;

package/dist/contracts/git.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { BuildSettingsSchema } from "./builds.js";
+import { BuildSettingsOverrideSchema, BuildSettingsSchema } from "./builds.js";
 import { gitProvider } from "./enums.js";
 const nullableString = z.string().trim().min(1).nullable();
 export const buildTargetValues = ["production", "preview"];
@@ -55,7 +55,7 @@ export const gitConnectionCreateSchema = z
     credential: z.string().trim().min(1).nullable().optional(),
     autoDeployProduction: z.boolean().default(true),
     autoDeployPreviews: z.boolean().default(true),
-    buildSettings: gitBuildSettingsSchema.partial().optional(),
+    buildSettings: BuildSettingsOverrideSchema.optional(),
 })
     .transform((value) => ({
     ...value,
@@ -67,7 +67,7 @@ export const gitConnectionPatchSchema = z.object({
     credential: z.string().trim().min(1).nullable().optional(),
     autoDeployProduction: z.boolean().optional(),
     autoDeployPreviews: z.boolean().optional(),
-    buildSettings: gitBuildSettingsSchema.partial().optional(),
+    buildSettings: BuildSettingsOverrideSchema.optional(),
 });
 export const gitConnectionAnalyzeSchema = z.object({
     ref: z.string().trim().min(1).optional(),
@@ -95,17 +95,16 @@ export const githubInstallationSchema = z.object({
     htmlUrl: z.string().url().nullable(),
 });
 export const githubInstallationsResponseSchema = z.object({
-    appConfigured: z.boolean(),
+    readiness: z.object({
+        canAuthorize: z.boolean(),
+        canInstall: z.boolean(),
+        webhookReady: z.boolean(),
+        codeStorageReady: z.boolean(),
+        ready: z.boolean(),
+    }),
     installUrl: z.string().url().nullable(),
     installations: z.array(githubInstallationSchema),
 });
-export const githubInstallationClaimSchema = z.object({
-    installationId: z.string().trim().min(1),
-    state: z.string().trim().min(1),
-});
-export const githubInstallationClaimResponseSchema = z.object({
-    installation: githubInstallationSchema,
-});
 export const githubRepositorySchema = z.object({
     id: z.string(),
     name: z.string(),

package/dist/contracts/grant-copy.d.ts

@@ -0,0 +1,43 @@
+import { OAUTH_SCOPE_COPY, oauthScopeCopy, type OAuthScopeCopy, type OAuthScopeId, type OAuthScopeRiskTint } from "./oauth-resources.js";
+/**
+ * The one vocabulary every authorization surface renders.
+ *
+ * Consent, the elevation diff, device approve, ledger chips, approval and grant
+ * emails, and the CLI's approval prose all read from here, so a permission
+ * never has one name in the browser and another in the inbox. Raw scope ids and
+ * purpose codes belong in developer views only.
+ *
+ * Scope copy is re-exported from `oauth-resources` rather than duplicated: the
+ * scope list and its descriptions are the OAuth wire contract, and a second
+ * copy of it is a second thing to drift.
+ */
+export { OAUTH_SCOPE_COPY as GRANT_SCOPE_COPY, oauthScopeCopy as grantScopeCopy, type OAuthScopeCopy as GrantScopeCopy, type OAuthScopeId as GrantScopeId, type OAuthScopeRiskTint as GrantRiskTint, };
+export type GrantScopeCopyEntry = OAuthScopeCopy & {
+    id: string;
+};
+/** Scope copy for a whole set, in the order given, ready to render as a list. */
+export declare function grantScopeCopyList(scopes: readonly string[]): GrantScopeCopyEntry[];
+/**
+ * Why a grant or decision is being asked for, in the user's language.
+ *
+ * Purpose strings are SERVER-OWNED. Only these codes and templates render as
+ * the reason a grant is requested; client identity is displayed separately and
+ * escaped. Client-authored purpose text is a consent-spoofing surface and is
+ * never accepted (§4.5).
+ *
+ * Each entry reads as the completion of "… is asking to <copy>".
+ */
+export declare const GRANT_PURPOSE_COPY: {
+    readonly "publish.confirm": "publish a new version";
+    readonly "deploy.confirm": "deploy a site";
+    readonly "version.rollback.confirm": "roll a site back to an earlier version";
+    readonly "domain.purchase.confirm": "purchase a domain";
+    readonly "domain.dns.confirm": "change domain DNS";
+    readonly "device.authorize": "connect the Spacefast CLI";
+    readonly "agent_handoff.redeem": "continue a Spacefast handoff";
+    readonly "claim.continue": "continue a claimed site";
+    readonly "oauth.connect": "connect to Spacefast";
+};
+export type GrantPurposeCode = keyof typeof GRANT_PURPOSE_COPY;
+/** Never throws: an unknown code renders the neutral fallback, never the code. */
+export declare function grantPurposeCopy(purposeCode: string): string;

package/dist/contracts/grant-copy.js

@@ -0,0 +1,44 @@
+import { OAUTH_SCOPE_COPY, oauthScopeCopy, } from "./oauth-resources.js";
+/**
+ * The one vocabulary every authorization surface renders.
+ *
+ * Consent, the elevation diff, device approve, ledger chips, approval and grant
+ * emails, and the CLI's approval prose all read from here, so a permission
+ * never has one name in the browser and another in the inbox. Raw scope ids and
+ * purpose codes belong in developer views only.
+ *
+ * Scope copy is re-exported from `oauth-resources` rather than duplicated: the
+ * scope list and its descriptions are the OAuth wire contract, and a second
+ * copy of it is a second thing to drift.
+ */
+export { OAUTH_SCOPE_COPY as GRANT_SCOPE_COPY, oauthScopeCopy as grantScopeCopy, };
+/** Scope copy for a whole set, in the order given, ready to render as a list. */
+export function grantScopeCopyList(scopes) {
+    return [...new Set(scopes)].map((id) => ({ id, ...oauthScopeCopy(id) }));
+}
+/**
+ * Why a grant or decision is being asked for, in the user's language.
+ *
+ * Purpose strings are SERVER-OWNED. Only these codes and templates render as
+ * the reason a grant is requested; client identity is displayed separately and
+ * escaped. Client-authored purpose text is a consent-spoofing surface and is
+ * never accepted (§4.5).
+ *
+ * Each entry reads as the completion of "… is asking to <copy>".
+ */
+export const GRANT_PURPOSE_COPY = {
+    "publish.confirm": "publish a new version",
+    "deploy.confirm": "deploy a site",
+    "version.rollback.confirm": "roll a site back to an earlier version",
+    "domain.purchase.confirm": "purchase a domain",
+    "domain.dns.confirm": "change domain DNS",
+    "device.authorize": "connect the Spacefast CLI",
+    "agent_handoff.redeem": "continue a Spacefast handoff",
+    "claim.continue": "continue a claimed site",
+    "oauth.connect": "connect to Spacefast",
+};
+/** Never throws: an unknown code renders the neutral fallback, never the code. */
+export function grantPurposeCopy(purposeCode) {
+    const match = Object.entries(GRANT_PURPOSE_COPY).find(([code]) => code === purposeCode);
+    return match?.[1] ?? "act in Spacefast";
+}

package/dist/contracts/grants.d.ts

@@ -263,8 +263,47 @@ export declare const managedGrantWriteSchema: z.ZodObject<{
     }, z.core.$strict>], "kind">;
 }, z.core.$strict>;
 export type ManagedGrantWrite = z.infer<typeof managedGrantWriteSchema>;
+declare const externalGrantWriteAudienceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"external">;
+    connectionId: z.ZodTemplateLiteral<`acn_${string}`>;
+    subject: z.ZodString;
+}, z.core.$strict>;
 export declare const directManagedGrantWriteSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
+    resources: z.ZodObject<{
+        include: z.ZodArray<z.ZodString>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    capabilities: z.ZodArray<z.ZodEnum<{
+        "page.view": "page.view";
+        "comments.read": "comments.read";
+        "comments.write": "comments.write";
+        "content.publish": "content.publish";
+        "access.manage": "access.manage";
+    }>>;
+    constraints: z.ZodDefault<z.ZodObject<{
+        notBefore: z.ZodOptional<z.ZodString>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+        maxUses: z.ZodOptional<z.ZodNumber>;
+        requireVerifiedEmail: z.ZodOptional<z.ZodBoolean>;
+        network: z.ZodOptional<z.ZodObject<{
+            ipCidrs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            countries: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            excludedCountries: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            excludedUserAgentSubstrings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"live">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"version">;
+        versionId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"branch">;
+        branch: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"all_versions">;
+    }, z.core.$strict>], "kind">;
     audience: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"public">;
     }, z.core.$strict>, z.ZodObject<{
@@ -273,20 +312,11 @@ export declare const directManagedGrantWriteSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"person">;
         personId: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"link">;
-        linkId: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"password">;
-        credentialId: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"machine">;
-        machineId: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"external">;
-        issuer: z.ZodString;
-        subject: z.ZodString;
     }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+export type DirectManagedGrantWrite = z.infer<typeof directManagedGrantWriteSchema>;
+export declare const spaceGrantCreateSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
     resources: z.ZodObject<{
         include: z.ZodArray<z.ZodString>;
         exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -321,8 +351,25 @@ export declare const directManagedGrantWriteSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"all_versions">;
     }, z.core.$strict>], "kind">;
+    audience: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"public">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"team">;
+        teamId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"person">;
+        personId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"external">;
+        connectionId: z.ZodTemplateLiteral<`acn_${string}`>;
+        subject: z.ZodString;
+    }, z.core.$strict>], "kind">;
 }, z.core.$strict>;
-export type DirectManagedGrantWrite = z.infer<typeof directManagedGrantWriteSchema>;
+export type SpaceGrantCreate = z.infer<typeof spaceGrantCreateSchema>;
+/** The external branch of the create body, once its subject has been read. */
+export type ExternalManagedGrantWrite = Omit<SpaceGrantCreate, "audience"> & {
+    audience: z.infer<typeof externalGrantWriteAudienceSchema>;
+};
 export declare const grantSourceExplanationSchema: z.ZodObject<{
     editable: z.ZodBoolean;
     label: z.ZodString;
@@ -1137,43 +1184,4 @@ export declare const identityConnectionSchema: z.ZodObject<{
     revokedAt: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
 export type IdentityConnection = z.infer<typeof identityConnectionSchema>;
-export declare const externalGrantCreateSchema: z.ZodObject<{
-    name: z.ZodString;
-    resources: z.ZodObject<{
-        include: z.ZodArray<z.ZodString>;
-        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    }, z.core.$strict>;
-    capabilities: z.ZodArray<z.ZodEnum<{
-        "page.view": "page.view";
-        "comments.read": "comments.read";
-        "comments.write": "comments.write";
-        "content.publish": "content.publish";
-        "access.manage": "access.manage";
-    }>>;
-    constraints: z.ZodDefault<z.ZodObject<{
-        notBefore: z.ZodOptional<z.ZodString>;
-        expiresAt: z.ZodOptional<z.ZodString>;
-        maxUses: z.ZodOptional<z.ZodNumber>;
-        requireVerifiedEmail: z.ZodOptional<z.ZodBoolean>;
-        network: z.ZodOptional<z.ZodObject<{
-            ipCidrs: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            countries: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            excludedCountries: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            excludedUserAgentSubstrings: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>>;
-    }, z.core.$strict>>;
-    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"live">;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"version">;
-        versionId: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"branch">;
-        branch: z.ZodString;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"all_versions">;
-    }, z.core.$strict>], "kind">;
-    connectionId: z.ZodTemplateLiteral<`acn_${string}`>;
-    subject: z.ZodString;
-}, z.core.$strict>;
-export type ExternalGrantCreate = z.infer<typeof externalGrantCreateSchema>;
+export {};

package/dist/contracts/grants.js

@@ -482,12 +482,55 @@ export const managedGrantWriteSchema = grantDimensionsSchema.superRefine((value,
         });
     }
 });
-export const directManagedGrantWriteSchema = managedGrantWriteSchema.superRefine((value, context) => {
-    if (!["public", "team", "person"].includes(value.audience.kind)) {
+// The subjects a manager can name directly. Link, password, and machine
+// subjects are minted by their credential workflow, so they are absent from the
+// write audiences rather than refused by a refinement after the fact.
+const publicGrantAudienceSchema = z.object({ kind: z.literal("public") }).strict();
+const teamGrantAudienceSchema = z
+    .object({ kind: z.literal("team"), teamId: grantReferenceSchema })
+    .strict();
+const personGrantAudienceSchema = z
+    .object({ kind: z.literal("person"), personId: grantReferenceSchema })
+    .strict();
+// The external-identity subject names the Team connection that authenticates
+// it; the issuer is resolved from that connection server-side, so a caller
+// never asserts one.
+const externalGrantWriteAudienceSchema = z
+    .object({
+    kind: z.literal("external"),
+    connectionId: registeredIdSchema("acn"),
+    subject: z.string().trim().min(1).max(255),
+})
+    .strict();
+const directManagedGrantAudienceSchema = z.discriminatedUnion("kind", [
+    publicGrantAudienceSchema,
+    teamGrantAudienceSchema,
+    personGrantAudienceSchema,
+]);
+export const directManagedGrantWriteSchema = grantDimensionsSchema
+    .extend({ audience: directManagedGrantAudienceSchema })
+    .superRefine(validateGrantAudienceCapabilityBoundary);
+// One create body for `POST /v1/spaces/{spaceId}/grants`: one object whose
+// `audience` is the discriminated union of every subject a manager can name.
+// Deliberately NOT a union of two whole bodies — a top-level union collapses
+// every structural failure into one issue with an empty path, and the problem
+// document loses its RFC 6901 `pointer`.
+const managedGrantWriteAudienceSchema = z.discriminatedUnion("kind", [
+    publicGrantAudienceSchema,
+    teamGrantAudienceSchema,
+    personGrantAudienceSchema,
+    externalGrantWriteAudienceSchema,
+]);
+export const spaceGrantCreateSchema = grantDimensionsSchema
+    .extend({ audience: managedGrantWriteAudienceSchema })
+    .superRefine((value, context) => {
+    validateGrantAudienceCapabilityBoundary(value, context);
+    // An opaque external subject is unreadable in the Grant list without one.
+    if (value.audience.kind === "external" && value.name === undefined) {
         context.addIssue({
             code: "custom",
-            path: ["audience", "kind"],
-            message: "direct managed Grants support only public, team, and person audiences; credential-backed audiences use their dedicated workflow",
+            path: ["name"],
+            message: "an external identity Grant needs a name; its subject is opaque",
         });
     }
 });
@@ -510,20 +553,85 @@ export const spaceGrantSchema = z
     updatedAt: z.string().datetime(),
 })
     .strict();
+// The whole query describes one hypothetical visit: who is knocking, at which
+// URL, on which deployment. Each field is documented because this operation is
+// the explainer an agent reaches for when access is refused and it needs to
+// know why.
 export const grantCheckQuerySchema = z
     .object({
-    path: z.string().min(1).max(2048).default("/"),
-    target: z.enum(["live", "version", "branch"]).default("live"),
-    targetId: z.string().trim().min(1).max(255).optional(),
-    audience: grantAudienceKindSchema.default("public"),
-    personId: z.string().trim().min(1).max(255).optional(),
-    linkId: z.string().trim().min(1).max(255).optional(),
-    passwordCredentialId: z.string().trim().min(1).max(255).optional(),
-    machineId: z.string().trim().min(1).max(255).optional(),
-    issuer: z.string().trim().min(1).max(255).optional(),
-    subject: z.string().trim().min(1).max(255).optional(),
-    verifiedEmail: z.enum(["true", "false"]).optional(),
-    ipAddress: z.string().trim().min(1).max(64).optional(),
+    path: z
+        .string()
+        .min(1)
+        .max(2048)
+        .default("/")
+        .describe("Request path to simulate, for example `/admin`."),
+    target: z
+        .enum(["live", "version", "branch"])
+        .default("live")
+        .describe("Which deployment the visit lands on: the live channel, one version, or a branch."),
+    targetId: z
+        .string()
+        .trim()
+        .min(1)
+        .max(255)
+        .optional()
+        .describe("The version id or branch name named by `target`. Required for `version` and `branch`, and rejected for `live`."),
+    audience: grantAudienceKindSchema
+        .default("public")
+        .describe("Who is knocking. Each audience needs its own identifying parameter below, and rejects the others."),
+    personId: z
+        .string()
+        .trim()
+        .min(1)
+        .max(255)
+        .optional()
+        .describe("The person to simulate. Required with `audience=person`."),
+    linkId: z
+        .string()
+        .trim()
+        .min(1)
+        .max(255)
+        .optional()
+        .describe("The share link to simulate. Required with `audience=link`."),
+    passwordCredentialId: z
+        .string()
+        .trim()
+        .min(1)
+        .max(255)
+        .optional()
+        .describe("The password credential to simulate. Required with `audience=password`."),
+    machineId: z
+        .string()
+        .trim()
+        .min(1)
+        .max(255)
+        .optional()
+        .describe("The machine credential to simulate. Required with `audience=machine`."),
+    issuer: z
+        .string()
+        .trim()
+        .min(1)
+        .max(255)
+        .optional()
+        .describe("Identity connection issuer for the external identity to simulate. Required with `audience=external`."),
+    subject: z
+        .string()
+        .trim()
+        .min(1)
+        .max(255)
+        .optional()
+        .describe("Subject claim of the external identity to simulate. Required with `audience=external`."),
+    verifiedEmail: z
+        .enum(["true", "false"])
+        .optional()
+        .describe("Whether the simulated visitor's email counts as verified."),
+    ipAddress: z
+        .string()
+        .trim()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe("Client IP to evaluate network constraints against."),
 })
     .strict()
     .superRefine((value, context) => {
@@ -783,10 +891,3 @@ export const identityConnectionSchema = z
     revokedAt: z.string().datetime().nullable(),
 })
     .strict();
-export const externalGrantCreateSchema = z
-    .object({
-    connectionId: registeredIdSchema("acn"),
-    subject: z.string().min(1).max(255),
-    ...credentialGrantFields,
-})
-    .strict();

package/dist/contracts/ids.d.ts

@@ -22,7 +22,7 @@ export declare const ID_PREFIXES: {
     readonly ntf: "Notification";
     readonly pvc: "ProviderClient";
     readonly tgs: "TagSet";
-    readonly tgv: "TagVersion";
+    readonly tgv: "TagRevision";
     readonly tgr: "TagRelease";
     readonly tga: "TagRuntimeArtifact";
     readonly tgp: "TagPreviewSession";
@@ -34,6 +34,9 @@ export declare const ID_PREFIXES: {
     readonly acn: "IdentityConnection";
     readonly pwd: "SpacePasswordCredential";
     readonly mch: "SpaceMachineCredential";
+    readonly pti: "PartnerTokenIssuer";
+    readonly usg: "UsageRecord";
+    readonly upr: "UsagePeriod";
 };
 export type IdPrefix = keyof typeof ID_PREFIXES;
 /** Any registered public resource id, e.g. `spc_…` or `ver_…`. */

package/dist/contracts/ids.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-// Id prefix registry (internal-docs/platform.md "Id prefix registry", L1106-1127).
+// Id prefix registry (the platform spec "Id prefix registry").
 // Every PUBLIC resource registers a prefix here before it ships; ids are globally
 // unique and handle ids (operations, exports, imports, transfers, builds) are
 // fetchable at a top-level collection with no extra context. Control-plane-internal
@@ -29,7 +29,7 @@ export const ID_PREFIXES = {
     ntf: "Notification",
     pvc: "ProviderClient",
     tgs: "TagSet",
-    tgv: "TagVersion",
+    tgv: "TagRevision",
     tgr: "TagRelease",
     tga: "TagRuntimeArtifact",
     tgp: "TagPreviewSession",
@@ -42,6 +42,9 @@ export const ID_PREFIXES = {
     acn: "IdentityConnection",
     pwd: "SpacePasswordCredential",
     mch: "SpaceMachineCredential",
+    pti: "PartnerTokenIssuer",
+    usg: "UsageRecord",
+    upr: "UsagePeriod",
 };
 /** Validate an id belonging to one registered public resource family. */
 export function registeredIdSchema(prefix) {
@@ -49,7 +52,7 @@ export function registeredIdSchema(prefix) {
 }
 // The main Stattic tenant every self-serve team/user/resource lives under. A
 // well-known CONSTANT, never configuration: grammatically a normal tenant id with
-// zero special cases in contracts, policy URIs, or parsers (spec L1100-1105).
+// zero special cases in contracts, policy URIs, or parsers (per the platform spec).
 export const MAIN_TENANT_ID = "ten_main";
 /** Mint a globally unique id for a registered public resource prefix. */
 export function createId(prefix) {

package/dist/contracts/internal.d.ts

@@ -1,9 +1,4 @@
 import { z } from "zod";
-export declare const conventionFilesSchema: z.ZodObject<{
-    redirects: z.ZodOptional<z.ZodString>;
-    headers: z.ZodOptional<z.ZodString>;
-    routes: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
 export declare const manifestFileSchema: z.ZodObject<{
     path: z.ZodString;
     size: z.ZodNumber;
@@ -11,24 +6,18 @@ export declare const manifestFileSchema: z.ZodObject<{
     contentType: z.ZodOptional<z.ZodString>;
     sourceUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export declare const uploadManifestFileSchema: z.ZodUnion<readonly [z.ZodObject<{
-    path: z.ZodString;
-    size: z.ZodNumber;
-    contentType: z.ZodOptional<z.ZodString>;
-    sourceUrl: z.ZodOptional<z.ZodString>;
-    sha256: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
+export declare const uploadManifestFileSchema: z.ZodObject<{
     path: z.ZodString;
     size: z.ZodNumber;
     sha256: z.ZodOptional<z.ZodString>;
     contentType: z.ZodOptional<z.ZodString>;
-    sourceUrl: z.ZodString;
-}, z.core.$strip>]>;
+    sourceUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export declare const pendingUploadSchema: z.ZodObject<{
     path: z.ZodString;
-    size: z.ZodNumber;
-    sha256: z.ZodOptional<z.ZodString>;
     sourceUrl: z.ZodOptional<z.ZodString>;
+    sha256: z.ZodOptional<z.ZodString>;
+    size: z.ZodNumber;
 }, z.core.$strip>;
 export declare const uploadSessionModeSchema: z.ZodEnum<{
     source: "source";
@@ -81,7 +70,8 @@ export declare const uploadInstructionsSchema: z.ZodObject<{
         contentType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     links: z.ZodObject<{
-        resume: z.ZodString;
+        refresh: z.ZodString;
+        resume: z.ZodOptional<z.ZodString>;
         finalize: z.ZodString;
     }, z.core.$strip>;
     details: z.ZodOptional<z.ZodObject<{
@@ -104,7 +94,7 @@ export declare const uploadInstructionsSchema: z.ZodObject<{
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                 registrar: "registrar";
-                wpcloud: "wpcloud";
+                infra: "infra";
                 dns: "dns";
                 runtime: "runtime";
             }>>>;