@hailer/mcp 1.3.21 → 1.3.32

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

@@ -1,80 +1,112 @@
 ---
 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
+description: Fetching and displaying images from Hailer in React apps — load when an app needs to show activity images, handle file uploads, build image carousels, or debug 403 image errors
+version: 2.4.3
+triggers:
+  - image
+  - picture
+  - photo
+  - file upload
+  - display image
+  - HailerImage
 ---
 
 # Hailer Apps Image Handling
 
 Pattern for fetching and displaying images from Hailer in React apps.
 
+## Permissions / Auth Requirements
+
+**Standard uploads (via the Hailer UI file modifier or `uploadFile` without `isPublic: true`) are auth-gated.**
+
+A viewer must have **workflow read membership** on the workflow that owns the activity holding the file. Without it, image requests return 403. This applies even inside Hailer apps.
+
+| Upload path | Public? | Required to view |
+|---|---|---|
+| `uploadFile(file, name, { isPublic: true })` | Yes — via /public/ routes | Nothing |
+| `uploadFile(file, name, { isPublic: false })` (or default) | No | Workflow read membership |
+| Hailer UI file modifier (standard attachment) | No | Workflow read membership |
+
+**`isPublic` must be set at upload time** — there is no API to flip a file from private to public after the fact.
+
+**Practical design checklist:**
+1. Will all app users have workflow read on the source workflow? → standard upload works.
+2. Are some users members of the insight but NOT the source workflow? → grant them workflow read too.
+3. Is the image truly public-facing (embed in email, external site)? → upload with `{ isPublic: true }` and use the `/public/image/{size}/{id}` route.
+
+---
+
 ## Image URL Format
 
-Hailer serves images from this endpoint:
-```
-https://api.hailer.com/image/hires/{imageId}
-```
+Two route families — choose based on context:
+
+| Route | When to use |
+|-------|-------------|
+| `/image/{size}/{id}` | Same-origin React app with active Hailer session (hlrkey cookie present) |
+| `/public/image/{size}/{id}` | External embedding, email clients, cookieless cross-origin fetch, Node.js without a session — `isPublic: true` files only |
+
+**The bare `/image/{size}/{id}` route returns 403 unauthenticated regardless of `isPublic`.** For any context where you cannot guarantee an active Hailer session cookie, use `/public/image/...`. (Live-verified 2026-06-10.)
 
 ### 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
+**Correct formats:**
+- `https://api.hailer.com/image/hires/{imageId}` — same-origin session; requires auth (hlrkey cookie)
+- `https://api.hailer.com/image/thumb/{imageId}` — same-origin session thumbnail
+- `https://api.hailer.com/public/image/hires/{imageId}` — external/cookieless; `isPublic: true` files only
+- `https://api.hailer.com/public/image/thumb/{imageId}` — external/cookieless thumbnail
+
+Valid size tokens: `square25, square50, square75, square100, square200, profile, smallface, bigface, thumb, gallerycover, fullhd, hires, lores, pdf, original`
 
 **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
