@spacefast/common 0.0.2

package/dist/utils/publish-policy.js

@@ -0,0 +1,429 @@
+import { BRAND } from "../brand.js";
+import { WORST_CASE_QUOTAS } from "../contracts/quotas.js";
+import { SPACE_CONFIG_PRIVATE_FILES } from "../contracts/space-config.js";
+// The ONE static publish policy (internal-docs/platform.md "Upload Contract"):
+// path denials, manifest scale caps, plan caps, duplicate detection, and the
+// free-plan content rules live here. Consumed by API manifest validation, CLI
+// local preflight, inline archive extraction, and the runtime parity fixtures
+// (the PHP twin is runtime/engine/admin/upload-policy.php).
+import { canonicalizeVersionPath, normalizeVersionPath } from "./version-path.js";
+// Manifest scale caps (spec "Upload Contract"): the hard contract ceiling is
+// 100,000 files per version; plan policy may LOWER it (Free 20,000), never
+// raise it. Canonical paths cap at 1,024 bytes; manifest request bodies at
+// 16 MB, enforced fail-early before any upload session exists.
+export const MANIFEST_MAX_FILES_CEILING = 100_000;
+export const MANIFEST_MAX_PATH_BYTES = 1024;
+export const MANIFEST_MAX_BODY_BYTES = 16 * 1024 * 1024;
+export const MAX_VERSION_FILE_SIZE_BYTES = 64 * 1024 * 1024;
+// Worst-case artifact ceiling lives in the named raise-only quota table.
+export const MAX_VERSION_TOTAL_BYTES = WORST_CASE_QUOTAS.maxArtifactBytes;
+const IGNORED_EXACT_PATHS = new Set([
+    ".DS_Store",
+    ".gitignore",
+    ".env",
+    ".env.local",
+    ".env.production",
+    ".env.development",
+    ".env.test",
+    ".npmrc",
+    ".netrc",
+    ".stattic/state.json",
+    "_routes.json",
+]);
+const IGNORED_SEGMENTS = new Set([
+    ".aws",
+    ".git",
+    ".hg",
+    ".ssh",
+    ".svn",
+    ".wrangler",
+    ".vercel",
+    ".netlify",
+    ".turbo",
+    ".cache",
+    "node_modules",
+]);
+const RESERVED_CONVENTION_PATHS = new Set(["_headers", "_redirects"]);
+const SENSITIVE_FILE_PATTERNS = [
+    /^\.env\./,
+    /^id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/,
+    /(^|[.-])private[.-]?key$/i,
+    /\.(pem|key|p12|pfx)$/i,
+];
+// Denied runtime private/control paths (spec "Static path policy").
+const STATIC_EXECUTION_CONTROL_FILES = new Set([".htaccess", ".user.ini"]);
+const STATIC_RUNTIME_CONTROL_SEGMENTS = new Set(["__spacefast", "__stattic"]);
+const STATIC_RUNTIME_CONTROL_PATHS = new Set([".well-known/stattic-runtime"]);
+const STATIC_RUNTIME_CONTROL_PREFIXES = [".stattic/storage", ".stattic/engine"];
+export function normalizePublishPath(relativePath) {
+    return relativePath.replace(/\\/g, "/").replace(/^\/+/g, "");
+}
+export function publishPathIgnored(relativePath) {
+    const path = normalizePublishPath(relativePath);
+    if (IGNORED_EXACT_PATHS.has(path) || /(?:^|\/)\.next\/cache(?:\/|$)/.test(path)) {
+        return true;
+    }
+    return path
+        .split("/")
+        .some((segment) => IGNORED_SEGMENTS.has(segment) ||
+        IGNORED_EXACT_PATHS.has(segment) ||
+        SENSITIVE_FILE_PATTERNS.some((pattern) => pattern.test(segment)));
+}
+export function publishPathIsConvention(relativePath) {
+    return RESERVED_CONVENTION_PATHS.has(normalizePublishPath(relativePath));
+}
+// Provider runtime features that have no Spacefast equivalent (spec "Routing And
+// Headers", migration diagnostics): Cloudflare Pages `_worker.js`/`_routes.json`
+// and Pages/Netlify function directories publish as inert content with a
+// warning so migrations are never silent.
+export function providerRuntimeFeatureWarnings(paths) {
+    const warnings = [];
+    const seen = new Set();
+    const featureForPath = (path) => {
+        if (path === "_worker.js") {
+            return "Cloudflare Pages _worker.js";
+        }
+        if (path === "_routes.json") {
+            return "Cloudflare Pages _routes.json";
+        }
+        if (path.startsWith("functions/")) {
+            return "Pages Functions (functions/)";
+        }
+        if (path.startsWith("netlify/functions/")) {
+            return "Netlify Functions (netlify/functions/)";
+        }
+        return null;
+    };
+    for (const rawPath of paths) {
+        const path = normalizePublishPath(rawPath);
+        const feature = featureForPath(path);
+        if (!feature || seen.has(feature)) {
+            continue;
+        }
+        seen.add(feature);
+        warnings.push({
+            severity: "warning",
+            code: "provider_runtime_feature_unsupported",
+            message: `${feature} is a provider runtime feature ${BRAND.productName} does not execute; it publishes as inert static content.`,
+            path,
+        });
+    }
+    return warnings;
+}
+function pathViolation(code, message, path) {
+    return { code, message, path };
+}
+function basename(path) {
+    const index = path.lastIndexOf("/");
+    return index >= 0 ? path.slice(index + 1) : path;
+}
+export function staticUploadPathViolation(path, options = {}) {
+    const rawPath = path;
+    if (rawPath !== rawPath.trim() ||
+        rawPath.startsWith("/") ||
+        rawPath.includes("\\") ||
+        rawPath.includes("//")) {
+        return pathViolation("invalid_file_path", "File path is invalid.", rawPath);
+    }
+    let normalizedPath;
+    try {
+        normalizedPath = normalizeVersionPath(path);
+    }
+    catch {
+        return pathViolation("invalid_file_path", "File path is invalid.", rawPath);
+    }
+    if (normalizedPath !== rawPath) {
+        return pathViolation("invalid_file_path", "File path is invalid.", normalizedPath);
+    }
+    if (new TextEncoder().encode(normalizedPath).length > MANIFEST_MAX_PATH_BYTES) {
+        return pathViolation("path_too_long", `File paths support up to ${MANIFEST_MAX_PATH_BYTES} bytes in canonical form.`, normalizedPath);
+    }
+    const lowerName = basename(normalizedPath).toLowerCase();
+    const lowerPath = normalizedPath.toLowerCase();
+    const segments = normalizedPath.split("/");
+    const invalidSegment = segments.find((segment) => segment.endsWith(".") || segment.endsWith(" "));
+    if (invalidSegment) {
+        return pathViolation("invalid_file_path", "File path is invalid.", normalizedPath);
+    }
+    if (STATIC_EXECUTION_CONTROL_FILES.has(lowerName)) {
+        return pathViolation("static_control_file_not_supported", "Static deploys cannot upload execution-control files.", normalizedPath);
+    }
+    const reservedRuntimeControlFiles = options.reservedRuntimeControlFiles
+        ? new Set(Array.from(options.reservedRuntimeControlFiles, (name) => name.toLowerCase()))
+        : null;
+    if (reservedRuntimeControlFiles?.has(lowerName) && lowerPath === lowerName) {
+        return pathViolation("static_runtime_control_path_not_supported", "Static deploys cannot upload runtime control paths.", normalizedPath);
+    }
+    const controlSegment = segments.find((segment) => STATIC_RUNTIME_CONTROL_SEGMENTS.has(segment.toLowerCase()));
+    if (controlSegment) {
+        return pathViolation("static_runtime_control_path_not_supported", "Static deploys cannot upload runtime control paths.", normalizedPath);
+    }
+    if (STATIC_RUNTIME_CONTROL_PREFIXES.some((prefix) => lowerPath === prefix || lowerPath.startsWith(`${prefix}/`))) {
+        return pathViolation("static_runtime_control_path_not_supported", "Static deploys cannot upload runtime control paths.", normalizedPath);
+    }
+    if (STATIC_RUNTIME_CONTROL_PATHS.has(lowerPath)) {
+        return pathViolation("static_runtime_control_path_not_supported", "Static deploys cannot upload runtime control paths.", normalizedPath);
+    }
+    return null;
+}
+export function firstStaticUploadPathViolation(paths, options = {}) {
+    for (const path of paths) {
+        const violation = staticUploadPathViolation(path, options);
+        if (violation) {
+            return violation;
+        }
+    }
+    return null;
+}
+export function resolveManifestFileCap(maxFiles) {
+    return Math.min(MANIFEST_MAX_FILES_CEILING, maxFiles && maxFiles > 0 ? maxFiles : MANIFEST_MAX_FILES_CEILING);
+}
+// The shared manifest validator (spec "Upload Contract"): canonicalizes every
+// path (decode-once + NFC), enforces the static path policy, the scale caps,
+// and plan caps, rejects post-canonicalization duplicates, and emits the
+// case-collision warning. Runs BEFORE any upload session is created; archive
+// extraction routes through the same checks. Returns the manifest with
+// canonical paths — callers use the returned files, never the input.
+export function validatePublishManifest(files, caps = {}) {
+    const maxFiles = resolveManifestFileCap(caps.maxFiles);
+    if (files.length > maxFiles) {
+        return {
+            error: {
+                code: "manifest_too_many_files",
+                message: `Versions support up to ${maxFiles.toLocaleString()} files on this plan.`,
+                details: { fileCount: files.length, limit: maxFiles },
+            },
+            files: null,
+            warnings: [],
+        };
+    }
+    const canonicalFiles = [];
+    const canonicalPaths = new Set();
+    const lowercasePaths = new Map();
+    const warnings = [];
+    for (const file of files) {
+        let canonicalPath;
+        try {
+            canonicalPath = canonicalizeVersionPath(file.path);
+        }
+        catch {
+            return {
+                error: {
+                    code: "invalid_file_path",
+                    message: `Invalid file path "${file.path}".`,
+                    details: { path: file.path },
+                },
+                files: null,
+                warnings: [],
+            };
+        }
+        if (canonicalPaths.has(canonicalPath)) {
+            return {
+                error: {
+                    code: "manifest_duplicate_path",
+                    message: `Manifest contains duplicate path "${canonicalPath}" after canonicalization.`,
+                    details: { path: canonicalPath },
+                },
+                files: null,
+                warnings: [],
+            };
+        }
+        const violation = staticUploadPathViolation(canonicalPath);
+        if (violation) {
+            return {
+                error: {
+                    code: violation.code,
+                    message: violation.message,
+                    details: { path: violation.path },
+                },
+                files: null,
+                warnings: [],
+            };
+        }
+        // Case-only-differing paths are distinct (paths are byte-exact and
+        // case-sensitive) but cannot round-trip case-insensitive filesystems.
+        const lowercase = canonicalPath.toLowerCase();
+        const caseSibling = lowercasePaths.get(lowercase);
+        if (caseSibling !== undefined && caseSibling !== canonicalPath) {
+            warnings.push({
+                severity: "warning",
+                code: "path_case_collision",
+                message: `"${canonicalPath}" and "${caseSibling}" differ only by letter case and cannot coexist on case-insensitive filesystems.`,
+                path: canonicalPath,
+            });
+        }
+        else {
+            lowercasePaths.set(lowercase, canonicalPath);
+        }
+        canonicalPaths.add(canonicalPath);
+        canonicalFiles.push(canonicalPath === file.path ? file : { ...file, path: canonicalPath });
+    }
+    const maxFileBytes = caps.maxFileBytes && caps.maxFileBytes > 0 ? caps.maxFileBytes : MAX_VERSION_FILE_SIZE_BYTES;
+    const oversized = canonicalFiles.find((file) => file.size > maxFileBytes);
+    if (oversized) {
+        return {
+            error: {
+                code: "version_file_too_large",
+                message: `File ${oversized.path} exceeds the ${maxFileBytes} byte per-file limit for this plan.`,
+                details: { path: oversized.path, size: oversized.size, limit: maxFileBytes },
+            },
+            files: null,
+            warnings: [],
+        };
+    }
+    const totalBytes = canonicalFiles.reduce((sum, file) => sum + file.size, 0);
+    if (totalBytes > MAX_VERSION_TOTAL_BYTES) {
+        return {
+            error: {
+                code: "version_total_bytes_exceeded",
+                message: `Version exceeds the ${MAX_VERSION_TOTAL_BYTES} byte total size limit.`,
+                details: { totalBytes, limit: MAX_VERSION_TOTAL_BYTES },
+            },
+            files: null,
+            warnings: [],
+        };
+    }
+    warnings.push(...providerRuntimeFeatureWarnings(canonicalFiles.map((file) => file.path)));
+    return { error: null, files: canonicalFiles, warnings };
+}
+// ---------------------------------------------------------------------------
+// Free-plan publish content policy (spec "Plans And Limits"). Free spaces
+// publish web content; other file types are ignored with a diagnostic.
+const FREE_PLAN_ALLOWED_UPLOAD_EXTENSIONS = new Set([
+    ".html",
+    ".htm",
+    ".css",
+    ".js",
+    ".mjs",
+    ".cjs",
+    ".json",
+    ".map",
+    ".webmanifest",
+    ".txt",
+    ".md",
+    ".csv",
+    // Opaque static payloads used by migration fixtures and served as
+    // application/octet-stream by the runtime.
+    ".customtype",
+    ".xml",
+    ".svg",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".avif",
+    ".ico",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".otf",
+]);
+const LINE_SPLIT_PATTERN = /\r?\n/;
+const BASIC_AUTH_HEADER_PATTERN = /^basic-auth\s*:/i;
+function extensionForPath(filePath) {
+    const normalized = normalizePublishPath(filePath).toLowerCase();
+    const fileName = normalized.split("/").at(-1) ?? normalized;
+    const extensionIndex = fileName.lastIndexOf(".");
+    return extensionIndex > 0 ? fileName.slice(extensionIndex) : "";
+}
+function freePlanDeniedExecutablePath(filePath) {
+    return normalizePublishPath(filePath)
+        .toLowerCase()
+        .split("/")
+        .some((segment) => segment === "bin");
+}
+export function freePlanCanUploadPath(filePath, options) {
+    const path = normalizePublishPath(filePath);
+    // Root Spacefast config files are platform machinery, not user content (spec "Space
+    // Configuration Files": ships in the manifest, same lifecycle as
+    // `_redirects`/`_headers`) — the plan's content-extension gate must never
+    // eat it (e2e checkpoint 4: it was silently dropped on free publishes,
+    // disabling fallback/meta/templates/theme for every free space).
+    if (SPACE_CONFIG_PRIVATE_FILES.includes(path)) {
+        return true;
+    }
+    if (freePlanDeniedExecutablePath(path)) {
+        return false;
+    }
+    const extension = extensionForPath(path);
+    return (publishPathIsConvention(path) ||
+        extension === "" ||
+        FREE_PLAN_ALLOWED_UPLOAD_EXTENSIONS.has(extension) ||
+        (options?.claimedSpace === true && extension === ".sh"));
+}
+export function freePlanCanUploadContentType(contentType) {
+    const normalized = contentType?.split(";")[0]?.trim().toLowerCase();
+    return (normalized === "text/html" ||
+        normalized === "text/plain" ||
+        normalized === "text/css" ||
+        normalized === "text/csv" ||
+        normalized === "text/markdown" ||
+        normalized === "text/javascript" ||
+        normalized === "application/javascript" ||
+        normalized === "application/json" ||
+        normalized === "application/manifest+json" ||
+        normalized === "application/gzip" ||
+        normalized === "image/svg+xml" ||
+        normalized === "application/xml" ||
+        normalized === "text/xml" ||
+        normalized?.startsWith("image/") ||
+        normalized?.startsWith("font/") ||
+        false);
+}
+export function filterFreePlanManifest(files, options) {
+    const allowed = [];
+    const ignored = [];
+    for (const file of files) {
+        if (freePlanCanUploadPath(file.path, options) ||
+            freePlanCanUploadContentType(file.contentType)) {
+            allowed.push(file);
+        }
+        else {
+            ignored.push(file.path);
+        }
+    }
+    return { allowed, ignored };
+}
+// Free-plan `_headers` compile policy (spec "Plans And Limits", amended
+// 2026-06-10): custom response headers stay FREE; the Basic-Auth header
+// MECHANISM is the paid feature. Basic-Auth operations are dropped from free
+// compiles with a `free_headers_basic_auth_disabled` warning; every other
+// header operation passes through untouched.
+export function filterFreePlanHeaders(content) {
+    const output = [];
+    let droppedBasicAuthCount = 0;
+    let pendingMatcher = null;
+    let matcherEmitted = false;
+    const emitOperation = (rawLine) => {
+        if (pendingMatcher !== null && !matcherEmitted) {
+            output.push(pendingMatcher);
+            matcherEmitted = true;
+        }
+        output.push(rawLine);
+    };
+    for (const rawLine of content.split(LINE_SPLIT_PATTERN)) {
+        const trimmed = rawLine.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+            continue;
+        }
+        if (!rawLine.startsWith(" ") && !rawLine.startsWith("\t")) {
+            pendingMatcher = trimmed;
+            matcherEmitted = false;
+            continue;
+        }
+        if (pendingMatcher === null) {
+            continue;
+        }
+        if (BASIC_AUTH_HEADER_PATTERN.test(trimmed)) {
+            droppedBasicAuthCount += 1;
+        }
+        else {
+            emitOperation(rawLine);
+        }
+    }
+    return {
+        headers: output.length > 0 ? `${output.join("\n")}\n` : undefined,
+        droppedBasicAuthCount,
+    };
+}

