Shopping Agent Architecture

Mobile App
  │
  ├─ POST /api/v1/shopping/scan-token          (menu scan flow)
  │     ↓
  │   Hono API (Edge)
  │     ├─ Cache check (Supabase)
  │     ├─ Dedup check (active Trigger.dev runs)
  │     └─ Trigger.dev task trigger → returns publicAccessToken + runId
  │
  ├─ WebSocket subscription (useRealtimeTaskTrigger)
  │     ↓
  │   Trigger.dev: shopping-menu-scan task
  │     │
  │     Stage 1: cache-check ──────────── 5%
  │     Stage 2: scrape (Firecrawl) ───── 10–40%
  │     Stage 3: match (pg_trgm) ──────── 40–60%
  │     Stage 4: personalize (Claude) ─── 60–85%
  │     Stage 5: cache-save (Supabase) ── 85–95%
  │     Stage 6: complete ──────────────── 100%
  │     │
  │     └─ Task output → WebSocket → Mobile App renders results
  │
  └─ POST /api/v1/research/strains/queue-batch  (discovery queue flow)
        Authorization: Bearer <Clerk token>
        body: { strainNames, source: "shopping_discovery" }
        ↓
      Hono API (Edge)
        ↓
      Trigger.dev: strain research pipeline
        ↓
      Supabase strains_v2 (full profile added within hours)

const cached = await supabase
  .from('menu_scans')
  .select('*')
  .eq('website_domain', dispensaryDomain)
  .gt('expires_at', new Date().toISOString())
  .order('scanned_at', { ascending: false })
  .limit(1)
  .single();

if (cached.data) {
  // Return cached result immediately — skip all subsequent stages
  return buildOutputFromCache(cached.data);
}

import { extractProducts, DISPENSARY_EXTRACT_SCHEMA } from '@tiwih/trigger';

const result = await extractProducts(
  ['https://dispensary.com/shop/*'],  // Wildcard pattern
  {
    schema: DISPENSARY_EXTRACT_SCHEMA,  // Plain JSON schema (not Zod!)
    prompt: 'Extract all cannabis products...',
    showSources: true,
    timeout: 180,
  }
);
// result.products: DispensaryProduct[]
// result.sources: string[] (URLs that were crawled)

import { scrapeAndExtract } from '@tiwih/trigger';

const result = await scrapeAndExtract(
  'https://dispensary.com/shop/flower',
  { waitFor: 3000 }  // Wait for JS rendering
);
// result.products: DispensaryProduct[]

import { scrapeMenuPage, extractProductsWithAI } from '@tiwih/trigger';

const scrapeResult = await scrapeMenuPage(url, { waitFor: 3000 });
const products = await extractProductsWithAI(scrapeResult.markdown, {
  maxProducts: 200,
});
// products: DispensaryProduct[]

import { discoverSitemapUrls } from '@tiwih/trigger';

const sitemap = await discoverSitemapUrls('dispensary.com');
// sitemap.menuUrls: string[]  — URLs matching /menu, /shop, /products, etc.
// sitemap.productUrls: string[]  — Individual product page URLs
// sitemap.totalDiscovered: number  — Total URLs found

Extract (wildcard) ─── products > 0? ──→ Return
        │ no
        ▼
Scrape+JSON ────────── products > 0? ──→ Return
        │ no
        ▼
Scrape → AI ────────── products > 0? ──→ Return
        │ no
        ▼
Sitemap Discovery ──── find menu URLs → Retry Extract/Scrape

task.updateMetadata({
  stage: 'scrape',
  progress: 10 + (extractedSoFar / estimatedTotal) * 30,
  message: `Scanning menu... found ${extractedSoFar} products`,
  productCount: extractedSoFar,
});

# Test the orchestrator (cascading fallback)
pnpm test:shopping                    # Default: Nuera Cannabis
pnpm test:shopping --url <url>        # Custom URL
pnpm test:shopping --sitemap          # Test sitemap discovery

# Test all 3 Firecrawl extraction methods side by side
pnpm test:extract                     # Default: Nuera Cannabis /shop/flower
pnpm test:extract <url> scrape        # Test only scrape+JSON mode
pnpm test:extract <url> wildcard      # Test only wildcard extract mode
pnpm test:extract <url> specific      # Test only specific-URL extract mode

SELECT id, slug, name_display, high_family
FROM strains_v2
WHERE name_canonical = lower(trim($1))
LIMIT 1;

SELECT id, slug, name_display, high_family
FROM strains_v2
WHERE slug = slugify($1)
LIMIT 1;

SELECT id, slug, name_display, high_family,
       similarity(name_canonical, lower(trim($1))) AS sim
FROM strains_v2
WHERE similarity(name_canonical, lower(trim($1))) > 0.4
ORDER BY sim DESC
LIMIT 1;

const BATCH_SIZE = 20;
const batches = chunk(extractedProducts, BATCH_SIZE);
const matchResults: Product[] = [];

for (const batch of batches) {
  const batchResults = await Promise.all(
    batch.map(product => matchProduct(product, supabase))
  );
  matchResults.push(...batchResults);
}

