@spacefast/common 0.0.23 → 0.0.24

package/dist/contracts/spaces.js

@@ -1,23 +1,65 @@
 import { z } from "zod";
 import { SPACE_SLUG_MAX_LENGTH } from "../slug-policy/index.js";
+import { normalizeVersionPath } from "../utils/version-path.js";
 import { publishedAccessSchema } from "./access.js";
 import { AsyncOperationSchema, baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema, } from "./common.js";
 import { versionStatus, spaceStatus } from "./enums.js";
-import { runtimeKindSchema } from "./execution.js";
-import { conventionFilesSchema, uploadInstructionsSchema, manifestFileSchema } from "./internal.js";
+import { conventionFilesSchema, uploadInstructionsSchema, manifestFileSchema, uploadManifestFileSchema, } from "./internal.js";
 import { VersionSchema, PublishSourceSchema, SpaceSchema, spaceSettingsDigestSchema, } from "./resources.js";
 import { runtimeAppSchema } from "./runtime-app.js";
 import { SPACE_CONFIG_ACCEPTED_FILES, spaceConfigSchema, spacePlacementConfigSchema, } from "./space-config.js";
 import { principalIdSchema } from "./transfers.js";
+// Capacity accounting for the provider site a space runs on. A space IS a
+// site, so occupancy is not a question — storage is. Warm-pool inventory rows
+// carry the same shape before a space adopts them.
+export const SpaceCapacitySchema = z
+    .object({
+    storageBytes: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Storage budget for the space in bytes."),
+})
+    .describe("Capacity accounting for a space's provider site.");
+export const SpacePressureSchema = z
+    .object({
+    ewmaLimitedPct: z.number().nonnegative().optional(),
+    ewma429: z.number().nonnegative().optional(),
+    ewma429PerMin: z.number().nonnegative().optional(),
+    ewmaWorkersMax: z.number().nonnegative().optional(),
+    ewmaCpuPct: z.number().nonnegative().optional(),
+    lastSampleAt: z.string().datetime().optional(),
+    consecutivePressured: z.number().int().nonnegative().optional(),
+    consecutiveClean: z.number().int().nonnegative().optional(),
+    // Monotonic CAS token shared by explicit operator hold actions and the
+    // pressure sampler. Every durable hold transition advances it, including
+    // transitions that restore a prior timestamp.
+    placementHoldRevision: z.number().int().nonnegative().optional(),
+    // Provenance stamp for the sampler's automatic hold: set on trip to the
+    // exact hold instant it wrote, so release only clears holds the pressure
+    // pipeline itself set — never an operator-set placement hold.
+    pressureHoldUntil: z.string().datetime().optional(),
+    // Last time a bulk-lane engine job on this space reported activity via the
+    // job callbacks (runtime/callback-events.ts); the sampler discounts the
+    // CPU signal while this is within the sampling window.
+    lastBulkLaneActivityAt: z.string().datetime().optional(),
+})
+    .passthrough()
+    .describe("Placement pressure signals computed outside the request path.");
 export const spaceClaimReceiptSchema = z.object({
-    token: z
+    key: z
         .string()
         .min(1)
-        .describe("One-time, space-scoped credential returned only at anonymous space creation. Save it immediately. The server never shows it again. You need it to publish and manage the space until the space is claimed."),
+        .describe("The space key (sfc_…): the one credential for this unclaimed space. Bearer auth for publish, update, status, sharing, rotation, and the one-time continuation exchange. Returned only at creation and rotation; save it immediately."),
     url: z
         .string()
         .url()
-        .describe("Browser-only claim link with a short-lived, one-use path token. The access origin consumes it into an HttpOnly handoff, then redirects to a clean claim page. API clients use the separate claim token as bearer auth for publish, update, status, and exchange."),
+        .describe("The site door: the live URL with the space key in /__/<key> form. Opening it exchanges the key for a private view session and lands on the site. Same key, URL form — share it as carefully as the key."),
+    claimUrl: z
+        .string()
+        .url()
+        .describe("Claim page link in /claim#<key> form. The fragment is the key; browsers never send it to a server and the claim page strips it before analytics. Works until expiresAt and can be opened more than once."),
     expiresAt: z.string().datetime(),
 });
 export const SpaceCreateResponseSchema = z.object({
@@ -42,10 +84,6 @@ export const principalRefInputSchema = z.object({
 });
 export const spaceCreateSchema = z
     .object({
-    // `siteId` selects the static site the space lives under. Optional today:
-    // when omitted the tenant's default static site is resolved (internal-docs/platform.md "Site
-    // Context Resolution"). Spaces are valid only under static sites.
-    siteId: z.string().min(1).optional(),
     teamId: z.string().nullable().optional(),
     principal: principalRefInputSchema.optional(),
     slug: z.string().min(2).max(55).optional(),
@@ -108,50 +146,25 @@ export const spacePatchSchema = z
         });
     }
 });
