@sellhapi/mcp 0.0.0-stage → 0.1.1

package/dist/resources/design-direction-schema.js

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * DesignDirection schema resource.
+ *
+ * Exposes the exact DesignDirection TypeScript interface + field documentation
+ * so AI clients can generate a valid direction JSON themselves (zero SellHapi
+ * Claude cost) and submit it via the apply_design_direction tool.
+ *
+ * Mirrors the interface in generate2.controller.ts. Keep in sync when that
+ * interface changes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESIGN_DIRECTION_SCHEMA = void 0;
+exports.DESIGN_DIRECTION_SCHEMA = `
+# SellHapi Design Direction Schema
+
+Use this schema to generate a \`DesignDirection\` JSON object and submit it via
+\`apply_design_direction\`. This path costs SellHapi nothing — your own LLM does
+the work. Only fall back to \`set_design_direction\` if you cannot generate
+structured JSON reliably.
+
+---
+
+## Top-level object
+
+\`\`\`typescript
+{
+  businessType:    string;           // REQUIRED. e.g. "fashion", "bakery", "photography"
+  capabilityIds:   string[];         // REQUIRED. Active capability IDs. See /api/mcp/capabilities.
+  capabilitySlots?: CapabilitySlot[]; // Optional. Richer slot-per-purpose model (see below).
+  pages:           Page[];           // REQUIRED. Non-empty. One entry per storefront page.
+  visualDirection: VisualDirection;  // REQUIRED. All visual tokens.
+  businessContext: BusinessContext;  // REQUIRED. Business identity.
+  storefrontConfig?: StorefrontConfig; // Optional. Only for storefront-mode projects.
+  displayModes?: DisplayModes;       // Optional. Product display preferences.
+}
+\`\`\`
+
+---
+
+## Page
+
+Each page the storefront will have. Minimum 1, typically 3–6.
+
+\`\`\`typescript
+{
+  slug:     string;    // URL-safe identifier. e.g. "home", "products", "about", "contact"
+  title:    string;    // Display name. e.g. "Home", "Shop", "About Us"
+  sections: string[];  // Section labels in order. e.g. ["hero", "product-grid", "testimonials", "newsletter"]
+}
+\`\`\`
+
+**Section label conventions:**
+- Use lowercase kebab-case
+- Should describe content purpose: "hero", "featured-products", "services-list", "booking-cta",
+  "testimonials", "faq", "team", "newsletter", "about-story", "contact-form", "events-grid"
+- Capability-specific sections should reference the capability:
+  "appointment-booking", "donation-campaigns", "membership-tiers", "events-list"
+
+**Common page structures:**
+
+Physical products store:
+\`\`\`
+home:     ["hero", "featured-products", "collections", "testimonials", "newsletter"]
+products: ["filter-bar", "product-grid", "pagination"]
+about:    ["brand-story", "values", "team"]
+contact:  ["contact-form", "location-map"]
+\`\`\`
+
+Service business:
+\`\`\`
+home:     ["hero", "services-overview", "how-it-works", "testimonials", "booking-cta"]
+services: ["services-list", "pricing"]
+about:    ["our-story", "team", "credentials"]
+contact:  ["contact-form", "faq"]
+\`\`\`
+
+---
+
+## VisualDirection
+
+All fields except the optional ones are required.
+
+\`\`\`typescript
+{
+  // Descriptive aesthetic — free text. e.g. "Minimal luxury", "Vibrant street market"
+  style:           string;
+
+  primaryColor:    string;   // Main brand color — hex. e.g. "#1a1a2e"
+  accentColor:     string;   // CTA / highlight color — hex. e.g. "#e94560"
+  backgroundColor: string;   // Page background — hex. Can be dark, cream, off-white.
+  surfaceColor:    string;   // Card / panel background — hex.
+  textColor:       string;   // Primary text color — hex.
+
+  headingFont:     string;   // Google Fonts name for headings. e.g. "Playfair Display", "Space Grotesk"
+  bodyFont:        string;   // Google Fonts name for body copy. e.g. "Inter", "DM Sans"
+  fontStyle:       string;   // Description. e.g. "editorial serif headings with clean sans body"
+
+  // Enum values — use exactly as written:
+  cardStyle:    "flat" | "soft-shadow" | "bordered" | "glassmorphism";
+  buttonStyle:  "pill" | "rounded" | "sharp" | "outline-first";
+  visualEffect: "flat" | "subtle-gradient" | "glassmorphism" | "textured";
+
+  mood: string;  // e.g. "sophisticated and aspirational", "warm and approachable"
+
+  // Optional — include when you have reference site analysis or strong design intent:
+  layoutPattern?:          string;  // e.g. "full-bleed hero, 3-col card grid, alternating split sections"
+  spacingRhythm?:          string;  // e.g. "generous whitespace, section padding 80–120px"
+  typographyScale?:        string;  // e.g. "oversized display ~72px, 17px body, tight heading tracking"
+  componentNotes?:         string;  // e.g. "rounded cards with drop shadow, pill category tags"
+  distinctiveElements?:    string;  // e.g. "full-bleed photography, sticky glassmorphic nav"
+}
+\`\`\`
+
+**Color guidance:**
+- All color fields must be valid hex strings (#rrggbb or #rgb)
+- Ensure sufficient contrast: textColor vs backgroundColor ≥ 4.5:1 (WCAG AA)
+- primaryColor and accentColor should be visually distinct
+- surfaceColor is usually a slightly lighter/darker variant of backgroundColor
+
+**Font guidance:**
+- Use Google Fonts names exactly as they appear on fonts.google.com
+- Pairing examples: "Playfair Display" + "Inter", "Space Grotesk" + "DM Sans",
+  "Syne" + "Outfit", "Cormorant Garamond" + "Jost"
+
+---
+
+## BusinessContext
+
+\`\`\`typescript
+{
+  name:               string;    // REQUIRED. Business name. e.g. "Adire Lagos"
+  tagline:            string;    // One-line value prop. e.g. "Authentic Nigerian fashion for the bold"
+  targetAudience:     string;    // e.g. "Nigerian professionals aged 25–40 who value craftsmanship"
+  uniqueSellingPoints: string[]; // 2–4 bullets. e.g. ["Handcrafted in Lagos", "Free delivery over ₦15,000"]
+}
+\`\`\`
+
+---
+
+## CapabilitySlot (optional, more expressive than capabilityIds alone)
+
+\`\`\`typescript
+{
+  purpose:      string;    // Human-readable job. e.g. "Let customers book sessions"
+  capability:   string;    // Selected capability ID. e.g. "appointments"
+  alternatives: string[];  // Valid swaps for this slot. Always include the selected capability.
+}
+\`\`\`
+
+---
+
+## StorefrontConfig (optional)
+
+\`\`\`typescript
+{
+  storeType: "fashion" | "beauty" | "food" | "electronics" | "general";
+  vendorOverrides: string[];  // Free-text additions. e.g. ["Feature collections on homepage"]
+}
+\`\`\`
+
+---
+
+## DisplayModes (optional — only for stores with physical_products)
+
+\`\`\`typescript
+{
+  productGrid:  boolean;  // Main product grid (useProducts)
+  collections:  boolean;  // Product collections (useProductCollections)
+  sections:     boolean;  // Category sections (useSections)
+  bundles:      boolean;  // Bundles & deals (useStorefrontBundles)
+}
+\`\`\`
+
+---
+
+## Full example — Lagos fashion store
+
+\`\`\`json
+{
+  "businessType": "fashion",
+  "capabilityIds": ["physical_products", "content", "customer_accounts"],
+  "pages": [
+    {
+      "slug": "home",
+      "title": "Home",
+      "sections": ["hero", "featured-products", "collections", "brand-story", "testimonials", "newsletter"]
+    },
+    {
+      "slug": "shop",
+      "title": "Shop",
+      "sections": ["filter-bar", "product-grid"]
+    },
+    {
+      "slug": "about",
+      "title": "About",
+      "sections": ["brand-story", "values", "team"]
+    },
+    {
+      "slug": "contact",
+      "title": "Contact",
+      "sections": ["contact-form", "faq"]
+    }
+  ],
+  "visualDirection": {
+    "style": "Minimal luxury",
+    "primaryColor": "#1a1a2e",
+    "accentColor": "#c9a84c",
+    "backgroundColor": "#fafaf8",
+    "surfaceColor": "#ffffff",
+    "textColor": "#1a1a2e",
+    "headingFont": "Cormorant Garamond",
+    "bodyFont": "Inter",
+    "fontStyle": "editorial serif headings with clean sans body",
+    "cardStyle": "soft-shadow",
+    "buttonStyle": "sharp",
+    "visualEffect": "flat",
+    "mood": "sophisticated and aspirational",
+    "layoutPattern": "full-bleed hero, 2-col editorial split, 3-col product grid",
+    "spacingRhythm": "generous whitespace, 100–120px section padding",
+    "typographyScale": "oversized display 72px, 16px body, tight tracking on headings"
+  },
+  "businessContext": {
+    "name": "Adire Lagos",
+    "tagline": "Authentic Nigerian fashion for the bold",
+    "targetAudience": "Nigerian professionals aged 25–40 who value craftsmanship",
+    "uniqueSellingPoints": [
+      "Handcrafted adire fabric from Abeokuta",
+      "Free delivery over ₦15,000",
+      "30-day returns"
+    ]
+  },
+  "storefrontConfig": {
+    "storeType": "fashion",
+    "vendorOverrides": []
+  }
+}
+\`\`\`
+
+---
+
+## Submission
+
+Once you have generated the direction JSON and the user has reviewed it:
+
+\`\`\`
+apply_design_direction(projectId, direction)
+\`\`\`
+
+The server validates the shape, filters any unrecognised capabilityIds, and stores
+the direction on the project. Status advances to "directing".
+`;

