@hailer/mcp 1.1.13 → 1.1.15

package/.claude/skills/hailer-apps-pictures/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: hailer-apps-pictures
+description: Pattern for fetching and displaying images from Hailer in React apps
+version: 1.0.0
+triggers: When building Hailer apps that need to display images from activities or insights
+---
+
+# Hailer Apps Image Handling
+
+Pattern for fetching and displaying images from Hailer in React apps.
+
+## Image URL Format
+
+Hailer serves images from this endpoint:
+```
+https://api.hailer.com/image/hires/{imageId}
+```
+
+### URL Patterns
+
+**Correct formats (use these):**
+- `https://api.hailer.com/image/hires/{imageId}` - High-resolution images, works without authentication
+- `https://api.hailer.com/image/thumbnail/{imageId}` - Thumbnail version for lists/grids
+
+**Wrong formats (don't use):**
+- `https://app.hailer.com/api/files/{imageId}` - CORS issues in browsers
+- `https://api.hailer.com/files/{imageId}` - Authentication required, may fail in apps
+- `https://api.hailer.com/image/{imageId}` - Missing size parameter
+
+### Utility Function
+
+```typescript
+function getImageUrl(imageId: string, size: 'hires' | 'thumbnail' = 'hires'): string {
+  return `https://api.hailer.com/image/${size}/${imageId}`;
+}
+
+// Usage
+const url = getImageUrl('abc123', 'hires');      // https://api.hailer.com/image/hires/abc123
+const thumbUrl = getImageUrl('abc123', 'thumbnail'); // https://api.hailer.com/image/thumbnail/abc123
+```
+
+### Extracting imageId from Activity Fields
+
+Image IDs typically come from file fields in activities. Extract them from the activity structure:
+
+```typescript
+// From a file field in an activity
+const fileField = activity.fields.image_file; // e.g., { id: "file_xyz", name: "photo.jpg" }
+const imageId = fileField?.id;
+
+// From insight data with embedded URLs
+const imageUrl = item.mainProductImageUrl; // e.g., "https://api.hailer.com/image/hires/abc123"
+const imageId = imageUrl.split('/').pop(); // Extract from end of URL
+
+// From JSON array of IDs
+const imageIds = JSON.parse(item.allPictures); // ["id1", "id2", "id3"]
+```
+
+## Data Structure
+
+Product/activity images typically come from insights with two fields:
+
+```typescript
+interface WithImages {
+  mainProductImageUrl: string;  // Full URL to main image
+  allPictures: string;          // JSON string: '["id1", "id2", "id3"]'
+}
+```
+
+## HailerImage Component
+
+Create a wrapper component for CORS handling and error states:
+
+```tsx
+// components/HailerImage.tsx
+import { Image, ImageProps, Icon } from '@chakra-ui/react';
+import { FaImage } from 'react-icons/fa6';
+import { useState, useEffect } from 'react';
+import { useHailer } from '../hailer/use-hailer';
+
+interface HailerImageProps extends Omit<ImageProps, 'src'> {
+  hailerImageUrl?: string;
+  fallbackIcon?: boolean;
+}
+
+export const HailerImage = ({
+  hailerImageUrl,
+  fallbackIcon = true,
+  alt = 'Image',
+  ...imageProps
+}: HailerImageProps) => {
+  const { inside, hailer } = useHailer();  // ← CORRECT: Destructure from useHailer()
+  const [blobUrl, setBlobUrl] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [isError, setIsError] = useState(false);
+
+  useEffect(() => {
+    const loadImage = async () => {
+      if (!hailerImageUrl) {
+        setIsError(true);
+        setIsLoading(false);
+        return;
+      }
+
+      if (!hailer?.ready) {
+        setIsLoading(true);
+        return;
+      }
+
+      try {
+        const isHailerApiUrl = hailerImageUrl.includes('api.hailer.com');
+        const isLocalDevelopment = window.location.hostname === 'localhost';
+
+        if (isLocalDevelopment && isHailerApiUrl) {
+          // CORS blocks api.hailer.com in localhost
+          console.log('Local development: Hailer images blocked by CORS. Will work in production.');
+          setIsError(true);
+          setIsLoading(false);
+          return;
+        }
+
+        setBlobUrl(hailerImageUrl);
+        setIsError(false);
+      } catch (error) {
+        console.error('Error loading image from Hailer:', error);
+        setIsError(true);
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    loadImage();
+
+    return () => {
+      if (blobUrl) {
+        URL.revokeObjectURL(blobUrl);
+      }
+    };
+  }, [hailerImageUrl, hailer?.ready]);
+
+  if (isLoading || isError || !blobUrl) {
+    return fallbackIcon ? (
+      <Icon as={FaImage} color="gray.200" {...imageProps} />
+    ) : null;
+  }
+
+  return (
+    <Image
+      {...imageProps}
+      src={blobUrl}
+      alt={alt}
+      onError={() => setIsError(true)}
+    />
+  );
+};
+```
+
+## Usage: Single Image
+
+```tsx
+<HailerImage
+  hailerImageUrl={product.mainProductImageUrl}
+  loading="lazy"
+  objectFit="cover"
+  maxW="100%"
+  h="auto"
+  aspectRatio={1}
+  alt="Product image"
+/>
+```
+
+## Usage: Image Carousel
+
+For multiple images stored as JSON array of IDs:
+
+```tsx
+const ProductImageCarousel = ({ allPictures, mainImageUrl }: Props) => {
+  const [currentIndex, setCurrentIndex] = useState(0);
+
+  // Parse JSON string to array of IDs
+  const imageIds = useMemo(() => {
+    if (!allPictures) return [];
+    try {
+      const parsed = JSON.parse(allPictures);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  }, [allPictures]);
+
+  const hasMultiple = imageIds.length > 1;
+
+  // Construct URL from ID
+  const getCurrentUrl = () => {
+    if (imageIds.length === 0) return mainImageUrl || '';
+    const id = imageIds[currentIndex];
+    return id ? `https://api.hailer.com/image/hires/${id}` : mainImageUrl || '';
+  };
+
+  const goNext = () => setCurrentIndex(i => (i + 1) % imageIds.length);
+  const goPrev = () => setCurrentIndex(i => (i - 1 + imageIds.length) % imageIds.length);
+
+  return (
+    <Box position="relative">
+      <Image src={getCurrentUrl()} alt="Product" objectFit="contain" />
+
+      {hasMultiple && (
+        <>
+          <IconButton
+            icon={<FaChevronLeft />}
+            onClick={goPrev}
+            position="absolute"
+            left={2}
+            top="50%"
+            transform="translateY(-50%)"
+          />
+          <IconButton
+            icon={<FaChevronRight />}
+            onClick={goNext}
+            position="absolute"
+            right={2}
+            top="50%"
+            transform="translateY(-50%)"
+          />
+          <Text textAlign="center">
+            {currentIndex + 1} / {imageIds.length}
+          </Text>
+        </>
+      )}
+    </Box>
+  );
+};
+```
+
+## Fetching Image Data from Insights
+
+```typescript
+// In App.tsx or data fetching hook
+const fetchProducts = async () => {
+  const data = await hailer.api.public.insight.dataAsObject(PRODUCT_INSIGHT_KEY);
+
+  return data.map(item => ({
+    // ... other fields
+    mainProductImageUrl: item.mainProductImageUrl || '',
+    allPictures: item.allPictures || '[]',
+  }));
+};
+```
+
+## Key Points
+
+| Aspect | Details |
+|--------|---------|
+| **URL Format** | `https://api.hailer.com/image/hires/{imageId}` |
+| **CORS** | Blocked in localhost, works in production |
+| **Fallback** | Use `FaImage` icon from react-icons/fa6 |
+| **Performance** | Use `loading="lazy"` for catalog images |
+| **Multiple Images** | Store as JSON array of IDs, construct URLs on demand |
+| **Memory** | Revoke blob URLs on component cleanup |
+
+## Dependencies
+
+```json
+{
+  "@chakra-ui/react": "^2.x",
+  "react-icons": "^5.x",
+  "@hailer/app-sdk": "^2.x"
+}
+```

package/.claude/skills/hailer-design-system/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: hailer-design-system
+description: Chakra UI v2 theme, colors, icons, and component patterns for Hailer apps
+version: 1.0.0
+triggers: Build app, UI components, styling, theme, colors, icons, buttons, forms
+---
+
+# Hailer Design System
+
+Chakra UI v2 with custom Hailer theme.
+
+**Full reference:** Read `docs/design-system/HAILER_DESIGN_SYSTEM.md` for comprehensive documentation (all icons, all components, full examples).
+
+## Setup
+
+The `react-ts` scaffold template already includes the design system at `src/hailer/theme/`. **Do NOT copy from other projects.**
+
+```tsx
+// Already set up by scaffold in main.tsx
+import { ChakraProvider } from '@chakra-ui/react';
+import { theme } from './hailer/theme/theme';
+
+<ChakraProvider theme={theme}>
+  <App />
+</ChakraProvider>
+```
+
+---
+
+## Colors
+
+**Let theme handle colors automatically.** Rarely specify manually.
+
+| Use | Color |
+|-----|-------|
+| Primary action | `colorScheme="green"` |
+| Secondary action | `colorScheme="blue"` |
+| Destructive | `colorScheme="red"` |
+| Neutral | `colorScheme="gray"` |
+
+**Semantic tokens (auto light/dark):**
+- `subtleText` - Muted text
+- `bodyText` - Main text
+- `chakra-body-bg` - Page background
+
+---
+
+## Buttons
+
+**Variants:**
+- `solid` (default) - For 1-2 button groups
+- `outline` - For 3+ buttons in a series
+- `ghost` - Subtle secondary actions
+
+**Critical rules:**
+- Max 2 color schemes per button group
+- Right-align button groups (`justify="flex-end"`)
+- Primary action on the RIGHT
+- Add Hailer icon to primary button
+
+```tsx
+// Two buttons - correct
+<HStack spacing={3} justify="flex-end">
+  <Button colorScheme="gray">Cancel</Button>
+  <Button colorScheme="green">Save</Button>
+</HStack>
+
+// 3+ buttons - use outline
+<HStack spacing={3}>
+  <Button variant="outline" colorScheme="green" leftIcon={<HailerPlus />}>Create</Button>
+  <Button variant="outline" colorScheme="gray">Export</Button>
+  <Button variant="outline" colorScheme="gray">Filter</Button>
+</HStack>
+```
+
+---
+
+## Icons
+
+**CRITICAL: Only use Hailer icons. Never external libraries.**
+
+```tsx
+import { HailerPlus, HailerSettings } from './hailer/theme/icons';
+
+<HailerPlus boxSize={6} />
+<Button leftIcon={<HailerPlus />}>Add</Button>
+<IconButton icon={<HailerSettings />} aria-label="Settings" />
+```
+
+**Common icons:**
+- Actions: `HailerPlus`, `HailerEdit`, `HailerTrash`, `HailerSave`
+- Navigation: `HailerChevron`, `HailerMenu`, `HailerSearch`
+- Status: `HailerWarning`, `HailerInfo`, `HailerTick`
+- Objects: `HailerUser`, `HailerCalendar`, `HailerFile`, `HailerActivities`
+
+---
+
+## Typography
+
+| Size | Use |
+|------|-----|
+| `2xl` | Page title |
+| `xl` | Section header |
+| `lg` | Subsection |
+| `md` | Card headers |
+| `sm` | Labels |
+
+```tsx
+<Heading size="2xl">Page Title</Heading>
+<Text fontSize="sm" color="subtleText">Caption</Text>
+```
+
+---
+
+## Spacing
+
+```tsx
+<Box p={8} maxW="1400px" mx="auto">  // Page container
+  <VStack spacing={6} align="stretch">  // Section spacing
+    {/* Content */}
+  </VStack>
+</Box>
+```
+
+---
+
+## Forms
+
+```tsx
+<FormControl isInvalid={hasError}>
+  <FormLabel>Field Label</FormLabel>
+  <Input placeholder="Enter text..." />
+  <FormHelperText>Helper text</FormHelperText>
+  <FormErrorMessage>Error message</FormErrorMessage>
+</FormControl>
+```
+
+**Selection controls:** Only green colorScheme for Checkbox, Radio, Switch.
+
+---
+
+## Tables
+
+**CRITICAL: Use Chakra Table components, not HTML.**
+
+```tsx
+<TableContainer>
+  <Table variant="simple" size="md">
+    <Thead>
+      <Tr>
+        <Th>Name</Th>
+        <Th isNumeric>Count</Th>
+      </Tr>
+    </Thead>
+    <Tbody>
+      <Tr>
+        <Td>Item</Td>
+        <Td isNumeric>42</Td>
+      </Tr>
+    </Tbody>
+  </Table>
+</TableContainer>
+```
+
+---
+
+## Modals
+
+```tsx
+<Modal isOpen={isOpen} onClose={onClose} size="md">
+  <ModalOverlay />
+  <ModalContent>
+    <ModalHeader>Title</ModalHeader>
+    <ModalCloseButton />
+    <ModalBody>Content</ModalBody>
+    <ModalFooter>
+      <Button onClick={onClose}>Cancel</Button>
+      <Button colorScheme="green">Save</Button>
+    </ModalFooter>
+  </ModalContent>
+</Modal>
+```
+
+---
+
+## Feedback
+
+**Toast:**
+```tsx
+toast({
+  description: "Your changes have been saved.",
+  status: "success",
+  duration: 3000,
+  isClosable: true
+});
+```
+
+**Alert:**
+```tsx
+<Alert status="error">
+  <AlertIcon />
+  <AlertDescription>Something went wrong.</AlertDescription>
+</Alert>
+```
+
+---
+
+## Stats
+
+**Always use Stat components, not manual Box/Text:**
+
+```tsx
+<Stat>
+  <StatLabel>Total Users</StatLabel>
+  <StatNumber>1,234</StatNumber>
+  <StatHelpText>
+    <StatArrow type="increase" />
+    23%
+  </StatHelpText>
+</Stat>
+```
+
+---
+
+## Content Tone
+
+- Clear, supportive, human
+- Use contractions ("you're", "we'll")
+- Never blame the user
+- Warm success messages: "Your changes have been saved."
+- Helpful errors: "We couldn't save your changes. Please try again."