package/dist/utils/query-client.d.ts

@@ -0,0 +1,7 @@
+import { QueryClient } from "@tanstack/react-query";
+export type ApiErrorLike = {
+    status: number;
+};
+export declare function createSpacefastQueryClient(options?: {
+    isClientError?: (error: unknown) => error is ApiErrorLike;
+}): QueryClient;

package/dist/utils/query-client.js

@@ -0,0 +1,21 @@
+import { QueryClient } from "@tanstack/react-query";
+export function createSpacefastQueryClient(options) {
+    return new QueryClient({
+        defaultOptions: {
+            queries: {
+                retry: (failureCount, error) => {
+                    if (options?.isClientError?.(error)) {
+                        const { status } = error;
+                        if (status >= 400 && status < 500 && status !== 408 && status !== 429) {
+                            return false;
+                        }
+                    }
+                    return failureCount < 2;
+                },
+                staleTime: 60_000,
+                refetchOnWindowFocus: true,
+                refetchOnReconnect: true,
+            },
+        },
+    });
+}

package/dist/utils/query-keys.d.ts

@@ -0,0 +1,75 @@
+export declare const qk: {
+    session: () => readonly ["session"];
+    authCapabilities: () => readonly ["auth", "capabilities"];
+    accountSessions: () => readonly ["account", "sessions"];
+    accountConnections: () => readonly ["account", "connections"];
+    accountInvitations: () => readonly ["account", "invitations"];
+    apiTokens: () => readonly ["api-tokens"];
+    agentAccounts: () => readonly ["agent-accounts"];
+    mcpDashboard: () => readonly ["mcp", "dashboard"];
+    mcpApproval: (id: string) => readonly ["mcp", "approval", string];
+    teams: () => readonly ["teams", "list"];
+    team: (ref: string) => readonly ["teams", "by-ref", string];
+    teamMembers: (id: string) => readonly ["teams", string, "members"];
+    teamInvites: (id: string) => readonly ["teams", string, "invites"];
+    teamBilling: (id: string) => readonly ["teams", string, "billing"];
+    teamUsage: (id: string) => readonly ["teams", string, "usage"];
+    teamEntitlements: (id: string) => readonly ["teams", string, "entitlements"];
+    teamFeatures: (id: string) => readonly ["teams", string, "features"];
+    teamSettings: (id: string) => readonly ["teams", string, "settings"];
+    teamSpaces: (id: string) => readonly ["teams", string, "spaces"];
+    teamDomains: (id: string) => readonly ["teams", string, "domains"];
+    teamManagedDomains: (id: string) => readonly ["teams", string, "managed-domains"];
+    domainBindings: () => readonly ["domain-bindings"];
+    slugAvailability: (kind: "team" | "space", slug: string, teamId?: string, currentSlug?: string) => readonly ["slugs", "availability", "team" | "space", string, string, string];
+    teamVariables: (id: string) => readonly ["teams", string, "variables"];
+    teamActivity: (id: string, limit: number) => readonly ["teams", string, "activity", number];
+    space: (id: string) => readonly ["spaces", string];
+    spaceByRef: (teamRef: string, spaceRef: string) => readonly ["spaces", "by-ref", string, string];
+    spaceVersions: (id: string) => readonly ["spaces", string, "versions"];
+    spaceCollaboration: (id: string) => readonly ["spaces", string, "collaboration"];
+    spaceAnnotations: (id: string) => readonly ["spaces", string, "annotations"];
+    spaceActivity: (id: string, limit: number) => readonly ["spaces", string, "activity", number];
+    spaceDeployments: (id: string) => readonly ["spaces", string, "deployments"];
+    spaceTags: (id: string) => readonly ["spaces", string, "tags"];
+    spaceTagVersion: (id: string, versionId: string) => readonly ["spaces", string, "tags", "versions", string];
+    build: (id: string) => readonly ["builds", string];
+    buildLogs: (id: string) => readonly ["builds", string, "logs"];
+    spaceRepositoryConnection: (id: string, connectionType?: string) => readonly ["spaces", string, "repository-connection", string];
+    repositoryInstallations: (spaceId: string) => readonly ["repository-connections", "installations", string];
+    repositoryInstallationRepositories: (installationId: string) => readonly ["repository-connections", "installations", string, "repositories"];
+    spaceRepositoryAnalyze: (id: string, connectionType?: string, ref?: string, root?: string) => readonly ["spaces", string, "repository-connection", string, "analyze", string, string];
+    spaceRepositoryWebhookDeliveries: (id: string, connectionType?: string) => readonly ["spaces", string, "repository-webhook-deliveries", string];
+    teamWebhooks: (teamId: string) => readonly ["teams", string, "webhooks"];
+    webhook: (webhookId: string) => readonly ["webhooks", string];
+    webhookDeliveries: (webhookId: string) => readonly ["webhooks", string, "deliveries"];
+    spaceVersion: (id: string, versionId: string) => readonly ["spaces", string, "versions", string];
+    spaceVersionAnnotations: (id: string, versionId: string, status?: string) => readonly ["spaces", string, "versions", string, "annotations", string];
+    spaceVersionFiles: (id: string, versionId: string) => readonly ["spaces", string, "versions", string, "files"];
+    spaceVersionFile: (id: string, versionId: string, path: string) => readonly ["spaces", string, "versions", string, "files", string];
+    spaceVersionFileDirectUrl: (id: string, versionId: string, path: string) => readonly ["spaces", string, "versions", string, "files", string, "direct-url"];
+    spaceVersionFileUrlPreview: (id: string, versionId: string, path: string) => readonly ["spaces", string, "versions", string, "files", string, "url-preview"];
+    spaceVersionFileDiff: (id: string, versionId: string, baseVersionId?: string) => readonly ["spaces", string, "versions", string, "files", "diff", string];
+    spaceVersionConventionArtifacts: (id: string, versionId: string) => readonly ["spaces", string, "versions", string, "convention-artifacts"];
+    spaceVersionConventionArtifact: (id: string, versionId: string, kind: "redirects" | "headers") => readonly ["spaces", string, "versions", string, "convention-artifacts", "redirects" | "headers"];
+    spaceVersionRoutingSummary: (id: string, versionId: string) => readonly ["spaces", string, "versions", string, "routing-summary"];
+    spaceDiagnostics: (id: string) => readonly ["spaces", string, "diagnostics"];
+    spaceDomains: (id: string) => readonly ["spaces", string, "domains"];
+    spaceRuntimeStatus: (id: string) => readonly ["spaces", string, "runtime"];
+    spaceApplyState: (id: string) => readonly ["spaces", string, "apply-state"];
+    spaceZero: (id: string) => readonly ["spaces", string, "zero"];
+    spaceZeroDb: (id: string) => readonly ["spaces", string, "zero", "db"];
+    spaceZeroLogs: (id: string, limit: number) => readonly ["spaces", string, "zero", "logs", number];
+    spaceZeroRealtimeEvents: (id: string, limit: number) => readonly ["spaces", string, "zero", "realtime", "events", number];
+    spaceVariables: (id: string) => readonly ["spaces", string, "variables"];
+    spaceCertificates: (id: string) => readonly ["spaces", string, "runtime", "certificates"];
+    spaceLogs: (id: string, kind: "build" | "access" | "runtime") => readonly ["spaces", string, "logs", "build" | "access" | "runtime"];
+    spaceAnalytics: (id: string, window: string) => readonly ["spaces", string, "analytics", string];
+    domain: (teamId: string, ref: string) => readonly ["teams", string, "domains", string];
+    domainDiagnostics: (teamId: string, domainId: string) => readonly ["teams", string, "domains", string, "diagnostics"];
+    domainDnsCapabilities: (domainId: string) => readonly ["domains", string, "dns", "capabilities"];
+    domainDnsRecords: (domainId: string) => readonly ["domains", string, "dns", "records"];
+    domainDnsOperations: (domainId: string) => readonly ["domains", string, "dns", "operations"];
+    domainActions: (domainId: string) => readonly ["domains", string, "actions"];
+    domainProviderConnections: (teamId: string) => readonly ["domains", "provider-connections", string];
+};