package/dist/resources/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP Resources — teach AI clients how to write valid SellHapi storefront code.
+ *
+ * These resources are automatically loaded by AI clients when they connect.
+ * They contain everything needed to generate React code that passes BuildGuard
+ * and correctly uses the @sellhapi/studio-runtime hooks.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerResources(server: McpServer): void;

package/dist/resources/index.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * MCP Resources — teach AI clients how to write valid SellHapi storefront code.
+ *
+ * These resources are automatically loaded by AI clients when they connect.
+ * They contain everything needed to generate React code that passes BuildGuard
+ * and correctly uses the @sellhapi/studio-runtime hooks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerResources = registerResources;
+const runtime_hooks_js_1 = require("./runtime-hooks.js");
+const build_rules_js_1 = require("./build-rules.js");
+const capability_patterns_js_1 = require("./capability-patterns.js");
+const design_direction_schema_js_1 = require("./design-direction-schema.js");
+const wireframe_schema_js_1 = require("./wireframe-schema.js");
+function registerResources(server) {
+    // ── Runtime Hooks ──────────────────────────────────────────────────────────
+    server.registerResource("runtime-hooks", "sellhapi://runtime-hooks", {
+        description: "Complete reference for all @sellhapi/studio-runtime hooks — signatures, return shapes, and usage examples. Read this BEFORE generating any storefront code.",
+        mimeType: "text/plain",
+    }, async () => ({
+        contents: [{ uri: "sellhapi://runtime-hooks", text: runtime_hooks_js_1.RUNTIME_HOOKS, mimeType: "text/plain" }],
+    }));
+    // ── Build Rules ────────────────────────────────────────────────────────────
+    server.registerResource("build-rules", "sellhapi://build-rules", {
+        description: "BuildGuard validation rules — what code patterns are allowed and forbidden. Code that violates these rules will be rejected by push_code.",
+        mimeType: "text/plain",
+    }, async () => ({
+        contents: [{ uri: "sellhapi://build-rules", text: build_rules_js_1.BUILD_RULES, mimeType: "text/plain" }],
+    }));
+    // ── Design Direction Schema ────────────────────────────────────────────────
+    server.registerResource("design-direction-schema", "sellhapi://design-direction-schema", {
+        description: "Complete DesignDirection JSON schema with field documentation, enum values, font pairing guidance, and a full example. Read this before calling apply_design_direction — generate the direction object yourself (free) instead of using set_design_direction (costs Claude API credits).",
+        mimeType: "text/plain",
+    }, async () => ({
+        contents: [{ uri: "sellhapi://design-direction-schema", text: design_direction_schema_js_1.DESIGN_DIRECTION_SCHEMA, mimeType: "text/plain" }],
+    }));
+    // ── Wireframe Schema ───────────────────────────────────────────────────────
+    server.registerResource("wireframe-schema", "sellhapi://wireframe-schema", {
+        description: "Wireframe shape, section conventions, nav/footer rules, data-hook reference table, and user-presentation format. Read this before generating wireframes. The wireframe is the user's checkpoint — present each page to the user for approval before calling apply_wireframe.",
+        mimeType: "text/plain",
+    }, async () => ({
+        contents: [{ uri: "sellhapi://wireframe-schema", text: wireframe_schema_js_1.WIREFRAME_SCHEMA, mimeType: "text/plain" }],
+    }));
+    // ── Capability Patterns ────────────────────────────────────────────────────
+    // Fetched live from sell_api on each read — auto-generated from STUDIO_PROMPT_REGISTRY.
+    // Falls back to the bundled static copy if the API is unreachable.
+    server.registerResource("capability-patterns", "sellhapi://capability-patterns", {
+        description: "Per-capability data shapes, anti-patterns, hook checklists, and UX flows. Auto-generated from the live server registry — always up to date. Covers: products, digital products, services, appointments, events, donations, memberships, content, listings, customer auth.",
+        mimeType: "text/plain",
+    }, async () => {
+        const text = await (0, capability_patterns_js_1.buildCapabilityPatterns)();
+        return { contents: [{ uri: "sellhapi://capability-patterns", text, mimeType: "text/plain" }] };
+    });
+}

