@rovela-ai/sdk 0.19.4 → 0.19.6

package/templates/store-template/.claude/skills/manage-products/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: manage-products
+description: Use when the user asks about products, inventory, orders, customers, or any database operation. Covers postgres-mcp queries, table schemas, and JSONB patterns.
+---
+
+# Database & Product Management
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `execute_sql` | Run SELECT, INSERT, UPDATE, DELETE queries |
+| `list_objects` | View all tables in the database |
+| `get_object_details` | Get column definitions for a table |
+
+Usage: `nextjs_call` with `port="3000"` and `toolName="execute_sql"`
+
+## Workflow
+
+1. Use `list_objects` to see available tables
+2. Use `get_object_details` to understand table columns
+3. Test SELECT queries before running mutations
+4. Always use `RETURNING *` for INSERT/UPDATE
+5. Handle errors gracefully in the UI
+
+## Core Tables
+
+| Table | Key Columns |
+|-------|-------------|
+| `products` | id, name, slug, price, status (`draft`/`active`/`archived`), categoryId, hasVariants, images (JSONB string[]), videos (JSONB string[]), metafields (JSONB key/label/value/type), translations (JSONB per-locale name/description) |
+| `product_variants` | id, productId (CASCADE), sku, name, price, inventory, attributes (JSONB), image, video |
+| `categories` | id, name, slug, parentId (self-ref), order, translations (JSONB) |
+| `orders` | id, customerId, email, status, total, currency (ISO snapshot — display orders in THIS currency), refundAmount, returnReason, shippingAddress (JSONB) |
+| `order_items` | id, orderId (CASCADE), productId, variantId, name, price, quantity |
+| `customers` | id, email (unique), name, passwordHash, phone, groupId, locale, stripeCustomerId, emailVerified |
+| `store_settings` | id, storeName, storeEmail, storeCurrency, storeTimezone, storeCountry, defaultLocale, enabledLocales, taxIncludedInPrices, shippingMode |
+
+**Money contract (load-bearing)**: `price`, `total` etc. are DECIMAL CURRENCY UNITS — `29.99`, NEVER cents (`2999`). No ×100/÷100 anywhere except the Stripe API boundary. On multilingual stores (`enabled_locales`), catalog content can carry per-locale `translations` — when editing names/descriptions, keep every enabled locale in sync (CLAUDE.md §5.5).
+
+## Order Status Flow
+
+```
+pending → paid → shipped → delivered
+              ↘ cancelled
+              ↘ refunded
+              ↘ return_requested
+```
+
+## Common Queries
+
+```sql
+-- Get active products
+SELECT * FROM products WHERE status = 'active'
+
+-- Get product with variants
+SELECT p.*, json_agg(pv.*) as variants
+FROM products p
+LEFT JOIN product_variants pv ON pv.product_id = p.id
+WHERE p.slug = 'product-slug' GROUP BY p.id
+
+-- Update product price (DECIMAL currency units — 29.99, never cents)
+UPDATE products SET price = 29.99 WHERE id = 'uuid' RETURNING *
+
+-- Add a product
+INSERT INTO products (name, slug, price, status, description)
+VALUES ('Product Name', 'product-name', 29.99, 'active', 'Description')
+RETURNING *
+
+-- Update order status
+UPDATE orders SET status = 'shipped', updated_at = NOW() WHERE id = 'uuid' RETURNING *
+
+-- Get store stats
+SELECT COUNT(*) as total, SUM(CASE WHEN status = 'active' THEN 1 ELSE 0 END) as active
+FROM products
+```
+
+## JSONB Patterns
+
+### Product Media (Images & Videos)
+```sql
+-- Both images and videos are stored as JSONB arrays of plain URL strings.
+-- The storefront detects video vs image at render time by URL extension
+-- (`.mp4` / `.webm` / `.mov` → <video>, otherwise <img>).
+
+UPDATE products
+SET images = '["https://.../shirt-front.webp", "https://.../shirt-back.webp"]'::jsonb,
+    videos = '["https://.../shirt-demo.mp4"]'::jsonb
+WHERE id = 'uuid' RETURNING *
+
+-- Query products with their primary image
+SELECT id, name, images->>0 AS main_image FROM products
+
+-- Variant-specific image (swatch) and video (optional demo)
+UPDATE product_variants
+SET image = 'https://.../red-swatch.webp',
+    video = 'https://.../red-demo.mp4'
+WHERE id = 'uuid' RETURNING *
+```
+
+### Variant Attributes
+```sql
+-- Attributes stored as JSONB object
+INSERT INTO product_variants (product_id, name, sku, price, inventory, attributes)
+VALUES ('uuid', 'Large / Blue', 'SKU-LG-BL', 2999, 50, '{"size": "Large", "color": "Blue"}'::jsonb)
+RETURNING *
+```
+
+## Full product creation recipe (single-call from a feature card)
+
+When a feature card asks you to create one product (e.g. "Create a product"
+card), follow this exact recipe so the row is consistent with every other
+product in the catalog. The card passes `name`, `price`, `description?`,
+`hasVariants`, and the R2 image URL in `<inputs>`. You provide everything
+else from defaults.
+
+```sql
+-- 1. Pick or create a category (prefer existing).
+SELECT id, name, slug FROM categories;
+-- If nothing fits:
+-- INSERT INTO categories (name, slug) VALUES ('Apparel', 'apparel') RETURNING id, slug;
+
+-- 2. INSERT the product. Required defaults:
+--    status='active', has_variants=<from inputs>, inventory=100,
+--    track_inventory=true, images=JSONB array with the R2 URL.
+INSERT INTO products (
+  name, slug, description, price, status, has_variants,
+  inventory, track_inventory, images, category_id
+) VALUES (
+  'Single Origin Espresso',
+  'single-origin-espresso',                -- lowercase-kebab from name
+  '...2-3 sentence brand-voice description...',
+  29.99,
+  'active',
+  false,
+  100,
+  true,
+  '["https://r2.../stores/{id}/generated/products/...webp"]'::jsonb,
+  '<category_id>'
+) RETURNING id, slug;
+
+-- 3. Default variant (required even when has_variants=false — the cart
+--    needs SOMETHING addable to it).
+INSERT INTO product_variants (
+  product_id, name, sku, price, inventory, attributes
+) VALUES (
+  '<product_id from step 2>',
+  'Default',
+  'single-origin-espresso-default',         -- slug-default
+  29.99,
+  100,
+  '{}'::jsonb
+) RETURNING id;
+
+-- 4. If has_variants=true, INSERT a sensible scaffold instead of the default.
+--    Examples by product type:
+--    - Apparel: name in (S, M, L), attributes {"size": "S"} etc.
+--    - Footwear: name in (38, 39, 40, 41, 42), attributes {"size": "40"}
+--    - Anything else: 2 sensible color/size presets you infer from the name.
+--    Each variant: same price as the parent, inventory split evenly,
+--    sku = slug-{lowercased attribute value}.
+```
+
+### Slug rules
+
+- Lowercase, kebab-case, ASCII only
+- Strip punctuation other than hyphens
+- Truncate to 60 chars
+- Must be unique against `products.slug` — append `-2`, `-3`, etc. if collision
+
+### Description fallback
+
+If the card didn't supply a description, write 2-3 sentences that match the
+store's brand voice (read CLAUDE.md `<brand_voice>` if present). Specifics over
+fluff — never "high-quality product for discerning customers".
+
+### After insert
+
+Verify the product is reachable: the storefront serves `/products/<slug>`
+once the row is `status='active'`. A quick `SELECT slug FROM products WHERE
+id = $1` then `curl localhost:3000/products/<slug>` confirms.
+
+## Safety Rules
+
+- Use `status = 'archived'` instead of DELETE for products (preserves order history)
+- Always verify WHERE clauses before UPDATE/DELETE
+- Handle NULL `customer_id` for guest checkout orders
+- Test SELECT first, then mutate