package/dist/utils/query-keys.js

@@ -0,0 +1,78 @@
+export const qk = {
+    session: () => ["session"],
+    authCapabilities: () => ["auth", "capabilities"],
+    accountSessions: () => ["account", "sessions"],
+    accountConnections: () => ["account", "connections"],
+    accountInvitations: () => ["account", "invitations"],
+    apiTokens: () => ["api-tokens"],
+    agentAccounts: () => ["agent-accounts"],
+    mcpDashboard: () => ["mcp", "dashboard"],
+    mcpApproval: (id) => ["mcp", "approval", id],
+    // The teams LIST gets its own leaf so invalidating it never cascades into
+    // ["teams", id, ...] resource queries (members, spaces, domains, ...).
+    teams: () => ["teams", "list"],
+    // Keyed by slug (the URL ref), so it lives outside the id namespace.
+    team: (ref) => ["teams", "by-ref", ref],
+    teamMembers: (id) => ["teams", id, "members"],
+    teamInvites: (id) => ["teams", id, "invites"],
+    teamBilling: (id) => ["teams", id, "billing"],
+    teamUsage: (id) => ["teams", id, "usage"],
+    teamEntitlements: (id) => ["teams", id, "entitlements"],
+    teamFeatures: (id) => ["teams", id, "features"],
+    teamSettings: (id) => ["teams", id, "settings"],
+    teamSpaces: (id) => ["teams", id, "spaces"],
+    teamDomains: (id) => ["teams", id, "domains"],
+    teamManagedDomains: (id) => ["teams", id, "managed-domains"],
+    domainBindings: () => ["domain-bindings"],
+    slugAvailability: (kind, slug, teamId, currentSlug) => ["slugs", "availability", kind, slug, teamId ?? "", currentSlug ?? ""],
+    teamVariables: (id) => ["teams", id, "variables"],
+    teamActivity: (id, limit) => ["teams", id, "activity", limit],
+    space: (id) => ["spaces", id],
+    spaceByRef: (teamRef, spaceRef) => ["spaces", "by-ref", teamRef, spaceRef],
+    spaceVersions: (id) => ["spaces", id, "versions"],
+    spaceCollaboration: (id) => ["spaces", id, "collaboration"],
+    spaceAnnotations: (id) => ["spaces", id, "annotations"],
+    spaceActivity: (id, limit) => ["spaces", id, "activity", limit],
+    spaceDeployments: (id) => ["spaces", id, "deployments"],
+    spaceTags: (id) => ["spaces", id, "tags"],
+    spaceTagVersion: (id, versionId) => ["spaces", id, "tags", "versions", versionId],
+    build: (id) => ["builds", id],
+    buildLogs: (id) => ["builds", id, "logs"],
+    spaceRepositoryConnection: (id, connectionType = "connected") => ["spaces", id, "repository-connection", connectionType],
+    repositoryInstallations: (spaceId) => ["repository-connections", "installations", spaceId],
+    repositoryInstallationRepositories: (installationId) => ["repository-connections", "installations", installationId, "repositories"],
+    spaceRepositoryAnalyze: (id, connectionType = "connected", ref = "", root = "") => ["spaces", id, "repository-connection", connectionType, "analyze", ref, root],
+    spaceRepositoryWebhookDeliveries: (id, connectionType = "connected") => ["spaces", id, "repository-webhook-deliveries", connectionType],
+    teamWebhooks: (teamId) => ["teams", teamId, "webhooks"],
+    webhook: (webhookId) => ["webhooks", webhookId],
+    webhookDeliveries: (webhookId) => ["webhooks", webhookId, "deliveries"],
+    spaceVersion: (id, versionId) => ["spaces", id, "versions", versionId],
+    spaceVersionAnnotations: (id, versionId, status = "open") => ["spaces", id, "versions", versionId, "annotations", status],
+    spaceVersionFiles: (id, versionId) => ["spaces", id, "versions", versionId, "files"],
+    spaceVersionFile: (id, versionId, path) => ["spaces", id, "versions", versionId, "files", path],
+    spaceVersionFileDirectUrl: (id, versionId, path) => ["spaces", id, "versions", versionId, "files", path, "direct-url"],
+    spaceVersionFileUrlPreview: (id, versionId, path) => ["spaces", id, "versions", versionId, "files", path, "url-preview"],
+    spaceVersionFileDiff: (id, versionId, baseVersionId) => ["spaces", id, "versions", versionId, "files", "diff", baseVersionId ?? ""],
+    spaceVersionConventionArtifacts: (id, versionId) => ["spaces", id, "versions", versionId, "convention-artifacts"],
+    spaceVersionConventionArtifact: (id, versionId, kind) => ["spaces", id, "versions", versionId, "convention-artifacts", kind],
+    spaceVersionRoutingSummary: (id, versionId) => ["spaces", id, "versions", versionId, "routing-summary"],
+    spaceDiagnostics: (id) => ["spaces", id, "diagnostics"],
+    spaceDomains: (id) => ["spaces", id, "domains"],
+    spaceRuntimeStatus: (id) => ["spaces", id, "runtime"],
+    spaceApplyState: (id) => ["spaces", id, "apply-state"],
+    spaceZero: (id) => ["spaces", id, "zero"],
+    spaceZeroDb: (id) => ["spaces", id, "zero", "db"],
+    spaceZeroLogs: (id, limit) => ["spaces", id, "zero", "logs", limit],
+    spaceZeroRealtimeEvents: (id, limit) => ["spaces", id, "zero", "realtime", "events", limit],
+    spaceVariables: (id) => ["spaces", id, "variables"],
+    spaceCertificates: (id) => ["spaces", id, "runtime", "certificates"],
+    spaceLogs: (id, kind) => ["spaces", id, "logs", kind],
+    spaceAnalytics: (id, window) => ["spaces", id, "analytics", window],
+    domain: (teamId, ref) => ["teams", teamId, "domains", ref],
+    domainDiagnostics: (teamId, domainId) => ["teams", teamId, "domains", domainId, "diagnostics"],
+    domainDnsCapabilities: (domainId) => ["domains", domainId, "dns", "capabilities"],
+    domainDnsRecords: (domainId) => ["domains", domainId, "dns", "records"],
+    domainDnsOperations: (domainId) => ["domains", domainId, "dns", "operations"],
+    domainActions: (domainId) => ["domains", domainId, "actions"],
+    domainProviderConnections: (teamId) => ["domains", "provider-connections", teamId],
+};