package/dist/resources/runtime-hooks.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runtime hooks reference — extracted from @sellhapi/studio-runtime.
+ * This resource teaches AI clients the exact hook signatures and return shapes.
+ */
+export declare const RUNTIME_HOOKS = "\n# @sellhapi/studio-runtime \u2014 Hook Reference\n\nAll imports come from \"@sellhapi/studio-runtime\". No other network/data access is allowed.\n\n## IMPORTANT RULES\n- All prices are in kobo (divide by 100 for Naira display): product.priceKobo / 100\n- product.images is string[] \u2014 each element IS the URL. NEVER access .url on it.\n- Always include type: 'physical' | 'digital' when calling addItem()\n- If you use useCart/addItem, you MUST render <CartDrawer /> in App.tsx\n- FetchState<T> = { data: T; loading: boolean; error: string | null }\n\n---\n\n## ROUTING (required for multi-page storefronts)\n\nuseHashRouter()\n  Returns: { route: string; params: Record<string, string>; navigate: (route: string) => void }\n  Usage: const { route, navigate } = useHashRouter();\n  Routes: \"#/\" (home), \"#/product/:id\", \"#/digital/:id\", \"#/services/:id\", etc.\n\n---\n\n## PHYSICAL PRODUCTS\n\nuseProducts(options?)\n  Options: { limit?: number; categoryId?: string; collectionId?: string; sectionId?: string; sort?: \"newest\"|\"price_asc\"|\"price_desc\"; search?: string; ids?: string[] }\n  Returns: FetchState<StoreProduct[]>\n  StoreProduct: { id, name, priceKobo, compareAtPriceKobo, imageUrl, images: string[], category, type: \"physical\"|\"digital\", variants: StoreProductVariant[], inStock }\n\nuseProduct(productId: string)\n  Returns: FetchState<StoreProductDetail | null>\n  StoreProductDetail: extends StoreProduct + { description, variants: StoreProductVariant[] }\n  StoreProductVariant: { id, size, color, priceKobo, compareAtPriceKobo, stock, imageUrl }\n\nuseCategories()\n  Returns: FetchState<StoreCategory[]>\n  StoreCategory: { name: string; count: number }\n\nuseProductCollections()\n  Returns: FetchState<ProductCollection[]>\n  ProductCollection: { id, name, coverImage: string | null }\n\nuseSections()\n  Returns: FetchState<StoreSection[]>\nuseSection(sectionId: string)\n  Returns: FetchState<StoreProduct[]>\n\n---\n\n## CART & CHECKOUT\n\nuseCart()\n  Returns: {\n    items: CartItem[]; count: number; totalKobo: number; savingsKobo: number; isEmpty: boolean;\n    addItem: (item: { productId, name, priceKobo, imageUrl?, variantId?, variantLabel?, quantity?, type: \"physical\"|\"digital\" }) => void;\n    removeItem: (productId, variantId?) => void;\n    updateQty: (productId, quantity, variantId?) => void;\n    clear: () => void;\n    openCart: () => void;        // MUST call after addItem \u2014 opens the cart drawer\n    openCheckout: () => void;\n  }\n\nCartDrawer \u2014 REQUIRED component if using cart. Import from \"@sellhapi/studio-runtime\".\n  Usage: <CartDrawer /> in App.tsx root. Without it, openCart() does nothing.\n\nuseCartCheckout()\n  Returns: { initiate: (customer: { name, email, phone, address? }, options?: { deliveryMethod?, shippingRateId?, discountCode?, note? }) => Promise<CommerceActionResult>; loading; error }\n  CommerceActionResult: { paymentLink: string } \u2014 redirect to paymentLink\n\nuseProductCheckout()\n  Returns: { initiate: (input: { productId, quantity, variantId?, customer: { name, email, phone, address? }, deliveryMethod? }) => Promise<CommerceActionResult>; loading; error }\n  Use for single-product \"Buy Now\" flows only. For multi-product stores, use cart.\n\nuseShippingRates()\n  Returns: FetchState<ShippingRate[]>\n  ShippingRate: { id, name, amountKobo, estimatedDays }\n\nuseValidateDiscount()\n  Returns: { validate: (code: string) => Promise<DiscountValidationResult>; validating; error }\n\nuseCheckoutConfig()\n  Returns: FetchState<CheckoutConfig>\n  CheckoutConfig: { deliveryEnabled, pickupEnabled, deliveryOnly, pickupOnly }\n\n---\n\n## DIGITAL PRODUCTS\n\nuseDigitalProducts(options?)\n  Options: { limit?: number }\n  Returns: FetchState<StoreProduct[]> (filtered to type=\"digital\")\n\nuseDigitalProduct(productId: string)\n  Returns: FetchState<StoreProductDetail | null>\n\n---\n\n## SERVICES\n\nuseServiceListings(options?)\n  Options: { limit?: number; category?: string }\n  Returns: FetchState<StorefrontServiceListing[]>\n  StorefrontServiceListing: { id, title, description, coverImage, category, priceKobo, availability, addOns: ServiceAddOn[], subServices: SubService[] }\n\nuseServiceListing(listingId: string)\n  Returns: FetchState<StorefrontServiceListing | null>\n\nuseCheckoutService()\n  Returns: { checkout: (input: { listingId, customer: { name, email, phone }, addOnIds?, subServiceIds? }) => Promise<{ paymentLink }>; loading; error }\n\nuseInitiateEngagement()\n  Returns: { submit: (input: { listingId, customer: { name, email, phone }, message? }) => Promise<void>; submitting; submitted; error }\n\n---\n\n## APPOINTMENTS\n\nuseServices(options?)\n  Options: { limit?: number }\n  Returns: FetchState<StorefrontService[]>\n  StorefrontService: { id, name, description, durationMinutes, priceKobo, imageUrl, category }\n\nuseAvailableDates(options)\n  Options: { serviceId: string; month: string } (month format: \"YYYY-MM\")\n  Returns: FetchState<string[]> \u2014 array of date strings \"YYYY-MM-DD\"\n\nuseAvailability(options)\n  Options: { serviceId: string; date: string } (date format: \"YYYY-MM-DD\")\n  Returns: FetchState<AvailabilitySlot[]>\n  AvailabilitySlot: { id, startTime, endTime, status }\n\nuseBookAppointment()\n  Returns: { initiate: (input: { serviceId, slotId, customer: { name, email, phone } }) => Promise<CommerceActionResult>; loading; error }\n\n---\n\n## EVENTS\n\nuseEvents(options?)\n  Options: { limit?: number }\n  Returns: FetchState<StorefrontEvent[]>\n  StorefrontEvent: { id, name, description, date, endDate, location, imageUrl, ticketTypes: StorefrontTicketType[] }\n  StorefrontTicketType: { id, name, priceKobo, quantity, sold, available }\n\nuseEvent(eventId: string)\n  Returns: FetchState<StorefrontEvent | null>\n\nusePurchaseTickets()\n  Returns: { initiate: (input: { eventId, tickets: [{ ticketTypeId, quantity }], customer: { name, email, phone } }) => Promise<CommerceActionResult>; loading; error }\n\nuseCreateRSVP()\n  Returns: { submit: (input: { eventId, name, email, phone? }) => Promise<void>; loading; success; error }\n\n---\n\n## DONATIONS\n\nuseDonationCampaigns(options?)\n  Options: { limit?: number; ids?: string[] }\n  Returns: FetchState<StorefrontDonationCampaign[]>\n  StorefrontDonationCampaign: { id, name, description, imageUrl, goalAmountKobo: number|null, raisedAmountKobo: number }\n  WARNING: .raised, .raisedAmount, .goalAmount DO NOT EXIST. Use .raisedAmountKobo and .goalAmountKobo only.\n\nuseDonationCampaign(campaignId: string)\n  Returns: FetchState<StorefrontDonationCampaign | null>\n\nuseDonate()\n  Returns: { initiate: (input: { campaignId, amountKobo, customer: { name, email, phone } }) => Promise<CommerceActionResult>; loading; error }\n\n---\n\n## MEMBERSHIPS\n\nuseMemberships()\n  Returns: FetchState<StorefrontMembershipTier[]>\n  StorefrontMembershipTier: { id, name, description, priceKobo, billingPeriod: \"monthly\"|\"yearly\"|\"one_time\", benefits: string[]|null, imageUrl: string|null, isFeatured }\n  WARNING: .price, .amount, .features, .perks DO NOT EXIST. Use .priceKobo and .benefits only.\n  WARNING: billingPeriod is \"yearly\" not \"annual\".\n\nuseSubscribeMembership()\n  Returns: { initiate: (input: { tierId, customer: { name, email, phone } }) => Promise<CommerceActionResult>; loading; error }\n\n---\n\n## CONTENT & CMS\n\nuseContentItems(options: { type: string })\n  Type values: \"image\", \"video\", \"testimonial\", \"faq\", \"stat\", \"feature\", \"team_member\", \"logo_cloud\", \"pricing\"\n  Returns: FetchState<ContentItem[]>\n\nConvenience aliases (all return FetchState<ContentItem[]>):\n  useContentImages(), useContentVideos(), useContentTestimonials(), useContentFaqs(),\n  useContentStats(), useContentFeatures(), useContentTeam(), useContentLogoCloud(), useContentPricing()\n\nuseArticles(options?)\n  Options: { limit?: number; category?: string; tag?: string }\n  Returns: FetchState<StorefrontArticle[]>\n\nuseArticle(slug: string)\n  Returns: FetchState<StorefrontArticle | null>\n\nuseContentForm(formId: string)\n  Returns: { form: ContentFormSchema | null; loading; error }\n  ContentFormSchema: { id, name, fields: ContentFormField[] }\n  ContentFormField: { id, label, type, required, options?, placeholder? }\n\nuseSubmitForm(formId: string)\n  Returns: { submit: (data: Record<string, unknown>) => Promise<void>; submitting; submitted; error }\n\nuseMailingListSubscribe()\n  Returns: { subscribe: (email: string) => Promise<void>; subscribing; subscribed; error }\n\n---\n\n## LISTINGS\n\nuseListings(options?)\n  Options: { listingTypeId?: string; page?: number; limit?: number; filters?: Record<string, string> }\n  Returns: { listings: StorefrontListing[]; total; page; totalPages; loading; error }\n\nuseListingDetail(slugOrId: string)\n  Returns: { listing: StorefrontListingDetail | null; related: StorefrontListing[]; loading; error }\n\nuseListingFilters(listingTypeId?: string)\n  Returns: { fieldDefinitions; params; setParam; reset; loading; error }\n\nAction hooks (each takes listingId):\n  useListingEnquiry(id) \u2014 { submit: ({ name, email?, phone?, message? }) => Promise<void>; loading; success; error }\n  useListingApplication(id) \u2014 { submit: ({ name, email, phone?, coverNote?, resumeUrl? }) => Promise<void>; loading; success; error }\n  useListingPayment(id) \u2014 { checkout: (customer, fieldData?) => Promise<void>; loading; error }\n  useListingReserve(id) \u2014 { reserve: (data?) => Promise<void>; loading; success; alreadyReserved; error }\n  useListingDownload(id) \u2014 { download: () => Promise<void>; downloadUrl; loading; error }\n\n---\n\n## CUSTOMER ACCOUNTS\n\nuseCustomerAuth()\n  Returns: { customer: { id, name, email, phone, address } | null; isLoggedIn: boolean; isLoading: boolean;\n    signUp: (name, email, password) => Promise<void>; signIn: (email, password) => Promise<void>; signOut: () => void; error }\n  WARNING: field is isLoggedIn, NOT isAuthenticated.\n\nuseMyOrders() \u2014 { orders: MyOrder[]; loading; error }\nuseMyAppointments() \u2014 { appointments: MyAppointment[]; loading; error }\nuseMyPurchases() \u2014 { purchases: MyPurchase[]; loading; error }\nuseMyMembership() \u2014 { membership: MyMembership | null; loading; error }\nuseMyProfile() \u2014 { profile: { name, email, phone, address } | null; update: ({ name, phone, address }) => Promise<void>; updating; updateError }\n\n---\n\n## ORDER TRACKING\n\nuseOrderStatus() \u2014 { status: OrderStatusData | null; loading; error }\nuseOrderLookup() \u2014 { lookup: (orderRef, email) => Promise<OrderLookupItem[]>; items; loading; error }\n\n---\n\n## COMPONENTS (import from \"@sellhapi/studio-runtime\")\n\nCartDrawer \u2014 renders the slide-out cart drawer. REQUIRED if using useCart().\n";

