@hanzo/shopify 1.0.0

package/src/app/Assistant.tsx

@@ -0,0 +1,330 @@
+// The Hanzo AI assistant panel — a Polaris React component. All the logic-heavy
+// work (action catalogs, prompt assembly, request shaping, HMAC) lives in its
+// own tested modules on the server + in api.ts; this component binds them to
+// Polaris UI. It talks ONLY to the backend proxy (createApi) — it never holds a
+// secret and never calls Shopify or api.hanzo.ai directly.
+//
+// Two tabs: Products (read a product, run a content action, preview, write back)
+// and Orders (read an order, run a support action, copy). The action catalogs
+// are the server's, mirrored here for labels so the buttons never drift from
+// what the server will run.
+
+import { useCallback, useEffect, useState } from 'react';
+import {
+  Badge,
+  BlockStack,
+  Box,
+  Button,
+  ButtonGroup,
+  Card,
+  InlineStack,
+  Select,
+  Tabs,
+  Text,
+  TextField,
+  Banner,
+} from '@shopify/polaris';
+import type { Api, Product, Order } from './api';
+import type { LaunchContext } from './context';
+import { toGid } from './context';
+
+// The action buttons the panel shows. Ids MUST match the server's PRODUCT_ACTIONS
+// / ORDER_ACTIONS keys — the server validates the id, so a mismatch is a clean
+// 400, but we keep them in sync so the UI is honest.
+const PRODUCT_ACTIONS = [
+  { id: 'writeDescription', label: 'Write description', target: 'descriptionHtml' as const },
+  { id: 'rewriteDescription', label: 'Rewrite description', target: 'descriptionHtml' as const },
+  { id: 'seoTitle', label: 'SEO title', target: 'seoTitle' as const },
+  { id: 'seoDescription', label: 'SEO meta description', target: 'seoDescription' as const },
+];
+const ORDER_ACTIONS = [
+  { id: 'summarize', label: 'Summarize order' },
+  { id: 'draftReply', label: 'Draft customer reply' },
+  { id: 'extractIssues', label: 'Extract issues' },
+];
+
+export interface AssistantProps {
+  api: Api;
+  ctx: LaunchContext;
+}
+
+export function Assistant({ api, ctx }: AssistantProps): JSX.Element {
+  const [tab, setTab] = useState(ctx.resource === 'order' ? 1 : 0);
+  const [models, setModels] = useState<string[]>([]);
+  const [model, setModel] = useState('');
+
+  useEffect(() => {
+    api
+      .listModels()
+      .then((ids) => {
+        setModels(ids);
+        if (ids.length) setModel((m) => m || ids[0]);
+      })
+      .catch(() => setModels([]));
+  }, [api]);
+
+  const modelSelect =
+    models.length > 0 ? (
+      <Select
+        label="Model"
+        labelInline
+        options={models.map((id) => ({ label: id, value: id }))}
+        value={model}
+        onChange={setModel}
+      />
+    ) : null;
+
+  const tabs = [
+    { id: 'products', content: 'Products' },
+    { id: 'orders', content: 'Orders' },
+  ];
+
+  return (
+    <BlockStack gap="400">
+      <Tabs tabs={tabs} selected={tab} onSelect={setTab} />
+      <Box paddingInlineStart="400" paddingInlineEnd="400" paddingBlockEnd="400">
+        {tab === 0 ? (
+          <ProductPanel api={api} model={model} modelSelect={modelSelect} initialId={ctx.resource === 'product' ? ctx.resourceId : ''} />
+        ) : (
+          <OrderPanel api={api} model={model} modelSelect={modelSelect} initialId={ctx.resource === 'order' ? ctx.resourceId : ''} />
+        )}
+      </Box>
+    </BlockStack>
+  );
+}
+
+// ---- Product panel --------------------------------------------------------
+
+function ProductPanel(props: { api: Api; model: string; modelSelect: JSX.Element | null; initialId: string }): JSX.Element {
+  const { api, model, modelSelect, initialId } = props;
+  const [idInput, setIdInput] = useState(initialId);
+  const [product, setProduct] = useState<Product | null>(null);
+  const [output, setOutput] = useState('');
+  const [target, setTarget] = useState<'descriptionHtml' | 'seoTitle' | 'seoDescription'>('descriptionHtml');
+  const [busy, setBusy] = useState(false);
+  const [status, setStatus] = useState<{ tone: 'success' | 'critical' | 'info'; text: string } | null>(null);
+
+  const load = useCallback(async () => {
+    const gid = toGid('Product', idInput);
+    if (!gid) return;
+    setBusy(true);
+    setStatus(null);
+    try {
+      setProduct(await api.getProduct(gid));
+      setOutput('');
+    } catch (e: any) {
+      setStatus({ tone: 'critical', text: e?.message || 'Failed to load product' });
+      setProduct(null);
+    } finally {
+      setBusy(false);
+    }
+  }, [api, idInput]);
+
+  useEffect(() => {
+    if (initialId) void load();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [initialId]);
+
+  const run = useCallback(
+    async (actionId: string, writeTarget: 'descriptionHtml' | 'seoTitle' | 'seoDescription') => {
+      if (!product) return;
+      setBusy(true);
+      setStatus(null);
+      setTarget(writeTarget);
+      try {
+        setOutput(await api.runProductAction(product.id, actionId, model));
+      } catch (e: any) {
+        setStatus({ tone: 'critical', text: e?.message || 'Generation failed' });
+      } finally {
+        setBusy(false);
+      }
+    },
+    [api, product, model],
+  );
+
+  const writeBack = useCallback(async () => {
+    if (!product || !output) return;
+    setBusy(true);
+    setStatus(null);
+    try {
+      const w =
+        target === 'descriptionHtml'
+          ? { descriptionHtml: output }
+          : target === 'seoTitle'
+            ? { seoTitle: output.trim() }
+            : { seoDescription: output.trim() };
+      await api.updateProduct(product.id, w);
+      setStatus({ tone: 'success', text: `Saved to ${target === 'descriptionHtml' ? 'description' : target === 'seoTitle' ? 'SEO title' : 'SEO meta description'}.` });
+    } catch (e: any) {
+      setStatus({ tone: 'critical', text: e?.message || 'Save failed' });
+    } finally {
+      setBusy(false);
+    }
+  }, [api, product, output, target]);
+
+  return (
+    <BlockStack gap="400">
+      <Card>
+        <BlockStack gap="300">
+          <InlineStack gap="200" align="start" blockAlign="end">
+            <Box width="70%">
+              <TextField
+                label="Product ID or GID"
+                value={idInput}
+                onChange={setIdInput}
+                autoComplete="off"
+                placeholder="gid://shopify/Product/123 or 123"
+              />
+            </Box>
+            <Button onClick={() => void load()} loading={busy} variant="primary">
+              Load
+            </Button>
+          </InlineStack>
+          {product && (
+            <InlineStack gap="200" blockAlign="center">
+              <Text as="span" variant="headingSm">{product.title}</Text>
+              {product.status && <Badge>{product.status}</Badge>}
+            </InlineStack>
+          )}
+        </BlockStack>
+      </Card>
+
+      {product && (
+        <Card>
+          <BlockStack gap="300">
+            <InlineStack align="space-between" blockAlign="center">
+              <Text as="h3" variant="headingSm">Generate content</Text>
+              {modelSelect}
+            </InlineStack>
+            <ButtonGroup>
+              {PRODUCT_ACTIONS.map((a) => (
+                <Button key={a.id} onClick={() => void run(a.id, a.target)} disabled={busy}>
+                  {a.label}
+                </Button>
+              ))}
+            </ButtonGroup>
+          </BlockStack>
+        </Card>
+      )}
+
+      {status && <Banner tone={status.tone}>{status.text}</Banner>}
+
+      {output && (
+        <Card>
+          <BlockStack gap="300">
+            <TextField label="Generated content" value={output} onChange={setOutput} multiline={6} autoComplete="off" />
+            <InlineStack gap="200">
+              <Button onClick={() => void writeBack()} variant="primary" loading={busy}>
+                Save to product
+              </Button>
+            </InlineStack>
+          </BlockStack>
+        </Card>
+      )}
+    </BlockStack>
+  );
+}
+
+// ---- Order panel ----------------------------------------------------------
+
+function OrderPanel(props: { api: Api; model: string; modelSelect: JSX.Element | null; initialId: string }): JSX.Element {
+  const { api, model, modelSelect, initialId } = props;
+  const [idInput, setIdInput] = useState(initialId);
+  const [order, setOrder] = useState<Order | null>(null);
+  const [output, setOutput] = useState('');
+  const [busy, setBusy] = useState(false);
+  const [status, setStatus] = useState<{ tone: 'success' | 'critical' | 'info'; text: string } | null>(null);
+
+  const load = useCallback(async () => {
+    const gid = toGid('Order', idInput);
+    if (!gid) return;
+    setBusy(true);
+    setStatus(null);
+    try {
+      setOrder(await api.getOrder(gid));
+      setOutput('');
+    } catch (e: any) {
+      setStatus({ tone: 'critical', text: e?.message || 'Failed to load order' });
+      setOrder(null);
+    } finally {
+      setBusy(false);
+    }
+  }, [api, idInput]);
+
+  useEffect(() => {
+    if (initialId) void load();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [initialId]);
+
+  const run = useCallback(
+    async (actionId: string) => {
+      if (!order) return;
+      setBusy(true);
+      setStatus(null);
+      try {
+        setOutput(await api.runOrderAction(order.id, actionId, model));
+      } catch (e: any) {
+        setStatus({ tone: 'critical', text: e?.message || 'Generation failed' });
+      } finally {
+        setBusy(false);
+      }
+    },
+    [api, order, model],
+  );
+
+  return (
+    <BlockStack gap="400">
+      <Card>
+        <BlockStack gap="300">
+          <InlineStack gap="200" align="start" blockAlign="end">
+            <Box width="70%">
+              <TextField
+                label="Order ID or GID"
+                value={idInput}
+                onChange={setIdInput}
+                autoComplete="off"
+                placeholder="gid://shopify/Order/123 or 123"
+              />
+            </Box>
+            <Button onClick={() => void load()} loading={busy} variant="primary">
+              Load
+            </Button>
+          </InlineStack>
+          {order && (
+            <InlineStack gap="200" blockAlign="center">
+              <Text as="span" variant="headingSm">{order.name}</Text>
+              {order.financialStatus && <Badge>{order.financialStatus}</Badge>}
+              {order.fulfillmentStatus && <Badge>{order.fulfillmentStatus}</Badge>}
+            </InlineStack>
+          )}
+        </BlockStack>
+      </Card>
+
+      {order && (
+        <Card>
+          <BlockStack gap="300">
+            <InlineStack align="space-between" blockAlign="center">
+              <Text as="h3" variant="headingSm">Order actions</Text>
+              {modelSelect}
+            </InlineStack>
+            <ButtonGroup>
+              {ORDER_ACTIONS.map((a) => (
+                <Button key={a.id} onClick={() => void run(a.id)} disabled={busy}>
+                  {a.label}
+                </Button>
+              ))}
+            </ButtonGroup>
+          </BlockStack>
+        </Card>
+      )}
+
+      {status && <Banner tone={status.tone}>{status.text}</Banner>}
+
+      {output && (
+        <Card>
+          <TextField label="Result" value={output} onChange={setOutput} multiline={8} autoComplete="off" />
+        </Card>
+      )}
+    </BlockStack>
+  );
+}

package/src/app/api.ts

@@ -0,0 +1,126 @@
+// The admin panel's backend client — pure request shaping over the server proxy.
+// The frontend NEVER holds the Shopify secret or the Hanzo key: it calls the
+// server's /v1/* endpoints with its shop domain, and the server holds the token
+// and talks to Shopify + api.hanzo.ai. This module is pure over an injected
+// `fetch` (App Bridge's authenticated fetch in the app; a mock in tests), so the
+// request shaping is unit-testable without a browser.
+//
+// Every method returns typed data or throws with the server's error message, so
+// the React panel has ONE way to handle failure: try/catch on await.
+
+// A product as the panel consumes it (the server's parseProduct output).
+export interface Product {
+  id: string;
+  title: string;
+  handle: string;
+  descriptionHtml: string;
+  description: string;
+  productType: string;
+  vendor: string;
+  tags: string[];
+  status: string;
+  seoTitle: string;
+  seoDescription: string;
+}
+
+// An order as the panel consumes it (the server's parseOrder output).
+export interface Order {
+  id: string;
+  name: string;
+  note: string;
+  email: string;
+  financialStatus: string;
+  fulfillmentStatus: string;
+  createdAt: string;
+  totalAmount: string;
+  currency: string;
+  customerName: string;
+  shipTo: string;
+  lineItems: Array<{ title: string; quantity: number; sku: string }>;
+}
+
+// The fields a product write-back may carry. Only what is set is sent.
+export interface ProductWriteback {
+  descriptionHtml?: string;
+  seoTitle?: string;
+  seoDescription?: string;
+}
+
+export interface ApiOptions {
+  /** Backend base (the server behind hanzoai/ingress). '' means same-origin. */
+  baseUrl?: string;
+  /** The shop domain (from App Bridge host/shop). Sent on every call. */
+  shop: string;
+  /**
+   * The fetch to use. In the app this is App Bridge's authenticated fetch (adds
+   * the session-token Authorization header so the server can trust the shop).
+   * In tests, a mock. Defaults to global fetch.
+   */
+  fetch?: typeof fetch;
+}
+
+// asError turns a non-ok response body into a thrown Error carrying the server's
+// message. One place decodes the { error } envelope so every call fails the same
+// way.
+async function asError(resp: Response): Promise<never> {
+  let msg = `HTTP ${resp.status}`;
+  try {
+    const data: any = await resp.json();
+    if (data?.error) msg = String(data.error);
+  } catch {
+    /* non-JSON body — keep the status */
+  }
+  throw new Error(msg);
+}
+
+// createApi builds the panel's typed client bound to a shop + fetch. Every method
+// is a single request to the server proxy.
+export function createApi(opts: ApiOptions) {
+  const base = (opts.baseUrl ?? '').replace(/\/+$/, '');
+  const doFetch = opts.fetch ?? fetch;
+  const shop = opts.shop;
+
+  async function getJson(path: string, query: Record<string, string>): Promise<any> {
+    const q = new URLSearchParams({ shop, ...query }).toString();
+    const resp = await doFetch(`${base}${path}?${q}`);
+    if (!resp.ok) return asError(resp);
+    return resp.json();
+  }
+
+  async function postJson(path: string, body: Record<string, unknown>): Promise<any> {
+    const resp = await doFetch(`${base}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ shop, ...body }),
+    });
+    if (!resp.ok) return asError(resp);
+    return resp.json();
+  }
+
+  return {
+    getProduct(id: string): Promise<Product> {
+      return getJson('/v1/product', { id });
+    },
+    getOrder(id: string): Promise<Order> {
+      return getJson('/v1/order', { id });
+    },
+    async listModels(): Promise<string[]> {
+      const data = await getJson('/v1/models', {});
+      return Array.isArray(data?.models) ? data.models : [];
+    },
+    async runProductAction(id: string, action: string, model?: string): Promise<string> {
+      const data = await postJson('/v1/product/action', { id, action, model });
+      return String(data?.content ?? '');
+    },
+    async runOrderAction(id: string, action: string, model?: string): Promise<string> {
+      const data = await postJson('/v1/order/action', { id, action, model });
+      return String(data?.content ?? '');
+    },
+    async updateProduct(id: string, w: ProductWriteback): Promise<{ id: string; title: string }> {
+      const data = await postJson('/v1/product/update', { id, ...w });
+      return data?.product ?? { id, title: '' };
+    },
+  };
+}
+
+export type Api = ReturnType<typeof createApi>;

package/src/app/context.ts

@@ -0,0 +1,54 @@
+// Reading the embedded-app launch context — pure, browser-string-in / values-out,
+// so it is unit-testable without an iframe. Shopify launches the embedded admin
+// app inside an iframe with `shop`, `host`, and (from an admin block/action
+// extension on a product/order page) the resource `id` in the URL query. The
+// React panel reads this once at mount.
+
+// The launch context the panel needs. `shop` scopes every backend call; `host`
+// is App Bridge's base64 host param; `resource` + `resourceId` are set when the
+// app opened from a product or order page (an admin link/action), so the panel
+// can jump straight to that subject.
+export interface LaunchContext {
+  shop: string;
+  host: string;
+  resource: 'product' | 'order' | '';
+  resourceId: string;
+}
+
+// Shopify sometimes passes a bare numeric id and sometimes a GID
+// (gid://shopify/Product/123). toGid normalizes a value to a GID for a resource
+// kind — the Admin GraphQL API takes GIDs. A value already in gid:// form is
+// returned unchanged; a bare number is wrapped. Pure.
+export function toGid(kind: 'Product' | 'Order', id: string): string {
+  const v = id.trim();
+  if (!v) return '';
+  if (v.startsWith('gid://')) return v;
+  return `gid://shopify/${kind}/${v}`;
+}
+
+// resourceKind maps a `resource` query value to the GID kind, defaulting to ''
+// (no resource). Only 'product' and 'order' are surfaces this app acts on.
+function resourceOf(v: string | null): 'product' | 'order' | '' {
+  return v === 'product' || v === 'order' ? v : '';
+}
+
+// parseLaunchContext reads the iframe URL's query string into a LaunchContext.
+// A GID passed for the resource id is preserved; a bare id is normalized to a GID
+// for the named resource. Pure.
+export function parseLaunchContext(search: string): LaunchContext {
+  const q = new URLSearchParams(search);
+  const resource = resourceOf(q.get('resource'));
+  const rawId = q.get('id') ?? '';
+  const resourceId =
+    resource === 'product'
+      ? toGid('Product', rawId)
+      : resource === 'order'
+        ? toGid('Order', rawId)
+        : rawId;
+  return {
+    shop: q.get('shop') ?? '',
+    host: q.get('host') ?? '',
+    resource,
+    resourceId,
+  };
+}

package/src/app/index.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Hanzo AI for Shopify</title>
+  <!--
+    App Bridge is loaded from Shopify's CDN and MUST be the first script, with
+    the app's API key in a meta tag. Shopify requires this for an embedded admin
+    app so the iframe registers window.shopify (session tokens, navigation).
+    build.js stamps __SHOPIFY_API_KEY__ (public — the client id, never the secret)
+    and __ENTRY__ / __BASE__.
+  -->
+  <meta name="shopify-api-key" content="__SHOPIFY_API_KEY__" />
+  <script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="__ENTRY__"></script>
+</body>
+</html>

package/src/app/main.tsx

@@ -0,0 +1,51 @@
+// The embedded-app browser entry point — the one impure, browser-only module. It
+// reads the launch context, builds the App Bridge authenticated fetch, wires the
+// backend Api, and mounts the Polaris React app. Everything logic-heavy it uses
+// (context parsing, request shaping, session-token fetch) is a pure, tested
+// module; this file is the DOM glue.
+//
+// App Bridge (window.shopify) is loaded by the CDN script tag in index.html with
+// the app's api-key meta, per Shopify's embedded-app requirement. We read the
+// session token through it on every request (session-fetch) so the server can
+// trust which shop is calling.
+
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import '@shopify/polaris/build/esm/styles.css';
+import { App } from './App';
+import { createApi } from './api';
+import { parseLaunchContext } from './context';
+import { authenticatedFetch } from './session-fetch';
+
+// The App Bridge global the CDN script registers. idToken() returns a fresh
+// session-token JWT. Typed minimally — we use only idToken.
+declare global {
+  interface Window {
+    shopify?: { idToken(): Promise<string> };
+  }
+}
+
+// The backend base is stamped into the page as <meta name="hanzo:base"> at build
+// time (build.js). Empty means same-origin (the app and the API served together).
+function backendBase(): string {
+  const meta = document.querySelector('meta[name="hanzo:base"]');
+  return (meta?.getAttribute('content') ?? '').replace(/\/+$/, '');
+}
+
+function boot(): void {
+  const ctx = parseLaunchContext(window.location.search);
+  const getIdToken: () => Promise<string> = () =>
+    window.shopify ? window.shopify.idToken() : Promise.resolve('');
+  const fetchImpl = authenticatedFetch(fetch.bind(window), getIdToken);
+  const api = createApi({ baseUrl: backendBase(), shop: ctx.shop, fetch: fetchImpl });
+
+  const root = document.getElementById('root');
+  if (!root) throw new Error('missing #root');
+  createRoot(root).render(
+    <StrictMode>
+      <App api={api} ctx={ctx} />
+    </StrictMode>,
+  );
+}
+
+boot();

package/src/app/session-fetch.ts

@@ -0,0 +1,31 @@
+// App Bridge session-token fetch — pure and injectable so it is unit-testable
+// without App Bridge or a browser. Shopify's embedded-app auth model: App Bridge
+// (window.shopify) mints a short-lived session token (a signed JWT) via
+// `shopify.idToken()`; the frontend attaches it as `Authorization: Bearer <jwt>`
+// on every backend call, and the server verifies it (the shop identity is in the
+// token, so the server does not trust the shop query param blindly). This wraps a
+// base fetch to add that header, refreshing the token per request (tokens expire
+// in ~1 minute, so we never cache one).
+//
+// getIdToken is injected: in the app it is `() => window.shopify.idToken()`; in
+// tests it is a stub. That keeps this module free of any global and fully pure.
+
+export type IdTokenSource = () => Promise<string>;
+
+// authenticatedFetch returns a fetch that, before each request, fetches a fresh
+// session token and adds it as a Bearer header. It merges (does not clobber) any
+// caller headers. If token retrieval fails, the request still goes out without
+// the header — the server will reject it — so a token outage surfaces as a clean
+// 401 from the server rather than a thrown fetch here.
+export function authenticatedFetch(baseFetch: typeof fetch, getIdToken: IdTokenSource): typeof fetch {
+  return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const headers = new Headers(init?.headers);
+    try {
+      const token = await getIdToken();
+      if (token) headers.set('Authorization', `Bearer ${token}`);
+    } catch {
+      /* no token — let the server 401 */
+    }
+    return baseFetch(input, { ...init, headers });
+  };
+}