+- `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}`;
+function getImageUrl(
+  imageId: string,
+  size: 'hires' | 'thumb' = 'hires',
+  options: { external?: boolean } = {}
+): string {
+  return options.external
+    ? `https://api.hailer.com/public/image/${size}/${imageId}`
+    : `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
+// Same-origin Hailer app (session cookie present):
+const url = getImageUrl('abc123', 'hires');
+// External embed / email / cookieless (isPublic: true files only):
+const externalUrl = getImageUrl('abc123', 'hires', { external: true });
+// Note: 'thumbnail' is NOT a valid size token — use 'thumb'
 ```
 
 ### 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 a file-modifier field in an activity — value is a JSON-stringified array of file IDs
+const ids: string[] = JSON.parse(activity.fields.image_file ?? '[]');
+const imageId = ids[0];
 
 // 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
+const imageId = imageUrl.split('/').pop();
 
 // 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:
+**iOS app version compatibility:** This component works as-is on iOS 2.2.4+ and all web. On older iOS app versions (pre-2.2.4), WKWebView blocks third-party auth cookies inside the `apps.hailer.com` iframe → `api.hailer.com` image requests fail.
 
 ```tsx
 // components/HailerImage.tsx
 import { Image, ImageProps, Icon } from '@chakra-ui/react';
-import { FaImage } from 'react-icons/fa6';
+import { HailerImage as HailerImageIcon } from '../hailer/theme/icons/HailerImage'; // aliased — this component is also named HailerImage. No barrel index in the icons dir; import the specific file.
 import { useState, useEffect } from 'react';
 import useHailer from '../hailer/use-hailer';
 
@@ -89,23 +121,15 @@ export const HailerImage = ({
   alt = 'Image',
   ...imageProps
 }: HailerImageProps) => {
-  const { inside, hailer } = useHailer();  // ← CORRECT: Destructure from useHailer()
+  const { inside, hailer } = 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) {  // NOTE: verify .ready exists on SDK type — may need .activity or similar
-        setIsLoading(true);
-        return;
-      }
+      if (!hailerImageUrl) { setIsError(true); setIsLoading(false); return; }
+      if (!inside) { setIsLoading(true); return; }
 
       try {
         const isHailerApiUrl = hailerImageUrl.includes('api.hailer.com');
@@ -113,7 +137,6 @@ export const HailerImage = ({
 
         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;
@@ -122,7 +145,6 @@ export const HailerImage = ({
         setBlobUrl(hailerImageUrl);
         setIsError(false);
       } catch (error) {
-        console.error('Error loading image from Hailer:', error);
         setIsError(true);
       } finally {
         setIsLoading(false);
@@ -132,15 +154,13 @@ export const HailerImage = ({
     loadImage();
 
     return () => {
-      if (blobUrl) {
-        URL.revokeObjectURL(blobUrl);
-      }
+      if (blobUrl) URL.revokeObjectURL(blobUrl);
     };
-  }, [hailerImageUrl, hailer?.ready]);
+  }, [hailerImageUrl, inside]);
 
   if (isLoading || isError || !blobUrl) {
     return fallbackIcon ? (
-      <Icon as={FaImage} color="gray.200" {...imageProps} />
+      <Icon as={HailerImageIcon} color="gray.200" {...imageProps} />
     ) : null;
   }
 
@@ -171,26 +191,22 @@ export const HailerImage = ({
 
 ## Usage: Image Carousel
 
-For multiple images stored as JSON array of IDs:
+For multiple images stored as a 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 [];
-    }
+    } catch { return []; }
   }, [allPictures]);
 
   const hasMultiple = imageIds.length > 1;
 
-  // Construct URL from ID
   const getCurrentUrl = () => {
     if (imageIds.length === 0) return mainImageUrl || '';
     const id = imageIds[currentIndex];
@@ -206,25 +222,21 @@ const ProductImageCarousel = ({ allPictures, mainImageUrl }: Props) => {
 
       {hasMultiple && (
         <>
+          {/* Use the Hailer design-system chevron — never external icon libs.
+              Apply a rotate() transform if it doesn't already point left/right. */}
           <IconButton
-            icon={<FaChevronLeft />}
+            aria-label="Previous image"
+            icon={<HailerChevron />}
             onClick={goPrev}
-            position="absolute"
-            left={2}
-            top="50%"
-            transform="translateY(-50%)"
+            position="absolute" left={2} top="50%" transform="translateY(-50%)"
           />
           <IconButton
-            icon={<FaChevronRight />}
+            aria-label="Next image"
+            icon={<HailerChevron />}
             onClick={goNext}
-            position="absolute"
-            right={2}
-            top="50%"
-            transform="translateY(-50%)"
+            position="absolute" right={2} top="50%" transform="translateY(-50%)"
           />
-          <Text textAlign="center">
-            {currentIndex + 1} / {imageIds.length}
-          </Text>
+          <Text textAlign="center">{currentIndex + 1} / {imageIds.length}</Text>
         </>
       )}
     </Box>
@@ -232,38 +244,130 @@ const ProductImageCarousel = ({ allPictures, mainImageUrl }: Props) => {
 };
 ```
 
-## Fetching Image Data from Insights
+---
+
+## File Upload Pattern
+
+For app-sdk 2.4.x+, use `hailer.file.upload()` — `hailer.ui.files.uploadFile()` is marked `@deprecated` in 2.4.x. Both have the same signature and return a `fileId` string.
 
 ```typescript
-// In App.tsx or data fetching hook
-const fetchProducts = async () => {
-  const data = await hailer.public.insight.dataAsObject(PRODUCT_INSIGHT_KEY);
-
-  return data.map(item => ({
-    // ... other fields
-    mainProductImageUrl: item.mainProductImageUrl || '',
-    allPictures: item.allPictures || '[]',
-  }));
+// Preferred for app-sdk 2.4.x+
+const fileId = await hailer.file.upload(file, fileName, { isPublic: false });
+const publicFileId = await hailer.file.upload(file, fileName, { isPublic: true });
+
+// Legacy (still works but deprecated in 2.4.x)
+const fileId = await hailer.ui.files.uploadFile(file, fileName, { isPublic: false });
+
+// Pass fileIds when creating an activity
+await hailer.activity.create('workflowId', [
+  { name: 'Activity', fields: { /* ... */ } }
+], { fileIds: [fileId] });
+```
+
+**`isPublic: true` must be set at upload time.** There is no API to promote a file from private to public after creation.
+
+**`fileIds` only bind at `activity.create`.** There is no `attachFiles`/`addFiles` method on app-sdk. Defer activity creation until files are ready.
+
+### Canonical upload-during-form-fill pattern
+
+```tsx
+const uploadPromiseRef = useRef<Promise<string[]> | null>(null);
+
+// When user selects files — start upload immediately
+const handleFilesSelected = (files: File[]) => {
+  uploadPromiseRef.current = Promise.all(
+    files.map(f => hailer.file.upload(f, f.name, {}))
+  );
 };
+
+// On Save — await the in-flight promise, then create atomically
+const handleSave = async () => {
+  const fileIds = uploadPromiseRef.current ? await uploadPromiseRef.current : [];
+  await hailer.activity.create(workflowId, [{ name, fields }], { fileIds });
+};
+```
+
+---
+
+## Server-to-Server Image Fetching
+
+For **public files** (`isPublic: true`), use `/public/image/{size}/{id}` for cookieless or external fetches. The bare `/image/{size}/{id}` route requires the `hlrkey` cookie — it returns 403 unauthenticated regardless of `isPublic` (live-verified 2026-06-10).
+
+```
+# Cookieless/external (isPublic files only):
+https://api.hailer.com/public/image/{size}/{imageId}
+
+# Same-origin / hlrkey-authenticated:
+https://api.hailer.com/image/{size}/{imageId}
 ```
 
+Diagnostic: 404 on `/public/` = file not isPublic; 403 on bare route = missing auth.
+
+---
+
 ## 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 |
+| **URL Format** | Same-origin session: `/image/{size}/{id}`; external/cookieless: `/public/image/{size}/{id}` |
+| **Auth — standard files** | Requires workflow read membership; bare `/image/` route only |
+| **Auth — public files** | `isPublic: true` at upload time; use `/public/image/` for cookieless access |
+| **CORS** | Blocked in localhost browser, works in production and from Node.js |
+| **Fallback** | Use the design-system `HailerImage` icon (import aliased to `HailerImageIcon`) |
 | **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 |
 
+---
+
+## Diagnostic Overlay Pattern (iOS / Debug Builds)
+
+Use when diagnosing image load failures on iOS — when console access isn't available.
+
+```typescript
+// At module top — NOT inside the component
+const imageLoadStats = {
+  directLoadSuccess: 0,
+  S0_filget: 0,
+  S1_rpc: 0,
+  error: 0,
+};
+```
+
+```tsx
+// components/DiagnosticOverlay.tsx
+import { useEffect, useState } from 'react';
+import { imageLoadStats } from '../components/YourImageComponent';
+
+export const DiagnosticOverlay = () => {
+  const [snap, setSnap] = useState({ ...imageLoadStats });
+
+  useEffect(() => {
+    const id = setInterval(() => setSnap({ ...imageLoadStats }), 500);
+    return () => clearInterval(id);
+  }, []);
+
+  return (
+    <div style={{
+      position: 'fixed', bottom: 0, left: 0, right: 0,
+      background: 'rgba(0,0,0,0.75)', color: '#fff',
+      fontSize: 11, padding: '4px 8px', zIndex: 9999,
+    }}>
+      direct:{snap.directLoadSuccess} S0:{snap.S0_filget} S1:{snap.S1_rpc} err:{snap.error}
+    </div>
+  );
+};
+```
+
+Mount once in `App.tsx`. Bump the manifest version for each diagnostic build; strip the overlay after the fix is verified.
+
+---
+
 ## Dependencies
 
 ```json
 {
   "@chakra-ui/react": "^2.x",
-  "react-icons": "^5.x",
   "@hailer/app-sdk": "^2.x"
 }
 ```