package/dist/resources/runtime-hooks.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * Runtime hooks reference — extracted from @sellhapi/studio-runtime.
+ * This resource teaches AI clients the exact hook signatures and return shapes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_HOOKS = void 0;
+exports.RUNTIME_HOOKS = `
+# @sellhapi/studio-runtime — Hook Reference
+
+All imports come from "@sellhapi/studio-runtime". No other network/data access is allowed.
+
+## IMPORTANT RULES
+- All prices are in kobo (divide by 100 for Naira display): product.priceKobo / 100
+- product.images is string[] — each element IS the URL. NEVER access .url on it.
+- Always include type: 'physical' | 'digital' when calling addItem()
+- If you use useCart/addItem, you MUST render <CartDrawer /> in App.tsx
+- FetchState<T> = { data: T; loading: boolean; error: string | null }
+
+---
+
+## ROUTING (required for multi-page storefronts)
+
+useHashRouter()
+  Returns: { route: string; params: Record<string, string>; navigate: (route: string) => void }
+  Usage: const { route, navigate } = useHashRouter();
+  Routes: "#/" (home), "#/product/:id", "#/digital/:id", "#/services/:id", etc.
+
+---
+
+## PHYSICAL PRODUCTS
+
+useProducts(options?)
+  Options: { limit?: number; categoryId?: string; collectionId?: string; sectionId?: string; sort?: "newest"|"price_asc"|"price_desc"; search?: string; ids?: string[] }
+  Returns: FetchState<StoreProduct[]>
+  StoreProduct: { id, name, priceKobo, compareAtPriceKobo, imageUrl, images: string[], category, type: "physical"|"digital", variants: StoreProductVariant[], inStock }
+
+useProduct(productId: string)
+  Returns: FetchState<StoreProductDetail | null>
+  StoreProductDetail: extends StoreProduct + { description, variants: StoreProductVariant[] }
+  StoreProductVariant: { id, size, color, priceKobo, compareAtPriceKobo, stock, imageUrl }
+
+useCategories()
+  Returns: FetchState<StoreCategory[]>
+  StoreCategory: { name: string; count: number }
+
+useProductCollections()
+  Returns: FetchState<ProductCollection[]>
+  ProductCollection: { id, name, coverImage: string | null }
+
+useSections()
+  Returns: FetchState<StoreSection[]>
+useSection(sectionId: string)
+  Returns: FetchState<StoreProduct[]>
+
+---
+
+## CART & CHECKOUT
+
+useCart()
+  Returns: {
+    items: CartItem[]; count: number; totalKobo: number; savingsKobo: number; isEmpty: boolean;
+    addItem: (item: { productId, name, priceKobo, imageUrl?, variantId?, variantLabel?, quantity?, type: "physical"|"digital" }) => void;
+    removeItem: (productId, variantId?) => void;
+    updateQty: (productId, quantity, variantId?) => void;
+    clear: () => void;
+    openCart: () => void;        // MUST call after addItem — opens the cart drawer
+    openCheckout: () => void;
+  }
+
+CartDrawer — REQUIRED component if using cart. Import from "@sellhapi/studio-runtime".
+  Usage: <CartDrawer /> in App.tsx root. Without it, openCart() does nothing.
+
+useCartCheckout()
+  Returns: { initiate: (customer: { name, email, phone, address? }, options?: { deliveryMethod?, shippingRateId?, discountCode?, note? }) => Promise<CommerceActionResult>; loading; error }
+  CommerceActionResult: { paymentLink: string } — redirect to paymentLink
+
+useProductCheckout()
+  Returns: { initiate: (input: { productId, quantity, variantId?, customer: { name, email, phone, address? }, deliveryMethod? }) => Promise<CommerceActionResult>; loading; error }
+  Use for single-product "Buy Now" flows only. For multi-product stores, use cart.
+
+useShippingRates()
+  Returns: FetchState<ShippingRate[]>
+  ShippingRate: { id, name, amountKobo, estimatedDays }
+
+useValidateDiscount()
+  Returns: { validate: (code: string) => Promise<DiscountValidationResult>; validating; error }
+
+useCheckoutConfig()
+  Returns: FetchState<CheckoutConfig>
+  CheckoutConfig: { deliveryEnabled, pickupEnabled, deliveryOnly, pickupOnly }
+
+---
+
+## DIGITAL PRODUCTS
+
+useDigitalProducts(options?)
+  Options: { limit?: number }
+  Returns: FetchState<StoreProduct[]> (filtered to type="digital")
+
+useDigitalProduct(productId: string)
+  Returns: FetchState<StoreProductDetail | null>
+
+---
+
+## SERVICES
+
+useServiceListings(options?)
+  Options: { limit?: number; category?: string }
+  Returns: FetchState<StorefrontServiceListing[]>
+  StorefrontServiceListing: { id, title, description, coverImage, category, priceKobo, availability, addOns: ServiceAddOn[], subServices: SubService[] }
+
+useServiceListing(listingId: string)
+  Returns: FetchState<StorefrontServiceListing | null>
+
+useCheckoutService()
+  Returns: { checkout: (input: { listingId, customer: { name, email, phone }, addOnIds?, subServiceIds? }) => Promise<{ paymentLink }>; loading; error }
+
+useInitiateEngagement()
+  Returns: { submit: (input: { listingId, customer: { name, email, phone }, message? }) => Promise<void>; submitting; submitted; error }
+
+---
+
+## APPOINTMENTS
+
+useServices(options?)
+  Options: { limit?: number }
+  Returns: FetchState<StorefrontService[]>
+  StorefrontService: { id, name, description, durationMinutes, priceKobo, imageUrl, category }
+
+useAvailableDates(options)
+  Options: { serviceId: string; month: string } (month format: "YYYY-MM")
+  Returns: FetchState<string[]> — array of date strings "YYYY-MM-DD"
+
+useAvailability(options)
+  Options: { serviceId: string; date: string } (date format: "YYYY-MM-DD")
+  Returns: FetchState<AvailabilitySlot[]>
+  AvailabilitySlot: { id, startTime, endTime, status }
+
+useBookAppointment()
+  Returns: { initiate: (input: { serviceId, slotId, customer: { name, email, phone } }) => Promise<CommerceActionResult>; loading; error }
+
+---
+
+## EVENTS
+
+useEvents(options?)
+  Options: { limit?: number }
+  Returns: FetchState<StorefrontEvent[]>
+  StorefrontEvent: { id, name, description, date, endDate, location, imageUrl, ticketTypes: StorefrontTicketType[] }
+  StorefrontTicketType: { id, name, priceKobo, quantity, sold, available }
+
+useEvent(eventId: string)
+  Returns: FetchState<StorefrontEvent | null>
+
+usePurchaseTickets()
+  Returns: { initiate: (input: { eventId, tickets: [{ ticketTypeId, quantity }], customer: { name, email, phone } }) => Promise<CommerceActionResult>; loading; error }
+
+useCreateRSVP()
+  Returns: { submit: (input: { eventId, name, email, phone? }) => Promise<void>; loading; success; error }
+
+---
+
+## DONATIONS
+
+useDonationCampaigns(options?)
+  Options: { limit?: number; ids?: string[] }
+  Returns: FetchState<StorefrontDonationCampaign[]>
+  StorefrontDonationCampaign: { id, name, description, imageUrl, goalAmountKobo: number|null, raisedAmountKobo: number }
+  WARNING: .raised, .raisedAmount, .goalAmount DO NOT EXIST. Use .raisedAmountKobo and .goalAmountKobo only.
+
+useDonationCampaign(campaignId: string)
+  Returns: FetchState<StorefrontDonationCampaign | null>
+
+useDonate()
+  Returns: { initiate: (input: { campaignId, amountKobo, customer: { name, email, phone } }) => Promise<CommerceActionResult>; loading; error }
+
+---
+
+## MEMBERSHIPS
+
+useMemberships()
+  Returns: FetchState<StorefrontMembershipTier[]>
+  StorefrontMembershipTier: { id, name, description, priceKobo, billingPeriod: "monthly"|"yearly"|"one_time", benefits: string[]|null, imageUrl: string|null, isFeatured }
+  WARNING: .price, .amount, .features, .perks DO NOT EXIST. Use .priceKobo and .benefits only.
+  WARNING: billingPeriod is "yearly" not "annual".
+
+useSubscribeMembership()
+  Returns: { initiate: (input: { tierId, customer: { name, email, phone } }) => Promise<CommerceActionResult>; loading; error }
+
+---
+
+## CONTENT & CMS
+
+useContentItems(options: { type: string })
+  Type values: "image", "video", "testimonial", "faq", "stat", "feature", "team_member", "logo_cloud", "pricing"
+  Returns: FetchState<ContentItem[]>
+
+Convenience aliases (all return FetchState<ContentItem[]>):
+  useContentImages(), useContentVideos(), useContentTestimonials(), useContentFaqs(),
+  useContentStats(), useContentFeatures(), useContentTeam(), useContentLogoCloud(), useContentPricing()
+
+useArticles(options?)
+  Options: { limit?: number; category?: string; tag?: string }
+  Returns: FetchState<StorefrontArticle[]>
+
+useArticle(slug: string)
+  Returns: FetchState<StorefrontArticle | null>
+
+useContentForm(formId: string)
+  Returns: { form: ContentFormSchema | null; loading; error }
+  ContentFormSchema: { id, name, fields: ContentFormField[] }
+  ContentFormField: { id, label, type, required, options?, placeholder? }
+
+useSubmitForm(formId: string)
+  Returns: { submit: (data: Record<string, unknown>) => Promise<void>; submitting; submitted; error }
+
+useMailingListSubscribe()
+  Returns: { subscribe: (email: string) => Promise<void>; subscribing; subscribed; error }
+
+---
+
+## LISTINGS
+
+useListings(options?)
+  Options: { listingTypeId?: string; page?: number; limit?: number; filters?: Record<string, string> }
+  Returns: { listings: StorefrontListing[]; total; page; totalPages; loading; error }
+
+useListingDetail(slugOrId: string)
+  Returns: { listing: StorefrontListingDetail | null; related: StorefrontListing[]; loading; error }
+
+useListingFilters(listingTypeId?: string)
+  Returns: { fieldDefinitions; params; setParam; reset; loading; error }
+
+Action hooks (each takes listingId):
+  useListingEnquiry(id) — { submit: ({ name, email?, phone?, message? }) => Promise<void>; loading; success; error }
+  useListingApplication(id) — { submit: ({ name, email, phone?, coverNote?, resumeUrl? }) => Promise<void>; loading; success; error }
+  useListingPayment(id) — { checkout: (customer, fieldData?) => Promise<void>; loading; error }
+  useListingReserve(id) — { reserve: (data?) => Promise<void>; loading; success; alreadyReserved; error }
+  useListingDownload(id) — { download: () => Promise<void>; downloadUrl; loading; error }
+
+---
+
+## CUSTOMER ACCOUNTS
+
+useCustomerAuth()
+  Returns: { customer: { id, name, email, phone, address } | null; isLoggedIn: boolean; isLoading: boolean;
+    signUp: (name, email, password) => Promise<void>; signIn: (email, password) => Promise<void>; signOut: () => void; error }
+  WARNING: field is isLoggedIn, NOT isAuthenticated.
+
+useMyOrders() — { orders: MyOrder[]; loading; error }
+useMyAppointments() — { appointments: MyAppointment[]; loading; error }
+useMyPurchases() — { purchases: MyPurchase[]; loading; error }
+useMyMembership() — { membership: MyMembership | null; loading; error }
+useMyProfile() — { profile: { name, email, phone, address } | null; update: ({ name, phone, address }) => Promise<void>; updating; updateError }
+
+---
+
+## ORDER TRACKING
+
+useOrderStatus() — { status: OrderStatusData | null; loading; error }
+useOrderLookup() — { lookup: (orderRef, email) => Promise<OrderLookupItem[]>; items; loading; error }
+
+---
+
+## COMPONENTS (import from "@sellhapi/studio-runtime")
+
+CartDrawer — renders the slide-out cart drawer. REQUIRED if using useCart().
+`;