package/templates/store-template/.claude/skills/override-sdk-component/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: override-sdk-component
+description: Use when the user wants to customize cart, checkout, auth, product, or any SDK component behavior. Covers the copy-and-modify pattern for @rovela-ai/sdk components.
+---
+
+# Override SDK Components
+
+## Why Override (Not Edit)
+
+Only `/app` directory is deployed to Vercel — `node_modules` is rebuilt from `package.json`.
+Changes to files inside `node_modules/@rovela-ai/sdk/` will be lost on deployment.
+
+## Step-by-Step Process
+
+### 1. Find the SDK Source
+
+Read the component source from `node_modules/@rovela-ai/sdk/dist/`:
+
+```bash
+# Example: find CartIcon source
+cat node_modules/@rovela-ai/sdk/dist/cart/components/CartIcon.js
+```
+
+### 2. Create Your Override
+
+Copy the component logic into `/app/components/`:
+
+```tsx
+// /app/components/CartIcon.tsx
+'use client';
+
+// Copy SDK component code here, then modify
+export default function CartIcon() {
+  // Your customized version
+}
+```
+
+### 3. Update Imports
+
+Replace SDK imports with your local version wherever it's used:
+
+```tsx
+// Before
+import { CartIcon } from '@rovela-ai/sdk/cart';
+
+// After
+import CartIcon from '@/components/CartIcon';
+```
+
+### 4. Verify
+
+Run error check (get_errors) to confirm no TypeScript issues.
+
+## Customization Pattern — variants, NOT inline overrides
+
+When the override needs visual customization (different colors, sizes, shadows, hover states), add a new `cva` variant to the component file. Do NOT inline-override with raw classes at call sites.
+
+### ✅ Correct — new variant inside the component
+
+```tsx
+// /app/components/AddToCartButton.tsx
+import { cva } from 'class-variance-authority';
+
+const addToCartVariants = cva(
+  "inline-flex items-center justify-center rounded-md font-medium transition-[var(--transition-smooth)]",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        hero: "bg-[var(--gradient-primary)] text-primary-foreground shadow-[var(--shadow-elegant)] hover:shadow-[var(--shadow-glow)]",
+        editorial: "bg-transparent border border-foreground/20 text-foreground hover:bg-foreground hover:text-background",
+        outline: "border border-border bg-background hover:bg-muted",
+      },
+      size: {
+        default: "h-10 px-4",
+        sm: "h-9 px-3 text-sm",
+        lg: "h-12 px-6 text-base",
+      },
+    },
+    defaultVariants: { variant: "default", size: "default" },
+  },
+);
+
+export function AddToCartButton({ variant, size, ...props }) {
+  return <button className={addToCartVariants({ variant, size })} {...props} />;
+}
+```
+
+```tsx
+// At the call site — pick a variant, no raw classes
+<AddToCartButton variant="hero">Shop now</AddToCartButton>
+<AddToCartButton variant="editorial" size="lg">Browse collection</AddToCartButton>
+```
+
+### ❌ Wrong — inline overrides bypass the design system
+
+```tsx
+// Don't do this — the design system loses its grip on the component
+<AddToCartButton className="bg-primary/90 hover:bg-primary text-white px-6 shadow-xl">
+  Shop now
+</AddToCartButton>
+```
+
+Inline overrides rot. Variants compose. When the merchant later asks "make all the hero CTAs feel more premium," you update one variant in one file; with inline overrides, you'd hunt every call site.
+
+### Brand-expression tokens in variants
+
+Use the platform-shipped brand-expression CSS variables (--gradient-primary, --shadow-elegant, --shadow-glow, --transition-smooth — see the `customize-theme` skill for the full scaffold) in your variants. They keep customizations brand-tinted instead of generic.
+
+## Available SDK Components by Module
+
+### Products (7 components)
+`ProductCard`, `ProductGrid`, `ProductDetails`, `VariantSelector`, `ProductGallery`, `ProductSearch`, `ProductSort`
+
+Import: `@rovela-ai/sdk/products`
+
+### Cart (6 components)
+`CartDrawer`, `CartItem`, `CartSummary`, `CartIcon`, `AddToCartButton`, `QuantitySelector`
+
+Import: `@rovela-ai/sdk/cart`
+
+### Checkout (6 components)
+`CheckoutButton`, `CheckoutFlow`, `CheckoutSuccess`, `OrderSummary`, `ShippingForm`, `ShippingOptions`
+
+Import: `@rovela-ai/sdk/checkout`
+
+### Auth (7 components)
+`SignInForm`, `SignUpForm`, `ForgotPasswordForm`, `ResetPasswordForm`, `VerifyEmailNotice`, `UserMenu`, `AuthGuard`
+
+Import: `@rovela-ai/sdk/auth`
+
+### Media (3 components)
+`ImageUpload`, `DropZone`, `useUpload`
+
+Import: `@rovela-ai/sdk/media`
+
+### Other modules (rarely overridden)
+The SDK has 11 modules total. Also available: `core` (StoreSettingsProvider, i18n `useT`/`LocaleLink`, cookie consent), `analytics` (AnalyticsProvider + admin views), `emails` (templates + the merchant-editable layer — edited at `/admin/emails`, not by overriding components), `admin` (the dashboard kit — admin components are NOT candidates for copy-and-modify overrides; custom admin pages compose the kit per CLAUDE.md §7.6 instead), `shipping`, `theme`.
+
+## Common Overrides
+
+| What to Customize | SDK Component | Override Location |
+|-------------------|---------------|-------------------|
+| Cart icon badge style | `CartIcon` | `/app/components/CartIcon.tsx` |
+| Product card layout | `ProductCard` | `/app/components/ProductCard.tsx` |
+| Add-to-cart animation | `AddToCartButton` | `/app/components/AddToCartButton.tsx` |
+| Checkout form fields | `ShippingForm` | `/app/components/ShippingForm.tsx` |
+| Sign-in page design | `SignInForm` | `/app/components/SignInForm.tsx` |
+
+## Important
+
+- Keep the same props interface as the SDK component for drop-in replacement
+- SDK hooks (`useCart`, `useAuth`, `useStoreSettings`) work in your overridden components
+- Don't override Provider components (`CartProvider`, `StoreSettingsProvider`) — wrap or configure them instead

