@hanzo/shopify 1.0.0

package/src/config.ts

@@ -0,0 +1,122 @@
+// Shopify config — the api.hanzo.ai model gateway (default model + endpoints),
+// the Shopify Admin API version + OAuth scopes, and the server-side secret set
+// (Shopify API key/secret + webhook HMAC). Endpoints and the bearer choice
+// mirror @hanzo/docusign and @hanzo/notion so the productivity suite stays DRY;
+// the commerce-specific pieces (product-context assembly, the AI actions) live
+// in hanzo.ts / actions.ts, not here.
+
+// ---- Hanzo model gateway --------------------------------------------------
+
+// Where the Hanzo model gateway lives. `@hanzo/ai` (createAiClient) defaults
+// here too. /v1 only, never an /api/ prefix (api.hanzo.ai IS the api host).
+export const HANZO_API_BASE_URL = 'https://api.hanzo.ai';
+
+// Default model. A Zen model (qwen3+). Overridable per-request via the picker;
+// the gateway routes it.
+export const DEFAULT_MODEL = 'zen5';
+
+// Public IAM origin that mints Hanzo user tokens, and the OAuth client id an
+// inbound Hanzo token is audienced to (owner-scoping validation via @hanzo/iam).
+export const DEFAULT_IAM_SERVER_URL = 'https://hanzo.id';
+export const DEFAULT_IAM_CLIENT_ID = 'hanzo-shopify';
+
+// chatCompletionsURL / modelsURL — the model gateway endpoints. The client
+// (createAiClient) builds these itself; these exist for tests + honest docs.
+export function chatCompletionsURL(): string {
+  return `${HANZO_API_BASE_URL}/v1/chat/completions`;
+}
+export function modelsURL(): string {
+  return `${HANZO_API_BASE_URL}/v1/models`;
+}
+
+// ---- Shopify Admin API ----------------------------------------------------
+//
+// Shopify Admin API is versioned by calendar quarter (YYYY-MM). We pin ONE
+// version and move it forward deliberately — never a speculative future one.
+// The GraphQL Admin API is the primary surface (productUpdate, product/order
+// reads); REST is legacy. Every call is against the per-shop host
+// `https://{shop}/admin/api/{version}/graphql.json`.
+export const ADMIN_API_VERSION = '2025-01';
+
+// The OAuth scopes the app requests. read/write products for content write-back,
+// read_orders for order insight + support drafting. No scope we do not use.
+export const OAUTH_SCOPES = ['read_products', 'write_products', 'read_orders'] as const;
+
+// Product description text budget. A product body_html plus its metafields and
+// variants can run long; this caps the characters of product context we attach
+// to any one request so it fits comfortably in a model window alongside the
+// reply. Honest truncation, never silent drop.
+export const PRODUCT_CHAR_BUDGET = 20_000;
+
+// A Shopify shop domain looks like `my-store.myshopify.com`. isShopDomain is the
+// boundary guard: OAuth install/callback and webhook handlers validate the shop
+// parameter against this before it is ever placed in a URL, so an attacker
+// cannot point the OAuth dance or an API call at an arbitrary host. Shopify's
+// rule: hostname ending in `.myshopify.com`, only [a-z0-9-] in the store slug.
+export function isShopDomain(shop: string | undefined | null): shop is string {
+  return typeof shop === 'string' && /^[a-z0-9][a-z0-9-]*\.myshopify\.com$/.test(shop);
+}
+
+// adminGraphqlUrl builds the GraphQL Admin API endpoint for a shop. Pure — the
+// request wrappers in shopify-api.ts take this string. Callers MUST have passed
+// `shop` through isShopDomain first (server.ts does).
+export function adminGraphqlUrl(shop: string, version: string = ADMIN_API_VERSION): string {
+  return `https://${shop}/admin/api/${version}/graphql.json`;
+}
+
+// ---- Server-side configuration (Shopify OAuth + webhook HMAC) --------------
+//
+// These are read from the environment by src/server/server.ts. They NEVER reach
+// the browser bundle: the API key (client id) is public, but the API secret is
+// server-only — it signs the OAuth exchange AND is the HMAC key Shopify uses to
+// sign both the OAuth callback and every webhook. readServerConfig throws on a
+// missing secret so a server that can neither complete OAuth nor verify a
+// webhook refuses to start.
+
+export interface ServerConfig {
+  /** Shopify API key / OAuth client id (public — appears in the authorize URL). */
+  shopifyApiKey: string;
+  /**
+   * Shopify API secret (SERVER ONLY). Two jobs: the OAuth token-exchange
+   * `client_secret`, AND the HMAC-SHA256 key for the OAuth callback signature
+   * and every webhook signature. One secret, both trust gates.
+   */
+  shopifyApiSecret: string;
+  /** OAuth redirect registered on the app (e.g. https://shopify.hanzo.ai/oauth/callback). */
+  shopifyRedirectUri: string;
+  /** The scopes string sent to /admin/oauth/authorize (space is not used — comma). */
+  scopes: string;
+  /**
+   * Hanzo API key the server uses to run AI on behalf of a shop when no user
+   * bearer is in the loop (the webhook path). Optional: without it the server
+   * still does OAuth + Admin API + verifies webhooks, but the webhook cannot
+   * run a model call (it logs and skips), which readServerConfig reports.
+   */
+  hanzoApiKey: string;
+  /** Listen port. */
+  port: number;
+}
+
+// readServerConfig fails fast (throws) if a required Shopify secret is missing.
+// hanzoApiKey is the one optional field (see above). Pure given an env map, so
+// it is unit-tested without touching process.env.
+export function readServerConfig(env: Record<string, string | undefined>): ServerConfig {
+  const shopifyApiKey = env.SHOPIFY_API_KEY;
+  const shopifyApiSecret = env.SHOPIFY_API_SECRET;
+  const shopifyRedirectUri = env.SHOPIFY_REDIRECT_URI;
+  const missing: string[] = [];
+  if (!shopifyApiKey) missing.push('SHOPIFY_API_KEY');
+  if (!shopifyApiSecret) missing.push('SHOPIFY_API_SECRET');
+  if (!shopifyRedirectUri) missing.push('SHOPIFY_REDIRECT_URI');
+  if (missing.length > 0) {
+    throw new Error(`Missing required environment: ${missing.join(', ')}`);
+  }
+  return {
+    shopifyApiKey: shopifyApiKey!,
+    shopifyApiSecret: shopifyApiSecret!,
+    shopifyRedirectUri: shopifyRedirectUri!,
+    scopes: env.SHOPIFY_SCOPES || OAUTH_SCOPES.join(','),
+    hanzoApiKey: env.HANZO_API_KEY || '',
+    port: Number(env.PORT) || 8791,
+  };
+}

