@sellhapi/mcp 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# @sellhapi/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for SellHapi — build and manage storefronts from AI tools.
+
+## Two modes
+
+**Stdio** (Claude Code, Cursor, Windsurf) — runs locally, authenticates with API key.
+
+**Hosted HTTP** (ChatGPT, Claude web) — runs as a service, authenticates via OAuth 2.1.
+
+## Setup — stdio
+
+### 1. Install
+
+```bash
+npm install -g @sellhapi/mcp
+```
+
+### 2. Get an API key
+
+Go to **sellhapi.com** → Settings → API Keys → Create Key.
+
+### 3. Configure your AI tool
+
+**Claude Code** — add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sellhapi": {
+      "command": "sellhapi-mcp",
+      "args": ["--api-key", "sk_live_your_key_here"]
+    }
+  }
+}
+```
+
+**Cursor** — add to MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "sellhapi": {
+      "command": "npx",
+      "args": ["-y", "@sellhapi/mcp", "--api-key", "sk_live_your_key_here"]
+    }
+  }
+}
+```
+
+Or set the environment variable instead of `--api-key`:
+
+```bash
+export SELLHAPI_API_KEY=sk_live_your_key_here
+```
+
+## Setup — hosted
+
+### 1. Build
+
+```bash
+npm install
+npm run build
+```
+
+### 2. Configure environment
+
+```bash
+cp .env.example .env
+# Edit .env with your values
+```
+
+Required env vars:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | HTTP port | `3100` |
+| `SELLHAPI_API_URL` | sell_api base URL | production |
+| `MCP_SERVER_URL` | Public URL of this server (for OAuth metadata) | `http://localhost:PORT` |
+
+### 3. Run
+
+```bash
+npm run start:hosted
+```
+
+Endpoints:
+
+- `POST /mcp` — MCP Streamable HTTP (initialize + messages)
+- `GET /mcp` — SSE stream
+- `DELETE /mcp` — session teardown
+- `GET /health` — health check
+- `/.well-known/oauth-authorization-server` — OAuth metadata
+
+### sell_api env vars
+
+The sell_api server needs these for OAuth:
+
+| Variable | Description |
+|----------|-------------|
+| `MCP_OAUTH_SECRET` | JWT signing secret for MCP access tokens. Falls back to `JWT_VENDOR_SECRET` if not set. |
+| `SELLHAPI_VENDOR_URL` | Base URL for consent pages (default: `https://sellhapi.com`) |
+
+## Tools
+
+### Studio (5)
+- `list_projects` — list vendor's Studio projects
+- `get_project` — get project details with code
+- `create_project` — create a new project
+- `push_code` — push React code (validated by BuildGuard)
+- `deploy_website` — publish project to live storefront
+
+### Commerce (8)
+- `list_products`, `list_digital_products`, `list_service_listings`
+- `list_events`, `list_membership_tiers`, `list_donation_campaigns`
+- `list_appointment_services`, `list_capabilities`
+
+### Content (4)
+- `list_content`, `list_forms`, `list_collections`, `list_articles`
+
+### Intelligence (2)
+- `list_orders`, `get_wallet_balance`
+
+## Resources
+
+- `sellhapi://runtime-hooks` — available React hooks from @sellhapi/studio-runtime
+- `sellhapi://build-rules` — BuildGuard validation rules
+- `sellhapi://capability-patterns` — UX patterns per capability
+
+## Auth
+
+**API key** (`sk_live_...`) — for stdio clients. Create at sellhapi.com → Settings → API Keys.
+
+**OAuth 2.1** — for web clients. The hosted server proxies OAuth to sell_api. Supports dynamic client registration (RFC 7591) and PKCE (S256).
+
+## Development
+
+```bash
+npm run dev    # watch mode (tsc --watch)
+npm run build  # compile
+npm start      # stdio mode
+npm run start:hosted  # hosted HTTP mode
+```

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+/**
+ * HTTP client for sell_api.
+ * All MCP tools delegate to this client for actual API calls.
+ *
+ * Supports two modes:
+ *   1. Module-level config (stdio) — single API key set once via configure()
+ *   2. Per-request context (hosted) — API key scoped via AsyncLocalStorage
+ *
+ * In hosted mode, withApiKey() wraps each request handler to scope the
+ * credentials. Tool code is identical in both modes — get/post/etc. resolve
+ * the active key automatically.
+ */
+/** Set module-level credentials (stdio mode). */
+export declare function configure(key: string, base?: string): void;
+/**
+ * Run a callback with scoped API key credentials (hosted mode).
+ * All get/post/etc. calls inside the callback will use these credentials.
+ */
+export declare function withApiKey<T>(apiKey: string, baseUrl: string | undefined, fn: () => T): T;
+/** Error with full response body preserved for structured error handling. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: any;
+    constructor(message: string, status: number, body: any);
+}
+export declare function apiCall<T = unknown>(method: "GET" | "POST" | "PATCH" | "DELETE", path: string, body?: unknown): Promise<T>;
+/**
+ * Convenience wrappers.
+ */
+export declare const get: <T = unknown>(path: string) => Promise<T>;
+export declare const post: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+export declare const patch: <T = unknown>(path: string, body?: unknown) => Promise<T>;
+export declare const del: <T = unknown>(path: string) => Promise<T>;

