@spacefast/common 0.0.23 → 0.0.24

package/dist/contracts/platform.js

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import { CursorPaginationSchema, baseDiagnosticSchema, cursorListQuerySchema } from "./common.js";
-import { executionLogEntrySchema } from "./execution.js";
 export const domainPurchaseContactSchema = z.object({
     firstName: z.string().trim().min(1).max(80),
     lastName: z.string().trim().min(1).max(80),
@@ -29,29 +28,47 @@ export const accessLogEntrySchema = z.object({
     bytes: z.number().int().nonnegative(),
 });
 /**
- * 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
  * predate the rename; runtime logs have never been served to anyone, so there
  * is no caller to keep and no reason to inherit the wart.
  */
-export const runtimeLogEntrySchema = executionLogEntrySchema;
+export const runtimeLogEntrySchema = z
+    .object({
+    id: z.string().min(1),
+    timestamp: z.string().datetime(),
+    level: z.enum(["debug", "info", "warn", "error"]),
+    requestId: z.string().min(1).nullable(),
+    versionId: z.string().min(1).nullable(),
+    /** Zero names the mutation; Functions names the handler. */
+    handlerName: z.string().min(1).nullable(),
+    message: z.string(),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+})
+    .strict();
 /**
- * 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 const runtimeLogListQuerySchema = cursorListQuerySchema.extend({
+export const runtimeLogListQuerySchema = logWindowQuerySchema.extend({
     requestId: z
         .string()
         .min(1)
@@ -74,75 +91,63 @@ export const accessLogListResponseSchema = z.object({
 /**
  * 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 const runtimeLogListResponseSchema = z.object({
     data: z.array(runtimeLogEntrySchema),
     pagination: CursorPaginationSchema,
+    warnings: z
+        .array(baseDiagnosticSchema)
+        .optional()
+        .describe("List-level diagnostics; log_retention_clamped names the effective `since` when the requested window exceeds the plan's log retention."),
 });
 export const analyticsQuerySchema = z.object({
     window: z
-        .enum(["48h", "7d", "30d", "custom"])
+        .enum(["48h", "7d", "30d"])
         .optional()
-        .describe('Analytics summary window. Defaults to "7d". "custom" requires since/until.'),
-    since: z.string().datetime().optional().describe("Start of the custom analytics window."),
-    until: z.string().datetime().optional().describe("End of the custom analytics window."),
+        .describe('Analytics summary window. Defaults to "7d".'),
 });
 // Served by `GET /v1/spaces/{spaceId}/analytics`: traffic summary over the
-// requested window, read from Spacefast's own per-space rollups (ingested on
-// demand from provider edge metrics; staleness bounded by the freshness TTL).
-// Counts cover main hostnames only: default, custom-domain, and channel.
-// Immutable version-URL traffic is ingested but never surfaced here.
+// requested window, read live from the hosting provider's edge metrics — no
+// local store exists. Counts cover every hostname mapped to the space's site;
+// a provider outage means this endpoint errors rather than answers stale.
 export const analyticsResponseSchema = z.object({
     spaceId: z.string().describe("The space id the traffic was aggregated for."),
-    window: z.enum(["48h", "7d", "30d", "custom"]).describe("Resolved summary window."),
-    since: z.string().describe("Resolved window start (ISO 8601), after retention clamping."),
-    until: z.string().describe("Resolved window end (ISO 8601)."),
-    granularity: z.enum(["hourly", "daily"]).describe("Series bucket size, resolved from the plan."),
-    dataAsOf: z
-        .string()
-        .nullable()
-        .describe("End of the last fully-ingested hour; null until the first ingest starts."),
-    refreshing: z
-        .boolean()
-        .describe("Whether an ingest run is active or the server just triggered one."),
+    window: z.enum(["48h", "7d", "30d"]).describe("Resolved summary window."),
+    since: z.string().describe("Window start (ISO 8601)."),
+    until: z.string().describe("Window end (ISO 8601)."),
+    granularity: z
+        .enum(["hourly", "daily"])
+        .describe("Series bucket size: hourly for the 48h window, daily otherwise."),
     views: z
         .number()
-        .describe("Successful non-crawler requests (status < 400, assets included) summed across main hostnames over the window."),
-    visitors: z
-        .number()
-        .nullable()
-        .describe("Unique-visitor estimate. Always null because per-hostname unique-visitor data is not yet available from the hosting provider."),
+        .describe("Successful non-crawler requests (status < 400, assets included) over the window."),
     bandwidthBytes: z.number().describe("Total response bytes in the window."),
-    visitorsByHost: z
+    visitorsByDay: z
         .array(z.object({
-        host: z.string(),
-        series: z.array(z.object({
-            date: z.string().describe("UTC day (ISO 8601)."),
-            visitors: z.number(),
-            views: z.number(),
-        })),
+        date: z.string().describe("UTC day (ISO 8601)."),
+        visitors: z.number(),
     }))
-        .describe("Per-hostname daily visitor estimates. Always empty because per-hostname unique-visitor data is not yet available from the hosting provider."),
+        .describe("Daily unique-visitor estimates. Daily is the provider's finest uniques resolution, and uniques are never summed across days."),
     topPaths: z
         .array(z.object({ path: z.string(), views: z.number() }))
         .describe("Most-viewed paths, capped at 10."),
@@ -157,65 +162,4 @@ export const analyticsResponseSchema = z.object({
         bandwidthBytes: z.number(),
     }))
         .describe("Time series across the window."),
-    warnings: z
-        .array(baseDiagnosticSchema)
-        .optional()
-        .describe("Diagnostics; analytics_retention_clamped names the effective `since` when the requested window exceeds the plan's analytics retention."),
-});
-export const runtimeCertificateSchema = z.object({
-    id: z.number().int().positive().nullable(),
-    status: z.string().nullable(),
-    domains: z.array(z.string()),
-    expiration: z.string().nullable(),
-    raw: z.record(z.string(), z.unknown()),
-});
-export const runtimeCertificatesSchema = z.object({
-    data: z.array(runtimeCertificateSchema),
-    pagination: CursorPaginationSchema,
-});
-const certificatePayload = z.object({
-    domains: z.array(z.string()).optional(),
-    certificate: z.string().min(1),
-    privateKey: z.string().min(1),
-    csr: z.string().optional(),
-    trustedCertificates: z.string().optional(),
-    clientCertificate: z.string().optional(),
-});
-export const runtimeCertificateStageSchema = certificatePayload;
-export const runtimeCertificateUpdateSchema = certificatePayload.extend({
-    domains: z.array(z.string()).default([]),
-});
-export const runtimeCertificateValidateSchema = certificatePayload;
-export const runtimeCertificateMutationResponseSchema = z.object({
-    certificate: runtimeCertificateSchema.nullable(),
-    raw: z.record(z.string(), z.unknown()),
-});
-export const runtimeCertificateValidationResponseSchema = z.object({
-    valid: z.boolean(),
-    errors: z.array(z.string()),
-    warnings: z.array(z.string()),
-    validations: z.record(z.string(), z.record(z.string(), z.unknown())),
-});
-export const runtimeCertificateActivateSchema = z.object({
-    domains: z.array(z.string()).optional(),
-});
-export const runtimeCertificateActionResponseSchema = z.object({
-    ok: z.literal(true),
-    certificateId: z.number().int().positive(),
-    raw: z.record(z.string(), z.unknown()),
-});
-export const runtimeSslInfoSchema = z.object({
-    domain: z.string().min(1),
-    raw: z.record(z.string(), z.unknown()),
-});
-export const runtimeSslDomainSchema = z.object({
-    domain: z.string().min(1),
-});
-export const runtimeSslToggleSchema = runtimeSslDomainSchema.extend({
-    enabled: z.boolean(),
-});
-export const runtimeSslActionResponseSchema = z.object({
-    ok: z.literal(true),
-    domain: z.string().min(1),
-    raw: z.record(z.string(), z.unknown()),
 });