@spacefast/common 0.0.26 → 0.2.1

package/dist/contracts/commerce.d.ts

@@ -0,0 +1,165 @@
+import { z } from "zod";
+/**
+ * Partner commerce contracts (companion spec `2026-08-23-partner-commerce-design.md`
+ * §2 usage, §3 entitlements, and §4 principal lifecycle.
+ *
+ * This is the single home for the commercial layer: the principal lifecycle
+ * status/actor vocabulary, the per-tenant plan catalog declared in the
+ * system-space manifest, and the imperative plan-assignment request. The
+ * principal directory shape (`principals.ts`) and the manifest schema
+ * (`space-config.ts`) both import from here, so the vocabulary has one owner.
+ */
+export declare const PRINCIPAL_LIFECYCLE_STATUSES: readonly ["active", "suspended", "closed"];
+export declare const principalLifecycleStatusSchema: z.ZodEnum<{
+    active: "active";
+    suspended: "suspended";
+    closed: "closed";
+}>;
+export type PrincipalLifecycleStatus = z.infer<typeof principalLifecycleStatusSchema>;
+export declare const PRINCIPAL_STATUS_ACTORS: readonly ["partner", "spacefast"];
+export declare const principalStatusActorSchema: z.ZodEnum<{
+    spacefast: "spacefast";
+    partner: "partner";
+}>;
+export type PrincipalStatusActor = z.infer<typeof principalStatusActorSchema>;
+export declare const PLAN_CATALOG_CAPS: {
+    /** Max distinct plans a tenant may declare. */
+    readonly plans: 64;
+    /** Max plan-name length (also the assigned-plan and defaultPlan bound). */
+    readonly planNameChars: 64;
+    /** A plan can grant at most every known feature key. */
+    readonly features: number;
+};
+export declare const QUOTA_ENFORCEMENT_POLICIES: readonly ["warn", "block"];
+export declare const quotaEnforcementPolicySchema: z.ZodEnum<{
+    warn: "warn";
+    block: "block";
+}>;
+export type QuotaEnforcementPolicy = z.infer<typeof quotaEnforcementPolicySchema>;
+export declare const planCatalogEntrySchema: z.ZodObject<{
+    features: z.ZodArray<z.ZodEnum<{
+        zero: "zero";
+        "plans.paid.available": "plans.paid.available";
+        "anonymous.publishing": "anonymous.publishing";
+        "beta.enrollment_gate": "beta.enrollment_gate";
+        "domains.search": "domains.search";
+        "domains.registration": "domains.registration";
+        "domains.dns_management": "domains.dns_management";
+        "domains.wpcom_dns": "domains.wpcom_dns";
+        "domains.domain_connect": "domains.domain_connect";
+        "domains.proxy_bindings": "domains.proxy_bindings";
+        "collab.notices": "collab.notices";
+        "collab.comments": "collab.comments";
+        "content.managed": "content.managed";
+        "sites.dedicated_runtime": "sites.dedicated_runtime";
+        "collab.drawing": "collab.drawing";
+        tags: "tags";
+        functions: "functions";
+        "spaces.slug_rename": "spaces.slug_rename";
+        "pages.templates": "pages.templates";
+        "branding.hide": "branding.hide";
+    }>>;
+    quotas: z.ZodObject<{
+        spaces: z.ZodOptional<z.ZodNumber>;
+        storageBytes: z.ZodOptional<z.ZodNumber>;
+        buildMinutesPerMonth: z.ZodOptional<z.ZodNumber>;
+        customDomains: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    quotaPolicy: z.ZodOptional<z.ZodEnum<{
+        warn: "warn";
+        block: "block";
+    }>>;
+}, z.core.$strict>;
+export type PlanCatalogEntry = z.infer<typeof planCatalogEntrySchema>;
+export declare const planCatalogSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    features: z.ZodArray<z.ZodEnum<{
+        zero: "zero";
+        "plans.paid.available": "plans.paid.available";
+        "anonymous.publishing": "anonymous.publishing";
+        "beta.enrollment_gate": "beta.enrollment_gate";
+        "domains.search": "domains.search";
+        "domains.registration": "domains.registration";
+        "domains.dns_management": "domains.dns_management";
+        "domains.wpcom_dns": "domains.wpcom_dns";
+        "domains.domain_connect": "domains.domain_connect";
+        "domains.proxy_bindings": "domains.proxy_bindings";
+        "collab.notices": "collab.notices";
+        "collab.comments": "collab.comments";
+        "content.managed": "content.managed";
+        "sites.dedicated_runtime": "sites.dedicated_runtime";
+        "collab.drawing": "collab.drawing";
+        tags: "tags";
+        functions: "functions";
+        "spaces.slug_rename": "spaces.slug_rename";
+        "pages.templates": "pages.templates";
+        "branding.hide": "branding.hide";
+    }>>;
+    quotas: z.ZodObject<{
+        spaces: z.ZodOptional<z.ZodNumber>;
+        storageBytes: z.ZodOptional<z.ZodNumber>;
+        buildMinutesPerMonth: z.ZodOptional<z.ZodNumber>;
+        customDomains: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    quotaPolicy: z.ZodOptional<z.ZodEnum<{
+        warn: "warn";
+        block: "block";
+    }>>;
+}, z.core.$strict>>;
+export type PlanCatalog = z.infer<typeof planCatalogSchema>;
+export declare const defaultPlanNameSchema: z.ZodString;
+export declare const materializedPlanCatalogSchema: z.ZodObject<{
+    plans: z.ZodRecord<z.ZodString, z.ZodObject<{
+        features: z.ZodArray<z.ZodEnum<{
+            zero: "zero";
+            "plans.paid.available": "plans.paid.available";
+            "anonymous.publishing": "anonymous.publishing";
+            "beta.enrollment_gate": "beta.enrollment_gate";
+            "domains.search": "domains.search";
+            "domains.registration": "domains.registration";
+            "domains.dns_management": "domains.dns_management";
+            "domains.wpcom_dns": "domains.wpcom_dns";
+            "domains.domain_connect": "domains.domain_connect";
+            "domains.proxy_bindings": "domains.proxy_bindings";
+            "collab.notices": "collab.notices";
+            "collab.comments": "collab.comments";
+            "content.managed": "content.managed";
+            "sites.dedicated_runtime": "sites.dedicated_runtime";
+            "collab.drawing": "collab.drawing";
+            tags: "tags";
+            functions: "functions";
+            "spaces.slug_rename": "spaces.slug_rename";
+            "pages.templates": "pages.templates";
+            "branding.hide": "branding.hide";
+        }>>;
+        quotas: z.ZodObject<{
+            spaces: z.ZodOptional<z.ZodNumber>;
+            storageBytes: z.ZodOptional<z.ZodNumber>;
+            buildMinutesPerMonth: z.ZodOptional<z.ZodNumber>;
+            customDomains: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        quotaPolicy: z.ZodOptional<z.ZodEnum<{
+            warn: "warn";
+            block: "block";
+        }>>;
+    }, z.core.$strict>>;
+    defaultPlan: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type MaterializedPlanCatalog = z.infer<typeof materializedPlanCatalogSchema>;
+export declare const PRINCIPAL_STATUS_REASON_CHARS = 512;
+export declare const principalSuspendSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PrincipalSuspend = z.infer<typeof principalSuspendSchema>;
+export declare const principalUnsuspendSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PrincipalUnsuspend = z.infer<typeof principalUnsuspendSchema>;
+export declare const principalCloseSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+    force: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type PrincipalClose = z.infer<typeof principalCloseSchema>;
+export declare const principalPlanAssignSchema: z.ZodObject<{
+    plan: z.ZodString;
+}, z.core.$strict>;
+export type PrincipalPlanAssign = z.infer<typeof principalPlanAssignSchema>;

package/dist/contracts/commerce.js

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import { FEATURE_KEYS, featureKeySchema } from "./features.js";
+/**
+ * Partner commerce contracts (companion spec `2026-08-23-partner-commerce-design.md`
+ * §2 usage, §3 entitlements, and §4 principal lifecycle.
+ *
+ * This is the single home for the commercial layer: the principal lifecycle
+ * status/actor vocabulary, the per-tenant plan catalog declared in the
+ * system-space manifest, and the imperative plan-assignment request. The
+ * principal directory shape (`principals.ts`) and the manifest schema
+ * (`space-config.ts`) both import from here, so the vocabulary has one owner.
+ */
+// Principal lifecycle status (§4). `active` is the default; `suspended` is
+// reversible (spaces serve the suspended page, mutations rejected); `closed` is
+// terminal (retention window then deletion).
+export const PRINCIPAL_LIFECYCLE_STATUSES = ["active", "suspended", "closed"];
+export const principalLifecycleStatusSchema = z
+    .enum(PRINCIPAL_LIFECYCLE_STATUSES)
+    .describe("Principal lifecycle status: active, suspended (reversible), or closed (terminal).");
+// Who applied the current status. `partner` is the tenant's own management key;
+// `spacefast` is a platform-applied (legal/abuse) action the partner cannot
+// lift. The status surface distinguishes the actor so a Spacefast suspension is
+// visibly unliftable by the partner (§4).
+export const PRINCIPAL_STATUS_ACTORS = ["partner", "spacefast"];
+export const principalStatusActorSchema = z
+    .enum(PRINCIPAL_STATUS_ACTORS)
+    .describe("Actor that applied the current status: the partner, or Spacefast.");
+// Bounds for the plan catalog. Self-contained (not in SPACE_CONFIG_CAPS) so the
+// manifest schema imports from commerce, never the reverse. A plan may grant at
+// most every known feature; plan names are short arbitrary per-tenant strings.
+export const PLAN_CATALOG_CAPS = {
+    /** Max distinct plans a tenant may declare. */
+    plans: 64,
+    /** Max plan-name length (also the assigned-plan and defaultPlan bound). */
+    planNameChars: 64,
+    /** A plan can grant at most every known feature key. */
+    features: FEATURE_KEYS.length,
+};
+const planNameSchema = z.string().trim().min(1).max(PLAN_CATALOG_CAPS.planNameChars);
+// How a tripped quota is enforced (companion spec §3c). `block` rejects the
+// triggering mutation with a typed problem naming the quota; `warn` records an
+// event and lets the mutation through. Serving is NEVER cut by quota — only by
+// suspension (§4). Omitted = `block`.
+export const QUOTA_ENFORCEMENT_POLICIES = ["warn", "block"];
+export const quotaEnforcementPolicySchema = z
+    .enum(QUOTA_ENFORCEMENT_POLICIES)
+    .describe("How a tripped quota is enforced: warn (event only) or block (reject).");
+const quotaLimitSchema = z.number().int().safe().nonnegative();
+// One plan's entitlements: feature keys plus mutation-time quotas. Feature
+// names are validated against the live `FEATURE_KEYS` vocabulary.
+export const planCatalogEntrySchema = z
+    .object({
+    features: z
+        .array(featureKeySchema)
+        .max(PLAN_CATALOG_CAPS.features)
+        .describe("Feature keys this plan grants. Each must be a known Spacefast feature key."),
+    quotas: z
+        .object({
+        spaces: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("Max spaces a principal on this plan may own. Omitted = no space-count cap."),
+        storageBytes: quotaLimitSchema
+            .optional()
+            .describe("Max measured bytes stored by the principal. Omitted = no storage cap."),
+        buildMinutesPerMonth: quotaLimitSchema
+            .optional()
+            .describe("Max build minutes in one UTC month. Omitted = no monthly build cap."),
+        customDomains: quotaLimitSchema
+            .optional()
+            .describe("Max active custom domains. Omitted = no custom-domain cap."),
+    })
+        .strict()
+        .describe("Quotas that the platform checks at the mutation that can exceed each limit."),
+    quotaPolicy: quotaEnforcementPolicySchema
+        .optional()
+        .describe("Enforcement policy for this plan's quotas. Omitted = block."),
+})
+    .strict()
+    .describe("Entitlements for one plan: granted features and enforced quotas.");
+// The per-tenant plan catalog: plan name → entitlements. Plan NAMES are
+// arbitrary per-tenant strings (the reseller's own vocabulary); feature keys
+// inside each plan are the fixed Spacefast vocabulary.
+export const planCatalogSchema = z
+    .record(planNameSchema, planCatalogEntrySchema)
+    .refine((plans) => Object.keys(plans).length <= PLAN_CATALOG_CAPS.plans, `at most ${PLAN_CATALOG_CAPS.plans} plans`)
+    .describe("Per-tenant plan catalog declared in the system-space manifest.");
+// The plan unassigned principals fall back to. A bare name here; the manifest
+// schema cross-checks it against the declared `plans` keys.
+export const defaultPlanNameSchema = planNameSchema.describe("Name of the plan unassigned principals fall back to. Must be a key in `plans`.");
+// What the plan-catalog materializer freezes onto the tenant: the declared
+// catalog paired with the manifest's `defaultPlan` (null when the manifest
+// declared `plans` without a default). Entitlement resolution reads this one
+// blob — the assigned plan resolves against `plans`, and an unassigned or
+// stale principal falls back to `defaultPlan`.
+export const materializedPlanCatalogSchema = z
+    .object({
+    plans: planCatalogSchema,
+    defaultPlan: defaultPlanNameSchema.nullable(),
+})
+    .strict()
+    .describe("Materialized per-tenant plan catalog: the declared plans plus the default plan name.");
+// The free-text reason a lifecycle transition records on the principal
+// (`external_principals.status_reason`, bounded by the column). Optional on
+// every transition; surfaced back on the principal so an operator sees why.
+export const PRINCIPAL_STATUS_REASON_CHARS = 512;
+const statusReasonSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(PRINCIPAL_STATUS_REASON_CHARS)
+    .describe("Free-text reason recorded with the status change.");
+// Suspend a principal (§4): reversibly darken its spaces (402 suspended page)
+// and reject its mutations. Idempotent.
+export const principalSuspendSchema = z
+    .object({ reason: statusReasonSchema.optional() })
+    .strict()
+    .describe("Suspend an external principal: its spaces serve the suspended page and writes are blocked.");
+// Lift a suspension (§4). A partner may only lift a suspension it applied; a
+// Spacefast-applied (legal/abuse) suspension is not liftable by the partner.
+export const principalUnsuspendSchema = z
+    .object({ reason: statusReasonSchema.optional() })
+    .strict()
+    .describe("Lift a principal suspension and restore its spaces.");
+// Close a principal (§4): terminal. Refused while the principal still owns
+// spaces unless `force` tombstones them in the same call. Idempotent.
+export const principalCloseSchema = z
+    .object({
+    reason: statusReasonSchema.optional(),
+    force: z
+        .boolean()
+        .optional()
+        .describe("Tombstone the principal's remaining spaces instead of refusing the close."),
+})
+    .strict()
+    .describe("Close an external principal (terminal). Requires no owned spaces, or `force` to tombstone them.");
+// Imperative plan assignment (§3b): `PUT /v1/principals/{type}/{id}/plan` with a
+// plan name from the live manifest. Runtime state, not manifest config.
+export const principalPlanAssignSchema = z
+    .object({
+    plan: planNameSchema.describe("Plan name from the live system-space manifest to assign to this principal."),
+})
+    .strict()
+    .describe("Assign a principal to a plan from the tenant's live plan catalog.");

package/dist/contracts/common.d.ts

@@ -9,8 +9,8 @@ export declare const baseDiagnosticSchema: 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>>;
@@ -176,8 +176,8 @@ export declare const AsyncOperationSchema: 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>>;
@@ -220,8 +220,8 @@ export declare function mutationEnvelope<T extends z.ZodType>(data: T): z.ZodObj
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;

package/dist/contracts/common.js

@@ -6,14 +6,13 @@ export const SpaceViewerSchema = z.object({
     description: z.string().nullable(),
     ogImagePath: z.string().nullable(),
 });
-// The ONE Diagnostic shape (the platform spec). Every lifecycle
-// resource (versions, builds, bindings, assignments, exports, imports, transfers)
+// The ONE Diagnostic shape (the platform spec). Every lifecycle resource
 // carries `diagnostics: Diagnostic[]` using exactly this vocabulary.
 export const baseDiagnosticSchema = z.object({
     code: z
         .string()
         .describe("Stable snake_case diagnostic code naming the public contract that produced it."),
-    severity: diagnosticSeverity.describe("How actionable the diagnostic is: info, warning, error."),
+    severity: diagnosticSeverity.describe("How actionable the diagnostic is."),
     message: z.string().describe("Human-readable explanation with enough detail to act on."),
     path: z
         .string()
@@ -26,7 +25,7 @@ export const baseDiagnosticSchema = z.object({
     fix: z
         .string()
         .nullish()
-        .describe("Concrete, agent-actionable remediation hint for this diagnostic (react-doctor model), when one can be derived."),
+        .describe("Concrete, agent-actionable remediation hint, when one can be derived."),
     retryable: z
         .boolean()
         .nullish()
@@ -41,9 +40,9 @@ export const DnsInstructionSchema = z.object({
     ttl: z.number().int().optional(),
     purpose: z.enum(["verification", "routing", "ssl"]).describe("Why this record is needed."),
 });
-// One shared requiredActions vocabulary (the platform spec):
-// lifecycle resources expose the concrete user steps that unblock them. New action types are
-// added HERE, never as per-resource variants.
+// One shared requiredActions vocabulary (the platform spec): the concrete user
+// steps that unblock a resource. New action types are added HERE, never
+// as per-resource variants.
 export const requiredActionSchema = z.discriminatedUnion("type", [
     z
         .object({
@@ -64,14 +63,13 @@ export const requiredActionSchema = z.discriminatedUnion("type", [
 export const requiredActionsSchema = z
     .array(requiredActionSchema)
     .describe("Concrete user steps that unblock this resource, using the one shared vocabulary.");
-// The error shape (the platform spec "Global API Conventions"): every 4xx/5xx body
-// is one RFC 9457 problem details document served as `application/problem+json`. `type` and
-// `title` are derived mechanically from `code` (see contracts/error-codes.ts); `code`,
-// `pointer` (RFC 6901), `details`, `suggestions`, `next`, and `requestId` are extension members.
+// The error shape (the platform spec "Global API Conventions"): every 4xx/5xx
+// body is one RFC 9457 problem document served as `application/problem+json`.
+// `type` and `title` derive mechanically from `code` (see contracts/error-codes.ts).
 export const ProblemDetailsSchema = z.object({
     type: z
         .string()
-        .describe("Problem type URI. It resolves to the error docs page. The server derives it mechanically from `code` against the docs origin."),
+        .describe("Problem type URI resolving to the error docs page. The server derives it mechanically from `code` against the docs origin."),
     title: z
         .string()
         .describe("Short human-readable summary of the problem type. The server derives it mechanically from `code`."),
@@ -95,7 +93,7 @@ export const ProblemDetailsSchema = z.object({
 });
 // Success envelope (the platform spec "Global API Conventions"): `{ data: T }` for
 // single resources and mutations, `{ data: T[], pagination }` for lists. Mutations whose work
-// outlives the request also carry `operation` — wrap with `.extend({ operation: ... })`.
+// outlives the request also carry `operation`. Wrap with `.extend({ operation: ... })`.
 export function dataEnvelope(data) {
     return z.object({ data });
 }
@@ -121,16 +119,10 @@ export const CursorPaginationSchema = z.object({
     hasMore: z.boolean().describe("Whether another page exists after this one."),
 });
 export const CURSOR_MAX_LENGTH = 4_096;
-// The ONE list query shape (default 20, max 100, opaque cursor, newest-first). Extend with
-// module-specific filters; never redeclare `limit`/`cursor`.
+// The ONE list query shape, newest-first. Extend with module-specific filters;
+// never redeclare `limit`/`cursor`.
 export const cursorListQuerySchema = z.object({
-    limit: z.coerce
-        .number()
-        .int()
-        .min(1)
-        .max(100)
-        .default(20)
-        .describe("Page size: default 20, maximum 100."),
+    limit: z.coerce.number().int().min(1).max(100).default(20).describe("Page size."),
     cursor: z
         .string()
         .min(1)
@@ -138,9 +130,7 @@ export const cursorListQuerySchema = z.object({
         .optional()
         .describe("Opaque cursor from the previous page's `nextCursor`."),
 });
-// The operator-only offset list-response shape (superadmin surfaces): the named
-// items array, plus `total`/`limit`/`offset` and the offset `pagination` block.
-// Callers pass the items key, item schema, and their pagination schema so the
+// The operator-only offset list-response shape (superadmin surfaces). The
 // emitted object is byte-for-byte the hand-written
 // `z.object({ <key>: z.array(...), total, limit, offset, pagination })`.
 export function makeOffsetListSchema(itemsKey, item, pagination) {
@@ -172,10 +162,9 @@ export const AsyncOperationSchema = z.object({
     createdAt: z.string().datetime(),
     finishedAt: z.string().datetime().optional(),
 });
-// Mutation envelope for async-capable verbs: the post-mutation resource in `data`
-// plus `operation` when work outlives the request (poll the resource or the
-// operation). `operation` is always present and null when the mutation completed
-// synchronously, so the wire shape is deterministic per route.
+// Mutation envelope for async-capable verbs: the post-mutation resource in
+// `data`, plus `operation` when work outlives the request. `operation` is always
+// present, so the wire shape is deterministic per route.
 export function mutationEnvelope(data) {
     return z.object({
         data,