function assignTags(product: Product, userContext: UserContext): PersonalizationTag[] {
  const tags: PersonalizationTag[] = [];

  if (userContext.favoriteStrainIds.includes(product.strainId)) {
    tags.push('favorite_in_stock');
  }
  if (userContext.lowStashStrainIds.includes(product.strainId)) {
    tags.push('running_low');
  }
  if (userContext.recentStrainIds.includes(product.strainId)) {
    tags.push('bought_before');
  }
  if (isSimilarToFavorite(product, userContext)) {
    tags.push('similar_to_favorite');
  }
  if (matchesPreferences(product, userContext)) {
    tags.push('matches_preferences');
  }
  if (!product.strainId) {
    tags.push('new_discovery');
  }
  if (isOnSale(product)) {
    tags.push('great_deal');
  }

  return tags;
}

const recommendations = await generateObject({
  model: anthropic('claude-sonnet-4-6'),
  schema: RecommendationsSchema,
  prompt: `
    You are a knowledgeable cannabis advisor.

    The user has the following preferences:
    - Favorite strains: ${favoriteNames.join(', ')}
    - Preferred types: ${userContext.preferredTypes.join(', ')}
    - Recently purchased: ${recentNames.join(', ')}

    Here are the available products at this dispensary:
    ${JSON.stringify(taggedProducts, null, 2)}

    Select the 3-5 best products for this user and explain in 1-2 sentences why each
    is a great match. Focus on the specific combination of tags and strain properties
    that make it right for them. Be specific — mention actual terpene names, effects,
    or price value when relevant.
  `,
});

await supabase.from('menu_scans').upsert({
  website_domain: dispensaryDomain,
  categories_hash: computeCategoriesHash(products),
  scanned_at: new Date().toISOString(),
  expires_at: addHours(new Date(), 4).toISOString(),
  total_products: products.length,
  matched_count: products.filter(p => p.matched).length,
  unmatched_count: products.filter(p => !p.matched).length,
  products_json: products,
  recommendations_json: recommendations,
  discoveries_json: discoveries,
}, {
  onConflict: 'website_domain,categories_hash',
});

const activeRuns = await trigger.runs.list({
  taskIdentifier: 'shopping-menu-scan',
  status: ['EXECUTING', 'WAITING'],
  metadata: { dispensaryDomain },
});

if (activeRuns.data.length > 0) {
  // Return a token for the already-running scan
  const token = await trigger.auth.createPublicToken({
    scopes: { read: { runs: [activeRuns.data[0].id] } },
  });
  return { source: 'dedup', publicAccessToken: token, runId: activeRuns.data[0].id };
}

import { useRealtimeTaskTrigger } from '@trigger.dev/react-hooks';
import type { ShoppingMenuScanTask } from '@tiwih/trigger';

function ShoppingAgentScreen({ dispensary }) {
  const { submit, runs } = useRealtimeTaskTrigger<typeof ShoppingMenuScanTask>(
    'shopping-menu-scan'
  );

  const handleShopNow = async () => {
    const { publicAccessToken, cachedResult, runId } = await api.shopping.scanToken({
      dispensaryDomain: dispensary.domain,
      menuUrl: dispensary.menuUrl,
      userId: currentUser.id,
      userContext: buildUserContext(favorites, stash, orders),
    });

    if (cachedResult) {
      // Skip scan — go directly to results
      setResults(cachedResult);
      return;
    }

    // Subscribe to the live run
    submit(
      { dispensaryDomain: dispensary.domain, menuUrl: dispensary.menuUrl },
      { publicAccessToken }
    );
  };

  const activeRun = runs[0];
  const metadata = activeRun?.metadata;

  if (activeRun?.status === 'COMPLETED') {
    return <ResultsScreen data={activeRun.output} />;
  }

  return (
    <ScanScreen
      stage={metadata?.stage}
      progress={metadata?.progress ?? 0}
      message={metadata?.message ?? 'Starting...'}
    />
  );
}

DiscoveryScreen
  │
  ├─ useAuth() from Clerk — obtain Clerk session token
  │
  └─ POST /api/v1/research/strains/queue-batch
       {
         strainNames: ["Strain A", "Strain B", ...],
         source: "shopping_discovery"
       }
       Authorization: Bearer <clerk_token>
         │
         ↓
       Hono API (Edge) — validates auth, enqueues strains
         │
         ↓
       Trigger.dev strain research pipeline
         │
         ↓
       Supabase strains_v2 (full strain profile, typically within hours)

// Source enum values for /api/v1/research/strains/queue-batch
type QueueBatchSource = 'order_upload' | 'manual' | 'shopping_discovery';

// DiscoveryScreen.tsx (simplified)
import { useAuth } from '@clerk/clerk-expo';

const { getToken } = useAuth();
const submittingRef = useRef(false); // guard against double-submission

const handleQueueForResearch = async (strainNames: string[]) => {
  if (submittingRef.current) return;
  submittingRef.current = true;

  try {
    const token = await getToken();
    const response = await fetch(
      `${Config.API_BASE_URL}/api/v1/research/strains/queue-batch`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${token}`,
        },
        body: JSON.stringify({
          strainNames,
          source: 'shopping_discovery',
        }),
      }
    );

    if (!response.ok) throw new Error('Queue request failed');
    Alert.alert('Queued', `${strainNames.length} strain(s) queued for research.`);
  } catch {
    Alert.alert('Error', 'Could not queue strains. Please try again.');
  } finally {
    submittingRef.current = false;
  }
};

# Deploy trigger tasks (from monorepo root)
cd packages/trigger && npx trigger deploy