@spacefast/common 0.0.2

package/dist/contracts/features.js

@@ -0,0 +1,406 @@
+import { z } from "zod";
+// Spec plan vocabulary (internal-docs/platform.md "Plans And Limits").
+// `enterprise` and `internal` are named plans without self-serve pricing.
+export const PLAN_CODES = ["free", "personal", "work", "enterprise", "internal"];
+export const planCodeSchema = z.enum(PLAN_CODES).describe("Plan code.");
+export const DEFAULT_PLAN_CODE = "free";
+export const FEATURE_KEYS = [
+    "plans.paid.available",
+    "anonymous.publishing",
+    "beta.enrollment_gate",
+    "domains.search",
+    "domains.registration",
+    "domains.dns_management",
+    "domains.proxy_bindings",
+    "annotations.preview_loader",
+    "annotations.comments",
+    "annotations.anonymous_reviewers",
+    "annotations.cli",
+    "annotations.notices",
+    "annotations.spacefast_token",
+    "annotations.published_comments",
+    "sites.dedicated_runtime",
+    "shelf",
+    "tags",
+    "zero",
+];
+export const featureKeySchema = z.enum(FEATURE_KEYS).describe("Feature flag key.");
+// Feature override states (env `SPACEFAST_FLAG_*` and the feature_overrides
+// table). `kill_switch` short-circuits every other resolution layer.
+export const FEATURE_OVERRIDE_STATES = ["enabled", "disabled", "kill_switch"];
+export const featureOverrideStateSchema = z.enum(FEATURE_OVERRIDE_STATES);
+export const planLimitValueSchema = z
+    .union([z.number().int().nonnegative(), z.literal("unlimited")])
+    .describe('Plan limit value; "unlimited" when the plan does not bound this axis.');
+// Named plan limit table (internal-docs/platform.md "Plans And Limits",
+// Free/Personal/Work columns verbatim). Keys mirror `PlanPolicyResponse.limits`
+// so plan policy is a projection of this data, never a re-derivation.
+export const planLimitsSchema = z
+    .object({
+    storageBytes: planLimitValueSchema,
+    teamMembers: planLimitValueSchema,
+    subTeams: planLimitValueSchema,
+    externalDomainGroups: planLimitValueSchema,
+    publicImmutableVersionWindowDays: planLimitValueSchema,
+    // Version retention (charter arbitration A3, internal plan data — never on
+    // the PlanPolicyResponse wire shape): `versionRetentionDays` is the included
+    // full-retention window; after it versions stay stored but gated until
+    // `versionGatedKeepDays` from readyAt, then retention-delete with notice.
+    // Live and channel-referenced versions are never retention-deleted.
+    versionRetentionDays: planLimitValueSchema,
+    versionGatedKeepDays: planLimitValueSchema,
+    // Per-space daily bandwidth cap feeding the egress kill-switch sweep
+    // (internal-docs/platform.md "Abuse Posture"; internal plan data — never on
+    // the PlanPolicyResponse wire shape). WORST_CASE_QUOTAS
+    // .maxEgressBytesPerSpacePerDay stays the absolute platform ceiling.
+    egressBytesPerDay: planLimitValueSchema,
+    maxFileBytes: planLimitValueSchema,
+    // Files per version. Plan policy may LOWER the 100k contract ceiling
+    // (Free 20,000), never raise it; the validator clamps at the ceiling.
+    maxVersionFiles: planLimitValueSchema,
+    routingRules: planLimitValueSchema,
+    auditLogRetentionHours: planLimitValueSchema,
+    buildAccessLogRetentionHours: planLimitValueSchema,
+    // One pooled limit on purpose: pricing never separates user pushes from CI builds.
+    buildsDeploysMonthly: planLimitValueSchema,
+    // Queryable analytics history window. Storage retains rollups for everyone
+    // (env-bounded); this only clamps how far back the analytics API serves.
+    analyticsRetentionDays: planLimitValueSchema,
+})
+    .describe("Named plan limit table.");
+// Resolved team entitlements: plan limits after add-on grants plus the
+// capability dials that are not number|"unlimited" limits. Served by
+// `GET /v1/teams/{teamId}/entitlements`.
+export const teamEntitlementsSchema = z
+    .object({
+    planCode: planCodeSchema,
+    limits: planLimitsSchema,
+    headersBasicAuth: z
+        .boolean()
+        .describe("Whether `_headers` Basic-Auth rules compile on this plan."),
+    externalProxy: z.boolean().describe("Whether external proxy upstreams compile on this plan."),
+    runtimePhpWorkers: z.number().int().describe("PHP workers per serving site."),
+    analyticsHourlyGranularity: z
+        .boolean()
+        .describe("Whether analytics series resolve to hourly buckets (daily otherwise)."),
+    versionDiagnosticsIncluded: z
+        .boolean()
+        .describe("Whether version diagnostics are included with the plan."),
+})
+    .describe("Resolved entitlements for a team: plan limits after add-on grants.");
+// Wire projection of TeamEntitlements for GET /v1/teams/{teamId}/entitlements.
+// `versionRetentionDays`/`versionGatedKeepDays` (charter A3) and
+// `egressBytesPerDay` (abuse posture) are internal plan data — never on a wire
+// shape, mirroring PlanPolicyResponse's deliberate exclusion.
+export const teamEntitlementsResponseSchema = teamEntitlementsSchema
+    .extend({
+    limits: planLimitsSchema.omit({
+        versionRetentionDays: true,
+        versionGatedKeepDays: true,
+        egressBytesPerDay: true,
+    }),
+})
+    .describe("Resolved entitlements for a team: plan limits after add-on grants.");
+const GB = 1024 * 1024 * 1024;
+const MB = 1024 * 1024;
+const MONTH_HOURS = 30 * 24;
+const UNLIMITED_LIMITS = {
+    storageBytes: "unlimited",
+    teamMembers: "unlimited",
+    subTeams: "unlimited",
+    externalDomainGroups: "unlimited",
+    publicImmutableVersionWindowDays: "unlimited",
+    versionRetentionDays: "unlimited",
+    versionGatedKeepDays: "unlimited",
+    egressBytesPerDay: "unlimited",
+    maxFileBytes: "unlimited",
+    maxVersionFiles: "unlimited",
+    routingRules: "unlimited",
+    auditLogRetentionHours: "unlimited",
+    buildAccessLogRetentionHours: "unlimited",
+    buildsDeploysMonthly: "unlimited",
+    analyticsRetentionDays: "unlimited",
+};
+export const PLAN_DEFINITIONS = {
+    free: {
+        code: "free",
+        name: "Free",
+        monthlyPriceUsd: 0,
+        limits: {
+            storageBytes: 5 * GB,
+            teamMembers: 3,
+            subTeams: 0,
+            externalDomainGroups: 1,
+            publicImmutableVersionWindowDays: 7,
+            versionRetentionDays: 30, // included full-retention window (charter A3)
+            versionGatedKeepDays: 183, // kept gated ~6 months from readyAt, then deleted
+            egressBytesPerDay: 100 * GB, // = worst-case ceiling; tunable per plan
+            maxFileBytes: 50 * MB,
+            maxVersionFiles: 20_000,
+            routingRules: 10,
+            auditLogRetentionHours: 48,
+            buildAccessLogRetentionHours: 48,
+            buildsDeploysMonthly: 100,
+            analyticsRetentionDays: 30,
+        },
+        headersBasicAuth: false,
+        externalProxy: false,
+        runtimePhpWorkers: 2,
+        analyticsHourlyGranularity: false,
+    },
+    personal: {
+        code: "personal",
+        name: "Personal",
+        monthlyPriceUsd: 5,
+        limits: {
+            ...UNLIMITED_LIMITS,
+            storageBytes: 20 * GB,
+            teamMembers: 5,
+            subTeams: 0,
+            externalDomainGroups: 10,
+            maxFileBytes: 1 * GB,
+            routingRules: 1000,
+            auditLogRetentionHours: MONTH_HOURS,
+            buildAccessLogRetentionHours: MONTH_HOURS,
+            buildsDeploysMonthly: 1000,
+            analyticsRetentionDays: 365,
+        },
+        headersBasicAuth: true,
+        externalProxy: true,
+        runtimePhpWorkers: 4,
+        analyticsHourlyGranularity: true,
+    },
+    work: {
+        code: "work",
+        name: "Work",
+        monthlyPriceUsd: 15,
+        limits: {
+            ...UNLIMITED_LIMITS,
+            storageBytes: 50 * GB,
+            // 15 seats included; the $1/seat add-on rides EntitlementGrant
+            // ({ limit: "teamMembers", add: n }) — grants are no-ops on
+            // "unlimited" limits, so this must stay numeric.
+            teamMembers: 15,
+            subTeams: 0,
+        },
+        headersBasicAuth: true,
+        externalProxy: true,
+        runtimePhpWorkers: 4,
+        analyticsHourlyGranularity: true,
+    },
+    // Footnote-only publicly ("custom — talk to us"); manual grant, never self-serve.
+    enterprise: {
+        code: "enterprise",
+        name: "Enterprise",
+        monthlyPriceUsd: null,
+        limits: { ...UNLIMITED_LIMITS },
+        headersBasicAuth: true,
+        externalProxy: true,
+        runtimePhpWorkers: 4,
+        analyticsHourlyGranularity: true,
+    },
+    internal: {
+        code: "internal",
+        name: "Internal",
+        monthlyPriceUsd: null,
+        limits: { ...UNLIMITED_LIMITS },
+        headersBasicAuth: true,
+        externalProxy: true,
+        runtimePhpWorkers: 4,
+        analyticsHourlyGranularity: true,
+    },
+};
+export const FEATURE_DEFINITIONS = {
+    "plans.paid.available": {
+        key: "plans.paid.available",
+        name: "Paid plans available",
+        description: "Controls whether paid plan upgrade and management surfaces are available.",
+        defaultEnabled: false,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "anonymous.publishing": {
+        key: "anonymous.publishing",
+        name: "Anonymous publishing",
+        description: "Allows unauthenticated space creation and publishing.",
+        defaultEnabled: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    // Flipped in prod via env (`SPACEFAST_FLAG_BETA_ENROLLMENT_GATE`), so launch
+    // day is an env flip, not a deploy — exact precedent of anonymous.publishing.
+    "beta.enrollment_gate": {
+        key: "beta.enrollment_gate",
+        name: "Beta enrollment gate",
+        description: "Gates the whole API behind private-beta enrollment; non-enrolled credentials get 403 not_enrolled.",
+        defaultEnabled: false,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "domains.search": {
+        key: "domains.search",
+        name: "Domain search",
+        description: "Allows domain availability search and suggestion surfaces.",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "domains.registration": {
+        key: "domains.registration",
+        name: "Domain registration",
+        description: "Allows domain registration, purchase, and transfer-in surfaces.",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "domains.dns_management": {
+        key: "domains.dns_management",
+        name: "DNS management",
+        description: "Allows customer DNS zone, nameserver, and record-management surfaces.",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "domains.proxy_bindings": {
+        key: "domains.proxy_bindings",
+        name: "Domain proxy bindings",
+        description: "Allow a team to proxy custom-domain traffic to an external HTTP upstream.",
+        defaultEnabled: false,
+        enabledForA8c: true,
+        planDefaults: {
+            internal: true,
+        },
+    },
+    "annotations.preview_loader": {
+        key: "annotations.preview_loader",
+        name: "Annotations preview loader",
+        description: "Allows immutable version URLs to receive a no-secret preview overlay configuration.",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "annotations.comments": {
+        key: "annotations.comments",
+        name: "Annotation comments",
+        description: "Enables Cast-backed comments on eligible immutable version URLs.",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "annotations.anonymous_reviewers": {
+        key: "annotations.anonymous_reviewers",
+        name: "Anonymous annotation reviewers",
+        description: "Allows anyone-with-link annotation identities when space policy allows it.",
+        defaultEnabled: false,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "annotations.cli": {
+        key: "annotations.cli",
+        name: "Annotation CLI access",
+        description: "Enables scriptable annotation read/export/reply/resolve operations.",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "annotations.notices": {
+        key: "annotations.notices",
+        name: "Realtime notices",
+        description: "Reserved kill-switch for future realtime preview notices.",
+        defaultEnabled: false,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "annotations.spacefast_token": {
+        key: "annotations.spacefast_token",
+        name: "Spacefast-native annotation tokens",
+        description: "Mints collaboration tokens as Spacefast EdDSA access tokens (dedicated Cast kid) instead of the legacy HS256 path; the Spacefast-native auth cutover.",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "annotations.published_comments": {
+        key: "annotations.published_comments",
+        name: "Published host annotation comments",
+        description: "Allows the annotation overlay to mount comments on a space's live/published host, not just immutable preview URLs.",
+        defaultEnabled: false,
+        // ON in local dev so the Spacefast-native published path is exercised end-to-end
+        // alongside annotations.comments + annotations.spacefast_token (which already
+        // default on in dev). Production stays gated behind the per-space toggle.
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    "sites.dedicated_runtime": {
+        key: "sites.dedicated_runtime",
+        name: "Dedicated runtime sites",
+        description: "Allows teams to create dedicated WP.Cloud sites and place team spaces on them.",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    shelf: {
+        key: "shelf",
+        name: "Shelf",
+        description: "Exposes the per-user artifact shelf: dashboard curation and public /shelf/{handle} pages.",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    tags: {
+        key: "tags",
+        name: "Spacefast Tag Manager",
+        description: "Enables Spacefast Tag Manager command surfaces, SDK configuration, and governed tag workflows.",
+        defaultEnabled: false,
+        enabledInDevelopment: true,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+    zero: {
+        key: "zero",
+        name: "Spacefast Zero",
+        description: "Enables Spacefast Zero command surfaces and hosted Zero app workflows.",
+        defaultEnabled: false,
+        enabledForA8c: true,
+        planDefaults: {},
+    },
+};
+export const featureStateSourceSchema = z
+    .enum(["kill_switch", "env", "override", "default"])
+    .describe("Layer that decided the flag: kill_switch (emergency off), env (SPACEFAST_FLAG_* variable), " +
+    "override (feature_overrides row), default (plan/code default).");
+export const FeatureStateSchema = z.object({
+    key: featureKeySchema,
+    enabled: z.boolean().describe("Whether the feature is enabled for the requesting actor."),
+    source: featureStateSourceSchema,
+});
+export const FeatureStateResponseSchema = z.object({
+    planCode: planCodeSchema.describe("Plan the flags were evaluated against."),
+    features: z
+        .record(featureKeySchema, FeatureStateSchema)
+        .describe("Evaluated state for every known feature flag."),
+});
+export function normalizePlanCode(planCode) {
+    if (!planCode) {
+        return DEFAULT_PLAN_CODE;
+    }
+    const normalized = planCode.trim().toLowerCase();
+    return planCodeSchema.safeParse(normalized).data ?? DEFAULT_PLAN_CODE;
+}
+export function featureDefaultForPlan(key, planCode) {
+    const definition = FEATURE_DEFINITIONS[key];
+    return definition.planDefaults[normalizePlanCode(planCode)] ?? definition.defaultEnabled;
+}
+/** Numeric value of a plan limit; `null` means unlimited. */
+export function planLimitNumber(value) {
+    return value === "unlimited" ? null : value;
+}