package/dist/utils/runtime-paths.d.ts

@@ -0,0 +1,7 @@
+export declare const SPACEFAST_RUNTIME_NAMESPACE: "/__spacefast";
+export declare const RUNTIME_MANAGEMENT_API_PATH: "/__spacefast/api.php";
+export declare const RUNTIME_UPLOAD_API_PATH: "/__spacefast/upload.php";
+export declare const RUNTIME_HEALTH_PATH: "/__spacefast/health.php";
+export declare const RUNTIME_ACCESS_CALLBACK_PATH: "/__spacefast/access-callback.php";
+export declare function runtimeManagementPath(suffix: string): string;
+export declare function runtimeUploadPath(params: URLSearchParams | Record<string, string>): string;

package/dist/utils/runtime-paths.js

@@ -0,0 +1,28 @@
+export const SPACEFAST_RUNTIME_NAMESPACE = "/__spacefast";
+export const RUNTIME_MANAGEMENT_API_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/api.php`;
+export const RUNTIME_UPLOAD_API_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/upload.php`;
+export const RUNTIME_HEALTH_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/health.php`;
+export const RUNTIME_ACCESS_CALLBACK_PATH = `${SPACEFAST_RUNTIME_NAMESPACE}/access-callback.php`;
+export function runtimeManagementPath(suffix) {
+    const route = normalizeRuntimeRoute(suffix);
+    if (route === "/") {
+        return RUNTIME_MANAGEMENT_API_PATH;
+    }
+    const [pathname = "/", query = ""] = route.split("?", 2);
+    const params = new URLSearchParams({ route: pathname });
+    for (const [key, value] of new URLSearchParams(query)) {
+        params.append(key, value);
+    }
+    return `${RUNTIME_MANAGEMENT_API_PATH}?${params.toString()}`;
+}
+export function runtimeUploadPath(params) {
+    const query = params instanceof URLSearchParams ? params : new URLSearchParams(params);
+    return `${RUNTIME_UPLOAD_API_PATH}?${query.toString()}`;
+}
+function normalizeRuntimeRoute(suffix) {
+    if (suffix === "") {
+        return "/";
+    }
+    const route = suffix.startsWith("/") ? suffix : `/${suffix}`;
+    return route;
+}