package/templates/store-template/.env.example

@@ -0,0 +1,50 @@
+# =============================================================================
+# Store Template Environment Variables
+# =============================================================================
+# Copy this file to .env.local and fill in the values
+
+# =============================================================================
+# Database (Neon PostgreSQL - unique per store via Neon branches)
+# =============================================================================
+DATABASE_URL="postgresql://user:password@host/database?sslmode=require"
+
+# =============================================================================
+# Authentication (NextAuth.js)
+# =============================================================================
+NEXTAUTH_SECRET="generate-a-secure-secret-here"
+NEXTAUTH_URL="http://localhost:3000"
+
+# =============================================================================
+# Stripe Payments
+# =============================================================================
+# Platform credentials (from Rovela)
+STRIPE_SECRET_KEY="sk_test_..."
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
+STRIPE_WEBHOOK_SECRET="whsec_..."
+
+# Per-store connected account (set by platform)
+STRIPE_CONNECTED_ACCOUNT_ID="acct_..."
+
+# Optional: Platform fee percentage (default: 5)
+STRIPE_PLATFORM_FEE_PERCENT="5"
+
+# =============================================================================
+# Email (Resend)
+# =============================================================================
+RESEND_API_KEY="re_..."
+RESEND_FROM_EMAIL="store@yourdomain.com"
+
+# Store branding and configuration
+STORE_NAME="My Store"
+STORE_CURRENCY="usd"
+STORE_OWNER_EMAIL="owner@yourdomain.com"
+SUPPORT_EMAIL="support@yourdomain.com"
+
+# Optional branding for emails (future feature)
+STORE_LOGO_URL="https://..."
+STORE_ADDRESS="123 Main St, City, State 12345"
+
+# =============================================================================
+# Application URL
+# =============================================================================
+NEXT_PUBLIC_APP_URL="http://localhost:3000"

