@spacefast/common 0.2.1 → 0.4.1

package/dist/contracts/content.js

@@ -1,289 +1,39 @@
 import { z } from "zod";
-export const CONTENT_SCHEMA_FORMAT = "spacefast.content.schema";
-export const CONTENT_QUERY_FORMAT = "spacefast.content.query";
-export const CONTENT_SOURCE_FORMAT = "spacefast.content.source";
-export const CONTENT_RENDER_FORMAT = "spacefast.content.render";
-export const CONTENT_API_VERSION = 1;
-// The content model is authored as files in the Space and compiled at publish.
-// `content.config.ts` at the Space root is the entry module; sibling modules it
-// imports live under `content/`. Both are read out of the version being
-// published, so the compiled model is bound to that version and rolls back with
-// it. There is no API that mutates the content model out of band.
-export const CONTENT_CONFIG_FILE = "content.config.ts";
-export const CONTENT_CONFIG_DIRECTORY = "content/";
-export const CONTENT_CAPS = {
-    batchQueries: 25,
-    collections: 50,
-    fieldsPerCollection: 100,
-    filterClauses: 24,
-    pageSize: 100,
-    selectFields: 100,
-    sourceBytes: 2 * 1024 * 1024,
-    sourceFiles: 64,
-};
-const contentIdentifierSchema = z
-    .string()
-    .min(1)
-    .max(63)
-    .regex(/^[a-z][a-z0-9_-]*$/, "must start with a letter and contain lowercase letters, digits, _ or -");
-const contentFieldIdentifierSchema = z
-    .string()
-    .min(1)
-    .max(128)
-    .regex(/^[A-Za-z][A-Za-z0-9_-]*$/, "must start with a letter and contain letters, digits, _ or -");
-const contentSourcePathSchema = z
-    .string()
-    .min(1)
-    .max(240)
-    .regex(/^(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*\.(?:[cm]?[jt]sx?)$/, "must be a relative JavaScript or TypeScript module path");
-export const contentSourceBundleSchema = z
-    .object({
-    format: z.literal(CONTENT_SOURCE_FORMAT),
-    version: z.literal(CONTENT_API_VERSION),
-    entry: contentSourcePathSchema.default(CONTENT_CONFIG_FILE),
-    files: z
-        .record(contentSourcePathSchema, z.string().max(CONTENT_CAPS.sourceBytes))
-        .refine((files) => Object.keys(files).length <= CONTENT_CAPS.sourceFiles, {
-        message: `must contain at most ${CONTENT_CAPS.sourceFiles} files`,
+// What survives of the pre-content-model contracts: the one-use WordPress
+// editor session the dashboard opens. Everything the deleted
+// `@spacefast/content` client spoke — compile, activate, batch query, render,
+// document write, Markdown import — went with the routes that answered it, and
+// the batch-query read shape a Zero capsule used to be handed went with the
+// handler for it. A Space's content model is compiled at publish into
+// `content-model.php` and reached through the Abilities API; see
+// ./content-model.ts and ./content-model-sdk.ts.
+/**
+ * Where a content-editor launch lands.
+ *
+ * The requested screen selects the initial Zero view. The control plane turns
+ * it into a signed access grant before the runtime creates the session, so the
+ * iframe cannot widen its own navigation permissions.
+ *
+ * `collections` and `users` are the Content dashboard's two screens.
+ * Omitting the screen lands on WordPress's own admin, which is the escape
+ * hatch the dashboard opens in a new tab.
+ */
+export const contentAdminScreenSchema = z.enum(["collections", "users"]);
+export const contentAdminLaunchSchema = z
+    .object({ screen: contentAdminScreenSchema.optional() })
+    .strict();
+export const contentAdminAccessSchema = z.discriminatedUnion("surface", [
+    z
+        .object({
+        surface: z.literal("zero"),
+        initialScreen: contentAdminScreenSchema,
+        allowedScreens: z.union([
+            z.tuple([z.literal("collections")]),
+            z.tuple([z.literal("collections"), z.literal("users")]),
+        ]),
     })
-        .refine((files) => Object.entries(files).reduce((bytes, [name, source]) => bytes +
-        new TextEncoder().encode(name).byteLength +
-        new TextEncoder().encode(source).byteLength, 0) <= CONTENT_CAPS.sourceBytes, { message: `must contain at most ${CONTENT_CAPS.sourceBytes} bytes` }),
-    phpOnly: z.boolean().default(false),
-})
-    .strict()
-    .refine((bundle) => Object.hasOwn(bundle.files, bundle.entry), {
-    message: "entry must name one of files",
-    path: ["entry"],
-});
-export const contentCompileResponseSchema = z
-    .object({
-    revision: z.string().regex(/^[a-f0-9]{64}$/),
-    schemaVersion: z.number().int().positive(),
-    collections: z.number().int().nonnegative(),
-    fields: z.number().int().nonnegative(),
-    hooks: z.number().int().nonnegative(),
-    quickJsHooks: z.number().int().nonnegative(),
-})
-    .strict();
-// Activation points the Space's WordPress at an already-compiled release. A null
-// revision is the honest answer for a version that shipped no content config:
-// activating it leaves the Space with no managed content model, so rolling back
-// to a version from before the model existed restores exactly that.
-export const contentReleaseActivateResponseSchema = z
-    .object({
-    revision: z
-        .string()
-        .regex(/^[a-f0-9]{64}$/)
-        .nullable(),
-})
-    .strict();
-export const contentRenderInputSchema = z
-    .object({
-    format: z.literal(CONTENT_RENDER_FORMAT),
-    version: z.literal(CONTENT_API_VERSION),
-    collection: contentIdentifierSchema.default("posts"),
-    id: z.number().int().positive().optional(),
-    slug: z.string().trim().min(1).max(200).optional(),
-    field: contentFieldIdentifierSchema.default("content"),
-    output: z.enum(["blocks", "html"]).default("html"),
-})
-    .strict()
-    .refine((input) => (input.id === undefined) !== (input.slug === undefined), {
-    message: "set exactly one of id or slug",
-    path: ["id"],
-});
-export const contentRenderResponseSchema = z
-    .object({
-    id: z.number().int().positive(),
-    content: z.string(),
-    output: z.enum(["blocks", "html"]),
-})
-    .strict();
-const contentQueryKeySchema = z
-    .string()
-    .min(1)
-    .max(63)
-    .regex(/^[A-Za-z][A-Za-z0-9_-]*$/, "must be a safe query key");
-const contentLabelSchema = z.string().trim().min(1).max(120);
-const contentFieldBaseSchema = z.object({
-    label: contentLabelSchema,
-    required: z.boolean().default(false),
-    description: z.string().trim().max(500).optional(),
-});
-export const contentFieldSchema = z.discriminatedUnion("type", [
-    contentFieldBaseSchema.extend({
-        type: z.literal("text"),
-        multiline: z.boolean().default(false),
-        maxLength: z.number().int().positive().max(100_000).optional(),
-    }),
-    contentFieldBaseSchema.extend({ type: z.literal("markdown") }),
-    contentFieldBaseSchema.extend({ type: z.literal("richText") }),
-    contentFieldBaseSchema.extend({ type: z.literal("number") }),
-    contentFieldBaseSchema.extend({ type: z.literal("boolean") }),
-    contentFieldBaseSchema.extend({ type: z.literal("date") }),
-    contentFieldBaseSchema.extend({
-        type: z.literal("media"),
-        multiple: z.boolean().default(false),
-    }),
-    contentFieldBaseSchema.extend({
-        type: z.literal("relation"),
-        collection: contentIdentifierSchema,
-        multiple: z.boolean().default(false),
-    }),
-    contentFieldBaseSchema.extend({
-        type: z.literal("select"),
-        options: z.array(z.string().trim().min(1).max(120)).min(1).max(100),
-        multiple: z.boolean().default(false),
-    }),
-]);
-export const contentCollectionSchema = z
-    .object({
-    resourceId: z.string().min(8).max(96),
-    name: contentIdentifierSchema,
-    label: contentLabelSchema,
-    singularLabel: contentLabelSchema,
-    public: z.boolean().default(true),
-    fields: z
-        .record(contentFieldIdentifierSchema, contentFieldSchema)
-        .refine((fields) => Object.keys(fields).length <= CONTENT_CAPS.fieldsPerCollection, {
-        message: `must contain at most ${CONTENT_CAPS.fieldsPerCollection} fields`,
-    }),
-})
-    .strict();
-export const contentManifestSchema = z
-    .object({
-    format: z.literal(CONTENT_SCHEMA_FORMAT),
-    version: z.literal(CONTENT_API_VERSION),
-    collections: z
-        .record(contentIdentifierSchema, contentCollectionSchema)
-        .refine((collections) => Object.keys(collections).length <= CONTENT_CAPS.collections, {
-        message: `must contain at most ${CONTENT_CAPS.collections} collections`,
-    }),
-})
-    .strict()
-    .superRefine((manifest, context) => {
-    const resourceIds = new Map();
-    const collectionNames = new Set([
-        "posts",
-        "pages",
-        "media",
-        ...Object.keys(manifest.collections),
-    ]);
-    for (const [name, collection] of Object.entries(manifest.collections)) {
-        if (collection.name !== name) {
-            context.addIssue({
-                code: "custom",
-                message: `collection key "${name}" must match collection.name`,
-                path: ["collections", name, "name"],
-            });
-        }
-        if (name === "posts" || name === "pages" || name === "media") {
-            context.addIssue({
-                code: "custom",
-                message: `collection name "${name}" is reserved`,
-                path: ["collections", name],
-            });
-        }
-        const existingName = resourceIds.get(collection.resourceId);
-        if (existingName !== undefined) {
-            context.addIssue({
-                code: "custom",
-                message: `resourceId is already used by collection "${existingName}"`,
-                path: ["collections", name, "resourceId"],
-            });
-        }
-        else {
-            resourceIds.set(collection.resourceId, name);
-        }
-        for (const [fieldName, field] of Object.entries(collection.fields)) {
-            if (field.type === "relation" && !collectionNames.has(field.collection)) {
-                context.addIssue({
-                    code: "custom",
-                    message: `relation collection "${field.collection}" does not exist`,
-                    path: ["collections", name, "fields", fieldName, "collection"],
-                });
-            }
-        }
-    }
-});
-export const contentScalarSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
-const contentValueSchema = z.union([contentScalarSchema, z.array(contentScalarSchema).max(100)]);
-export const contentFilterSchema = z
-    .object({
-    field: contentFieldIdentifierSchema,
-    operator: z.enum(["eq", "neq", "in", "notIn", "gt", "gte", "lt", "lte", "contains", "exists"]),
-    value: contentValueSchema.optional(),
-})
-    .strict()
-    .superRefine((filter, context) => {
-    if (filter.operator !== "exists" && filter.value === undefined) {
-        context.addIssue({ code: "custom", message: "value is required", path: ["value"] });
-    }
-    if ((filter.operator === "in" || filter.operator === "notIn") && !Array.isArray(filter.value)) {
-        context.addIssue({ code: "custom", message: "value must be an array", path: ["value"] });
-    }
-});
-export const contentOrderSchema = z
-    .object({
-    field: contentFieldIdentifierSchema,
-    direction: z.enum(["asc", "desc"]).default("asc"),
-})
-    .strict();
-export const contentQuerySchema = z
-    .object({
-    collection: contentIdentifierSchema,
-    where: z.array(contentFilterSchema).max(CONTENT_CAPS.filterClauses).default([]),
-    orderBy: z.array(contentOrderSchema).max(1).default([]),
-    limit: z.number().int().positive().max(CONTENT_CAPS.pageSize).default(20),
-    cursor: z.string().min(1).max(512).optional(),
-    select: z.array(contentFieldIdentifierSchema).max(CONTENT_CAPS.selectFields).optional(),
-    status: z.enum(["publish", "draft", "any"]).default("publish"),
-})
-    .strict();
-export const contentBatchQueryRequestSchema = z
-    .object({
-    format: z.literal(CONTENT_QUERY_FORMAT),
-    version: z.literal(CONTENT_API_VERSION),
-    queries: z.record(contentQueryKeySchema, contentQuerySchema).refine((queries) => {
-        const length = Object.keys(queries).length;
-        return length > 0 && length <= CONTENT_CAPS.batchQueries;
-    }, { message: `must contain between 1 and ${CONTENT_CAPS.batchQueries} queries` }),
-})
-    .strict();
-export const contentItemSchema = z
-    .object({
-    id: z.number().int().positive(),
-    slug: z.string(),
-    status: z.string(),
-    title: z.string(),
-    createdAt: z.string(),
-    updatedAt: z.string(),
-    fields: z.record(z.string(), z.unknown()),
-})
-    .passthrough();
-export const contentQueryResultSchema = z.object({
-    items: z.array(contentItemSchema),
-    total: z.number().int().nonnegative(),
-    nextCursor: z.string().nullable(),
-});
-export const contentBatchQueryResponseSchema = z
-    .object({
-    format: z.literal(CONTENT_QUERY_FORMAT),
-    version: z.literal(CONTENT_API_VERSION),
-    results: z.record(contentQueryKeySchema, contentQueryResultSchema),
-})
-    .strict();
-const contentDocumentFields = {
-    collection: contentIdentifierSchema,
-    slug: z.string().trim().min(1).max(200),
-    title: z.string().max(500),
-    status: z.enum(["draft", "publish"]).default("draft"),
-    fields: z.record(contentFieldIdentifierSchema, z.unknown()).default({}),
-};
-export const contentDocumentInputSchema = z.union([
-    z.object({ ...contentDocumentFields, id: z.number().int().positive() }).strict(),
-    z.object({ ...contentDocumentFields, externalId: z.string().min(1).max(255) }).strict(),
+        .strict(),
+    z.object({ surface: z.literal("wordpress") }).strict(),
 ]);
 export const contentAdminSessionSchema = z
     .object({
@@ -291,13 +41,3 @@ export const contentAdminSessionSchema = z
     expiresAt: z.string().datetime(),
 })
     .strict();
-export const contentMarkdownSyncInputSchema = z
-    .object({
-    collection: contentIdentifierSchema.default("posts"),
-    markdown: z.string().max(200_000),
-    slug: z.string().trim().min(1).max(200),
-    source: z.string().trim().min(1).max(1_000),
-    status: z.enum(["draft", "publish"]).default("draft"),
-    title: z.string().max(500),
-})
-    .strict();

package/dist/contracts/dashboard-prefs.d.ts

@@ -24,6 +24,13 @@ export declare const dashboardPrefsPatchSchema: z.ZodRecord<z.ZodString, z.ZodUn
 export type DashboardPrefsPatch = z.infer<typeof dashboardPrefsPatchSchema>;
 /** The dashboard appearance key. */
 export declare const DASHBOARD_PREF_APPEARANCE = "appearance";
+/** Personal spaces-list layout, shared across teams. */
+export declare const DASHBOARD_PREF_SPACE_VIEW = "spaceView";
+export declare const spaceViewPreferenceSchema: z.ZodEnum<{
+    table: "table";
+    grid: "grid";
+}>;
+export type SpaceViewPreference = z.infer<typeof spaceViewPreferenceSchema>;
 /** Personal space favorites: the starred space ids, across every team. */
 export declare const DASHBOARD_PREF_SPACE_FAVORITES = "spaceFavorites";
 /**
@@ -44,9 +51,9 @@ export declare const DASHBOARD_PREF_SPACE_ORDERS = "spaceOrders";
 export declare const spaceOrdersPreferenceSchema: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
 export type SpaceOrdersPreference = z.infer<typeof spaceOrdersPreferenceSchema>;
 /**
- * Values the appearance preference may take. `system` follows the OS setting
- * live; the other two pin it. Mirrors the client-side `ThemePreference` union
- * in `@spacefast/app-shell/lib/theme`.
+ * `system` follows the OS setting live; the other two pin it. An absent account
+ * preference leaves the device choice alone. A device without a choice follows
+ * the system.
  */
 export declare const appearancePreferenceSchema: z.ZodEnum<{
     dark: "dark";

package/dist/contracts/dashboard-prefs.js

@@ -26,6 +26,9 @@ export const dashboardPrefsPatchSchema = z
     .describe("Preference keys to merge into the stored bag. A key set to `null` is deleted; every other key is overwritten. Keys you do not send are left alone.");
 /** The dashboard appearance key. */
 export const DASHBOARD_PREF_APPEARANCE = "appearance";
+/** Personal spaces-list layout, shared across teams. */
+export const DASHBOARD_PREF_SPACE_VIEW = "spaceView";
+export const spaceViewPreferenceSchema = z.enum(["grid", "table"]);
 /** Personal space favorites: the starred space ids, across every team. */
 export const DASHBOARD_PREF_SPACE_FAVORITES = "spaceFavorites";
 /**
@@ -44,8 +47,8 @@ export const DASHBOARD_PREF_SPACE_ORDERS = "spaceOrders";
  */
 export const spaceOrdersPreferenceSchema = z.record(z.string().max(64), z.array(z.string().max(64)).max(200));
 /**
- * Values the appearance preference may take. `system` follows the OS setting
- * live; the other two pin it. Mirrors the client-side `ThemePreference` union
- * in `@spacefast/app-shell/lib/theme`.
+ * `system` follows the OS setting live; the other two pin it. An absent account
+ * preference leaves the device choice alone. A device without a choice follows
+ * the system.
  */
 export const appearancePreferenceSchema = z.enum(["light", "dark", "system"]);

package/dist/contracts/data-location.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export declare const placementRegions: readonly ["ams", "bur", "dca", "dfw"];
+export declare const dataLocationSchema: z.ZodPipe<z.ZodString, z.ZodEnum<{
+    auto: "auto";
+    ams: "ams";
+    bur: "bur";
+    dca: "dca";
+    dfw: "dfw";
+}>>;

package/dist/contracts/data-location.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export const placementRegions = ["ams", "bur", "dca", "dfw"];
+export const dataLocationSchema = z
+    .string()
+    .trim()
+    .pipe(z.enum(["auto", ...placementRegions]))
+    .describe('Data location for a new Space; "auto" lets placement decide.');

package/dist/contracts/deployment-comparison.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+export declare const deploymentComparisonQuerySchema: z.ZodObject<{
+    baseVersionId: z.ZodString;
+    versionId: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const deploymentComparisonSchema: z.ZodObject<{
+    spaceId: z.ZodString;
+    view: z.ZodLiteral<"served">;
+    baseDeploymentVersionId: z.ZodString;
+    deploymentVersionId: z.ZodString;
+    baseVersionNumber: z.ZodNullable<z.ZodNumber>;
+    versionNumber: z.ZodNullable<z.ZodNumber>;
+    stats: z.ZodObject<{
+        files: z.ZodNumber;
+        added: z.ZodNumber;
+        modified: z.ZodNumber;
+        deleted: z.ZodNumber;
+    }, z.core.$strip>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        state: z.ZodEnum<{
+            deleted: "deleted";
+            added: "added";
+            modified: "modified";
+        }>;
+        before: z.ZodNullable<z.ZodObject<{
+            sha256: z.ZodString;
+            size: z.ZodNumber;
+            contentType: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+        after: z.ZodNullable<z.ZodObject<{
+            sha256: z.ZodString;
+            size: z.ZodNumber;
+            contentType: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    file: z.ZodNullable<z.ZodObject<{
+        path: z.ZodString;
+        before: z.ZodNullable<z.ZodString>;
+        after: z.ZodNullable<z.ZodString>;
+        beforeReason: z.ZodNullable<z.ZodEnum<{
+            unavailable: "unavailable";
+            binary: "binary";
+            not_present: "not_present";
+            too_large: "too_large";
+        }>>;
+        afterReason: z.ZodNullable<z.ZodEnum<{
+            unavailable: "unavailable";
+            binary: "binary";
+            not_present: "not_present";
+            too_large: "too_large";
+        }>>;
+    }, z.core.$strip>>;
+    sourceComparison: z.ZodNullable<z.ZodObject<{
+        repositoryId: z.ZodString;
+        baseSourceCommitSha: z.ZodString;
+        sourceCommitSha: z.ZodString;
+    }, z.core.$strip>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DeploymentComparison = z.infer<typeof deploymentComparisonSchema>;

package/dist/contracts/deployment-comparison.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { CursorPaginationSchema } from "./common.js";
+import { externalVersionFilePathSchema } from "./spaces.js";
+export const deploymentComparisonQuerySchema = z.object({
+    baseVersionId: z.string().min(1).max(64).describe("ID of the earlier deployment version."),
+    versionId: z.string().min(1).max(64).describe("ID of the deployment version to compare."),
+    path: externalVersionFilePathSchema
+        .max(1024)
+        .optional()
+        .describe("Read before-and-after text for this file path. Requires versions:download access."),
+    cursor: z
+        .string()
+        .max(4000)
+        .optional()
+        .describe("Copy the next cursor from this exact version comparison."),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(250)
+        .default(100)
+        .describe("Maximum changed paths to return."),
+});
+const artifactSchema = z.object({
+    sha256: z.string(),
+    size: z.number().int().nonnegative(),
+    contentType: z.string().nullable(),
+});
+const unavailableReasonSchema = z
+    .enum(["not_present", "binary", "too_large", "unavailable"])
+    .nullable();
+export const deploymentComparisonSchema = z.object({
+    spaceId: z.string(),
+    view: z.literal("served"),
+    baseDeploymentVersionId: z.string(),
+    deploymentVersionId: z.string(),
+    baseVersionNumber: z.number().int().nullable(),
+    versionNumber: z.number().int().nullable(),
+    stats: z.object({
+        files: z.number().int().nonnegative(),
+        added: z.number().int().nonnegative(),
+        modified: z.number().int().nonnegative(),
+        deleted: z.number().int().nonnegative(),
+    }),
+    files: z.array(z.object({
+        path: z.string(),
+        state: z.enum(["added", "modified", "deleted"]),
+        before: artifactSchema.nullable(),
+        after: artifactSchema.nullable(),
+    })),
+    file: z
+        .object({
+        path: z.string(),
+        before: z.string().nullable(),
+        after: z.string().nullable(),
+        beforeReason: unavailableReasonSchema,
+        afterReason: unavailableReasonSchema,
+    })
+        .nullable(),
+    sourceComparison: z
+        .object({
+        repositoryId: z.string(),
+        baseSourceCommitSha: z.string(),
+        sourceCommitSha: z.string(),
+    })
+        .nullable(),
+    pagination: CursorPaginationSchema,
+});