@spacefast/common 0.0.26 → 0.2.1

package/dist/contracts/tags.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
+import { normalizeSlug } from "../utils/slug.js";
 import { baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema, dataEnvelope, } from "./common.js";
-export const tagVersionStatusSchema = z.enum([
+export const tagRevisionStatusSchema = z.enum([
     "draft",
     "in_review",
     "approved",
@@ -21,6 +22,10 @@ export const TAG_PRIVACY_SIGNAL_CONSENT_CATEGORIES = [
     "marketing",
     "personalization",
 ];
+// `defaultGranted` is the non-GDPR default. `requiresConsentInGdprCountries`
+// mirrors wpcom's per-tracker flag of the same name: inside the GDPR zone the
+// category is denied until the visitor explicitly grants it, and the zone check
+// fails closed on unknown geo (see `isGdprCountry` in utils/privacy-regions).
 export const TAG_CONSENT_CATEGORY_DEFINITIONS = [
     {
         id: "necessary",
@@ -29,6 +34,7 @@ export const TAG_CONSENT_CATEGORY_DEFINITIONS = [
         defaultGranted: true,
         required: true,
         privacySignalDefaultDenied: false,
+        requiresConsentInGdprCountries: false,
     },
     {
         id: "functional",
@@ -37,6 +43,7 @@ export const TAG_CONSENT_CATEGORY_DEFINITIONS = [
         defaultGranted: true,
         required: false,
         privacySignalDefaultDenied: false,
+        requiresConsentInGdprCountries: false,
     },
     {
         id: "analytics",
@@ -45,6 +52,7 @@ export const TAG_CONSENT_CATEGORY_DEFINITIONS = [
         defaultGranted: true,
         required: false,
         privacySignalDefaultDenied: true,
+        requiresConsentInGdprCountries: true,
     },
     {
         id: "marketing",
@@ -53,6 +61,7 @@ export const TAG_CONSENT_CATEGORY_DEFINITIONS = [
         defaultGranted: true,
         required: false,
         privacySignalDefaultDenied: true,
+        requiresConsentInGdprCountries: true,
     },
     {
         id: "personalization",
@@ -61,6 +70,7 @@ export const TAG_CONSENT_CATEGORY_DEFINITIONS = [
         defaultGranted: true,
         required: false,
         privacySignalDefaultDenied: true,
+        requiresConsentInGdprCountries: true,
     },
 ];
 export const TAG_CONSENT_CATEGORY_IDS = TAG_CONSENT_CATEGORY_DEFINITIONS.map((category) => category.id);
@@ -75,6 +85,7 @@ export const tagConsentPolicySchema = z.object({
         defaultGranted: z.boolean(),
         required: z.boolean().default(false),
         privacySignalDefaultDenied: z.boolean().default(false),
+        requiresConsentInGdprCountries: z.boolean().default(false),
     }))
         .default(Object.fromEntries(TAG_CONSENT_CATEGORY_DEFINITIONS.map((category) => [
         category.id,
@@ -84,6 +95,7 @@ export const tagConsentPolicySchema = z.object({
             defaultGranted: category.defaultGranted,
             required: category.required,
             privacySignalDefaultDenied: category.privacySignalDefaultDenied,
+            requiresConsentInGdprCountries: category.requiresConsentInGdprCountries,
         },
     ]))),
     defaultByCategory: z.record(z.string(), z.boolean()).default(DEFAULT_TAG_CONSENT_DEFAULTS),
@@ -371,12 +383,12 @@ export const tagValidationResultSchema = z.object({
     requiredApprovals: z.array(z.string()),
     graphRevision: z.number().int().positive(),
 });
-export const tagVersionSchema = z.object({
+export const tagRevisionSchema = z.object({
     id: z.string(),
     tagSetId: z.string(),
-    versionNumber: z.number().int().positive(),
-    baseVersionId: z.string().nullable(),
-    status: tagVersionStatusSchema,
+    revisionNumber: z.number().int().positive(),
+    baseRevisionId: z.string().nullable(),
+    status: tagRevisionStatusSchema,
     title: z.string(),
     description: z.string().nullable(),
     graph: tagGraphSchema,
@@ -391,26 +403,28 @@ export const tagVersionSchema = z.object({
     publishedAt: z.string().nullable(),
     immutableAt: z.string().nullable(),
 });
-export const tagVersionListQuerySchema = cursorListQuerySchema.extend({
-    status: tagVersionStatusSchema.optional(),
+export const tagRevisionListQuerySchema = cursorListQuerySchema.extend({
+    status: tagRevisionStatusSchema
+        .optional()
+        .describe("Return only revisions in this review state."),
 });
-export const tagVersionListResponseSchema = z.object({
-    data: z.array(tagVersionSchema),
+export const tagRevisionListResponseSchema = z.object({
+    data: z.array(tagRevisionSchema),
     pagination: CursorPaginationSchema,
 });
-export const tagVersionResponseSchema = dataEnvelope(tagVersionSchema);
-export const tagVersionCreateSchema = z.object({
-    title: z.string().trim().min(1).max(255).default("Draft tag version"),
+export const tagRevisionResponseSchema = dataEnvelope(tagRevisionSchema);
+export const tagRevisionCreateSchema = z.object({
+    title: z.string().trim().min(1).max(255).default("Draft tag revision"),
     description: z.string().trim().max(4_000).nullable().optional(),
-    baseVersionId: z.string().trim().min(1).nullable().optional(),
+    baseRevisionId: z.string().trim().min(1).nullable().optional(),
     graph: tagGraphWriteSchema.optional(),
 });
-export const tagVersionPatchSchema = z.object({
+export const tagRevisionPatchSchema = z.object({
     title: z.string().trim().min(1).max(255).optional(),
     description: z.string().trim().max(4_000).nullable().optional(),
 });
 export const tagGraphResponseSchema = dataEnvelope(z.object({
-    versionId: z.string(),
+    revisionId: z.string(),
     graph: tagGraphSchema,
     graphRevision: z.number().int().positive(),
 }));
@@ -429,8 +443,8 @@ export const tagGraphPatchSchema = z.object({
 });
 export const tagValidateResponseSchema = dataEnvelope(tagValidationResultSchema);
 export const tagDiffSchema = z.object({
-    baseVersionId: z.string().nullable(),
-    targetVersionId: z.string(),
+    baseRevisionId: z.string().nullable(),
+    targetRevisionId: z.string(),
     addedTagIds: z.array(z.string()),
     removedTagIds: z.array(z.string()),
     changedTagIds: z.array(z.string()),
@@ -441,8 +455,8 @@ export const tagReleaseSchema = z.object({
     id: z.string(),
     tagSetId: z.string(),
     environment: tagEnvironmentSchema,
-    versionId: z.string(),
-    previousVersionId: z.string().nullable(),
+    revisionId: z.string(),
+    previousRevisionId: z.string().nullable(),
     sdkRevision: z.string(),
     staticDigest: z.string(),
     releaseNotes: z.string().nullable(),
@@ -483,7 +497,7 @@ export const tagInheritancePatchSchema = z.object({
 export const tagActivityEventSchema = z.object({
     id: z.string(),
     type: z.string(),
-    versionId: z.string().nullable(),
+    revisionId: z.string().nullable(),
     environment: tagEnvironmentSchema.nullable(),
     message: z.string(),
     actor: z.record(z.string(), z.unknown()).nullable(),
@@ -496,8 +510,8 @@ export const tagEffectiveTagResponseSchema = dataEnvelope(z.object({
     source: z.enum(["system", "team", "space", "unknown"]),
 }));
 export const tagReleasePutSchema = z.object({
-    versionId: z.string().trim().min(1),
-    expectedCurrentVersionId: z.string().trim().min(1).nullable().optional(),
+    revisionId: z.string().trim().min(1),
+    expectedCurrentRevisionId: z.string().trim().min(1).nullable().optional(),
     releaseNotes: z.string().trim().max(4_000).nullable().optional(),
 });
 export const tagApplySchema = z.object({
@@ -506,10 +520,10 @@ export const tagApplySchema = z.object({
     description: z.string().trim().max(4_000).nullable().optional(),
     submit: z.boolean().default(false),
     releaseEnvironment: tagEnvironmentSchema.optional(),
-    expectedCurrentVersionId: z.string().trim().min(1).nullable().optional(),
+    expectedCurrentRevisionId: z.string().trim().min(1).nullable().optional(),
 });
 export const tagApplyResponseSchema = dataEnvelope(z.object({
-    version: tagVersionSchema,
+    revision: tagRevisionSchema,
     validation: tagValidationResultSchema,
     release: tagReleaseSchema
         .extend({
@@ -525,7 +539,7 @@ export const tagApplyResponseSchema = dataEnvelope(z.object({
 }));
 export const tagPreviewSessionSchema = z.object({
     id: z.string(),
-    versionId: z.string(),
+    revisionId: z.string(),
     environment: tagEnvironmentSchema,
     previewUrl: z.string(),
     sdkRevision: z.string(),
@@ -536,6 +550,7 @@ export const tagPreviewSessionSchema = z.object({
     revokedAt: z.string().nullable(),
 });
 export const tagPreviewSessionResponseSchema = dataEnvelope(tagPreviewSessionSchema);
+export const tagPreviewSessionListResponseSchema = dataEnvelope(z.array(tagPreviewSessionSchema));
 export const tagPreviewSessionCreateSchema = z.object({
     url: z.string().url().optional(),
     ttlSeconds: z.number().int().min(60).max(86_400).default(3_600),
@@ -658,7 +673,7 @@ export const tagTemplateListResponseSchema = dataEnvelope(z.object({
 }));
 export const tagConsentPolicyResponseSchema = dataEnvelope(z.object({
     environment: tagEnvironmentSchema,
-    versionId: z.string().nullable(),
+    revisionId: z.string().nullable(),
     graphRevision: z.number().int().nonnegative(),
     policy: tagConsentPolicySchema,
 }));
@@ -883,12 +898,7 @@ function templateFieldValue(config, key) {
     return typeof value === "string" ? value.trim() : "";
 }
 export function safeTagIdPart(value) {
-    return value
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 64);
+    return normalizeSlug(value, { maxLength: 64 });
 }
 function htmlScript(code) {
     return /^\s*<script\b[^>]*>[\s\S]*<\/script>\s*$/i.test(code)
@@ -1224,12 +1234,12 @@ export function tagGraphFromTemplateSelections(selections) {
 export const tagEffectiveResponseSchema = dataEnvelope(z.object({
     tagSetId: z.string().nullable(),
     environment: tagEnvironmentSchema,
-    versionId: z.string().nullable(),
+    revisionId: z.string().nullable(),
     graph: tagGraphSchema,
     graphRevision: z.number().int().nonnegative(),
     sdkRevision: z.string().nullable(),
     sources: z.array(z.object({
         type: z.enum(["team", "space", "system"]),
-        versionId: z.string().nullable(),
+        revisionId: z.string().nullable(),
     })),
 }));

package/dist/contracts/teams.d.ts

@@ -6,12 +6,12 @@ export declare const teamMemberRole: z.ZodEnum<{
     member: "member";
 }>;
 /**
- * Better Auth stores the member role as free text, so every surface that reads
- * it back has to land on the same canonical value. Unknown roles carry no
- * privilege, so they read as the least-privileged one.
+ * Better Auth stores the member role as free text. Unknown roles carry no
+ * privilege, so they read as `member`.
  */
 export declare function normalizeTeamMemberRole(role: string | null | undefined): "admin" | "owner" | "member";
 export declare const teamInvitationCreateSchema: z.ZodObject<{
+    teamId: z.ZodString;
     email: z.ZodString;
     role: z.ZodDefault<z.ZodEnum<{
         admin: "admin";
@@ -26,6 +26,7 @@ export declare const teamMemberListQuerySchema: z.ZodObject<{
 export declare const teamInvitationListQuerySchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cursor: z.ZodOptional<z.ZodString>;
+    teamId: z.ZodString;
 }, z.core.$strip>;
 export declare const teamListQuerySchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -66,6 +67,28 @@ export declare const teamMemberRoleUpdateSchema: z.ZodObject<{
     }>;
 }, z.core.$strip>;
 export type TeamMember = z.infer<typeof TeamMemberSchema>;
+/**
+ * The one invitation status vocabulary, shared by the collection and the by-id
+ * read. Better Auth's organization plugin owns the stored column and writes
+ * `pending | accepted | rejected | canceled`; `expired` is derived, because a
+ * still-pending invitation past `expiresAt` can never be accepted and no writer
+ * ever rewrites the row.
+ */
+export declare const teamInvitationStatus: z.ZodEnum<{
+    canceled: "canceled";
+    expired: "expired";
+    pending: "pending";
+    accepted: "accepted";
+    rejected: "rejected";
+}>;
+export type TeamInvitationStatus = z.infer<typeof teamInvitationStatus>;
+/**
+ * The stored column is free text over a closed domain. An unrecognized value is
+ * not something a recipient may act on, so it fails closed to `canceled` —
+ * never `pending` (which would offer a dead link) and never `accepted` (which
+ * would claim a membership nobody holds).
+ */
+export declare function normalizeTeamInvitationStatus(status: string | null | undefined): "canceled" | "expired" | "pending" | "accepted" | "rejected";
 export declare const TeamInvitationSchema: z.ZodObject<{
     id: z.ZodString;
     teamId: z.ZodString;
@@ -75,7 +98,13 @@ export declare const TeamInvitationSchema: z.ZodObject<{
         owner: "owner";
         member: "member";
     }>;
-    status: z.ZodString;
+    status: z.ZodEnum<{
+        canceled: "canceled";
+        expired: "expired";
+        pending: "pending";
+        accepted: "accepted";
+        rejected: "rejected";
+    }>;
     expiresAt: z.ZodString;
     createdAt: z.ZodString;
 }, z.core.$strip>;
@@ -131,6 +160,30 @@ export declare const TeamDetailSchema: z.ZodObject<{
     logo: z.ZodNullable<z.ZodString>;
     metadata: z.ZodNullable<z.ZodString>;
     stripeCustomerId: z.ZodNullable<z.ZodString>;
+    systemSpaceId: z.ZodNullable<z.ZodString>;
+    manifestStatus: z.ZodObject<{
+        items: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            state: z.ZodEnum<{
+                active: "active";
+                failed: "failed";
+                pending: "pending";
+            }>;
+            detail: z.ZodOptional<z.ZodString>;
+            since: z.ZodString;
+            audience: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        sourceVersionId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    presentation: z.ZodNullable<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        logo: z.ZodOptional<z.ZodString>;
+        supportUrl: z.ZodOptional<z.ZodString>;
+        claimOrigin: z.ZodOptional<z.ZodString>;
+        accessHandoffOrigin: z.ZodOptional<z.ZodString>;
+        problemDocsBaseUrl: z.ZodOptional<z.ZodString>;
+        contacts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const teamListResponseSchema: z.ZodObject<{
     data: z.ZodArray<z.ZodObject<{
@@ -189,7 +242,7 @@ export declare const teamJoinResponseSchema: z.ZodObject<{
         role: z.ZodLiteral<"member">;
     }, z.core.$strip>;
 }, z.core.$strip>;
-export declare const teamInvitationAcceptSchema: z.ZodObject<{
+export declare const teamInvitationParamsSchema: z.ZodObject<{
     invitationId: z.ZodString;
 }, z.core.$strip>;
 export declare const teamInvitationAcceptResponseSchema: z.ZodObject<{
@@ -214,7 +267,13 @@ export declare const teamInvitationListResponseSchema: z.ZodObject<{
             owner: "owner";
             member: "member";
         }>;
-        status: z.ZodString;
+        status: z.ZodEnum<{
+            canceled: "canceled";
+            expired: "expired";
+            pending: "pending";
+            accepted: "accepted";
+            rejected: "rejected";
+        }>;
         expiresAt: z.ZodString;
         createdAt: z.ZodString;
     }, z.core.$strip>>;
@@ -263,14 +322,16 @@ export declare const teamUsageResponseSchema: z.ZodObject<{
         storageBytes: z.ZodNumber;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export declare const teamInvitationPreviewSchema: z.ZodObject<{
+export declare const teamInvitationDetailSchema: z.ZodObject<{
     id: z.ZodString;
     teamName: z.ZodString;
-    invitedEmail: z.ZodString;
+    email: z.ZodString;
     status: z.ZodEnum<{
+        canceled: "canceled";
         expired: "expired";
-        closed: "closed";
         pending: "pending";
+        accepted: "accepted";
+        rejected: "rejected";
     }>;
     expiresAt: z.ZodString;
 }, z.core.$strip>;
@@ -284,4 +345,6 @@ export declare const teamUpdateSchema: z.ZodObject<{
     logo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     metadata: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     defaultDataLocation: z.ZodOptional<z.ZodString>;
+    systemSpaceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    baseSystemSpaceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;

package/dist/contracts/teams.js

@@ -1,23 +1,30 @@
 import { z } from "zod";
 import { CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
 import { planCodeSchema, planLimitValueSchema } from "./features.js";
+import { systemPresentationSchema } from "./space-config.js";
+import { ManifestStatusSchema } from "./tenants.js";
 export const TEAM_ROLE_VALUES = ["owner", "admin", "member"];
 export const teamMemberRole = z.enum(TEAM_ROLE_VALUES);
 /**
- * Better Auth stores the member role as free text, so every surface that reads
- * it back has to land on the same canonical value. Unknown roles carry no
- * privilege, so they read as the least-privileged one.
+ * Better Auth stores the member role as free text. Unknown roles carry no
+ * privilege, so they read as `member`.
  */
 export function normalizeTeamMemberRole(role) {
     const parsed = teamMemberRole.safeParse(role ?? "member");
     return parsed.success ? parsed.data : "member";
 }
+// An invitation is its own resource under `/v1/team-invitations`, so the team
+// it belongs to travels in the body (create) or the query (list) instead of a
+// path segment.
 export const teamInvitationCreateSchema = z.object({
+    teamId: z.string().trim().min(1).describe("The team to invite this person to."),
     email: z.string().trim().email().toLowerCase(),
     role: teamMemberRole.default("member"),
 });
 export const teamMemberListQuerySchema = cursorListQuerySchema;
-export const teamInvitationListQuerySchema = cursorListQuerySchema;
+export const teamInvitationListQuerySchema = cursorListQuerySchema.extend({
+    teamId: z.string().trim().min(1).describe("The team whose invitations to list."),
+});
 export const teamListQuerySchema = cursorListQuerySchema;
 export const teamSpaceListQuerySchema = cursorListQuerySchema;
 export const TeamMemberUserSchema = z.object({
@@ -26,10 +33,9 @@ export const TeamMemberUserSchema = z.object({
     email: z.string().email().describe("The member's email address."),
     image: z.string().nullable().describe("Avatar URL, or null when the user has none."),
 });
-// The one membership shape: every surface that shows or edits a team member
-// (dashboard, superadmin, CLI, MCP) types from this. Better Auth's
-// organization plugin owns the underlying rows, but its plugin-inferred types
-// never cross an app boundary.
+// The one membership shape every surface types from. Better Auth's organization
+// plugin owns the underlying rows; its inferred types never cross an app
+// boundary.
 export const TeamMemberSchema = z.object({
     id: z.string().describe("The membership id, stable for the life of the membership."),
     teamId: z.string().describe("The team this membership belongs to."),
@@ -41,12 +47,36 @@ export const TeamMemberSchema = z.object({
 export const teamMemberRoleUpdateSchema = z.object({
     role: teamMemberRole.describe("The role to grant this member."),
 });
+/**
+ * The one invitation status vocabulary, shared by the collection and the by-id
+ * read. Better Auth's organization plugin owns the stored column and writes
+ * `pending | accepted | rejected | canceled`; `expired` is derived, because a
+ * still-pending invitation past `expiresAt` can never be accepted and no writer
+ * ever rewrites the row.
+ */
+export const teamInvitationStatus = z.enum([
+    "pending",
+    "accepted",
+    "rejected",
+    "canceled",
+    "expired",
+]);
+/**
+ * The stored column is free text over a closed domain. An unrecognized value is
+ * not something a recipient may act on, so it fails closed to `canceled` —
+ * never `pending` (which would offer a dead link) and never `accepted` (which
+ * would claim a membership nobody holds).
+ */
+export function normalizeTeamInvitationStatus(status) {
+    const parsed = teamInvitationStatus.safeParse(status);
+    return parsed.success ? parsed.data : "canceled";
+}
 export const TeamInvitationSchema = z.object({
     id: z.string(),
     teamId: z.string(),
     email: z.string().email(),
     role: teamMemberRole,
-    status: z.string(),
+    status: teamInvitationStatus,
     expiresAt: z.string().datetime(),
     createdAt: z.string().datetime(),
 });
@@ -73,6 +103,14 @@ export const TeamDetailSchema = TeamSummarySchema.extend({
         .string()
         .nullable()
         .describe("Stripe customer id linked to this team; null until billing is initialized."),
+    systemSpaceId: z
+        .string()
+        .nullable()
+        .describe("The space that supplies this team's page, theme, and presentation defaults."),
+    manifestStatus: ManifestStatusSchema.describe("The status of the restricted manifest from the team's system space."),
+    presentation: systemPresentationSchema
+        .nullable()
+        .describe("The presentation from the team's system space, or null when no value is active."),
 });
 export const teamListResponseSchema = z.object({
     data: z.array(TeamSummarySchema),
@@ -89,14 +127,14 @@ export const teamJoinResponseSchema = z.object({
         role: z.literal("member"),
     }),
 });
-// Accepting an invitation is by its id (the opaque token carried in the accept
-// email link and returned by the invitations list/preview endpoints).
-export const teamInvitationAcceptSchema = z.object({
+// Every by-id invitation door — read, accept, resend, revoke — is addressed by
+// the opaque token carried in the invite link.
+export const teamInvitationParamsSchema = z.object({
     invitationId: z
         .string()
         .trim()
         .min(1)
-        .describe("The invitation id to accept (the token from the invite link)."),
+        .describe("The invitation id (the token from the invite link)."),
 });
 export const teamInvitationAcceptResponseSchema = z.object({
     data: z.object({
@@ -112,8 +150,7 @@ export const teamInvitationListResponseSchema = z.object({
 });
 // Team activity is served by `GET /v1/teams/{teamId}/activity`, a facade over
 // the one activity store using the ActivityEvent contract (contracts/activity.ts).
-// `defaultDataLocation` is the spec Team field: "auto" lets placement decide,
-// any other value must be an available placement region id.
+// Any value other than "auto" must be an available placement region id.
 export const teamDataLocationSchema = z
     .string()
     .trim()
@@ -127,8 +164,7 @@ const infraCapabilityOptionSchema = z.object({
     id: z.string(),
     label: z.string(),
 });
-// Served by `GET /v1/teams/{teamId}/settings` (and echoed by the PATCH):
-// the default data location plus the placement options it may take.
+// Served by `GET /v1/teams/{teamId}/settings`, and echoed by the PATCH.
 export const teamSettingsResponseSchema = z.object({
     teamId: z.string().describe("The team id the settings belong to."),
     defaultDataLocation: teamDataLocationSchema,
@@ -153,7 +189,7 @@ export const teamUsageResponseSchema = z.object({
         members: z.number().int().describe("Team members."),
         storageBytes: z
             .number()
-            .describe("Disk actually occupied across the team's spaces, as measured by the serving infrastructure. Nothing is deduplicated: a file present in two spaces sits on two disks and counts twice."),
+            .describe("Disk occupied across the team's spaces, as measured by the serving infrastructure. Nothing is deduplicated: a file present in two spaces sits on two disks and counts twice."),
         storageQuotaBytes: z
             .union([z.number(), z.literal("unlimited")])
             .describe('Plan storage quota; "unlimited" when unbounded.'),
@@ -161,7 +197,7 @@ export const teamUsageResponseSchema = z.object({
         storageCalculatedAt: z
             .string()
             .nullable()
-            .describe("How far back the weakest measurement behind this total reaches. Null when the team's storage has not been measured yet. This is a lagging meter — expect it to trail the present by about an hour."),
+            .describe("How far back the weakest measurement behind this total reaches. Null when the team's storage has not been measured yet. The meter lags the present by about an hour."),
         buildsDeploysThisMonth: z
             .number()
             .int()
@@ -180,17 +216,21 @@ export const teamUsageResponseSchema = z.object({
         title: z.string().describe("Space display title."),
         storageBytes: z
             .number()
-            .describe("Disk this space occupies, as measured by the infrastructure serving it. Zero for a space that has not been measured yet."),
+            .describe("Disk this space occupies, as measured by the infrastructure serving it. Zero until the space has been measured."),
     }))
         .describe("Per-space storage breakdown for spaces the caller can read."),
 });
-// Served by `GET /v1/teams/invitations/{invitationId}/preview`: the unauthenticated
-// invite landing view (email is masked, never the full address).
-export const teamInvitationPreviewSchema = z.object({
+// Served by `GET /v1/team-invitations/{invitationId}`: the unauthenticated
+// invite landing view. Same field names and same status vocabulary as the
+// collection item; the address is masked and the team name is carried so the
+// page can render before sign-in.
+export const teamInvitationDetailSchema = z.object({
     id: z.string().describe("Invitation id."),
     teamName: z.string().describe("Inviting team's display name."),
-    invitedEmail: z.string().describe("Masked invited email address."),
-    status: z.enum(["pending", "expired", "closed"]).describe("Whether the invite can be accepted."),
+    email: z
+        .string()
+        .describe("The invited address, masked (`ja****@example.com`); never the full address."),
+    status: teamInvitationStatus.describe("Current state of the invitation. Only `pending` can be accepted."),
     expiresAt: z.string().describe("Instant when the invitation expires."),
 });
 export const teamCreateSchema = z.object({
@@ -219,6 +259,25 @@ export const teamUpdateSchema = z
     logo: z.string().trim().max(2048).nullable().optional(),
     metadata: z.string().nullable().optional(),
     defaultDataLocation: teamDataLocationSchema.optional(),
+    systemSpaceId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Set the team's system space. Use null to clear the current system space."),
+    baseSystemSpaceId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("The current system-space id that the caller expects. The update fails if this value is stale."),
+})
+    .superRefine((value, ctx) => {
+    if (value.baseSystemSpaceId !== undefined && value.systemSpaceId === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            message: "baseSystemSpaceId requires systemSpaceId.",
+            path: ["baseSystemSpaceId"],
+        });
+    }
 })
     .refine((value) => Object.keys(value).length > 0, {
     message: "At least one team field is required.",