package/dist/client.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * HTTP client for sell_api.
+ * All MCP tools delegate to this client for actual API calls.
+ *
+ * Supports two modes:
+ *   1. Module-level config (stdio) — single API key set once via configure()
+ *   2. Per-request context (hosted) — API key scoped via AsyncLocalStorage
+ *
+ * In hosted mode, withApiKey() wraps each request handler to scope the
+ * credentials. Tool code is identical in both modes — get/post/etc. resolve
+ * the active key automatically.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.del = exports.patch = exports.post = exports.get = exports.ApiError = void 0;
+exports.configure = configure;
+exports.withApiKey = withApiKey;
+exports.apiCall = apiCall;
+const node_async_hooks_1 = require("node:async_hooks");
+const DEFAULT_BASE_URL = "https://sell-api-xl2a.onrender.com";
+/** AsyncLocalStorage for per-request API key scoping in hosted mode. */
+const als = new node_async_hooks_1.AsyncLocalStorage();
+/** Module-level fallback for stdio mode (single key). */
+let globalCtx;
+/** Set module-level credentials (stdio mode). */
+function configure(key, base) {
+    globalCtx = {
+        apiKey: key,
+        baseUrl: (base ?? DEFAULT_BASE_URL).replace(/\/$/, ""),
+    };
+}
+/**
+ * Run a callback with scoped API key credentials (hosted mode).
+ * All get/post/etc. calls inside the callback will use these credentials.
+ */
+function withApiKey(apiKey, baseUrl, fn) {
+    const ctx = {
+        apiKey,
+        baseUrl: (baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, ""),
+    };
+    return als.run(ctx, fn);
+}
+/** Resolve the active credentials (ALS first, then module-level). */
+function getContext() {
+    const ctx = als.getStore() ?? globalCtx;
+    if (!ctx)
+        throw new Error("Client not configured — call configure() or use withApiKey()");
+    return ctx;
+}
+// ── API calls ────────────────────────────────────────────────────────────────
+/** Error with full response body preserved for structured error handling. */
+class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "ApiError";
+    }
+}
+exports.ApiError = ApiError;
+async function apiCall(method, path, body) {
+    const { apiKey, baseUrl } = getContext();
+    const url = `${baseUrl}${path}`;
+    const headers = {
+        "Authorization": `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+    };
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        data = { raw: text };
+    }
+    if (!res.ok) {
+        const msg = data?.error ?? data?.message ?? `HTTP ${res.status}`;
+        throw new ApiError(msg, res.status, data);
+    }
+    return data;
+}
+/**
+ * Convenience wrappers.
+ */
+const get = (path) => apiCall("GET", path);
+exports.get = get;
+const post = (path, body) => apiCall("POST", path, body);
+exports.post = post;
+const patch = (path, body) => apiCall("PATCH", path, body);
+exports.patch = patch;
+const del = (path) => apiCall("DELETE", path);
+exports.del = del;

package/dist/hosted.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * @sellhapi/mcp — hosted HTTP entry point with OAuth 2.1.
+ *
+ * For web-based AI clients (ChatGPT, Claude web) that connect via Streamable HTTP.
+ * Supports two auth methods:
+ *   1. API key (Bearer sk_live_...) — directly scoped
+ *   2. OAuth (Bearer eyJ...) — user logs in via SellHapi, AI client gets token
+ *
+ * The OAuth flow uses the MCP SDK's ProxyOAuthServerProvider which delegates
+ * all auth decisions to sell_api's OAuth endpoints. This server is stateless
+ * with respect to auth — it just proxies.
+ *
+ * Environment variables:
+ *   PORT              — HTTP port (default 3100)
+ *   SELLHAPI_API_URL  — sell_api base URL (default production)
+ *   MCP_SERVER_URL    — public URL of this MCP server (for OAuth metadata)
+ *
+ * Endpoints:
+ *   POST/GET/DELETE /mcp — MCP Streamable HTTP
+ *   GET /health          — Health check
+ *   /.well-known/*       — OAuth metadata (auto-mounted by mcpAuthRouter)
+ *   /authorize, /token, /register — OAuth (proxied to sell_api)
+ */
+export {};

package/dist/hosted.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * @sellhapi/mcp — hosted HTTP entry point with OAuth 2.1.
+ *
+ * For web-based AI clients (ChatGPT, Claude web) that connect via Streamable HTTP.
+ * Supports two auth methods:
+ *   1. API key (Bearer sk_live_...) — directly scoped
+ *   2. OAuth (Bearer eyJ...) — user logs in via SellHapi, AI client gets token
+ *
+ * The OAuth flow uses the MCP SDK's ProxyOAuthServerProvider which delegates
+ * all auth decisions to sell_api's OAuth endpoints. This server is stateless
+ * with respect to auth — it just proxies.
+ *
+ * Environment variables:
+ *   PORT              — HTTP port (default 3100)
+ *   SELLHAPI_API_URL  — sell_api base URL (default production)
+ *   MCP_SERVER_URL    — public URL of this MCP server (for OAuth metadata)
+ *
+ * Endpoints:
+ *   POST/GET/DELETE /mcp — MCP Streamable HTTP
+ *   GET /health          — Health check
+ *   /.well-known/*       — OAuth metadata (auto-mounted by mcpAuthRouter)
+ *   /authorize, /token, /register — OAuth (proxied to sell_api)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = __importDefault(require("express"));
+const node_crypto_1 = require("node:crypto");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const router_js_1 = require("@modelcontextprotocol/sdk/server/auth/router.js");
+const proxyProvider_js_1 = require("@modelcontextprotocol/sdk/server/auth/providers/proxyProvider.js");
+const client_js_1 = require("./client.js");
+const server_js_1 = require("./server.js");
+const PORT = parseInt(process.env.PORT ?? "3100", 10);
+const API_URL = process.env.SELLHAPI_API_URL ?? "https://sell-api-xl2a.onrender.com";
+const SERVER_URL = process.env.MCP_SERVER_URL ?? `http://localhost:${PORT}`;
+const sessions = new Map();
+const SESSION_TTL_MS = 30 * 60 * 1000;
+const MAX_SESSIONS = 1000;
+setInterval(() => {
+    const now = Date.now();
+    for (const [id, session] of sessions) {
+        if (now - session.lastUsed > SESSION_TTL_MS) {
+            session.transport.close?.();
+            sessions.delete(id);
+        }
+    }
+}, 5 * 60 * 1000).unref();
+// ── OAuth provider (proxies to sell_api) ─────────────────────────────────────
+const oauthProvider = new proxyProvider_js_1.ProxyOAuthServerProvider({
+    endpoints: {
+        authorizationUrl: `${API_URL}/api/mcp/oauth/authorize`,
+        tokenUrl: `${API_URL}/api/mcp/oauth/token`,
+        registrationUrl: `${API_URL}/api/mcp/oauth/register`,
+    },
+    async verifyAccessToken(token) {
+        const res = await fetch(`${API_URL}/api/mcp/oauth/verify-token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ token }),
+        });
+        if (!res.ok) {
+            throw new Error("Invalid or expired token");
+        }
+        const data = await res.json();
+        if (!data.vendorId) {
+            throw new Error("Invalid token — missing vendorId");
+        }
+        return {
+            token,
+            clientId: data.clientId,
+            scopes: data.scope ? data.scope.split(" ") : [],
+            expiresAt: data.expiresAt,
+            extra: { vendorId: data.vendorId },
+        };
+    },
+    async getClient(clientId) {
+        const res = await fetch(`${API_URL}/api/mcp/oauth/client/${encodeURIComponent(clientId)}`);
+        if (!res.ok)
+            return undefined;
+        const data = await res.json();
+        return data;
+    },
+});
+// ── Resolve API key from auth context ────────────────────────────────────────
+function resolveApiKeyFromAuth(req) {
+    const auth = req.headers.authorization;
+    if (!auth)
+        return null;
+    const token = auth.replace(/^Bearer\s+/i, "");
+    // API key path — pass through directly
+    if (token.startsWith("sk_live_")) {
+        return token;
+    }
+    // OAuth path — the authInfo was set by mcpAuthRouter's bearer middleware
+    // We use the token itself as the "API key" for the HTTP client
+    // The sell_api apiKeyAuth middleware accepts both sk_live_ and JWT tokens
+    return token;
+}
+// ── Express app ──────────────────────────────────────────────────────────────
+const app = (0, express_1.default)();
+app.set("trust proxy", 1); // Render runs behind a reverse proxy
+// CORS
+app.use((req, res, next) => {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, Mcp-Session-Id");
+    res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+    if (req.method === "OPTIONS") {
+        res.sendStatus(204);
+        return;
+    }
+    next();
+});
+// Health check
+app.get("/health", (_req, res) => {
+    res.json({ status: "ok", sessions: sessions.size });
+});
+// OAuth routes (metadata, authorize, token, register)
+// Must be mounted at root for .well-known discovery to work
+app.use((0, router_js_1.mcpAuthRouter)({
+    provider: oauthProvider,
+    issuerUrl: new URL(SERVER_URL),
+    scopesSupported: ["studio", "commerce", "content", "intelligence"],
+    serviceDocumentationUrl: new URL("https://sellhapi.com/mcp"),
+}));
+// MCP endpoint — JSON body parsing
+app.use("/mcp", express_1.default.json());
+// MCP POST — initialize or send message
+app.post("/mcp", async (req, res) => {
+    const apiKey = resolveApiKeyFromAuth(req);
+    if (!apiKey) {
+        res.status(401).json({ error: "Missing authorization" });
+        return;
+    }
+    const parsedBody = req.body;
+    const sessionId = req.headers["mcp-session-id"];
+    const isInit = Array.isArray(parsedBody)
+        ? parsedBody.some((m) => m.method === "initialize")
+        : parsedBody?.method === "initialize";
+    if (isInit) {
+        if (sessions.size >= MAX_SESSIONS) {
+            res.status(429).json({ error: "Too many active sessions. Try again later." });
+            return;
+        }
+        const server = (0, server_js_1.createMcpServer)();
+        const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+            sessionIdGenerator: () => (0, node_crypto_1.randomUUID)(),
+            onsessioninitialized: (sid) => {
+                console.log(`[mcp] session initialized: ${sid}`);
+                sessions.set(sid, { server, transport, apiKey, lastUsed: Date.now() });
+            },
+        });
+        transport.onclose = () => {
+            if (transport.sessionId)
+                sessions.delete(transport.sessionId);
+        };
+        try {
+            await server.connect(transport);
+            await (0, client_js_1.withApiKey)(apiKey, API_URL, () => transport.handleRequest(req, res, parsedBody));
+        }
+        catch (err) {
+            console.error("[mcp] init error:", err);
+            if (!res.headersSent)
+                res.status(500).json({ error: "Internal server error" });
+        }
+        return;
+    }
+    if (!sessionId || !sessions.has(sessionId)) {
+        console.log(`[mcp] unknown session: ${sessionId}, active sessions: ${sessions.size}`);
+        res.status(400).json({ error: "Missing or invalid Mcp-Session-Id. Initialize first." });
+        return;
+    }
+    const session = sessions.get(sessionId);
+    session.lastUsed = Date.now();
+    const method = Array.isArray(parsedBody)
+        ? parsedBody.map((m) => m.method).join(",")
+        : parsedBody?.method;
+    console.log(`[mcp] ${sessionId.slice(0, 8)}… method=${method}`);
+    try {
+        await (0, client_js_1.withApiKey)(session.apiKey, API_URL, () => session.transport.handleRequest(req, res, parsedBody));
+    }
+    catch (err) {
+        console.error(`[mcp] ${sessionId.slice(0, 8)}… error:`, err);
+        if (!res.headersSent)
+            res.status(500).json({ error: "Internal server error" });
+    }
+});
+// MCP GET — SSE stream
+app.get("/mcp", async (req, res) => {
+    const sessionId = req.headers["mcp-session-id"];
+    if (!sessionId || !sessions.has(sessionId)) {
+        res.status(400).json({ error: "Missing or invalid Mcp-Session-Id." });
+        return;
+    }
+    const session = sessions.get(sessionId);
+    session.lastUsed = Date.now();
+    try {
+        await (0, client_js_1.withApiKey)(session.apiKey, API_URL, () => session.transport.handleRequest(req, res));
+    }
+    catch (err) {
+        console.error(`[mcp] GET stream error:`, err);
+        if (!res.headersSent)
+            res.status(500).json({ error: "Internal server error" });
+    }
+});
+// MCP DELETE — session teardown
+app.delete("/mcp", (req, res) => {
+    const sessionId = req.headers["mcp-session-id"];
+    if (sessionId && sessions.has(sessionId)) {
+        const session = sessions.get(sessionId);
+        session.transport.close?.();
+        sessions.delete(sessionId);
+    }
+    res.sendStatus(204);
+});
+// ── Keep-alive ping (prevent Render free tier sleep) ────────────────────────
+// Ping sell_api every 10 minutes to keep it warm for tool calls
+setInterval(async () => {
+    try {
+        await fetch(API_URL);
+    }
+    catch { /* ignore */ }
+}, 10 * 60 * 1000).unref();
+// ── Start ────────────────────────────────────────────────────────────────────
+app.listen(PORT, () => {
+    console.log(`SellHapi MCP server (hosted + OAuth) listening on port ${PORT}`);
+    console.log(`  MCP endpoint: ${SERVER_URL}/mcp`);
+    console.log(`  OAuth issuer: ${SERVER_URL}`);
+    console.log(`  Health check: ${SERVER_URL}/health`);
+});

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * @sellhapi/mcp — stdio entry point.
+ *
+ * For local AI tools (Claude Code, Cursor, etc.) that connect via stdio.
+ *
+ * Usage:
+ *   npx @sellhapi/mcp --api-key sk_live_...
+ *   npx @sellhapi/mcp --api-key sk_live_... --base-url http://localhost:5000
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * @sellhapi/mcp — stdio entry point.
+ *
+ * For local AI tools (Claude Code, Cursor, etc.) that connect via stdio.
+ *
+ * Usage:
+ *   npx @sellhapi/mcp --api-key sk_live_...
+ *   npx @sellhapi/mcp --api-key sk_live_... --base-url http://localhost:5000
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const client_js_1 = require("./client.js");
+const server_js_1 = require("./server.js");
+// ── Parse CLI args ───────────────────────────────────────────────────────────
+function parseArgs() {
+    const args = process.argv.slice(2);
+    let apiKey;
+    let baseUrl;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--api-key" && args[i + 1]) {
+            apiKey = args[++i];
+        }
+        else if (args[i] === "--base-url" && args[i + 1]) {
+            baseUrl = args[++i];
+        }
+        else if (args[i].startsWith("--api-key=")) {
+            apiKey = args[i].split("=")[1];
+        }
+        else if (args[i].startsWith("--base-url=")) {
+            baseUrl = args[i].split("=")[1];
+        }
+    }
+    apiKey = apiKey ?? process.env.SELLHAPI_API_KEY;
+    baseUrl = baseUrl ?? process.env.SELLHAPI_BASE_URL;
+    if (!apiKey) {
+        console.error("Error: API key required. Use --api-key sk_live_... or set SELLHAPI_API_KEY env var.");
+        process.exit(1);
+    }
+    return { apiKey, baseUrl };
+}
+// ── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+    const { apiKey, baseUrl } = parseArgs();
+    (0, client_js_1.configure)(apiKey, baseUrl);
+    const server = (0, server_js_1.createMcpServer)();
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});

package/dist/resources/build-rules.d.ts

@@ -0,0 +1,5 @@
+/**
+ * BuildGuard rules — extracted from buildGuard.service.ts.
+ * Code that violates these rules will be rejected by push_code.
+ */
+export declare const BUILD_RULES = "\n# SellHapi BuildGuard Rules\n\nYour code MUST pass all these rules or push_code will reject it with specific violation details.\n\n## APPROVED IMPORTS (only these are allowed)\n\nExact matches:\n  @sellhapi/studio-runtime\n  react\n  react-dom\n  react-dom/client\n  react/jsx-runtime\n  react/jsx-dev-runtime\n  framer-motion\n  clsx\n  date-fns\n  zod\n  lucide-react\n\nSubpath imports allowed:\n  date-fns/*\n  react-dom/*\n  react/*\n\nRelative imports (./ and ../) are always allowed between project files.\n\nEVERYTHING ELSE IS BLOCKED \u2014 no axios, no tailwindcss, no lodash, no node builtins.\n\n## HARD VIOLATIONS (build fails)\n\n1. DISALLOWED IMPORTS\n   Any import not in the approved list above.\n   Violation: \"Import from X is not allowed.\"\n\n2. DYNAMIC REQUIRE\n   require() with non-string argument or unapproved package.\n   Violation: \"Dynamic require() is not allowed.\"\n\n3. DYNAMIC IMPORT\n   import() expressions (as opposed to static import statements).\n   Violation: \"Dynamic import() is not allowed in generated storefront code.\"\n\n4. CODE INJECTION\n   eval(), new Function(), Function() \u2014 all blocked.\n   Violation: \"eval()/Function() is not allowed \u2014 code injection risk.\"\n\n5. RAW NETWORK ACCESS\n   fetch(), new XMLHttpRequest(), new WebSocket() \u2014 all blocked.\n   Violation: \"Direct fetch() calls are not allowed. Use hooks from @sellhapi/studio-runtime instead.\"\n   All data must flow through runtime hooks.\n\n6. DANGEROUS GLOBALS\n   Blocked property access:\n   - process.env\n   - document.cookie, document.write(), document.writeln(), document.domain, document.execCommand()\n   - window.fetch, window.eval, window.Function\n   - window.XMLHttpRequest, window.WebSocket\n   - window.localStorage, window.sessionStorage, window.indexedDB\n   - navigator.sendBeacon\n   - Standalone: localStorage, sessionStorage, indexedDB\n   Violation: \"X is not allowed in storefront code.\"\n\n7. SUBSCRIPT ACCESS ON GLOBALS\n   window[\"fetch\"], globalThis[\"eval\"], self[\"XMLHttpRequest\"] \u2014 all blocked.\n   Violation: \"Subscript access on 'window' is not allowed.\"\n\n8. DANGEROUS JSX\n   dangerouslySetInnerHTML \u2014 blocked.\n   Violation: \"dangerouslySetInnerHTML is not allowed \u2014 XSS vector.\"\n\n9. MISSING CART DRAWER\n   If any file uses useCart or addItem, <CartDrawer /> MUST be rendered somewhere.\n   Violation: \"useCart/addItem is used but <CartDrawer /> is not rendered anywhere.\"\n\n## SOFT WARNINGS (build passes, but flagged)\n\n1. product.images[N].url \u2014 WRONG. images is string[], each element IS the URL.\n   Fix: use images[N] directly or product.imageUrl for primary.\n\n2. addItem() without type field \u2014 CartItem.type is required.\n   Fix: add type: 'physical' | 'digital' to every addItem() call.\n\n3. campaign.raised / campaign.goalAmount \u2014 WRONG field names.\n   Fix: use campaign.raisedAmountKobo / campaign.goalAmountKobo (divide by 100 for display).\n\n4. ticketType.soldCount \u2014 WRONG. Use ticketType.sold.\n\n## REQUIRED: data-region ATTRIBUTES\n\nEvery section that renders live data MUST have a data-region attribute on its outermost container element.\nThis is required for Studio's region selector, Layers panel, and entity injection to work.\n\nRequired attributes:\n  data-region=\"<slug>\"    \u2014 unique kebab-case identifier, e.g. \"hero\", \"products\", \"appointments\"\n  data-label=\"<name>\"     \u2014 human-readable label shown in Studio UI, e.g. \"Products Section\"\n  data-scope=\"content\"    \u2014 always \"content\" for data-driven sections\n\nExample:\n  <section data-region=\"products\" data-label=\"Products\" data-scope=\"content\">\n    {/* useProducts() renders here */}\n  </section>\n\n  <section data-region=\"appointments\" data-label=\"Consultations\" data-scope=\"content\">\n    {/* useServices() renders here */}\n  </section>\n\nALSO add data-region to static layout sections (hero, footer, nav) \u2014 these don't need data hooks but must still be selectable:\n  <section data-region=\"hero\" data-label=\"Hero\" data-scope=\"layout\">\n  <header data-region=\"navigation\" data-label=\"Navigation\" data-scope=\"navigation\">\n  <footer data-region=\"footer\" data-label=\"Footer\" data-scope=\"layout\">\n\nIf you use ANY data hook (useProducts, useServices, useEvents, etc.) without ANY data-region attributes, the build will warn you.\n\n## FILE STRUCTURE\n\nRequired: App.tsx (or App.jsx) as entry point.\nRecommended structure:\n  App.tsx              \u2014 main component with routing\n  components/          \u2014 reusable UI components\n  pages/               \u2014 route-level pages (ProductPage, EventPage, etc.)\n  styles/              \u2014 optional shared styles\n\n## BUNDLE SIZE LIMITS\n\nHard limit: 4 MB (build fails above this)\nWarning: 3.5 MB (runtime baseline is ~2.1 MB \u2014 aim to keep user code under 1.4 MB)\n\n## STYLING\n\nUse inline styles (React style objects) \u2014 this is the convention.\nCSS modules work but are not typical.\nTailwind is NOT available (not in approved imports).\nframer-motion is available for animations.\n\n## KEY PATTERNS\n\n1. All data comes from hooks. NEVER hardcode product names, prices, or content.\n2. Show loading states: if (loading) return <div>Loading...</div>\n3. Show empty states: if (data.length === 0) return <div>No items yet</div>\n4. Format prices: (priceKobo / 100).toLocaleString() for Naira display\n5. Use useHashRouter() for multi-page navigation\n6. Commerce actions return { paymentLink } \u2014 redirect: window.location.href = result.paymentLink\n";