@spacefast/common 0.0.2

package/dist/contracts/mcp.js

@@ -0,0 +1,161 @@
+import { z } from "zod";
+import { AnyObjectSchema, dataEnvelope } from "./common.js";
+export const hostedMcpSessionStatusSchema = z.enum(["active", "closed", "expired", "interrupted"]);
+export const hostedMcpWorkspaceSummarySchema = z.object({
+    files: z.number().int().nonnegative(),
+    totalBytes: z.number().int().nonnegative(),
+    updatedAt: z.string().datetime().nullable(),
+});
+export const hostedMcpSessionSchema = z.object({
+    sessionId: z.string(),
+    clientId: z.string().nullable(),
+    credentialId: z.string().nullable(),
+    credentialKind: z.string().nullable(),
+    scopes: z.array(z.string()),
+    policy: z.object({
+        credential: z.string(),
+        approvals: z.string(),
+        tools: z.string(),
+    }),
+    status: hostedMcpSessionStatusSchema,
+    metadata: AnyObjectSchema.nullable(),
+    workspace: hostedMcpWorkspaceSummarySchema,
+    ownerId: z.string().nullable(),
+    ownerLeaseExpiresAt: z.string().datetime().nullable(),
+    createdAt: z.string().datetime(),
+    lastSeenAt: z.string().datetime(),
+    closedAt: z.string().datetime().nullable(),
+});
+export const hostedMcpApprovalSchema = z.object({
+    id: z.string(),
+    runtime: z.enum(["hosted", "local"]),
+    tool: z.string(),
+    args: AnyObjectSchema,
+    preview: z.unknown(),
+    status: z.enum(["pending", "approved", "denied", "consumed", "expired"]),
+    decision: z.enum(["approve", "deny"]).nullable(),
+    decisionReason: z.string().nullable(),
+    decidedAt: z.string().datetime().nullable(),
+    createdAt: z.string().datetime(),
+    expiresAt: z.string().datetime(),
+});
+export const hostedMcpSessionEventSchema = z.object({
+    id: z.string(),
+    sessionId: z.string(),
+    eventType: z.string(),
+    tool: z.string().nullable(),
+    resourceUri: z.string().nullable(),
+    status: z.string().nullable(),
+    requestId: z.string().nullable(),
+    durationMs: z.number().int().nonnegative().nullable(),
+    data: AnyObjectSchema.nullable(),
+    createdAt: z.string().datetime(),
+});
+export const hostedMcpExecutionRunStatusSchema = z.enum([
+    "queued",
+    "running",
+    "approval_required",
+    "completed",
+    "failed",
+    "canceled",
+]);
+export const hostedMcpExecutionStepSchema = z.object({
+    id: z.string(),
+    runId: z.string(),
+    index: z.number().int().nonnegative(),
+    tool: z.string().nullable(),
+    status: z.string(),
+    dryRun: z.boolean().nullable(),
+    durationMs: z.number().int().nonnegative().nullable(),
+    input: AnyObjectSchema.nullable(),
+    output: z.unknown().nullable(),
+    createdAt: z.string().datetime(),
+});
+export const hostedMcpExecutionArtifactSchema = z.object({
+    id: z.string(),
+    runId: z.string(),
+    kind: z.enum(["log", "warning", "result", "resource", "file", "summary"]),
+    name: z.string(),
+    mimeType: z.string().nullable(),
+    sizeBytes: z.number().int().nonnegative().nullable(),
+    data: z.unknown().nullable(),
+    createdAt: z.string().datetime(),
+});
+export const hostedMcpExecutionRunSchema = z.object({
+    id: z.string(),
+    sessionId: z.string().nullable(),
+    credentialId: z.string().nullable(),
+    tool: z.string(),
+    mode: z.string().nullable(),
+    status: hostedMcpExecutionRunStatusSchema,
+    approvalId: z.string().nullable(),
+    cancellationRequested: z.boolean(),
+    summary: z.string().nullable(),
+    error: z.string().nullable(),
+    startedAt: z.string().datetime(),
+    completedAt: z.string().datetime().nullable(),
+    updatedAt: z.string().datetime(),
+    steps: z.array(hostedMcpExecutionStepSchema).optional(),
+    artifacts: z.array(hostedMcpExecutionArtifactSchema).optional(),
+});
+export const hostedMcpToolPolicySchema = z.object({
+    tool: z.string(),
+    runtime: z.enum(["hosted", "on-device", "both"]),
+    category: z.string(),
+    defaultMode: z.enum(["allow", "approval", "local-only"]),
+    approvalRequired: z.boolean(),
+    requiredScopes: z.array(z.string()),
+    clientPolicy: z.string(),
+    sessionPolicy: z.string(),
+});
+export const hostedMcpPolicyDefaultsSchema = z.object({
+    approvalTtlSeconds: z.number().int().positive(),
+    hostedTransport: z.string(),
+    onDeviceTransport: z.string(),
+    hostedBoundary: z.string(),
+    onDeviceBoundary: z.string(),
+    toolPolicies: z.array(hostedMcpToolPolicySchema),
+});
+export const hostedMcpSummarySchema = z.object({
+    rowLimit: z.number().int().positive(),
+    sessions: z.object({
+        total: z.number().int().nonnegative(),
+        active: z.number().int().nonnegative(),
+        closed: z.number().int().nonnegative(),
+        expired: z.number().int().nonnegative(),
+        interrupted: z.number().int().nonnegative(),
+    }),
+    approvals: z.object({
+        pending: z.number().int().nonnegative(),
+    }),
+    events: z.object({
+        recent: z.number().int().nonnegative(),
+    }),
+    executions: z.object({
+        recent: z.number().int().nonnegative(),
+        running: z.number().int().nonnegative(),
+    }),
+});
+export const hostedMcpDashboardSchema = z.object({
+    summary: hostedMcpSummarySchema,
+    policyDefaults: hostedMcpPolicyDefaultsSchema,
+    sessions: z.array(hostedMcpSessionSchema),
+    approvals: z.array(hostedMcpApprovalSchema),
+    events: z.array(hostedMcpSessionEventSchema),
+    executions: z.array(hostedMcpExecutionRunSchema),
+});
+export const hostedMcpDashboardResponseSchema = dataEnvelope(hostedMcpDashboardSchema);
+export const hostedMcpCloseSessionResponseSchema = dataEnvelope(hostedMcpSessionSchema);
+export const hostedMcpApprovalDecisionRequestSchema = z.object({
+    decision: z.enum(["approve", "deny"]),
+    reason: z.string().max(1_000).optional(),
+});
+export const hostedMcpApprovalResponseSchema = dataEnvelope(hostedMcpApprovalSchema);
+export const hostedMcpSessionEventsResponseSchema = dataEnvelope(z.object({
+    session: hostedMcpSessionSchema,
+    events: z.array(hostedMcpSessionEventSchema),
+}));
+export const hostedMcpExecutionRunsResponseSchema = dataEnvelope(z.object({
+    runs: z.array(hostedMcpExecutionRunSchema),
+}));
+export const hostedMcpExecutionRunResponseSchema = dataEnvelope(hostedMcpExecutionRunSchema);

