@spacefast/common 0.0.26 → 0.2.1

package/dist/contracts/tenants.d.ts

@@ -0,0 +1,135 @@
+import { z } from "zod";
+/**
+ * One manifest key's materialization status, as it surfaces on the tenant
+ * self-view. This is a projection, not the stored blob: the reconcile records a
+ * `declared` snapshot per item, but that (and any ownership proof inside it) is
+ * NEVER serialized to a partner surface — the self-view carries only where each
+ * key landed, not what was declared.
+ */
+export declare const ManifestStatusItemSchema: z.ZodObject<{
+    key: z.ZodString;
+    state: z.ZodEnum<{
+        active: "active";
+        failed: "failed";
+        pending: "pending";
+    }>;
+    detail: z.ZodOptional<z.ZodString>;
+    since: z.ZodString;
+    audience: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ManifestStatusItem = z.infer<typeof ManifestStatusItemSchema>;
+/**
+ * The materialization status of the tenant's system-space manifest: one item per
+ * declared key, plus the live version they were all converged from. Empty items
+ * with a null `sourceVersionId` means nothing is materialized (no designated
+ * system space, no live version, or an empty manifest).
+ */
+export declare const ManifestStatusSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        state: z.ZodEnum<{
+            active: "active";
+            failed: "failed";
+            pending: "pending";
+        }>;
+        detail: z.ZodOptional<z.ZodString>;
+        since: z.ZodString;
+        audience: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    sourceVersionId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ManifestStatus = z.infer<typeof ManifestStatusSchema>;
+/**
+ * A tenant's view of itself.
+ *
+ * Deliberately a self-view and not a tenant directory: a credential is rooted
+ * at exactly one tenant, so the only tenant it can read is its own. There is no
+ * list, and asking for another tenant's id is a refusal rather than an empty
+ * result.
+ *
+ * `provisioning.mode` is derived, not stored: a tenant whose sites run under
+ * its own provider client is `byo`, everything else is `managed`. That means
+ * the answer follows the actual account wiring instead of a flag someone has to
+ * remember to flip.
+ */
+export declare const TenantSelfSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        internal: "internal";
+        main: "main";
+        partner: "partner";
+    }>;
+    mode: z.ZodEnum<{
+        live: "live";
+        test: "test";
+    }>;
+    status: z.ZodEnum<{
+        active: "active";
+        past_due: "past_due";
+        suspended: "suspended";
+        deleted: "deleted";
+    }>;
+    name: z.ZodString;
+    defaultRegion: z.ZodNullable<z.ZodString>;
+    provisioning: z.ZodObject<{
+        mode: z.ZodEnum<{
+            managed: "managed";
+            byo: "byo";
+        }>;
+        providerClientId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    systemSpaceId: z.ZodNullable<z.ZodString>;
+    manifestStatus: z.ZodObject<{
+        items: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            state: z.ZodEnum<{
+                active: "active";
+                failed: "failed";
+                pending: "pending";
+            }>;
+            detail: z.ZodOptional<z.ZodString>;
+            since: z.ZodString;
+            audience: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        sourceVersionId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    presentation: z.ZodNullable<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        logo: z.ZodOptional<z.ZodString>;
+        supportUrl: z.ZodOptional<z.ZodString>;
+        claimOrigin: z.ZodOptional<z.ZodString>;
+        accessHandoffOrigin: z.ZodOptional<z.ZodString>;
+        problemDocsBaseUrl: z.ZodOptional<z.ZodString>;
+        contacts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type TenantSelf = z.infer<typeof TenantSelfSchema>;
+/**
+ * Compare-and-swap on the system space, house style: send the value you believe
+ * is current as `baseSystemSpaceId` and the write is rejected with a conflict
+ * if it has moved under you. Omit it to write unconditionally. This mirrors
+ * `baseSettingsDigest` on spaces — the CAS token rides in the body, not in an
+ * `If-Match` header.
+ */
+export declare const tenantPatchSchema: z.ZodObject<{
+    systemSpaceId: z.ZodNullable<z.ZodString>;
+    baseSystemSpaceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type TenantPatch = z.infer<typeof tenantPatchSchema>;
+export declare const TenantParamsSchema: z.ZodObject<{
+    tenantId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Promote the linked test tenant's system-space configuration onto this (live)
+ * tenant. An explicit export/copy, never a mode flip: the test tenant's
+ * system-space manifest (minus its token issuers, which each mode declares
+ * distinctly) is carried onto the live tenant's designated system space and
+ * reconciled with fresh ids and fresh verification. Test data stays test.
+ *
+ * No parameters today; the body is reserved for future promotion options
+ * (a subset of keys to promote, a dry-run, a CAS token).
+ */
+export declare const tenantPromoteSchema: z.ZodObject<{}, z.core.$strip>;
+export type TenantPromote = z.infer<typeof tenantPromoteSchema>;

package/dist/contracts/tenants.js

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import { tenantKind, tenantMode, tenantStatus } from "./enums.js";
+import { systemPresentationSchema } from "./space-config.js";
+/**
+ * One manifest key's materialization status, as it surfaces on the tenant
+ * self-view. This is a projection, not the stored blob: the reconcile records a
+ * `declared` snapshot per item, but that (and any ownership proof inside it) is
+ * NEVER serialized to a partner surface — the self-view carries only where each
+ * key landed, not what was declared.
+ */
+export const ManifestStatusItemSchema = z.object({
+    key: z.string().describe("The manifest key this item materializes."),
+    state: z
+        .enum(["pending", "active", "failed"])
+        .describe("Where the last reconcile landed this key."),
+    detail: z
+        .string()
+        .optional()
+        .describe("Human-readable reason, present when the state warrants one (typically `failed`)."),
+    since: z
+        .string()
+        .datetime()
+        .describe("When this key last CHANGED state — stable across no-op re-runs, so it reads as `<state> since …`."),
+    audience: z
+        .string()
+        .optional()
+        .describe("`tokenIssuers` only: the server-minted opaque audience for the issuer this key materialized. Not a secret — it rides in every partner token's `aud` claim and is verified server-side — and the partner needs it to sign the activation proof and to mint tokens, so it is served here rather than handed over out of band."),
+});
+/**
+ * The materialization status of the tenant's system-space manifest: one item per
+ * declared key, plus the live version they were all converged from. Empty items
+ * with a null `sourceVersionId` means nothing is materialized (no designated
+ * system space, no live version, or an empty manifest).
+ */
+export const ManifestStatusSchema = z.object({
+    items: z.array(ManifestStatusItemSchema).describe("Per-key materialization status."),
+    sourceVersionId: z
+        .string()
+        .nullable()
+        .describe("The system space's live version every item was converged from, or null when nothing is materialized."),
+});
+/**
+ * A tenant's view of itself.
+ *
+ * Deliberately a self-view and not a tenant directory: a credential is rooted
+ * at exactly one tenant, so the only tenant it can read is its own. There is no
+ * list, and asking for another tenant's id is a refusal rather than an empty
+ * result.
+ *
+ * `provisioning.mode` is derived, not stored: a tenant whose sites run under
+ * its own provider client is `byo`, everything else is `managed`. That means
+ * the answer follows the actual account wiring instead of a flag someone has to
+ * remember to flip.
+ */
+export const TenantSelfSchema = z.object({
+    id: z.string().describe("Tenant id."),
+    kind: tenantKind.describe("Tenant class."),
+    mode: tenantMode.describe("`test` for a linked test tenant (a sandbox twin), `live` otherwise. Distinct from `provisioning.mode`."),
+    status: tenantStatus.describe("Whether the tenant is active, past due, suspended, or deleted."),
+    name: z.string().describe("Human-readable tenant name."),
+    defaultRegion: z
+        .string()
+        .nullable()
+        .describe("Region new spaces are placed in unless one is requested; null means auto."),
+    provisioning: z
+        .object({
+        mode: z
+            .enum(["managed", "byo"])
+            .describe("`byo` when the tenant's sites run under its own provider client, `managed` when they run under ours."),
+        providerClientId: z
+            .string()
+            .nullable()
+            .describe("The tenant's own provider client (`pvc_`), when it has one."),
+    })
+        .describe("How this tenant's infrastructure is accounted for."),
+    systemSpaceId: z
+        .string()
+        .nullable()
+        .describe("Space designated as this tenant's own system surface (its dashboard, portal, or control page). Must be a space this tenant owns."),
+    manifestStatus: ManifestStatusSchema.describe("Materialization status of the system-space manifest, reconciled from that space's live version."),
+    presentation: systemPresentationSchema
+        .nullable()
+        .describe("The partner-facing branding and links currently materialized from the system-space manifest, or null when none is materialized."),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+});
+/**
+ * Compare-and-swap on the system space, house style: send the value you believe
+ * is current as `baseSystemSpaceId` and the write is rejected with a conflict
+ * if it has moved under you. Omit it to write unconditionally. This mirrors
+ * `baseSettingsDigest` on spaces — the CAS token rides in the body, not in an
+ * `If-Match` header.
+ */
+export const tenantPatchSchema = z.object({
+    systemSpaceId: z
+        .string()
+        .nullable()
+        .describe("Space to designate as the tenant's system surface, or null to clear it."),
+    baseSystemSpaceId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("The systemSpaceId the caller believes is current. When supplied and stale, the write is rejected instead of applied."),
+});
+export const TenantParamsSchema = z.object({
+    tenantId: z.string().min(1).describe("Tenant id. Must be the credential's own tenant."),
+});
+/**
+ * Promote the linked test tenant's system-space configuration onto this (live)
+ * tenant. An explicit export/copy, never a mode flip: the test tenant's
+ * system-space manifest (minus its token issuers, which each mode declares
+ * distinctly) is carried onto the live tenant's designated system space and
+ * reconciled with fresh ids and fresh verification. Test data stays test.
+ *
+ * No parameters today; the body is reserved for future promotion options
+ * (a subset of keys to promote, a dry-run, a CAS token).
+ */
+export const tenantPromoteSchema = z
+    .object({})
+    .describe("Promotion request. No parameters yet; reserved for future options.");

package/dist/contracts/test-triggers.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import type { TenantMode } from "./enums.js";
+export declare const testTriggerValues: readonly ["build_failure", "domain_verification_pending", "domain_verification_failed", "tls_failure", "rate_limit", "webhook_retry", "principal_suspension", "usage_correction"];
+export declare const testTrigger: z.ZodEnum<{
+    rate_limit: "rate_limit";
+    build_failure: "build_failure";
+    domain_verification_pending: "domain_verification_pending";
+    domain_verification_failed: "domain_verification_failed";
+    tls_failure: "tls_failure";
+    webhook_retry: "webhook_retry";
+    principal_suspension: "principal_suspension";
+    usage_correction: "usage_correction";
+}>;
+export type TestTrigger = z.infer<typeof testTrigger>;
+/**
+ * Every trigger, in one record: the reserved token, the input that carries it,
+ * and what a test tenant gets instead of success.
+ *
+ * `carrier` and `effect` are contract text, not commentary — the partner API
+ * document renders its trigger table straight from them, so a renamed token or
+ * a new trigger cannot leave the published contract describing something else.
+ *
+ * No token is a substring of another, so a plain `includes` scan is unambiguous.
+ * Keep them lowercase — the detector lowercases the input, and every carrier (a
+ * DNS label, a slug, a principal id) is compared case-insensitively.
+ */
+export declare const TEST_TRIGGER_META: {
+    readonly build_failure: {
+        readonly sentinel: "sf-sim-build-fail";
+        readonly carrier: "space slug";
+        readonly effect: "the space's next build fails";
+    };
+    readonly domain_verification_pending: {
+        readonly sentinel: "sf-sim-domain-pending";
+        readonly carrier: "custom domain name";
+        readonly effect: "domain verification stays pending";
+    };
+    readonly domain_verification_failed: {
+        readonly sentinel: "sf-sim-domain-fail";
+        readonly carrier: "custom domain name";
+        readonly effect: "domain verification fails";
+    };
+    readonly tls_failure: {
+        readonly sentinel: "sf-sim-tls-fail";
+        readonly carrier: "custom domain name";
+        readonly effect: "certificate issuance fails";
+    };
+    readonly rate_limit: {
+        readonly sentinel: "sf-sim-rate-limit";
+        readonly carrier: "space slug (on create)";
+        readonly effect: "the create returns 429 `rate_limited`";
+    };
+    readonly webhook_retry: {
+        readonly sentinel: "sf-sim-webhook-retry";
+        readonly carrier: "webhook URL";
+        readonly effect: "delivery fails and enters the retry schedule";
+    };
+    readonly principal_suspension: {
+        readonly sentinel: "sf-sim-suspend";
+        readonly carrier: "external principal id";
+        readonly effect: "the principal is suspended";
+    };
+    readonly usage_correction: {
+        readonly sentinel: "sf-sim-usage-correction";
+        readonly carrier: "space slug";
+        readonly effect: "the next settled usage sample appends a linked correction";
+    };
+};
+export declare function detectTestTrigger(input: string | null | undefined): TestTrigger | null;
+export declare function resolveTestTrigger(mode: TenantMode | string | null | undefined, input: string | null | undefined): TestTrigger | null;

package/dist/contracts/test-triggers.js

@@ -0,0 +1,116 @@
+// Reserved trigger values ("magic inputs") for LINKED TEST TENANTS
+// (partner-operations spec §1 "Test mode", L31-34). Stripe models test-mode
+// failures with magic inputs — a card number like `4000000000000341` that a
+// LIVE charge treats as an ordinary (invalid) number but a TEST charge turns
+// into a specific decline. We do the same for the partner API: a partner puts a
+// reserved token into the NATURAL input of an existing operation and, on a TEST
+// tenant only, that operation produces a specific failure state instead of
+// succeeding. There is NO new route and NO new field — a trigger is an ordinary
+// input value the caller already controls.
+//
+// The catalog itself is `TEST_TRIGGER_META` below — token, carrier and effect
+// per trigger, in one record, so the published API documentation renders from
+// the same data the detector matches on rather than a prose copy of it.
+//
+// The tokens carry a `sf-sim-` prefix so they are implausible as an organic name
+// and are valid across every carrier (a DNS label, a URL hostname, a slug, and a
+// principal id are all lowercase-hyphen-safe). A LIVE tenant treats the very same
+// value as ordinary input — the gate is `mode === "test"`, applied by every
+// interpreting call site (see `resolveTestTrigger`).
+//
+// FIDELITY (spec caveat): the `rate_limit` trigger FABRICATES a 429 problem
+// document — the partner-API rate limiter of ops §8 does not exist yet, so this
+// simulates the response a real limiter would return, not a real limiter. The
+// domain/TLS triggers synthesize provider (wp.cloud) SSL-info responses through
+// the simulated driver; there is no real DNS/cert in test mode.
+import { z } from "zod";
+export const testTriggerValues = [
+    "build_failure",
+    "domain_verification_pending",
+    "domain_verification_failed",
+    "tls_failure",
+    "rate_limit",
+    "webhook_retry",
+    "principal_suspension",
+    "usage_correction",
+];
+export const testTrigger = z.enum(testTriggerValues);
+/**
+ * Every trigger, in one record: the reserved token, the input that carries it,
+ * and what a test tenant gets instead of success.
+ *
+ * `carrier` and `effect` are contract text, not commentary — the partner API
+ * document renders its trigger table straight from them, so a renamed token or
+ * a new trigger cannot leave the published contract describing something else.
+ *
+ * No token is a substring of another, so a plain `includes` scan is unambiguous.
+ * Keep them lowercase — the detector lowercases the input, and every carrier (a
+ * DNS label, a slug, a principal id) is compared case-insensitively.
+ */
+export const TEST_TRIGGER_META = {
+    build_failure: {
+        sentinel: "sf-sim-build-fail",
+        carrier: "space slug",
+        effect: "the space's next build fails",
+    },
+    domain_verification_pending: {
+        sentinel: "sf-sim-domain-pending",
+        carrier: "custom domain name",
+        effect: "domain verification stays pending",
+    },
+    domain_verification_failed: {
+        sentinel: "sf-sim-domain-fail",
+        carrier: "custom domain name",
+        effect: "domain verification fails",
+    },
+    tls_failure: {
+        sentinel: "sf-sim-tls-fail",
+        carrier: "custom domain name",
+        effect: "certificate issuance fails",
+    },
+    rate_limit: {
+        sentinel: "sf-sim-rate-limit",
+        carrier: "space slug (on create)",
+        effect: "the create returns 429 `rate_limited`",
+    },
+    webhook_retry: {
+        sentinel: "sf-sim-webhook-retry",
+        carrier: "webhook URL",
+        effect: "delivery fails and enters the retry schedule",
+    },
+    principal_suspension: {
+        sentinel: "sf-sim-suspend",
+        carrier: "external principal id",
+        effect: "the principal is suspended",
+    },
+    usage_correction: {
+        sentinel: "sf-sim-usage-correction",
+        carrier: "space slug",
+        effect: "the next settled usage sample appends a linked correction",
+    },
+};
+// Return the trigger whose reserved token appears in `input`, or null. Carrier-
+// agnostic: `input` may be a slug, a hostname, a URL, or a principal id. The
+// token may be the whole value or a label within it (`sf-sim-tls-fail.acme.dev`).
+// This does NOT gate on mode — it is pure detection; `resolveTestTrigger` adds
+// the test-tenant gate.
+export function detectTestTrigger(input) {
+    if (!input)
+        return null;
+    const haystack = input.toLowerCase();
+    for (const trigger of testTriggerValues) {
+        if (haystack.includes(TEST_TRIGGER_META[trigger].sentinel))
+            return trigger;
+    }
+    return null;
+}
+// The one gate every interpreting call site shares: a trigger fires ONLY for a
+// `mode === "test"` tenant. A live tenant (or any non-test mode) always resolves
+// null, so the same input flows through the ordinary path — the no-leak-to-live
+// guarantee, in one place. `mode` is the owning tenant's mode (a `TenantMode`, or
+// the raw `tenants.mode` string).
+export function resolveTestTrigger(mode, input) {
+    if (mode !== "test")
+        return null;
+    return detectTestTrigger(input);
+}

package/dist/contracts/theme-json.js

@@ -1,13 +1,8 @@
 import { z } from "zod";
 // WordPress `theme.json`-compatible subset used only to infer Pages tokens.
-// Real WP theme.json carries dozens of unrelated keys (layout, blocks,
-// customTemplates, styles, ...); this schema accepts the file as a loose
-// object (`.passthrough()`) and only validates the two branches Pages
-// actually consume: `settings.color.palette` and
-// `settings.typography.fontFamilies`. Everything else rides through
-// unvalidated and is simply never read — this is not a reimplementation of
-// WP_Theme_JSON, just the safe slice that reaches presentation-only gate
-// pages.
+// The file is accepted as a loose object; only `settings.color.palette` and
+// `settings.typography.fontFamilies` are validated. Every other WP key rides
+// through unvalidated and is never read.
 const presetSlug = z
     .string()
     .min(1)

package/dist/contracts/transfers.d.ts

@@ -16,6 +16,7 @@ export declare const transferPrincipalSchema: z.ZodObject<{
     tenantId: z.ZodString;
 }, z.core.$strip>;
 export declare const spaceTransferCreateSchema: z.ZodObject<{
+    spaceId: z.ZodString;
     to: z.ZodObject<{
         principalType: z.ZodEnum<{
             team: "team";

package/dist/contracts/transfers.js

@@ -27,6 +27,7 @@ export const transferPrincipalSchema = transferPrincipalInputSchema.extend({
     tenantId: z.string().min(1).describe("Tenant both transfer parties live in."),
 });
 export const spaceTransferCreateSchema = z.object({
+    spaceId: z.string().min(1).describe("Space to transfer (`spc_`)."),
     to: transferPrincipalInputSchema.describe("Receiving principal. Must live in the space's tenant; cross-tenant transfers are unsupported."),
 });
 export const spaceTransferSchema = z.object({