-export const spaceClaimSchema = z
-    .object({
-    claimToken: z
-        .string()
-        .min(1)
-        .describe("One-time claim token returned at anonymous creation. API clients send it as bearer auth; browser claim links carry a separate browser handoff credential."),
-    teamId: z
+// The one claim endpoint (POST /v1/claim). A converging loop: the caller sends
+// what it has decided so far; the server either commits the claim or answers
+// with the single decision still missing (`login_required`, `team_required`,
+// `consent_required`).
+export const anonymousClaimSchema = z.object({
+    key: z
         .string()
         .min(1)
         .optional()
-        .describe("Team receiving the space. Inferred when you belong to exactly one team; otherwise required (`team_required`)."),
-    targetTeamId: z
+        .describe("The space key, when not sent as bearer auth. Browser claim pages send it here after reading the /claim#<key> fragment."),
+    teamId: z
         .string()
         .min(1)
         .optional()
-        .describe("Alias of teamId; must match when both are provided."),
-    agentContinuation: z
-        .boolean()
-        .optional()
-        .describe("User consent to keep the publishing agent authorized after the claim. The server independently proves continuation eligibility. Consent cannot grant continuation for an ineligible space."),
-})
-    .superRefine((value, ctx) => {
-    if (value.teamId && value.targetTeamId && value.teamId !== value.targetTeamId) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["teamId"],
-            message: "teamId and targetTeamId must match when both are provided.",
-        });
-    }
-});
-export const anonymousClaimAssignSchema = z.object({
-    teamId: z.string().min(1).optional(),
-    nonce: z.string().min(1).optional().describe("Browser claim nonce from the claim handoff."),
-    agentContinuation: z
-        .boolean()
-        .optional()
-        .describe("User consent to keep the publishing agent authorized after the claim. The server independently proves continuation eligibility. Consent cannot grant continuation for an ineligible space."),
-});
-export const anonymousClaimResolveSchema = z.object({
-    nonce: z.string().min(1).optional().describe("Browser claim nonce from the claim handoff."),
+        .describe("Team receiving the space. Inferred when the caller has exactly one writable team; otherwise the response answers `team_required` with the choices."),
     agentContinuation: z
         .boolean()
         .optional()
-        .describe("User consent applied when resolve auto-claims. The server independently proves continuation eligibility. Consent cannot grant continuation for an ineligible space."),
+        .describe("User consent to keep the publishing agent authorized after the claim. Required (true or false) when the space is continuation-eligible; the server independently proves eligibility, so consent cannot grant continuation to an ineligible space."),
 });
 export const anonymousClaimTeamSchema = z.object({
     id: z.string(),
@@ -185,18 +198,20 @@ export const anonymousClaimSharingSummarySchema = z.object({
 });
 export const anonymousClaimResponseSchema = z.object({
     state: z.enum(["unclaimed", "claimed"]),
-    action: z.enum(["claimed", "login_required", "team_required", "confirm_assign"]),
+    action: z.enum(["claimed", "login_required", "team_required", "consent_required"]),
     space: anonymousClaimSpacePreviewSchema,
     claim: z.object({
         expiresAt: z.string().datetime().nullable(),
         claimedAt: z.string().datetime().nullable(),
     }),
-    access: publishedAccessSchema,
+    access: publishedAccessSchema
+        .optional()
+        .describe("The space's reusable Open link, returned once the claim commits so the page can open the (private-by-default) site. Pre-claim callers already hold the key and its door URL."),
     continuation: z
         .object({
         eligible: z
             .boolean()
-            .describe("Server-proven continuation eligibility. Eligible means the publish intent records an originating agent that holds the claim token, the one-time exchange is unredeemed, and a safe secretless return exists. Only then can the UI offer continuation."),
+            .describe("Server-proven continuation eligibility. Eligible means the publish intent records an originating agent that holds the space key, the one-time exchange is unredeemed, and a safe secretless return exists. Only then can the UI offer continuation."),
         granted: z
             .boolean()
             .describe("Whether the claim left the one-time continuation exchange open for the originating agent."),
@@ -224,14 +239,16 @@ export const anonymousClaimStatusResponseSchema = z.object({
     }),
     claim: z.object({
         state: z.enum(["unclaimed", "claimed"]),
-        url: z.string().nullable(),
+        url: z
+            .string()
+            .nullable()
+            .describe("Claim page link (/claim#<key>) while the space is unclaimed; null after."),
         expiresAt: z.string().datetime().nullable(),
         continuation: z
             .enum(["available", "used", "unavailable"])
             .optional()
-            .describe("Present once the space is claimed. Whether this claim token can still be exchanged once for a durable API key (POST /v1/anonymous-claim/exchange)."),
+            .describe("Present once the space is claimed. Whether this key can still be exchanged once for a durable API key (POST /v1/claim/exchange)."),
     }),
-    access: publishedAccessSchema,
 });
 export const anonymousClaimExchangeResponseSchema = z.object({
     space: z.object({
@@ -253,14 +270,7 @@ export const anonymousClaimRotateSchema = z.object({
 });
 export const anonymousClaimRotateResponseSchema = z.object({
     spaceId: z.string(),
-    claimToken: z
-        .string()
-        .describe("Replacement claim token. Shown exactly once; store it before leaving this response."),
-    claimNonce: z
-        .string()
-        .describe("Replacement browser claim nonce embedded in claimUrl. Shown exactly once."),
-    claimUrl: z.string().url(),
-    expiresAt: z.string().datetime(),
+    claim: spaceClaimReceiptSchema.describe("Replacement space key, door URL, and claim link. Shown exactly once; the previous key, its URLs, and its view sessions stop working."),
 });
 export const spaceClaimReminderSchema = z.object({
     email: z
@@ -320,8 +330,8 @@ export const spaceVersionCreateSchema = z
         .optional()
         .describe("Finalize intent for a declared upload. When every declared file lands, the version finalizes itself; the explicit finalize call remains available for recovery and replay."),
     files: z
-        .array(manifestFileSchema)
-        .describe("The complete desired file manifest. For first deploys, send `path`, `size`, and `contentType` without hashes so upload can begin immediately. For updates, include `sha256` so the server can skip unchanged files."),
+        .array(uploadManifestFileSchema)
+        .describe("The complete desired file manifest. Local-byte entries require `sha256` and are uploaded to a content-addressed target. A `sourceUrl` entry may omit `sha256` because the runtime computes it while fetching. Hashes also let updates skip unchanged files."),
     ...manifestMutationFieldsSchema,
 })
     .superRefine(refineManifestMutationRules);
@@ -408,36 +418,57 @@ export const spaceFilesResponseSchema = z.object({
 export const spaceVersionFilePathQuerySchema = z.object({
     path: z.string().min(1),
 });
-export const spaceVersionFileQuerySchema = spaceVersionFilePathQuerySchema.extend({
-    download: z.string().optional(),
-});
-export const spaceVersionFileResponseSchema = z.object({
-    versionId: z.string(),
-    path: z.string(),
-    size: z.number().int().nonnegative(),
-    contentType: z.string().nullable(),
-    sha256: z.string().nullable(),
-    encoding: z.enum(["utf8", "base64"]),
-    content: z.string(),
-    truncated: z.boolean(),
-    cached: z.boolean(),
+/**
+ * Which representation of a path the runtime should hand back: `source` is the
+ * uploaded, pre-substitution object; `served` is the immutable byte the
+ * version actually serves. A private config input exists in `source` and is
+ * absent from `served`.
+ */
+export const spaceVersionFileViewSchema = z.enum(["source", "served"]);
+// Minting is a read, so it rides the URL — and a URL has a practical ceiling
+// that a JSON body does not. Clients chunk; each chunk is one authorization.
+export const VERSION_FILE_LINKS_MAX_PATHS = 200;
+// Structural admission only. Whether the version HOLDS a path is the runtime's
+// answer, given when the link is followed — the control plane keeps no catalog
+// to check against and does not round-trip per path to fake one.
+const spaceVersionFileLinkPathSchema = z
+    .string()
+    .min(1)
+    .refine((value) => {
+    try {
+        normalizeVersionPath(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, { message: "Path must be version-relative, without traversal or control characters." });
+/**
+ * Repeated `path` query parameters — `?path=index.html&path=about.html`. One
+ * path arrives as a bare string, so it is lifted into the batch shape before
+ * the per-path rules run.
+ */
+export const spaceVersionFileLinksQuerySchema = z.object({
+    path: z
+        .preprocess((value) => (typeof value === "string" ? [value] : value), z.array(spaceVersionFileLinkPathSchema).min(1).max(VERSION_FILE_LINKS_MAX_PATHS))
+        .describe("Version-relative file paths to mint read links for; repeat the parameter per path."),
+    view: spaceVersionFileViewSchema
+        .default("source")
+        .describe("Which representation to read: the uploaded source or the served byte."),
+});
+export const spaceVersionFileLinkSchema = z.object({
+    url: z.string().url().describe("Short-lived signed URL that serves the file's bytes."),
+    expiresAt: z.string().describe("When the link stops working."),
 });
-export const spaceVersionFileUrlPreviewSchema = z.object({
+/**
+ * Minting is blind to path validity — the control plane authorizes the version,
+ * not the path. A path that is not in the selected catalog view answers
+ * `version_file_not_found` when the link is followed.
+ */
+export const spaceVersionFileLinksResponseSchema = z.object({
     versionId: z.string(),
-    path: z.string(),
-    sha256: z.string().nullable(),
-    source: z.enum(["internet-shortcut", "webloc", "plain-url"]),
-    url: z.string().url(),
-    fetchedUrl: z.string().url().nullable(),
-    title: z.string().nullable(),
-    description: z.string().nullable(),
-    siteName: z.string().nullable(),
-    providerName: z.string().nullable(),
-    authorName: z.string().nullable(),
-    imageUrl: z.string().url().nullable(),
-    oEmbedUrl: z.string().url().nullable(),
-    status: z.enum(["ready", "unavailable"]),
-    cached: z.boolean(),
+    view: spaceVersionFileViewSchema,
+    links: z.record(z.string(), spaceVersionFileLinkSchema),
 });
 export const spaceVersionConventionArtifactKindSchema = z.enum(["redirects", "headers"]);
 export const spaceVersionConventionArtifactPathSchema = z.enum(["_redirects", "_headers"]);
@@ -500,61 +531,15 @@ export const spaceVersionComputedRoutingSummarySchema = z.object({
     source: z.object({
         artifacts: z.array(spaceVersionConventionArtifactMetadataSchema),
     }),
+    // Finalize-written scalars, not a replay of a stored compiled-routing blob:
+    // the runtime owns the compile and reports these counts on its receipt.
     compiled: z.object({
         redirectRuleCount: z.number().int().nonnegative(),
         headerRuleCount: z.number().int().nonnegative(),
-        staticRedirectCount: z.number().int().nonnegative(),
-        dynamicRedirectCount: z.number().int().nonnegative(),
         proxyRuleCount: z.number().int().nonnegative(),
     }),
     diagnostics: z.array(spaceVersionRoutingDiagnosticSchema),
 });
-export const spaceVersionFileDiffStatusSchema = z.enum([
-    "added",
-    "modified",
-    "deleted",
-    "renamed",
-    "unchanged",
-    "binary",
-    "too_large",
-]);
-export const spaceVersionFileDiffEntrySchema = z.object({
-    path: z.string(),
-    oldPath: z.string().nullable(),
-    status: spaceVersionFileDiffStatusSchema,
-    before: spaceVersionFileSchema.nullable(),
-    after: spaceVersionFileSchema.nullable(),
-    patch: z
-        .object({
-        format: z.literal("unified"),
-        content: z.string(),
-        truncated: z.boolean(),
-        truncationReason: z.literal("patch_byte_limit").nullable(),
-    })
-        .nullable(),
-    patchOmission: z
-        .enum(["input_too_large", "not_previewable", "content_unavailable", "patch_budget_exhausted"])
-        .nullable(),
-});
-export const spaceVersionFileDiffQuerySchema = cursorListQuerySchema.extend({
-    baseVersionId: z.string().optional(),
-});
-export const spaceVersionFileDiffResponseSchema = z.object({
-    versionId: z.string(),
-    baseVersionId: z.string().nullable(),
-    files: z.array(spaceVersionFileDiffEntrySchema),
-    pagination: CursorPaginationSchema,
-    limits: z.object({
-        maxFiles: z.number().int().positive(),
-        maxInputBytes: z.number().int().positive(),
-        maxPatchBytes: z.number().int().positive(),
-        readConcurrency: z.number().int().positive(),
-    }),
-    usage: z.object({
-        inputBytes: z.number().int().nonnegative(),
-        patchBytes: z.number().int().nonnegative(),
-    }),
-});
 // Upload state is inferable (internal-docs/platform.md L2216): `upload` present means bytes are
 // still needed (then finalize); `versionId` null means the manifest matched and nothing changed.
 // No redundant booleans ride along.
@@ -574,12 +559,11 @@ export const spaceVersionIntentResponseSchema = z.object({
 export const publishRequestSchema = z
     .object({
     spaceId: z.string().min(1).optional(),
-    siteId: z.string().min(1).optional(),
     teamId: z.string().nullable().optional(),
     principal: principalRefInputSchema.optional(),
     files: z
-        .array(manifestFileSchema)
-        .describe("Desired file manifest for a declared publish session. Clients upload returned paths, then finalize."),
+        .array(uploadManifestFileSchema)
+        .describe("Desired file manifest for a declared publish session. Local-byte entries require `sha256`; sourceUrl entries may omit it. Clients upload returned targets, then finalize."),
     ...manifestMutationFieldsSchema,
     source: PublishSourceSchema.optional().describe('Publish provenance recorded on the version; defaults to {kind: "direct_upload"}.'),
     // Same fields, same bounds as spaceVersionCreateSchema: a publish that ran
@@ -680,7 +664,9 @@ export const publishNextSchema = z.object({
 });
 export const publishReceiptSchema = z.object({
     space: publishReceiptSpaceSchema,
-    access: publishedAccessSchema.optional(),
+    access: publishedAccessSchema
+        .optional()
+        .describe("Reusable Open link for owned (team/external) publishes. Anonymous publishes get no separate access object: the space key in `claim` is the credential, and `claim.url` is the door."),
     version: publishReceiptVersionSchema,
     activation: publishActivationSchema,
     next: publishNextSchema,
@@ -711,7 +697,7 @@ export const publishReceiptSchema = z.object({
         status: z
             .string()
             .optional()
-            .describe("Claim-token-authenticated anonymous publish status endpoint."),
+            .describe("Space-key-authenticated anonymous publish status endpoint."),
     })
         .optional()
         .describe("Follow-up links so agents can act on the receipt without knowing the full API."),
@@ -768,14 +754,11 @@ export const spaceRuntimeStatusSchema = z.object({
         .describe("Live space URL. It moves to the latest version after a successful publish to `live`."),
     runtimeState: spaceStatus.describe("Space operation-lifecycle status."),
     liveVersionStatus: versionStatus.nullable(),
-    liveRuntimeKind: runtimeKindSchema
-        .nullable()
-        .describe("Runtime kind declared by the live version, if any."),
     pendingVersionStatus: versionStatus.nullable(),
     operation: AsyncOperationSchema.nullable(),
     app: runtimeAppSchema
         .nullable()
-        .describe("What the live version runs: its Zero capsule or Functions worker, discriminated by `runtimeKind`. Null for a static space. Also null for callers whose credential does not carry `versions:read`, because app details read version contents, not serving state."),
+        .describe("What the live version runs: its Zero capsule and its Functions worker, each null when the published tree carries none of that product (both null for a static space). The whole object is null for callers whose credential does not carry `versions:read`, because app details read version contents, not serving state."),
 });
 export const spaceApplyChangeBaseSchema = z.object({
     kind: z.enum(["variable", "routing", "access", "settings"]),

package/dist/contracts/superadmin-activity.d.ts

@@ -2,6 +2,61 @@ import { z } from "zod";
 export declare const superadminActivityListQuerySchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
+export declare const superadminActivityEventQuerySchema: z.ZodObject<{
+    spaceId: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+    principalType: z.ZodOptional<z.ZodEnum<{
+        team: "team";
+        external: "external";
+    }>>;
+    principalId: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        system: "system";
+        user: "user";
+        api_key: "api_key";
+        oauth_client: "oauth_client";
+        anonymous_claim: "anonymous_claim";
+    }>>;
+    actorId: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+    since: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SuperadminActivityEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    sequence: z.ZodNumber;
+    tenantId: z.ZodString;
+    principalType: z.ZodNullable<z.ZodString>;
+    principalId: z.ZodNullable<z.ZodString>;
+    spaceId: z.ZodNullable<z.ZodString>;
+    actorType: z.ZodString;
+    actorId: z.ZodString;
+    code: z.ZodString;
+    message: z.ZodString;
+    details: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export declare const SuperadminActivityEventListSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        sequence: z.ZodNumber;
+        tenantId: z.ZodString;
+        principalType: z.ZodNullable<z.ZodString>;
+        principalId: z.ZodNullable<z.ZodString>;
+        spaceId: z.ZodNullable<z.ZodString>;
+        actorType: z.ZodString;
+        actorId: z.ZodString;
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 export declare const SuperadminLatestUserSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -43,9 +98,7 @@ export declare const SuperadminLatestSpaceSchema: z.ZodObject<{
     teamSlug: z.ZodNullable<z.ZodString>;
     teamName: z.ZodNullable<z.ZodString>;
     externalCustomerId: z.ZodNullable<z.ZodString>;
-    placementMode: z.ZodString;
     siteId: z.ZodNullable<z.ZodString>;
-    siteClass: z.ZodNullable<z.ZodString>;
     siteStatus: z.ZodNullable<z.ZodString>;
     liveHostname: z.ZodNullable<z.ZodString>;
     disabledAt: z.ZodNullable<z.ZodString>;
@@ -65,9 +118,7 @@ export declare const SuperadminLatestSpaceListSchema: z.ZodObject<{
         teamSlug: z.ZodNullable<z.ZodString>;
         teamName: z.ZodNullable<z.ZodString>;
         externalCustomerId: z.ZodNullable<z.ZodString>;
-        placementMode: z.ZodString;
         siteId: z.ZodNullable<z.ZodString>;
-        siteClass: z.ZodNullable<z.ZodString>;
         siteStatus: z.ZodNullable<z.ZodString>;
         liveHostname: z.ZodNullable<z.ZodString>;
         disabledAt: z.ZodNullable<z.ZodString>;
@@ -198,6 +249,8 @@ export declare const SuperadminBadExperienceListSchema: z.ZodObject<{
         safetyReviews: z.ZodNumber;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export type SuperadminActivityEvent = z.infer<typeof SuperadminActivityEventSchema>;
+export type SuperadminActivityEventQuery = z.infer<typeof superadminActivityEventQuerySchema>;
 export type SuperadminLatestUser = z.infer<typeof SuperadminLatestUserSchema>;
 export type SuperadminLatestSpace = z.infer<typeof SuperadminLatestSpaceSchema>;
 export type SuperadminLatestVersion = z.infer<typeof SuperadminLatestVersionSchema>;

package/dist/contracts/superadmin-activity.js

@@ -1,7 +1,55 @@
 import { z } from "zod";
+import { AnyObjectSchema, CursorPaginationSchema } from "./common.js";
 export const superadminActivityListQuerySchema = z.object({
     limit: z.coerce.number().int().min(1).max(100).default(50),
 });
+// Cross-tenant reader over the `activity_events` audit log. Every superadmin
+// mutation appends there, but only tenant-scoped /v1 readers existed; this is
+// the operator's view of the same rows. At least one selective filter is
+// required (see the route) so a query lands on one of the table's indexes
+// instead of scanning the whole log.
+export const superadminActivityEventQuerySchema = z.object({
+    spaceId: z.string().min(1).optional().describe("Filter to events for one Space, cross-tenant."),
+    tenantId: z.string().min(1).optional().describe("Filter to one tenant."),
+    principalType: z
+        .enum(["team", "external"])
+        .optional()
+        .describe("Owning principal kind; must be paired with principalId."),
+    principalId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Owning principal id; must be paired with principalType."),
+    actorType: z
+        .enum(["user", "api_key", "oauth_client", "anonymous_claim", "system"])
+        .optional()
+        .describe("Actor kind; must be paired with actorId."),
+    actorId: z.string().min(1).optional().describe("Actor id; must be paired with actorType."),
+    code: z.string().min(1).optional().describe("Filter to one event code, e.g. `space.created`."),
+    since: z.string().datetime().optional().describe("Only events at or after this time."),
+    limit: z.coerce.number().int().min(1).max(200).default(50),
+    cursor: z.string().min(1).optional(),
+});
+// Operator surface: `message` and `details` are the raw audit payloads, not the
+// tenant-facing projection. Nothing here widens any /v1 response.
+export const SuperadminActivityEventSchema = z.object({
+    id: z.string(),
+    sequence: z.number().int().nonnegative(),
+    tenantId: z.string(),
+    principalType: z.string().nullable(),
+    principalId: z.string().nullable(),
+    spaceId: z.string().nullable(),
+    actorType: z.string(),
+    actorId: z.string(),
+    code: z.string(),
+    message: z.string(),
+    details: AnyObjectSchema.nullable(),
+    createdAt: z.string().datetime(),
+});
+export const SuperadminActivityEventListSchema = z.object({
+    data: z.array(SuperadminActivityEventSchema),
+    pagination: CursorPaginationSchema,
+});
 export const SuperadminLatestUserSchema = z.object({
     id: z.string(),
     name: z.string(),
@@ -30,9 +78,7 @@ export const SuperadminLatestSpaceSchema = z.object({
     teamSlug: z.string().nullable(),
     teamName: z.string().nullable(),
     externalCustomerId: z.string().nullable(),
-    placementMode: z.string(),
     siteId: z.string().nullable(),
-    siteClass: z.string().nullable(),
     siteStatus: z.string().nullable(),
     liveHostname: z.string().nullable(),
     disabledAt: z.string().datetime().nullable(),