@spacefast/common 0.0.21 → 0.0.24

package/dist/contracts/operations.js

@@ -11,7 +11,6 @@ export const userOperationKindSchema = z.enum([
     "domain_transfer_submit",
     "domain_dns_apply",
     "domain_lifecycle",
-    "variable_cascade",
     "webhook_deliver",
     "integration_release",
 ]);
@@ -45,3 +44,78 @@ export const operationListResponseSchema = z.object({
     data: z.array(UserOperationSchema),
     pagination: CursorPaginationSchema,
 });
+// ---------------------------------------------------------------------------
+// Superadmin operator surface: the operations rows ARE the queue, bucketed by
+// claim eligibility. Served by the control plane's feed service and consumed
+// by the superadmin dashboard and the e2e harness.
+/** Buckets an operator triages by. Live buckets partition the live population:
+ *  a queued row is exactly one of ready / scheduled / blocked. */
+export const SUPERADMIN_OPERATION_FILTERS = [
+    "all",
+    "ready",
+    "scheduled",
+    "blocked",
+    "running",
+    "stuck",
+    "retrying",
+    "failed",
+    "succeeded",
+    "canceled",
+];
+export const superadminOperationListQuerySchema = z.object({
+    filter: z.enum(SUPERADMIN_OPERATION_FILTERS).default("all"),
+    eventType: z.string().trim().min(1).max(160).optional(),
+    limit: z.coerce.number().int().min(1).max(200).default(50),
+    order: z.enum(["newest", "oldest"]).default("newest"),
+});
+export const SuperadminOperationRowSchema = z.object({
+    id: z.string(),
+    eventType: z.string(),
+    status: z.string(),
+    resourceType: z.string(),
+    resourceId: z.string(),
+    attempts: z.number().int().nonnegative(),
+    // The mutable eligibility clock, meaningless once the row is terminal — null
+    // there rather than a stale instant an operator would read as a schedule.
+    dueAt: z.string().datetime().nullable(),
+    leaseExpiresAt: z.string().datetime().nullable(),
+    // Computed with the database clock so row labels agree with server-side
+    // stuck filters and summary totals even when an operator's clock drifts.
+    stuck: z.boolean(),
+    blockedByOperationId: z.string().nullable(),
+    inflightKey: z.string().nullable(),
+    lastError: z.string().nullable(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    finishedAt: z.string().datetime().nullable(),
+});
+export const SuperadminOperationListSchema = z.object({
+    operations: z.array(SuperadminOperationRowSchema),
+    total: z.number().int().nonnegative(),
+    windowHours: z.number().int().positive(),
+});
+export const SuperadminOperationSummarySchema = z.object({
+    windowHours: z.number().int().positive(),
+    live: z.object({
+        ready: z.number().int().nonnegative(),
+        scheduled: z.number().int().nonnegative(),
+        blocked: z.number().int().nonnegative(),
+        running: z.number().int().nonnegative(),
+        stuck: z.number().int().nonnegative(),
+        retrying: z.number().int().nonnegative(),
+    }),
+    recent: z.object({
+        succeeded: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+        canceled: z.number().int().nonnegative(),
+    }),
+    oldestReadyAt: z.string().datetime().nullable(),
+    oldestRunningAt: z.string().datetime().nullable(),
+    kinds: z.array(z.object({
+        eventType: z.string(),
+        ready: z.number().int().nonnegative(),
+        running: z.number().int().nonnegative(),
+        stuck: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+    })),
+});

package/dist/contracts/pages.d.ts

@@ -15,8 +15,9 @@ export declare const routePageIdSchema: z.ZodEnum<{
     404: "404";
 }>;
 export type RoutePageId = z.infer<typeof routePageIdSchema>;
-export declare const CUSTOM_PAGE_IDS: readonly ["404", "denied", "access", "index", "preview"];
+export declare const CUSTOM_PAGE_IDS: readonly ["404", "denied", "access", "index", "preview", "collab"];
 export declare const customPageIdSchema: z.ZodEnum<{
+    collab: "collab";
     denied: "denied";
     index: "index";
     preview: "preview";
@@ -24,6 +25,9 @@ export declare const customPageIdSchema: z.ZodEnum<{
     404: "404";
 }>;
 export type CustomPageId = z.infer<typeof customPageIdSchema>;
+export declare const COLLAB_PAGE_SOURCE = "_pages/collab.html";
+export declare const COLLAB_PAGE_PATH: "/_pages/collab.html";
+export declare const COLLAB_PAGE_ELEMENTS: readonly ["sf-space", "sf-comments", "sf-thread", "sf-timeline", "sf-presence", "sf-versions"];
 export declare const PLATFORM_PAGE_IDS: readonly ["undeployed", "suspended", "legal", "gone", "runtime-error", "rate-limited", "tier-unavailable", "proxy-error", "method-not-allowed", "content-too-large"];
 export declare const platformPageIdSchema: z.ZodEnum<{
     legal: "legal";
@@ -62,5 +66,6 @@ export declare const runtimePagesSchema: z.ZodObject<{
         index: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     previews: z.ZodRecord<z.ZodString, z.ZodString>;
+    collab: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type RuntimePages = z.infer<typeof runtimePagesSchema>;

package/dist/contracts/pages.js

@@ -3,8 +3,28 @@ export const SITE_PAGE_IDS = ["404", "denied", "access", "index", "preview"];
 export const sitePageIdSchema = z.enum(SITE_PAGE_IDS);
 export const ROUTE_PAGE_IDS = ["404", "denied", "access"];
 export const routePageIdSchema = z.enum(ROUTE_PAGE_IDS);
-export const CUSTOM_PAGE_IDS = ["404", "denied", "access", "index", "preview"];
+// `collab` is publishable but has no built-in template: with no layout of their
+// own a Space's reviewers get the platform frame at `/__/collab`, so there is
+// nothing for a default `_pages/collab.html` to be. Hence CUSTOM ⊃ SITE.
+export const CUSTOM_PAGE_IDS = ["404", "denied", "access", "index", "preview", "collab"];
 export const customPageIdSchema = z.enum(CUSTOM_PAGE_IDS);
+// The Space-level review room the collaboration orb expands into, and the URL
+// its compiled document answers at (collab-public-api.html §3). One room per
+// Space, so one page, at the root — never a per-directory override.
+// The PHP mirror is SPACEFAST_COLLAB_PAGE_PATH in runtime/engine/shared/context.php.
+export const COLLAB_PAGE_SOURCE = "_pages/collab.html";
+export const COLLAB_PAGE_PATH = `/${COLLAB_PAGE_SOURCE}`;
+// Registered by the browser SDK, not by the server: the compiler leaves them
+// in the document untouched and they render nothing at publish time. Listed
+// here only so a collab layout using them is not read as a typo'd page slot.
+export const COLLAB_PAGE_ELEMENTS = [
+    "sf-space",
+    "sf-comments",
+    "sf-thread",
+    "sf-timeline",
+    "sf-presence",
+    "sf-versions",
+];
 export const PLATFORM_PAGE_IDS = [
     "undeployed",
     "suspended",
@@ -87,4 +107,7 @@ export const runtimePagesSchema = z.object({
         index: pageArtifactKeySchema.optional(),
     })),
     previews: z.record(z.string().startsWith("/").max(2048), pageArtifactKeySchema),
+    // Present only when the Space published its own review room; its absence is
+    // what tells the SDK to expand into the platform frame instead.
+    collab: pageArtifactKeySchema.optional(),
 });

package/dist/contracts/plan-policy.d.ts

@@ -16,14 +16,12 @@ export type PlanDisabledBehavior = z.infer<typeof planDisabledBehaviorSchema>;
 export declare const PlanPolicyResponseSchema: z.ZodObject<{
     principal: z.ZodObject<{
         type: z.ZodEnum<{
-            site: "site";
             space: "space";
             team: "team";
             external_principal: "external_principal";
         }>;
         id: z.ZodString;
     }, z.core.$strip>;
-    siteId: z.ZodOptional<z.ZodString>;
     spaceId: z.ZodOptional<z.ZodString>;
     plan: z.ZodEnum<{
         free: "free";
@@ -56,8 +54,8 @@ export declare const PlanPolicyResponseSchema: z.ZodObject<{
     warnings: z.ZodOptional<z.ZodArray<z.ZodObject<{
         severity: z.ZodEnum<{
             info: "info";
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         code: z.ZodString;
         message: z.ZodString;

package/dist/contracts/plan-policy.js

@@ -19,11 +19,10 @@ export const planDisabledBehaviorSchema = z.object({
 export const PlanPolicyResponseSchema = z.object({
     principal: z
         .object({
-        type: z.enum(["team", "site", "space", "external_principal"]),
+        type: z.enum(["team", "space", "external_principal"]),
         id: z.string(),
     })
         .describe("Principal the policy was resolved for."),
-    siteId: z.string().optional().describe("Site the policy was resolved against, when site-scoped."),
     spaceId: z
         .string()
         .optional()

package/dist/contracts/platform.d.ts

@@ -29,12 +29,19 @@ export declare const accessLogEntrySchema: z.ZodObject<{
     bytes: z.ZodNumber;
 }, z.core.$strip>;
 /**
- * One line a space's own code wrote, from whichever execution tier serves it.
+ * One line a space's own code wrote, whichever tier wrote it.
  *
- * This is `executionLogEntrySchema` verbatim rather than a platform-shaped
- * restatement of it: both tiers already emit that shape, and re-declaring it
- * here would be a second definition to keep in sync with the runtimes that
- * produce the records.
+ * There is exactly one place these come from: the hosting provider's PHP error
+ * log for the space's site. A Zero mutation, a PHP function, and a Functions
+ * worker on Cloudflare all end up writing to that file on the origin — the
+ * worker by tailing its output back to the origin that dispatched it — because
+ * it is the only stream the provider ships off the box and serves back. The
+ * runtime writes each record as one JSON line behind a marker; this is what the
+ * reader gets after pulling that line back out of the provider's message.
+ *
+ * `id` is minted by the runtime at write time rather than derived on read: the
+ * provider's log has no identity of its own, and a caller paging a window needs
+ * a stable key for a line it may see again at a page boundary.
  *
  * Unlike its access-log sibling there is no `ts` alongside `timestamp`. That
  * duplication is a compatibility alias the access log carries for callers that
@@ -58,17 +65,18 @@ export declare const runtimeLogEntrySchema: z.ZodObject<{
 }, z.core.$strict>;
 export type RuntimeLogEntry = z.infer<typeof runtimeLogEntrySchema>;
 /**
- * Handler logs are filtered, not windowed.
- *
- * The access log takes `since`/`until` because the provider indexes by time.
- * Neither execution tier does: Zero pages a local append-only store by cursor,
- * and the origin walks day files backwards from newest. Accepting a `since`
- * here would mean ignoring it, so it is absent — the filters below are the ones
- * both tiers actually honour.
+ * Windowed like its access-log sibling, because it reads the same provider
+ * index — `atomic_site_id` plus a `@timestamp` range — and that index has no
+ * other way in. The two log kinds sit side by side under one command, so they
+ * take one query shape; `requestId` and `handlerName` are the extra narrowings
+ * only handler output can answer, and they are applied over the pages the
+ * server fetched rather than by the provider, which indexes neither.
  */
 export declare const runtimeLogListQuerySchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     cursor: z.ZodOptional<z.ZodString>;
+    since: z.ZodOptional<z.ZodString>;
+    until: z.ZodOptional<z.ZodString>;
     requestId: z.ZodOptional<z.ZodString>;
     handlerName: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -92,8 +100,8 @@ export declare const accessLogListResponseSchema: z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
             info: "info";
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -111,26 +119,26 @@ export declare const accessLogListResponseSchema: z.ZodObject<{
 /**
  * Paged handler logs.
  *
- * The pagination block is deliberately the same `CursorPaginationSchema` the
- * access log uses — the two kinds sit side by side under one command, and a
- * caller should not have to learn a second paging idiom to read the other half
- * of its own space.
- *
  * One thing about that cursor is worth stating rather than discovering: **an
- * empty page does not mean the end.** `hasMore` is true whenever the server
- * stopped before reaching the oldest retained line, and the origin reader stops
- * on its own per-page bounds — day count, line count, bytes scanned — which it
- * can hit while a `requestId` or `handlerName` filter matched nothing in the
- * stretch it read. Both tiers satisfy the same rule: **`hasMore: false` means
- * you have seen everything; `hasMore: true` means keep paging, whatever `data`
- * held.** A client that stops on the first empty page will silently truncate a
- * filtered search.
+ * empty page does not mean the end.** The cursor walks the provider's scroll
+ * over every PHP-error-log line in the window, and only some of those lines are
+ * handler output — a page can come back empty because the stretch it scanned
+ * held none, or held none matching `requestId`/`handlerName`. The rule is
+ * **`hasMore: false` means you have seen everything; `hasMore: true` means keep
+ * paging, whatever `data` held.** A client that stops on the first empty page
+ * will silently truncate its own search.
  *
- * No `warnings` array, unlike the access log. Its one diagnostic is
- * `log_retention_clamped`, which reports a requested window being cut back to
- * the plan's retention — and there is no window to clamp here. An empty
- * diagnostics channel would be a field every caller must handle and no server
- * ever fills.
+ * `warnings` carries the same `log_retention_clamped` diagnostic the access log
+ * does, for the same reason: one window, one retention, one way of saying it
+ * was cut back.
+ *
+ * **These lines lag.** A record is written to a file on the origin, shipped off
+ * the box, and indexed before it can be read back, so a line a request just
+ * wrote will not be in the next page. Nothing here is live, and the delay is
+ * the provider's ingest lag rather than anything this surface schedules — it
+ * has not been measured against a real client yet, so no surface should quote
+ * a figure for it until the gate probe in
+ * `e2e-tests/direct/wpcloud-behavior.test.ts` has actually run.
  */
 export declare const runtimeLogListResponseSchema: z.ZodObject<{
     data: z.ZodArray<z.ZodObject<{
@@ -152,22 +160,37 @@ export declare const runtimeLogListResponseSchema: z.ZodObject<{
         nextCursor: z.ZodNullable<z.ZodString>;
         hasMore: z.ZodBoolean;
     }, z.core.$strip>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        severity: z.ZodEnum<{
+            info: "info";
+            warning: "warning";
+            error: "error";
+        }>;
+        message: z.ZodString;
+        path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            registrar: "registrar";
+            wpcloud: "wpcloud";
+            dns: "dns";
+            runtime: "runtime";
+        }>>>;
+        details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        fix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type RuntimeLogListResponse = z.infer<typeof runtimeLogListResponseSchema>;
 export declare const analyticsQuerySchema: z.ZodObject<{
     window: z.ZodOptional<z.ZodEnum<{
-        custom: "custom";
         "48h": "48h";
         "7d": "7d";
         "30d": "30d";
     }>>;
-    since: z.ZodOptional<z.ZodString>;
-    until: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const analyticsResponseSchema: z.ZodObject<{
     spaceId: z.ZodString;
     window: z.ZodEnum<{
-        custom: "custom";
         "48h": "48h";
         "7d": "7d";
         "30d": "30d";
@@ -178,18 +201,11 @@ export declare const analyticsResponseSchema: z.ZodObject<{
         hourly: "hourly";
         daily: "daily";
     }>;
-    dataAsOf: z.ZodNullable<z.ZodString>;
-    refreshing: z.ZodBoolean;
     views: z.ZodNumber;
-    visitors: z.ZodNullable<z.ZodNumber>;
     bandwidthBytes: z.ZodNumber;
-    visitorsByHost: z.ZodArray<z.ZodObject<{
-        host: z.ZodString;
-        series: z.ZodArray<z.ZodObject<{
-            date: z.ZodString;
-            visitors: z.ZodNumber;
-            views: z.ZodNumber;
-        }, z.core.$strip>>;
+    visitorsByDay: z.ZodArray<z.ZodObject<{
+        date: z.ZodString;
+        visitors: z.ZodNumber;
     }, z.core.$strip>>;
     topPaths: z.ZodArray<z.ZodObject<{
         path: z.ZodString;
@@ -205,107 +221,4 @@ export declare const analyticsResponseSchema: z.ZodObject<{
         views: z.ZodNumber;
         bandwidthBytes: z.ZodNumber;
     }, z.core.$strip>>;
-    warnings: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        code: z.ZodString;
-        severity: z.ZodEnum<{
-            info: "info";
-            error: "error";
-            warning: "warning";
-        }>;
-        message: z.ZodString;
-        path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
-            registrar: "registrar";
-            wpcloud: "wpcloud";
-            dns: "dns";
-            runtime: "runtime";
-        }>>>;
-        details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
-        fix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
-    }, z.core.$strip>>>;
-}, z.core.$strip>;
-export declare const runtimeCertificateSchema: z.ZodObject<{
-    id: z.ZodNullable<z.ZodNumber>;
-    status: z.ZodNullable<z.ZodString>;
-    domains: z.ZodArray<z.ZodString>;
-    expiration: z.ZodNullable<z.ZodString>;
-    raw: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-}, z.core.$strip>;
-export declare const runtimeCertificatesSchema: z.ZodObject<{
-    data: z.ZodArray<z.ZodObject<{
-        id: z.ZodNullable<z.ZodNumber>;
-        status: z.ZodNullable<z.ZodString>;
-        domains: z.ZodArray<z.ZodString>;
-        expiration: z.ZodNullable<z.ZodString>;
-        raw: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    }, z.core.$strip>>;
-    pagination: z.ZodObject<{
-        nextCursor: z.ZodNullable<z.ZodString>;
-        hasMore: z.ZodBoolean;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-export declare const runtimeCertificateStageSchema: z.ZodObject<{
-    domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    certificate: z.ZodString;
-    privateKey: z.ZodString;
-    csr: z.ZodOptional<z.ZodString>;
-    trustedCertificates: z.ZodOptional<z.ZodString>;
-    clientCertificate: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export declare const runtimeCertificateUpdateSchema: z.ZodObject<{
-    certificate: z.ZodString;
-    privateKey: z.ZodString;
-    csr: z.ZodOptional<z.ZodString>;
-    trustedCertificates: z.ZodOptional<z.ZodString>;
-    clientCertificate: z.ZodOptional<z.ZodString>;
-    domains: z.ZodDefault<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
-export declare const runtimeCertificateValidateSchema: z.ZodObject<{
-    domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    certificate: z.ZodString;
-    privateKey: z.ZodString;
-    csr: z.ZodOptional<z.ZodString>;
-    trustedCertificates: z.ZodOptional<z.ZodString>;
-    clientCertificate: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export declare const runtimeCertificateMutationResponseSchema: z.ZodObject<{
-    certificate: z.ZodNullable<z.ZodObject<{
-        id: z.ZodNullable<z.ZodNumber>;
-        status: z.ZodNullable<z.ZodString>;
-        domains: z.ZodArray<z.ZodString>;
-        expiration: z.ZodNullable<z.ZodString>;
-        raw: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    }, z.core.$strip>>;
-    raw: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-}, z.core.$strip>;
-export declare const runtimeCertificateValidationResponseSchema: z.ZodObject<{
-    valid: z.ZodBoolean;
-    errors: z.ZodArray<z.ZodString>;
-    warnings: z.ZodArray<z.ZodString>;
-    validations: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-export declare const runtimeCertificateActivateSchema: z.ZodObject<{
-    domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
-export declare const runtimeCertificateActionResponseSchema: z.ZodObject<{
-    ok: z.ZodLiteral<true>;
-    certificateId: z.ZodNumber;
-    raw: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-}, z.core.$strip>;
-export declare const runtimeSslInfoSchema: z.ZodObject<{
-    domain: z.ZodString;
-    raw: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-}, z.core.$strip>;
-export declare const runtimeSslDomainSchema: z.ZodObject<{
-    domain: z.ZodString;
-}, z.core.$strip>;
-export declare const runtimeSslToggleSchema: z.ZodObject<{
-    domain: z.ZodString;
-    enabled: z.ZodBoolean;
-}, z.core.$strip>;
-export declare const runtimeSslActionResponseSchema: z.ZodObject<{
-    ok: z.ZodLiteral<true>;
-    domain: z.ZodString;
-    raw: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;