package/src/server/actions.ts

@@ -0,0 +1,122 @@
+// The AI actions over a product or an order — each a prompt template applied to
+// the assembled context via the single `askProduct` / `askOrder` primitives in
+// hanzo.ts. There is exactly ONE code path to the model per subject: an action
+// is (id → prompt + subject), and the panel, the picker, and the webhook all
+// resolve an id here and call the matching ask. No action speaks to the gateway
+// directly.
+
+import { askOrder, askProduct, type AskOptions } from './hanzo.js';
+import type { ProductInfo, OrderInfo } from './shopify-api.js';
+
+// A product action's prompt is written to produce paste-ready content (a
+// description, an SEO title, a meta description). Prompts are specific and
+// output-shaped so results drop straight into the Shopify field.
+export const PRODUCT_ACTIONS = {
+  writeDescription: {
+    label: 'Write description',
+    prompt:
+      'Write a compelling product description for this product. 2–4 short ' +
+      'paragraphs (or a short intro plus a bullet list of key features/benefits). ' +
+      'Lead with the benefit, ground every claim in the product data above, and ' +
+      'match a confident, on-brand retail tone. Return only the description text, ' +
+      'ready to paste.',
+  },
+  rewriteDescription: {
+    label: 'Rewrite description',
+    prompt:
+      'Rewrite the current product description above to be clearer, more ' +
+      'persuasive, and better structured, WITHOUT adding any fact not present in ' +
+      'the product data. Keep it roughly the same length. Return only the rewritten ' +
+      'description, ready to paste.',
+  },
+  seoTitle: {
+    label: 'SEO title',
+    prompt:
+      'Write an SEO page title for this product: at most 60 characters, ' +
+      'front-loading the most important keyword, natural (not keyword-stuffed), and ' +
+      'accurate to the product. Return only the title text on a single line.',
+  },
+  seoDescription: {
+    label: 'SEO meta description',
+    prompt:
+      'Write an SEO meta description for this product: 140–160 characters, one or ' +
+      'two sentences, benefit-led, and accurate to the product data. Return only ' +
+      'the meta description text on a single line.',
+  },
+} as const;
+
+// An order action's prompt produces a summary, a customer reply, or an issue
+// extraction — the support/order-insight surface.
+export const ORDER_ACTIONS = {
+  summarize: {
+    label: 'Summarize order',
+    prompt:
+      'Summarize this order for a support agent at a glance: who ordered, what and ' +
+      'how much, the payment and fulfillment status, where it ships, and anything ' +
+      'notable in the note. Short bullets. No preamble.',
+  },
+  draftReply: {
+    label: 'Draft customer reply',
+    prompt:
+      'Draft a warm, professional reply to the customer about this order. Address ' +
+      'them by name if known, reference the order by its name/number, and speak ' +
+      'only to what the order data supports (status, items, shipping). Do not ' +
+      'promise dates, refunds, or policies that are not in the data. Return only ' +
+      'the email body, ready to send.',
+  },
+  extractIssues: {
+    label: 'Extract issues',
+    prompt:
+      'Read this order (especially the internal note) and extract any customer ' +
+      'issues, requests, or risks as a short prioritized list. For each: a one-line ' +
+      'description and a suggested next action. If nothing stands out, say so. Do ' +
+      'not invent issues that are not supported by the data.',
+  },
+} as const;
+
+// A product / order action id from the respective catalog.
+export type ProductActionId = keyof typeof PRODUCT_ACTIONS;
+export type OrderActionId = keyof typeof ORDER_ACTIONS;
+
+// isProductActionId / isOrderActionId narrow an arbitrary string to a known id.
+// Boundary guards — the panel and the server validate an inbound id here before
+// running it.
+export function isProductActionId(id: string): id is ProductActionId {
+  return Object.prototype.hasOwnProperty.call(PRODUCT_ACTIONS, id);
+}
+export function isOrderActionId(id: string): id is OrderActionId {
+  return Object.prototype.hasOwnProperty.call(ORDER_ACTIONS, id);
+}
+
+// productActionPrompt / orderActionPrompt resolve an id to its prompt. Each
+// throws on an unknown id (a boundary error surfaced to the caller) rather than
+// silently running a default.
+export function productActionPrompt(id: string): string {
+  if (!isProductActionId(id)) throw new Error(`Unknown product action: ${id}`);
+  return PRODUCT_ACTIONS[id].prompt;
+}
+export function orderActionPrompt(id: string): string {
+  if (!isOrderActionId(id)) throw new Error(`Unknown order action: ${id}`);
+  return ORDER_ACTIONS[id].prompt;
+}
+
+// productActionList / orderActionList are the ordered catalogs for building the
+// UI, derived from the action maps so the panel and the catalog can never drift.
+export function productActionList(): Array<{ id: ProductActionId; label: string }> {
+  return (Object.keys(PRODUCT_ACTIONS) as ProductActionId[]).map((id) => ({ id, label: PRODUCT_ACTIONS[id].label }));
+}
+export function orderActionList(): Array<{ id: OrderActionId; label: string }> {
+  return (Object.keys(ORDER_ACTIONS) as OrderActionId[]).map((id) => ({ id, label: ORDER_ACTIONS[id].label }));
+}
+
+// runProductAction / runOrderAction are the single entry points each surface
+// calls: resolve the action's prompt and run it over the assembled context via
+// the matching ask. One code path from an id to the model per subject. Async so
+// an unknown id surfaces as a rejected promise (not a synchronous throw), giving
+// callers ONE way to handle failure: await/.catch.
+export async function runProductAction(id: string, p: ProductInfo, opts: AskOptions = {}): Promise<string> {
+  return askProduct(productActionPrompt(id), p, opts);
+}
+export async function runOrderAction(id: string, o: OrderInfo, opts: AskOptions = {}): Promise<string> {
+  return askOrder(orderActionPrompt(id), o, opts);
+}