package/templates/store-template/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "next-devtools": {
+      "command": "npx",
+      "args": ["-y", "next-devtools-mcp@latest"]
+    }
+  }
+}

package/templates/store-template/.rovela/blueprint.example.json

@@ -0,0 +1,190 @@
+{
+  "version": "3.0.0",
+
+  "store": {
+    "id": "00000000-0000-0000-0000-000000000000",
+    "name": "Example Store",
+    "slug": "example-store",
+    "description": "An example e-commerce store built with Rovela SDK",
+    "productType": "physical",
+    "businessStage": "startup",
+    "currency": "USD",
+    "locale": "en-US"
+  },
+
+  "theme": {
+    "inspiration": "stripe",
+    "personality": { "x": 0.2, "y": 0 },
+    "colors": {
+      "primary": {
+        "50": "#eff6ff",
+        "100": "#dbeafe",
+        "200": "#bfdbfe",
+        "300": "#93c5fd",
+        "400": "#60a5fa",
+        "500": "#3b82f6",
+        "600": "#2563eb",
+        "700": "#1d4ed8",
+        "800": "#1e40af",
+        "900": "#1e3a8a",
+        "950": "#172554"
+      },
+      "secondary": {
+        "50": "#f8fafc",
+        "100": "#f1f5f9",
+        "200": "#e2e8f0",
+        "300": "#cbd5e1",
+        "400": "#94a3b8",
+        "500": "#64748b",
+        "600": "#475569",
+        "700": "#334155",
+        "800": "#1e293b",
+        "900": "#0f172a",
+        "950": "#020617"
+      },
+      "accent": {
+        "50": "#faf5ff",
+        "100": "#f3e8ff",
+        "200": "#e9d5ff",
+        "300": "#d8b4fe",
+        "400": "#c084fc",
+        "500": "#a855f7",
+        "600": "#9333ea",
+        "700": "#7e22ce",
+        "800": "#6b21a8",
+        "900": "#581c87",
+        "950": "#3b0764"
+      },
+      "neutral": {
+        "50": "#fafafa",
+        "100": "#f4f4f5",
+        "200": "#e4e4e7",
+        "300": "#d4d4d8",
+        "400": "#a1a1aa",
+        "500": "#71717a",
+        "600": "#52525b",
+        "700": "#3f3f46",
+        "800": "#27272a",
+        "900": "#18181b",
+        "950": "#09090b"
+      },
+      "semantic": {
+        "success": "#22c55e",
+        "error": "#ef4444",
+        "warning": "#f59e0b",
+        "info": "#3b82f6"
+      }
+    },
+    "typography": {
+      "heading": { "name": "Inter", "weights": [500, 600, 700], "fallback": ["system-ui", "sans-serif"] },
+      "body": { "name": "Inter", "weights": [400, 500], "fallback": ["system-ui", "sans-serif"] },
+      "mono": { "name": "JetBrains Mono", "weights": [400], "fallback": ["monospace"] }
+    },
+    "spacing": "balanced",
+    "borderRadius": "rounded",
+    "animation": "smooth"
+  },
+
+  "brand": {
+    "tagline": "Your tagline here",
+    "uniqueValue": "Your unique value proposition",
+    "targetAudience": "Your target audience description",
+    "voice": {
+      "tone": ["professional", "friendly"],
+      "personality": ["trustworthy", "innovative"],
+      "vocabulary": {
+        "preferred": ["quality", "value", "service"],
+        "avoid": ["cheap", "basic"]
+      }
+    },
+    "imagery": {
+      "style": "photography",
+      "subjects": ["products", "lifestyle"],
+      "treatments": ["natural lighting", "clean backgrounds"],
+      "avoid": ["cluttered", "low quality"]
+    }
+  },
+
+  "homepage": {
+    "hero": {
+      "headline": "Welcome to Example Store",
+      "subheadline": "Discover amazing products for your everyday needs",
+      "cta": { "text": "Shop Now", "link": "/products" },
+      "imageQuery": "modern ecommerce shopping lifestyle",
+      "imageUrl": "https://images.unsplash.com/photo-1441986300917-64674bd600d8?w=1080",
+      "layout": "center"
+    },
+    "features": {
+      "title": "Why Choose Us",
+      "subtitle": "We're committed to providing the best experience",
+      "items": [
+        {
+          "icon": "Truck",
+          "title": "Fast Shipping",
+          "description": "Get your orders delivered quickly and reliably"
+        },
+        {
+          "icon": "Shield",
+          "title": "Secure Payments",
+          "description": "Your transactions are protected with industry-standard security"
+        },
+        {
+          "icon": "HeadphonesIcon",
+          "title": "24/7 Support",
+          "description": "Our team is here to help whenever you need us"
+        }
+      ]
+    },
+    "cta": {
+      "headline": "Ready to Get Started?",
+      "description": "Join thousands of satisfied customers today",
+      "buttonText": "Browse Products",
+      "buttonLink": "/products"
+    }
+  },
+
+  "modules": {
+    "auth": {
+      "enabled": true,
+      "guestCheckout": true,
+      "customerAccounts": true
+    },
+    "products": {
+      "hasVariants": true,
+      "trackInventory": true
+    },
+    "orders": {
+      "processing": "instant",
+      "returnPolicy": "30-days",
+      "refundType": "full"
+    },
+    "shipping": {
+      "method": "carrier",
+      "rates": "flat",
+      "processingTime": "1-2-days"
+    },
+    "payments": {
+      "provider": "stripe",
+      "currency": "USD",
+      "taxHandling": "checkout"
+    },
+    "emails": {
+      "templates": ["order-confirmation", "shipping-update", "welcome", "password-reset"]
+    }
+  },
+
+  "seo": {
+    "title": "Example Store - Quality Products",
+    "description": "Shop amazing products at Example Store. Fast shipping, secure payments, and excellent customer service.",
+    "keywords": ["ecommerce", "online store", "shopping"]
+  },
+
+  "metadata": {
+    "blueprintVersion": "3.0.0",
+    "questionnaireId": "00000000-0000-0000-0000-000000000000",
+    "sdkVersion": "@rovela-ai/sdk@0.1.0",
+    "generatedBy": "example",
+    "generatedAt": "2025-11-29T00:00:00.000Z",
+    "confidence": 1.0
+  }
+}

package/templates/store-template/CLAUDE.md

@@ -0,0 +1,14 @@
+# Claude Agent Instructions
+
+> **Note:** This file is a placeholder. During sandbox initialization, it gets replaced with
+> project-specific instructions generated from the blueprint and questionnaire.
+
+If you're seeing this message, the sandbox may not have been properly initialized.
+Check that `/app/.rovela/blueprint.json` exists and contains valid blueprint data.
+
+The actual instructions include:
+- Store-specific configuration from blueprint
+- Homepage section content to implement
+- Theme and brand guidelines
+- SDK usage documentation
+- MCP tools reference (postgres-mcp, next-devtools, mcp-r2)