@sellhapi/mcp 0.0.0-stage → 0.1.2

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: {\n    id, name, priceKobo, imageUrl, images: string[], category,\n    type: \"physical\"|\"digital\", inStock,\n    originalPriceKobo: number | undefined,   // strikethrough price \u2014 show when > priceKobo\n    discountBadge: string | null,            // pre-formatted e.g. \"20% Off\" \u2014 show as badge\n    priceRange: { minKobo: number; maxKobo: number } | null,  // when variants differ in price\n    variants: StoreProductVariant[],\n  }\n  WARNING: compareAtPriceKobo does NOT exist. Use originalPriceKobo for strikethrough price.\n  WARNING: images is string[] \u2014 each element IS the URL. Never access .url on it.\n  WARNING: some image URLs contain spaces \u2014 always encode: u.includes(' ') ? u.split('/').map(encodeURIComponent).join('/') : u\n\nuseProduct(productId: string)\n  Returns: FetchState<StoreProductDetail | null>\n  StoreProductDetail: extends StoreProduct + { description, variants: StoreProductVariant[] }\n  StoreProductVariant: { id, options: Array<{ field: string; value: string }>, priceKobo?: number, stock?: number | null }\n  WARNING: variants have NO size/color/name fields \u2014 iterate options array for labels\n  Variant label helper: v.options?.map(o => o.value).join(' / ') || 'Standard'\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; from: string; to: string } (both \"YYYY-MM-DD\")\n  CRITICAL: to must always be from + 1 day \u2014 NEVER set from === to, it returns no slots\n  to = new Date(+new Date(from) + 86400000).toISOString().slice(0, 10)\n  Returns: FetchState<AvailabilitySlot[]>\n  AvailabilitySlot: { id, startTime, endTime, status: \"available\"|\"claimed\"|\"booked\"|\"blocked\" }\n  FILTER: only show slots where status === \"available\" \u2014 the hook returns all statuses\n\nuseBookAppointment()\n  Returns: { book: (input: { serviceId, dateTime: string, customerName, customerEmail, customerPhone }) => Promise<CommerceActionResult>; loading; error }\n  dateTime: slot.startTime (ISO datetime string from useAvailability result)\n  WARNING: NEVER pass slotId \u2014 pass dateTime: slot.startTime\n  WARNING: NEVER use initiate() for appointments \u2014 use book(). Returns { paymentLink } \u2014 redirect with window.location.href\n\n---\n\n## EVENTS\n\nuseEvents(options?)\n  Options: { limit?: number }\n  Returns: FetchState<StorefrontEvent[]>\n  StorefrontEvent: { id, name, description, startsAt, endsAt, location, imageUrl, ticketTypes: StorefrontTicketType[] }\n  WARNING: event.date and event.endDate do NOT exist \u2014 use startsAt and endsAt (ISO strings)\n  StorefrontTicketType: { id, name, priceKobo, quantity, sold, available }\n\nuseEvent(eventId: string)\n  Returns: FetchState<StorefrontEvent | null>\n\nusePurchaseTickets()\n  Returns: { initiate: (input: { eventId, ticketOrders: [{ ticketTypeId: string, quantity: number }], customer: { name, email, phone } }) => Promise<CommerceActionResult>; loading; error }\n  WARNING: param is ticketOrders not tickets\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(), useContentTeamMembers(), useContentLogoCloud(), useContentPricing()\n  WARNING: useContentTeam() does NOT exist \u2014 use useContentTeamMembers()\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,290 @@
+"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, imageUrl, images: string[], category,
+    type: "physical"|"digital", inStock,
+    originalPriceKobo: number | undefined,   // strikethrough price — show when > priceKobo
+    discountBadge: string | null,            // pre-formatted e.g. "20% Off" — show as badge
+    priceRange: { minKobo: number; maxKobo: number } | null,  // when variants differ in price
+    variants: StoreProductVariant[],
+  }
+  WARNING: compareAtPriceKobo does NOT exist. Use originalPriceKobo for strikethrough price.
+  WARNING: images is string[] — each element IS the URL. Never access .url on it.
+  WARNING: some image URLs contain spaces — always encode: u.includes(' ') ? u.split('/').map(encodeURIComponent).join('/') : u
+
+useProduct(productId: string)
+  Returns: FetchState<StoreProductDetail | null>
+  StoreProductDetail: extends StoreProduct + { description, variants: StoreProductVariant[] }
+  StoreProductVariant: { id, options: Array<{ field: string; value: string }>, priceKobo?: number, stock?: number | null }
+  WARNING: variants have NO size/color/name fields — iterate options array for labels
+  Variant label helper: v.options?.map(o => o.value).join(' / ') || 'Standard'
+
+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; from: string; to: string } (both "YYYY-MM-DD")
+  CRITICAL: to must always be from + 1 day — NEVER set from === to, it returns no slots
+  to = new Date(+new Date(from) + 86400000).toISOString().slice(0, 10)
+  Returns: FetchState<AvailabilitySlot[]>
+  AvailabilitySlot: { id, startTime, endTime, status: "available"|"claimed"|"booked"|"blocked" }
+  FILTER: only show slots where status === "available" — the hook returns all statuses
+
+useBookAppointment()
+  Returns: { book: (input: { serviceId, dateTime: string, customerName, customerEmail, customerPhone }) => Promise<CommerceActionResult>; loading; error }
+  dateTime: slot.startTime (ISO datetime string from useAvailability result)
+  WARNING: NEVER pass slotId — pass dateTime: slot.startTime
+  WARNING: NEVER use initiate() for appointments — use book(). Returns { paymentLink } — redirect with window.location.href
+
+---
+
+## EVENTS
+
+useEvents(options?)
+  Options: { limit?: number }
+  Returns: FetchState<StorefrontEvent[]>
+  StorefrontEvent: { id, name, description, startsAt, endsAt, location, imageUrl, ticketTypes: StorefrontTicketType[] }
+  WARNING: event.date and event.endDate do NOT exist — use startsAt and endsAt (ISO strings)
+  StorefrontTicketType: { id, name, priceKobo, quantity, sold, available }
+
+useEvent(eventId: string)
+  Returns: FetchState<StorefrontEvent | null>
+
+usePurchaseTickets()
+  Returns: { initiate: (input: { eventId, ticketOrders: [{ ticketTypeId: string, quantity: number }], customer: { name, email, phone } }) => Promise<CommerceActionResult>; loading; error }
+  WARNING: param is ticketOrders not tickets
+
+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(), useContentTeamMembers(), useContentLogoCloud(), useContentPricing()
+  WARNING: useContentTeam() does NOT exist — use useContentTeamMembers()
+
+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().
+`;