package/src/server/hanzo.ts

@@ -0,0 +1,222 @@
+// The Hanzo call and its request/response shaping over a PRODUCT or ORDER —
+// pure, host-agnostic, and fully unit-testable (no Shopify SDK, no DOM). The
+// Polaris panel and the webhook server are the thin glue that read a product/
+// order and hand it here.
+//
+// This is a THIN wrapper over the PUBLISHED headless client `@hanzo/ai`
+// (createAiClient) — we do NOT reimplement the transport. This module owns only
+// the commerce-aware layer: product/order context assembly + truncation + prompt
+// building, kept pure so it is tested and reused by both the panel backend and
+// the (browser-less) webhook. The AI actions (their prompt templates) live in
+// actions.ts, layered on `ask`.
+
+import { createAiClient, type AiClient } from '@hanzo/ai';
+import { DEFAULT_MODEL, HANZO_API_BASE_URL, PRODUCT_CHAR_BUDGET } from '../config.js';
+import type { ProductInfo, OrderInfo } from './shopify-api.js';
+
+// A message in the OpenAI-compatible schema — the shape @hanzo/ai's
+// chat.completions.create takes. Kept as a local alias so the prompt-assembly
+// functions (buildProductMessages/buildOrderMessages) have a precise, testable
+// return type independent of the SDK's broader union.
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+// SYSTEM_PROMPT grounds every answer in the store data provided. It forbids
+// inventing facts about the product or order (the failure mode that makes a
+// commerce assistant dangerous — fake specs, fake shipping promises), and keeps
+// output ready to paste into a Shopify field. Merchant-facing, brand-neutral.
+export const SYSTEM_PROMPT =
+  'You are Hanzo AI, an assistant for a Shopify merchant. You help write product ' +
+  'content (descriptions, SEO titles and meta descriptions) and handle orders and ' +
+  'support. Work ONLY from the product or order data provided below — never invent ' +
+  'specifications, materials, prices, dates, shipping promises, or policies that ' +
+  'are not supported by the data. Write in clear, natural, conversion-minded prose ' +
+  'for product content, and a warm, professional tone for customer replies. Return ' +
+  'only the requested content, ready to paste — no preamble, no meta commentary.';
+
+// ---- Product context assembly ---------------------------------------------
+//
+// A product's attributes are assembled into a compact, labeled block the model
+// reads as data (never as instructions). We include the existing description so
+// "rewrite" has the current copy to improve, and cap the whole block at the
+// budget — HTML descriptions can be long. Honest truncation, never silent drop.
+
+// The result of rendering a product down to what we attach: the text and whether
+// anything was truncated (so the prompt and UI can say so honestly).
+export interface ProductContext {
+  text: string;
+  truncated: boolean;
+}
+
+// stripHtml reduces an HTML description to readable text for the context block
+// (the model does not need the markup to understand the copy, and tags waste
+// budget). Minimal + total: drop tags, collapse whitespace. Pure.
+export function stripHtml(html: string): string {
+  return html
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// buildProductContext renders the product attributes into a labeled block,
+// capped at `budget` characters. The current description is the last (and
+// longest) field, so truncation trims it rather than the structured attributes
+// the model most needs. Pure and total. `truncated` is true whenever the render
+// was cut to fit.
+export function buildProductContext(p: ProductInfo, budget: number = PRODUCT_CHAR_BUDGET): ProductContext {
+  const lines: string[] = [];
+  lines.push(`Title: ${p.title}`);
+  if (p.productType) lines.push(`Type: ${p.productType}`);
+  if (p.vendor) lines.push(`Vendor: ${p.vendor}`);
+  if (p.tags.length) lines.push(`Tags: ${p.tags.join(', ')}`);
+  for (const o of p.options) {
+    if (o.name && o.values.length) lines.push(`Option ${o.name}: ${o.values.join(', ')}`);
+  }
+  if (p.variants.length) {
+    const vs = p.variants
+      .map((v) => [v.title, v.sku && `SKU ${v.sku}`, v.price && `$${v.price}`].filter(Boolean).join(' — '))
+      .join('; ');
+    lines.push(`Variants: ${vs}`);
+  }
+  if (p.seoTitle) lines.push(`Current SEO title: ${p.seoTitle}`);
+  if (p.seoDescription) lines.push(`Current SEO description: ${p.seoDescription}`);
+  const currentDesc = stripHtml(p.descriptionHtml || p.description);
+  if (currentDesc) lines.push(`Current description: ${currentDesc}`);
+
+  const full = lines.join('\n');
+  if (full.length <= budget) return { text: full, truncated: false };
+  return { text: full.slice(0, budget), truncated: true };
+}
+
+// ---- Order context assembly -----------------------------------------------
+
+export interface OrderContext {
+  text: string;
+  truncated: boolean;
+}
+
+// buildOrderContext renders an order into a labeled block. Orders are small; the
+// budget only bites on a huge line-item list or a long note, in which case we
+// truncate the tail honestly. Pure and total.
+export function buildOrderContext(o: OrderInfo, budget: number = PRODUCT_CHAR_BUDGET): OrderContext {
+  const lines: string[] = [];
+  lines.push(`Order: ${o.name}`);
+  if (o.createdAt) lines.push(`Placed: ${o.createdAt}`);
+  if (o.customerName) lines.push(`Customer: ${o.customerName}`);
+  if (o.email) lines.push(`Email: ${o.email}`);
+  if (o.financialStatus) lines.push(`Payment: ${o.financialStatus}`);
+  if (o.fulfillmentStatus) lines.push(`Fulfillment: ${o.fulfillmentStatus}`);
+  if (o.totalAmount) lines.push(`Total: ${o.totalAmount} ${o.currency}`.trim());
+  if (o.shipTo) lines.push(`Ship to: ${o.shipTo}`);
+  if (o.lineItems.length) {
+    const items = o.lineItems
+      .map((li) => `${li.quantity}× ${li.title}${li.sku ? ` (SKU ${li.sku})` : ''}`)
+      .join('; ');
+    lines.push(`Items: ${items}`);
+  }
+  if (o.note) lines.push(`Internal note: ${o.note}`);
+
+  const full = lines.join('\n');
+  if (full.length <= budget) return { text: full, truncated: false };
+  return { text: full.slice(0, budget), truncated: true };
+}
+
+// ---- Prompt assembly ------------------------------------------------------
+
+// contextNote is the one honest sentence prepended when the render was cut, so
+// the model does not answer as though it saw everything.
+function contextNote(truncated: boolean, kind: 'product' | 'order'): string {
+  return truncated
+    ? `Note: the ${kind} data below was truncated to fit — answer only from what is shown.`
+    : '';
+}
+
+// buildMessages fences the store data as DATA (never instructions) and rides the
+// honest note inside the user turn so it is never lost. Shared by product and
+// order paths — one assembly, one shape. Pure.
+export function buildMessages(task: string, contextText: string, note: string, fence: string): ChatMessage[] {
+  const system: ChatMessage = { role: 'system', content: SYSTEM_PROMPT };
+  const notePrefix = note ? `${note}\n\n` : '';
+  const user: ChatMessage = {
+    role: 'user',
+    content:
+      `${notePrefix}---- ${fence} ----\n${contextText}\n---- end ${fence} ----\n\n` +
+      `---- task ----\n${task}`,
+  };
+  return [system, user];
+}
+
+// buildProductMessages / buildOrderMessages are the two public assemblers the
+// actions + freeform ask use. Each windows its context and builds the message
+// list. Pure — the whole prompt is asserted in a test.
+export function buildProductMessages(task: string, p: ProductInfo): ChatMessage[] {
+  const ctx = buildProductContext(p);
+  return buildMessages(task, ctx.text, contextNote(ctx.truncated, 'product'), 'product');
+}
+
+export function buildOrderMessages(task: string, o: OrderInfo): ChatMessage[] {
+  const ctx = buildOrderContext(o);
+  return buildMessages(task, ctx.text, contextNote(ctx.truncated, 'order'), 'order');
+}
+
+// ---- The single call path -------------------------------------------------
+
+export interface AskOptions {
+  model?: string;
+  temperature?: number;
+  token?: string;
+  baseURL?: string;
+  /** Injected client (tests). Defaults to a real createAiClient. */
+  client?: AiClient;
+  signal?: AbortSignal;
+}
+
+// client resolves an AiClient: the injected one (tests) or a real published
+// @hanzo/ai client pointed at the gateway with the caller's bearer. One place
+// constructs it so the token/baseURL wiring is identical for every surface.
+function client(opts: AskOptions): AiClient {
+  return opts.client ?? createAiClient({ token: opts.token, baseUrl: opts.baseURL ?? HANZO_API_BASE_URL });
+}
+
+// runChat is the single path from a built message list to the model. Every
+// Shopify surface (the actions, a freeform question, the webhook auto-draft)
+// funnels here. Non-streaming: the panel renders the final text and the webhook
+// stores a finished draft. token may be empty (the gateway serves anonymous/
+// limited models).
+export async function runChat(messages: ChatMessage[], opts: AskOptions = {}): Promise<string> {
+  const res = await client(opts).chat.completions.create({
+    model: opts.model ?? DEFAULT_MODEL,
+    messages,
+    temperature: opts.temperature,
+    stream: false,
+  }, { signal: opts.signal });
+  const content = res.choices?.[0]?.message?.content;
+  if (typeof content !== 'string' || content === '') {
+    throw new Error('Hanzo API returned no content');
+  }
+  return content;
+}
+
+// askProduct / askOrder run ONE completion over a product/order with a freeform
+// task. The actions in actions.ts resolve their prompt and call these.
+export async function askProduct(task: string, p: ProductInfo, opts: AskOptions = {}): Promise<string> {
+  return runChat(buildProductMessages(task, p), opts);
+}
+
+export async function askOrder(task: string, o: OrderInfo, opts: AskOptions = {}): Promise<string> {
+  return runChat(buildOrderMessages(task, o), opts);
+}
+
+// listModels returns the model ids the caller may route to, from /v1/models via
+// the headless client. Org-scoped by the bearer; an empty token lists public
+// models.
+export async function listModels(opts: AskOptions = {}): Promise<string[]> {
+  const models = await client(opts).models.list({ signal: opts.signal });
+  return models.map((m) => m.id);
+}

package/src/server/oauth.ts

@@ -0,0 +1,165 @@
+// Shopify OAuth (Authorization Code Grant) — pure request shaping + the OAuth
+// callback HMAC verification. The API secret is held by the server (server.ts)
+// and never reaches the browser; these functions build the exact URL/body of
+// each OAuth call and verify Shopify's signature on the redirect, so the wire
+// shape and the trust gate are unit-testable without a network round-trip.
+//
+// Shopify's flow (shopify.dev/docs/apps/auth/oauth):
+//   1. redirect the merchant to https://{shop}/admin/oauth/authorize?…
+//   2. Shopify redirects back to our redirect_uri with ?code&hmac&shop&state&…
+//      — we VERIFY the `hmac` (HMAC-SHA256 over the sorted remaining params,
+//      hex) before trusting anything, then check `state` (CSRF).
+//   3. POST https://{shop}/admin/oauth/access_token with the code + secret to
+//      get the offline access token, stored server-side per shop.
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { isShopDomain } from '../config.js';
+
+// authorizeUrl is where the install flow sends the merchant's browser to grant
+// the app. `scope` is comma-joined (Shopify's convention, NOT space), `state`
+// is the CSRF nonce the server generates and re-checks on callback. Offline
+// access mode is the default (no `grant_options[]=per-user`), which is what a
+// background webhook needs — a long-lived token, not a per-user online one.
+export function authorizeUrl(args: {
+  shop: string;
+  apiKey: string;
+  scopes: string;
+  redirectUri: string;
+  state: string;
+}): string {
+  const q = new URLSearchParams({
+    client_id: args.apiKey,
+    scope: args.scopes,
+    redirect_uri: args.redirectUri,
+    state: args.state,
+  });
+  return `https://${args.shop}/admin/oauth/authorize?${q.toString()}`;
+}
+
+// A prepared token-exchange request: the pieces a single fetch needs. Pure
+// output so a test asserts the URL + JSON body without opening a socket. The
+// secret rides ONLY in the body, over TLS to Shopify's own host.
+export interface PreparedRequest {
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+}
+
+// tokenExchange builds the code→token request against the shop's
+// /admin/oauth/access_token. Shopify takes a JSON body of client_id +
+// client_secret + code and returns { access_token, scope }.
+export function tokenExchange(args: {
+  shop: string;
+  apiKey: string;
+  apiSecret: string;
+  code: string;
+}): PreparedRequest {
+  return {
+    url: `https://${args.shop}/admin/oauth/access_token`,
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: JSON.stringify({
+      client_id: args.apiKey,
+      client_secret: args.apiSecret,
+      code: args.code,
+    }),
+  };
+}
+
+// The token response we care about. Shopify returns access_token (the offline
+// token) + the granted scope. parseTokenResponse validates the one field we
+// must have and surfaces Shopify's own error otherwise.
+export interface ShopifyTokenSet {
+  access_token: string;
+  scope: string;
+}
+
+export function parseTokenResponse(data: any): ShopifyTokenSet {
+  if (!data || typeof data !== 'object') throw new Error('empty token response');
+  if (data.error || data.errors) {
+    const reason = data.error_description || data.error || JSON.stringify(data.errors);
+    throw new Error(`Shopify OAuth error: ${reason}`);
+  }
+  if (typeof data.access_token !== 'string' || data.access_token.length === 0) {
+    throw new Error('Shopify OAuth response missing access_token');
+  }
+  return { access_token: data.access_token, scope: String(data.scope ?? '') };
+}
+
+// ---- OAuth callback HMAC verification (the trust gate) --------------------
+//
+// Shopify signs the OAuth redirect: the `hmac` query param is
+// hex(HMAC-SHA256(apiSecret, message)), where `message` is the OTHER query
+// params (everything except `hmac` and the legacy `signature`) sorted by key
+// and joined `key=value&key=value` — with the ORIGINAL, still-URL-encoded
+// values. We must reconstruct that exact string. A callback that fails here is
+// discarded before any token exchange. Docs:
+// shopify.dev/docs/apps/auth/oauth/getting-started#step-4-confirm-installation
+
+// callbackMessage builds the signed message from a param map: drop hmac +
+// signature, sort the rest by key, then re-encode as an
+// application/x-www-form-urlencoded query string. This EXACTLY matches Shopify's
+// canonical form (stringifyQueryForAdmin → ProcessedQuery.stringify, which is a
+// URLSearchParams.toString()): keys/values are percent-encoded, spaces become
+// `+`. Building the raw `key=value` join instead would fail to validate any
+// callback whose values contain encodable characters (e.g. `host`, `state`), so
+// we mirror URLSearchParams here. `params` are the decoded values (as
+// URLSearchParams.forEach yields them); URLSearchParams re-encodes them the same
+// way Shopify did when it signed. Pure.
+export function callbackMessage(params: Record<string, string>): string {
+  const sorted = new URLSearchParams();
+  for (const key of Object.keys(params).filter((k) => k !== 'hmac' && k !== 'signature').sort()) {
+    sorted.append(key, params[key]);
+  }
+  return sorted.toString();
+}
+
+// computeCallbackHmac is hex(HMAC-SHA256(apiSecret, message)). Both verification
+// and any test fixture are built from it, so the value we compare is produced
+// exactly as Shopify produces it.
+export function computeCallbackHmac(apiSecret: string, message: string): string {
+  return createHmac('sha256', apiSecret).update(message, 'utf8').digest('hex');
+}
+
+// constantTimeEqualHex compares two hex digests without leaking length/position
+// via timing. Different-length inputs are unequal and short-circuit safely (we
+// never feed mismatched buffers to timingSafeEqual, which would throw).
+export function constantTimeEqualHex(a: string, b: string): boolean {
+  const ba = Buffer.from(a, 'hex');
+  const bb = Buffer.from(b, 'hex');
+  if (ba.length === 0 || ba.length !== bb.length) return false;
+  return timingSafeEqual(ba, bb);
+}
+
+// verifyCallbackHmac is the OAuth trust gate: reconstruct the signed message
+// from the callback params, recompute the hex HMAC with the app secret, and
+// constant-time compare against the provided `hmac` param. Returns false on any
+// missing input rather than throwing, so a malformed callback is a clean reject.
+export function verifyCallbackHmac(
+  apiSecret: string,
+  params: Record<string, string>,
+): boolean {
+  const provided = params.hmac;
+  if (!apiSecret || !provided) return false;
+  const expected = computeCallbackHmac(apiSecret, callbackMessage(params));
+  return constantTimeEqualHex(provided, expected);
+}
+
+// ---- Callback parameter validation ----------------------------------------
+
+// A validated OAuth callback: the shop, the code to exchange, and the state to
+// re-check. parseCallback pulls these from the query map AFTER the HMAC passed;
+// it re-validates the shop domain (defense in depth — never build a URL against
+// an unverified host) and throws on a missing code.
+export interface OAuthCallback {
+  shop: string;
+  code: string;
+  state: string;
+}
+
+export function parseCallback(params: Record<string, string>): OAuthCallback {
+  const shop = params.shop;
+  if (!isShopDomain(shop)) throw new Error('invalid or missing shop domain');
+  const code = params.code;
+  if (!code) throw new Error('missing code');
+  return { shop, code, state: params.state ?? '' };
+}