package/dist/contracts/me.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+export declare const meResponseSchema: z.ZodObject<{
+    subject: z.ZodObject<{
+        type: z.ZodEnum<{
+            external: "external";
+            user: "user";
+            system: "system";
+            team: "team";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    user: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        email: z.ZodNullable<z.ZodString>;
+        name: z.ZodNullable<z.ZodString>;
+        isAutomattician: z.ZodBoolean;
+        wpcom: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        isSuperadmin: z.ZodBoolean;
+    }, z.core.$strip>>;
+    tenants: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodString;
+        name: z.ZodString;
+        access: z.ZodEnum<{
+            full: "full";
+            scoped: "scoped";
+        }>;
+    }, z.core.$strip>>;
+    teams: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tenantId: z.ZodString;
+        name: z.ZodString;
+        slug: z.ZodNullable<z.ZodString>;
+        role: z.ZodNullable<z.ZodString>;
+        plan: z.ZodEnum<{
+            personal: "personal";
+            work: "work";
+            enterprise: "enterprise";
+            internal: "internal";
+            free: "free";
+        }>;
+    }, z.core.$strip>>;
+    intercom: z.ZodNullable<z.ZodObject<{
+        api_base: z.ZodString;
+        app_id: z.ZodString;
+        user_id: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        created_at: z.ZodOptional<z.ZodNumber>;
+        company: z.ZodOptional<z.ZodObject<{
+            company_id: z.ZodString;
+            name: z.ZodString;
+            plan: z.ZodOptional<z.ZodEnum<{
+                personal: "personal";
+                work: "work";
+                enterprise: "enterprise";
+                internal: "internal";
+                free: "free";
+            }>>;
+        }, z.core.$strip>>;
+        intercom_user_jwt: z.ZodString;
+        session_duration: z.ZodNumber;
+        expiresAt: z.ZodString;
+    }, z.core.$strip>>;
+    beta: z.ZodObject<{
+        gateEnabled: z.ZodBoolean;
+        enrolled: z.ZodBoolean;
+        wpcom: z.ZodBoolean;
+        eligibleTeams: z.ZodArray<z.ZodObject<{
+            teamId: z.ZodString;
+            name: z.ZodString;
+            slug: z.ZodNullable<z.ZodString>;
+            source: z.ZodEnum<{
+                invitation: "invitation";
+                auto_enroll_domain: "auto_enroll_domain";
+                automattician: "automattician";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type MeResponse = z.infer<typeof meResponseSchema>;

package/dist/contracts/me.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { betaEligibleTeamSourceSchema } from "./beta.js";
+import { planCodeSchema } from "./features.js";
+// `GET /v1/me` (internal-docs/platform.md route catalog): the authenticated
+// subject, its tenant grants, principal/team memberships, and a plan summary.
+// Works for every credential kind — sessions resolve their user and team
+// memberships; machine credentials resolve the teams and tenants their policy
+// grants.
+export const meResponseSchema = z.object({
+    subject: z
+        .object({
+        type: z
+            .enum(["user", "team", "external", "system"])
+            .describe("Subject kind: the session user, or the machine credential's acting subject."),
+        id: z.string().describe("Stable subject id."),
+    })
+        .describe("The authenticated subject of the calling credential."),
+    user: z
+        .object({
+        id: z.string().describe("User id."),
+        email: z.string().nullable().describe("User email."),
+        name: z.string().nullable().describe("User display name."),
+        isAutomattician: z
+            .boolean()
+            .describe("Whether the linked WordPress.com account is an Automattician."),
+        wpcom: z
+            .record(z.string(), z.unknown())
+            .nullable()
+            .describe("Raw WordPress.com `/me` payload from the user's last WP.com login."),
+        isSuperadmin: z.boolean().describe("Whether the user is a platform operator."),
+    })
+        .nullable()
+        .describe("User identity when known: the session user, or the machine credential's creator. Null for automation-created credentials."),
+    tenants: z
+        .array(z.object({
+        id: z.string().describe("Tenant id."),
+        kind: z.string().describe("Tenant kind."),
+        name: z.string().describe("Tenant display name."),
+        access: z
+            .enum(["full", "scoped"])
+            .describe("Grant level the credential's policy holds in this tenant: `full` covers the whole tenant subtree, `scoped` covers specific principals or resources within it."),
+    }))
+        .describe("Tenant grants derived from the credential's effective policy. The credential's home tenant is always included."),
+    teams: z
+        .array(z.object({
+        id: z.string().describe("Team id."),
+        tenantId: z.string().describe("Owning tenant id."),
+        name: z.string().describe("Team display name."),
+        slug: z.string().nullable().describe("Team slug."),
+        role: z
+            .string()
+            .nullable()
+            .describe("The caller's membership role. Null for policy-granted (non-member) access."),
+        plan: planCodeSchema.describe("The team's resolved plan code (plan summary)."),
+    }))
+        .describe("Teams the credential can act in: session team memberships, or the teams a machine credential's policy grants."),
+    intercom: z
+        .object({
+        api_base: z.string().url().describe("Intercom Messenger API base URL."),
+        app_id: z.string().describe("Intercom workspace app id."),
+        user_id: z.string().describe("Stable Intercom user id."),
+        email: z.string().email().optional().describe("User email when available."),
+        name: z.string().optional().describe("User display name when available."),
+        created_at: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("User creation time in Unix seconds."),
+        company: z
+            .object({
+            company_id: z.string().describe("Stable Intercom company id."),
+            name: z.string().describe("Company display name."),
+            plan: planCodeSchema.optional().describe("Resolved company plan code."),
+        })
+            .optional()
+            .describe("Current team as an Intercom company."),
+        intercom_user_jwt: z.string().min(1).describe("Short-lived server-signed Messenger JWT."),
+        session_duration: z.number().int().positive().describe("Messenger session cookie TTL in ms."),
+        expiresAt: z.string().datetime().describe("JWT expiry timestamp."),
+    })
+        .nullable()
+        .describe("Intercom Messenger boot payload for authenticated browser sessions."),
+    beta: z
+        .object({
+        gateEnabled: z
+            .boolean()
+            .describe("Whether the beta.enrollment_gate flag is on for this deployment."),
+        enrolled: z
+            .boolean()
+            .describe("Whether the subject user is enrolled (beta_enrolled_at is set)."),
+        wpcom: z.boolean().describe("Whether the user passed the Automattician check at enrollment."),
+        eligibleTeams: z
+            .array(z.object({
+            teamId: z.string().describe("Team id."),
+            name: z.string().describe("Team display name."),
+            slug: z.string().nullable().describe("Team slug."),
+            source: betaEligibleTeamSourceSchema,
+        }))
+            .describe("Teams the user may join via the picker (pending invitation or auto-enroll match)."),
+    })
+        .describe("Private-beta state. Dashboards key the blocked screen on gateEnabled && !enrolled, " +
+        "never on !enrolled alone — else launch-day flag-off would still block people."),
+});

package/dist/contracts/oauth-resources.d.ts

@@ -0,0 +1,30 @@
+export declare const OAUTH_AUTHORIZATION_SERVER_PATH: "/v1/auth";
+export declare const OAUTH_RESOURCE_PATHS: {
+    readonly api: "/v1";
+    readonly mcp: "/mcp";
+};
+export type OAuthResourceKey = keyof typeof OAUTH_RESOURCE_PATHS;
+export declare const OAUTH_API_RESOURCE_SCOPES: readonly ["teams:read", "spaces:read", "spaces:write", "publish:write", "domains:read", "domains:write"];
+export declare const OAUTH_MCP_TOOL_SCOPE: "mcp:tools";
+export declare const OAUTH_MCP_RESOURCE_SCOPES: readonly ["mcp:tools", "teams:read", "spaces:read", "spaces:write", "publish:write", "domains:read", "domains:write"];
+export declare const OAUTH_PROVIDER_SCOPES: readonly ["openid", "profile", "email", "offline_access", "teams:read", "spaces:read", "spaces:write", "publish:write", "domains:read", "domains:write", "mcp:tools"];
+export declare const OAUTH_RESOURCE_DEFINITIONS: {
+    readonly api: {
+        readonly key: "api";
+        readonly path: "/v1";
+        readonly name: "Spacefast API";
+        readonly accessTokenTtlSeconds: number;
+        readonly allowedScopes: readonly ["teams:read", "spaces:read", "spaces:write", "publish:write", "domains:read", "domains:write"];
+    };
+    readonly mcp: {
+        readonly key: "mcp";
+        readonly path: "/mcp";
+        readonly name: "Spacefast MCP";
+        readonly accessTokenTtlSeconds: number;
+        readonly allowedScopes: readonly ["mcp:tools", "teams:read", "spaces:read", "spaces:write", "publish:write", "domains:read", "domains:write"];
+    };
+};
+export declare function oauthResourceUrl(origin: string | URL, resource: OAuthResourceKey): string;
+export declare function oauthAuthorizationServerUrl(origin: string | URL): string;
+export declare function oauthTokenEndpointUrl(origin: string | URL): string;
+export declare function oauthResourceKeyForPathname(pathname: string): OAuthResourceKey | null;

package/dist/contracts/oauth-resources.js

@@ -0,0 +1,61 @@
+export const OAUTH_AUTHORIZATION_SERVER_PATH = "/v1/auth";
+export const OAUTH_RESOURCE_PATHS = {
+    api: "/v1",
+    mcp: "/mcp",
+};
+export const OAUTH_API_RESOURCE_SCOPES = [
+    "teams:read",
+    "spaces:read",
+    "spaces:write",
+    "publish:write",
+    "domains:read",
+    "domains:write",
+];
+export const OAUTH_MCP_TOOL_SCOPE = "mcp:tools";
+export const OAUTH_MCP_RESOURCE_SCOPES = [
+    OAUTH_MCP_TOOL_SCOPE,
+    ...OAUTH_API_RESOURCE_SCOPES,
+];
+export const OAUTH_PROVIDER_SCOPES = [
+    "openid",
+    "profile",
+    "email",
+    "offline_access",
+    ...OAUTH_API_RESOURCE_SCOPES,
+    OAUTH_MCP_TOOL_SCOPE,
+];
+export const OAUTH_RESOURCE_DEFINITIONS = {
+    api: {
+        key: "api",
+        path: OAUTH_RESOURCE_PATHS.api,
+        name: "Spacefast API",
+        accessTokenTtlSeconds: 15 * 60,
+        allowedScopes: OAUTH_API_RESOURCE_SCOPES,
+    },
+    mcp: {
+        key: "mcp",
+        path: OAUTH_RESOURCE_PATHS.mcp,
+        name: "Spacefast MCP",
+        accessTokenTtlSeconds: 15 * 60,
+        allowedScopes: OAUTH_MCP_RESOURCE_SCOPES,
+    },
+};
+export function oauthResourceUrl(origin, resource) {
+    return new URL(OAUTH_RESOURCE_PATHS[resource], origin).toString();
+}
+export function oauthAuthorizationServerUrl(origin) {
+    return new URL(OAUTH_AUTHORIZATION_SERVER_PATH, origin).toString();
+}
+export function oauthTokenEndpointUrl(origin) {
+    return new URL(`${OAUTH_AUTHORIZATION_SERVER_PATH}/oauth2/token`, origin).toString();
+}
+export function oauthResourceKeyForPathname(pathname) {
+    if (pathname === OAUTH_RESOURCE_PATHS.mcp) {
+        return "mcp";
+    }
+    if (pathname === OAUTH_RESOURCE_PATHS.api ||
+        pathname.startsWith(`${OAUTH_RESOURCE_PATHS.api}/`)) {
+        return "api";
+    }
+    return null;
+}

package/dist/contracts/operations.d.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+export declare const operationListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    resourceType: z.ZodOptional<z.ZodString>;
+    resourceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const operationListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            queued: "queued";
+            running: "running";
+            succeeded: "succeeded";
+            canceled: "canceled";
+        }>;
+        resources: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strip>>;
+        progress: z.ZodOptional<z.ZodObject<{
+            total: z.ZodNumber;
+            completed: z.ZodNumber;
+            failed: z.ZodNumber;
+        }, z.core.$strip>>;
+        diagnostics: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            severity: z.ZodEnum<{
+                info: "info";
+                warning: "warning";
+                error: "error";
+            }>;
+            message: z.ZodString;
+            path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                wpcloud: "wpcloud";
+                dns: "dns";
+                registrar: "registrar";
+                runtime: "runtime";
+            }>>>;
+            details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            fix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        }, z.core.$strip>>>;
+        createdAt: z.ZodString;
+        finishedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;