package/dist/resources/wireframe-schema.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Wireframe schema resource.
+ *
+ * Documents the exact shape and conventions for wireframe HTML submitted via
+ * apply_wireframe. The AI client generates mid-fidelity wireframes per page,
+ * presents each one to the user for review, then submits the approved set.
+ */
+export declare const WIREFRAME_SCHEMA = "\n# SellHapi Wireframe Schema\n\nWireframes are mid-fidelity HTML page layouts \u2014 one per storefront page.\nThey are the USER'S checkpoint before code is written: present each page\nwireframe in the conversation, collect feedback, revise if needed, then\ncall apply_wireframe only after the user approves the full set.\n\n---\n\n## Data shape\n\n```\n{ [pageSlug: string]: htmlString }\n```\n\n- Each key is a page slug that MUST match one of the slugs in designDirection.pages\n- Each value is a valid HTML string for that page's mid-fidelity wireframe\n- All pages from designDirection.pages should be included (missing pages means no wireframe guidance for code generation on that page)\n\n---\n\n## What a wireframe IS\n\nMid-fidelity structural HTML. It communicates:\n- Which sections appear on the page and in what order\n- What content each section contains (headings, CTAs, placeholder data)\n- Navigation structure (links, cart icon, CTA button)\n- Footer structure (columns, links)\n- Which runtime hook each section will use\n\nIt does NOT include:\n- Real CSS (use only inline style for basic layout structure if needed)\n- JavaScript or React\n- Actual product/service data (use descriptive placeholders)\n- Final colour values or fonts (those come from designDirection.visualDirection)\n\n---\n\n## Structure rules\n\n### Navigation \u2014 MANDATORY on every page\n```html\n<nav>\n  <div class=\"nav-logo\">[Business Name]</div>\n  <ul class=\"nav-links\">\n    <li><a href=\"#/home\">Home</a></li>\n    <li><a href=\"#/shop\">Shop</a></li>\n    <!-- one <li> per page in designDirection.pages -->\n  </ul>\n  <!-- If physical_products or digital_products in capabilityIds: -->\n  <button class=\"nav-cart\">Cart (0)</button>\n  <button class=\"nav-cta\">[Primary CTA]</button>\n</nav>\n```\n\n- Navigation HTML must be **identical across all pages** \u2014 copy verbatim after the first page\n- Highlight the current page's link as active (add class=\"active\" to that <li>)\n- Cart icon only when capability includes physical_products or digital_products\n\n### Footer \u2014 MANDATORY on every page\n```html\n<footer>\n  <div class=\"footer-col\">\n    <div class=\"footer-logo\">[Business Name]</div>\n    <p>[tagline]</p>\n  </div>\n  <div class=\"footer-col\">\n    <h4>NAVIGATE</h4>\n    <ul><!-- one <li> per page --></ul>\n  </div>\n  <div class=\"footer-col\">\n    <h4>RESOURCES</h4>\n    <ul><!-- relevant links for this business type --></ul>\n  </div>\n  <div class=\"footer-col\">\n    <h4>CONNECT</h4>\n    <!-- social platform links -->\n  </div>\n  <div class=\"footer-bottom\">\u00A9 [year] [Business Name]. All rights reserved.</div>\n</footer>\n```\n\n- Footer HTML must be **identical across all pages** \u2014 copy verbatim after the first page\n\n### Sections\nEach section gets a wrapper with a comment and data-hook attribute:\n\n```html\n<!-- Hero Section -->\n<section data-section=\"hero\" data-hook=\"none\">\n  <h1>[Headline \u2014 use the business tagline]</h1>\n  <p>[Supporting copy]</p>\n  <button>[Primary CTA]</button>\n  <div class=\"hero-image\">[Hero image placeholder]</div>\n</section>\n\n<!-- Product Grid Section -->\n<section data-section=\"product-grid\" data-hook=\"useProducts\">\n  <h2>Our Products</h2>\n  <div class=\"product-grid\">\n    <div class=\"product-card\">\n      <div class=\"product-image\">[Product image]</div>\n      <h3>[Product name]</h3>\n      <p>[Price in \u20A6]</p>\n      <button>Add to Cart</button>\n    </div>\n    <!-- repeat 2 more placeholder cards -->\n  </div>\n</section>\n\n<!-- Testimonials Section -->\n<section data-section=\"testimonials\" data-hook=\"useContentTestimonials\">\n  <h2>What Customers Say</h2>\n  <div class=\"testimonials-grid\">\n    <blockquote>[Testimonial 1]</blockquote>\n    <blockquote>[Testimonial 2]</blockquote>\n    <blockquote>[Testimonial 3]</blockquote>\n  </div>\n</section>\n```\n\n---\n\n## data-hook values by capability\n\nUse these exact hook names in data-hook attributes so code generation\nmatches the correct runtime hook:\n\n| Section type                  | data-hook                       |\n|-------------------------------|---------------------------------|\n| Product listing / grid        | useProducts                     |\n| Product collections           | useProductCollections           |\n| Single collection             | useCollection                   |\n| Category sections             | useSections                     |\n| Service listings              | useServiceListings              |\n| Appointment booking           | useBookAppointment              |\n| Available dates               | useAvailableDates               |\n| Events listing                | useEvents                       |\n| Donation campaigns            | useDonationCampaigns            |\n| Membership tiers              | useMemberships                  |\n| Content images                | useContentImages                |\n| Testimonials                  | useContentTestimonials          |\n| FAQs                          | useContentFaqs                  |\n| Team members                  | useContentTeam                  |\n| Stats / social proof          | useContentStats                 |\n| Feature highlights            | useContentFeatures              |\n| Contact / enquiry form        | useSubmitForm                   |\n| Listings (classifieds/jobs)   | useListings                     |\n| Non-data sections (hero, about, footer, nav) | none          |\n\n---\n\n## Presenting wireframes to the user\n\nBefore calling apply_wireframe, show each page to the user like this:\n\n```\n\uD83D\uDCC4 HOME PAGE\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n[NAV] Logo | Home \u00B7 Shop \u00B7 About \u00B7 Contact  [Cart] [Shop Now]\n\n[HERO]\n  \"Authentic Nigerian fashion for the bold\"\n  Subheading + CTA button\n  Full-width hero image\n\n[FEATURED PRODUCTS] (useProducts)\n  3-column product grid \u2014 6 products\n  Each card: image, name, price, Add to Cart\n\n[COLLECTIONS] (useProductCollections)\n  4 collection tiles with cover images\n\n[TESTIMONIALS] (useContentTestimonials)\n  3 customer quotes in a row\n\n[NEWSLETTER]\n  Email capture form\n\n[FOOTER] 4-column footer\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n\nDoes this structure look right? Any sections to add, remove, or reorder?\n```\n\nWait for explicit user approval before proceeding to apply_wireframe.\nIf the user requests changes, update the affected page(s) and show again.\n\n---\n\n## Submission\n\nOnce ALL pages are approved by the user:\n\n```\napply_wireframe(projectId, {\n  \"home\":    \"<nav>...</nav><main>...</main><footer>...</footer>\",\n  \"shop\":    \"<nav>...</nav><main>...</main><footer>...</footer>\",\n  \"about\":   \"<nav>...</nav><main>...</main><footer>...</footer>\",\n  \"contact\": \"<nav>...</nav><main>...</main><footer>...</footer>\"\n})\n```\n\nReturns: `{ pageCount: 4, slugs: [\"home\", \"shop\", \"about\", \"contact\"] }`\n\nAfter this, proceed to generate React code using the wireframe as your\nstructural reference. The wireframe defines WHAT to build \u2014 runtime-hooks\nand build-rules define HOW to build it in React.\n";