package/dist/contracts/operations.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { AsyncOperationSchema, CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
+export const operationListQuerySchema = cursorListQuerySchema.extend({
+    resourceType: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Filter to operations touching one resource type, e.g. `space`."),
+    resourceId: z.string().min(1).optional().describe("Filter to operations touching one resource."),
+});
+export const operationListResponseSchema = z.object({
+    data: z.array(AsyncOperationSchema),
+    pagination: CursorPaginationSchema,
+});

package/dist/contracts/plan-policy.d.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+export declare const PLAN_DISABLED_BEHAVIOR_CODES: readonly ["free_external_proxy_disabled", "free_headers_basic_auth_disabled", "routing_rules_over_plan", "immutable_version_requires_login"];
+export declare const planDisabledBehaviorSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        free_external_proxy_disabled: "free_external_proxy_disabled";
+        free_headers_basic_auth_disabled: "free_headers_basic_auth_disabled";
+        immutable_version_requires_login: "immutable_version_requires_login";
+        routing_rules_over_plan: "routing_rules_over_plan";
+    }>;
+    behavior: z.ZodString;
+    renderedAs: z.ZodEnum<{
+        warning: "warning";
+        ignored: "ignored";
+        platform_page: "platform_page";
+        login_redirect: "login_redirect";
+    }>;
+}, z.core.$strip>;
+export type PlanDisabledBehavior = z.infer<typeof planDisabledBehaviorSchema>;
+export declare const PlanPolicyResponseSchema: z.ZodObject<{
+    principal: z.ZodObject<{
+        type: z.ZodEnum<{
+            space: "space";
+            site: "site";
+            team: "team";
+            external_principal: "external_principal";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    siteId: z.ZodOptional<z.ZodString>;
+    spaceId: z.ZodOptional<z.ZodString>;
+    plan: z.ZodEnum<{
+        free: "free";
+        personal: "personal";
+        work: "work";
+        enterprise: "enterprise";
+        internal: "internal";
+    }>;
+    limits: z.ZodObject<{
+        storageBytes: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+        teamMembers: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+        subTeams: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+        externalDomainGroups: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+        boughtDomains: z.ZodLiteral<"unlimited">;
+        publicImmutableVersionWindowDays: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+        maxFileBytes: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+        maxVersionFiles: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+        routingRules: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+        auditLogRetentionHours: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+        buildAccessLogRetentionHours: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+        buildsDeploysMonthly: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"unlimited">]>;
+    }, z.core.$strip>;
+    usage: z.ZodOptional<z.ZodObject<{
+        storageBytes: z.ZodOptional<z.ZodNumber>;
+        teamMembers: z.ZodOptional<z.ZodNumber>;
+        subTeams: z.ZodOptional<z.ZodNumber>;
+        externalDomainGroups: z.ZodOptional<z.ZodNumber>;
+        routingRules: z.ZodOptional<z.ZodNumber>;
+        buildsDeploysThisMonth: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            error: "error";
+            info: "info";
+            warning: "warning";
+        }>;
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>>;
+    disabledBehaviors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodEnum<{
+            free_external_proxy_disabled: "free_external_proxy_disabled";
+            free_headers_basic_auth_disabled: "free_headers_basic_auth_disabled";
+            immutable_version_requires_login: "immutable_version_requires_login";
+            routing_rules_over_plan: "routing_rules_over_plan";
+        }>;
+        behavior: z.ZodString;
+        renderedAs: z.ZodEnum<{
+            warning: "warning";
+            ignored: "ignored";
+            platform_page: "platform_page";
+            login_redirect: "login_redirect";
+        }>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type PlanPolicyResponse = z.infer<typeof PlanPolicyResponseSchema>;

package/dist/contracts/plan-policy.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { diagnosticSeverity } from "./enums.js";
+import { planCodeSchema, planLimitValueSchema } from "./features.js";
+// Behaviors the platform disables (rather than failing publishes) when the
+// plan does not include them (internal-docs/platform.md "Plans And Limits").
+export const PLAN_DISABLED_BEHAVIOR_CODES = [
+    "free_external_proxy_disabled",
+    "free_headers_basic_auth_disabled",
+    "routing_rules_over_plan",
+    "immutable_version_requires_login",
+];
+export const planDisabledBehaviorSchema = z.object({
+    code: z
+        .enum(PLAN_DISABLED_BEHAVIOR_CODES)
+        .describe("Stable code identifying the disabled behavior."),
+    behavior: z.string().describe("What the platform does instead of honoring the behavior."),
+    renderedAs: z
+        .enum(["warning", "platform_page", "login_redirect", "ignored"])
+        .describe("How the disablement surfaces to users."),
+});
+export const PlanPolicyResponseSchema = z.object({
+    principal: z
+        .object({
+        type: z.enum(["team", "site", "space", "external_principal"]),
+        id: z.string(),
+    })
+        .describe("Principal the policy was resolved for."),
+    siteId: z.string().optional().describe("Site the policy was resolved against, when site-scoped."),
+    spaceId: z
+        .string()
+        .optional()
+        .describe("Space the policy was resolved against, when space-scoped."),
+    plan: planCodeSchema,
+    limits: z
+        .object({
+        storageBytes: planLimitValueSchema,
+        teamMembers: planLimitValueSchema,
+        subTeams: planLimitValueSchema,
+        externalDomainGroups: planLimitValueSchema,
+        boughtDomains: z
+            .literal("unlimited")
+            .describe("Domains bought through Spacefast never count against external domain limits."),
+        publicImmutableVersionWindowDays: planLimitValueSchema,
+        maxFileBytes: planLimitValueSchema,
+        maxVersionFiles: planLimitValueSchema.describe("Files per version; plan policy may lower the 100,000-file contract ceiling, never raise it."),
+        routingRules: planLimitValueSchema,
+        auditLogRetentionHours: planLimitValueSchema,
+        buildAccessLogRetentionHours: planLimitValueSchema,
+        buildsDeploysMonthly: planLimitValueSchema.describe("Pooled monthly limit: pricing never separates user pushes from CI builds."),
+    })
+        .describe("Named plan limits."),
+    usage: z
+        .object({
+        storageBytes: z.number().int().nonnegative().optional(),
+        teamMembers: z.number().int().nonnegative().optional(),
+        subTeams: z.number().int().nonnegative().optional(),
+        externalDomainGroups: z.number().int().nonnegative().optional(),
+        routingRules: z.number().int().nonnegative().optional(),
+        buildsDeploysThisMonth: z.number().int().nonnegative().optional(),
+    })
+        .optional()
+        .describe("Current usage against the named limits, where the platform meters it."),
+    warnings: z
+        .array(z.object({
+        severity: diagnosticSeverity,
+        code: z.string(),
+        message: z.string(),
+    }))
+        .optional()
+        .describe("Plan-level warnings (for example storage over quota)."),
+    disabledBehaviors: z
+        .array(planDisabledBehaviorSchema)
+        .optional()
+        .describe("Behaviors the plan disables instead of failing publishes."),
+});