@jytextiles/medusa-plugin-faire-store-sync 0.2.6 → 0.2.8

package/src/admin/routes/settings/faire/{settings → @settings}/page.tsx

@@ -2,7 +2,9 @@ import {
   Button,
   Drawer,
   Heading,
+  Input,
   Label,
+  Select,
   Skeleton,
   StatusBadge,
   Switch,
@@ -18,6 +20,7 @@ import { useNavigate } from "react-router-dom"
 import { faireApi } from "../../../../lib/api"
 
 const STATUS_KEY = ["faire", "status"]
+const TAXONOMY_KEY = ["faire", "taxonomy"]
 const PARENT = "/settings/faire"
 
 // Radix Select can't use an empty-string item value, so "Not set" uses this
@@ -28,7 +31,6 @@ const cleanSettings = (form: any) => {
   const out: any = { ...form }
   for (const key of [
     "default_brand_id",
-    "default_shipping_policy_id",
     "default_category",
   ]) {
     if (!out[key] || out[key] === NONE) out[key] = null
@@ -53,7 +55,7 @@ type Status = {
     connected: boolean
     brand: boolean
     wholesale_pricing: boolean
-    shipping_policy: boolean
+    taxonomy: boolean
     ready_to_publish: boolean
   }
 }
@@ -80,6 +82,14 @@ const FaireSyncSettingsDrawer = () => {
   const status = statusQuery.data
   const connected = !!status?.connected
 
+  const taxonomyQuery = useQuery({
+    queryKey: TAXONOMY_KEY,
+    queryFn: async () =>
+      ((await faireApi.taxonomy().catch(() => ({ taxonomy: [] }))) as any)
+        .taxonomy || [],
+  })
+  const taxonomy = taxonomyQuery.data ?? []
+
   useEffect(() => {
     if (status?.settings) setForm(status.settings)
   }, [status?.settings])
@@ -127,7 +137,7 @@ const FaireSyncSettingsDrawer = () => {
                   <ChecklistItem ok={status?.readiness.connected} label="Faire connected" />
                   <ChecklistItem ok={status?.readiness.brand} label="Brand configured" />
                   <ChecklistItem ok={status?.readiness.wholesale_pricing} label="Wholesale pricing" />
-                  <ChecklistItem ok={status?.readiness.shipping_policy} label="Shipping policy" />
+                  <ChecklistItem ok={status?.readiness.taxonomy} label="Default category" />
                 </div>
               </div>
 
@@ -142,8 +152,7 @@ const FaireSyncSettingsDrawer = () => {
                 </div>
                 <div className="grid grid-cols-1 gap-4">
                   <Field label="Brand ID">
-                    <input
-                      className="border-ui-border-base rounded-lg border px-3 py-2 text-sm"
+                    <Input
                       value={String(form.default_brand_id ?? "")}
                       onChange={(e) =>
                         setForm({ ...form, default_brand_id: e.target.value || null })
@@ -154,9 +163,8 @@ const FaireSyncSettingsDrawer = () => {
                   </Field>
                   <Field label="Wholesale markup % (off retail)">
                     <Tooltip content="Wholesale price = retail × (100 − markup%) / 100. E.g. 50 → half of retail.">
-                      <input
+                      <Input
                         type="number"
-                        className="border-ui-border-base rounded-lg border px-3 py-2 text-sm"
                         value={String(form.default_wholesale_markup_percent ?? "")}
                         onChange={(e) =>
                           setForm({
@@ -172,9 +180,8 @@ const FaireSyncSettingsDrawer = () => {
                     </Tooltip>
                   </Field>
                   <Field label="Default min order quantity">
-                    <input
+                    <Input
                       type="number"
-                      className="border-ui-border-base rounded-lg border px-3 py-2 text-sm"
                       value={String(form.default_min_order_quantity ?? 1)}
                       onChange={(e) =>
                         setForm({
@@ -188,9 +195,8 @@ const FaireSyncSettingsDrawer = () => {
                     />
                   </Field>
                   <Field label="Default lead time (days)">
-                    <input
+                    <Input
                       type="number"
-                      className="border-ui-border-base rounded-lg border px-3 py-2 text-sm"
                       value={String(form.default_lead_time_days ?? "")}
                       onChange={(e) =>
                         setForm({
@@ -204,16 +210,17 @@ const FaireSyncSettingsDrawer = () => {
                       placeholder="e.g. 14"
                     />
                   </Field>
-                  <Field label="Default category">
-                    <input
-                      className="border-ui-border-base rounded-lg border px-3 py-2 text-sm"
-                      value={String(form.default_category ?? "")}
-                      onChange={(e) =>
-                        setForm({ ...form, default_category: e.target.value || null })
-                      }
-                      disabled={!connected}
-                      placeholder="e.g. Home Decor"
-                    />
+                  <Field label="Fallback category (taxonomy)">
+                    <Tooltip content="Faire requires a category per product. Resolution order: product metadata → the product's Type (matched by name) → this fallback. Set the product Type or pick a category on the product page for accuracy.">
+                      <SelectField
+                        value={String(form.default_category ?? "")}
+                        onValueChange={(v) =>
+                          setForm({ ...form, default_category: v || null })
+                        }
+                        disabled={!connected}
+                        options={taxonomy.map((t: any) => ({ value: t.id, label: t.name }))}
+                      />
+                    </Tooltip>
                   </Field>
                   <Field label="Follow product status">
                     <Tooltip content="If on, published Medusa products are published on Faire; draft products sync as drafts.">
@@ -265,6 +272,37 @@ const Field = ({ label, children }: { label: string; children: React.ReactNode }
   </div>
 )
 
+const SelectField = ({
+  value,
+  onValueChange,
+  options,
+  disabled,
+}: {
+  value: string
+  onValueChange: (v: string) => void
+  options: { value: string; label: string }[]
+  disabled?: boolean
+}) => (
+  <Select
+    value={value ? value : NONE}
+    onValueChange={(v) => onValueChange(v === NONE ? "" : v)}
+    disabled={disabled}
+    size="small"
+  >
+    <Select.Trigger>
+      <Select.Value placeholder="Not set" />
+    </Select.Trigger>
+    <Select.Content>
+      <Select.Item value={NONE}>Not set</Select.Item>
+      {options.map((o) => (
+        <Select.Item key={o.value} value={o.value}>
+          {o.label}
+        </Select.Item>
+      ))}
+    </Select.Content>
+  </Select>
+)
+
 const ChecklistItem = ({ ok, label }: { ok?: boolean; label: string }) => (
   <div
     className={clx(

package/src/admin/routes/settings/faire/page.tsx

@@ -27,7 +27,7 @@ import {
   useQueryClient,
 } from "@tanstack/react-query"
 import { useState } from "react"
-import { useNavigate } from "react-router-dom"
+import { Outlet, useNavigate } from "react-router-dom"
 import { faireApi } from "../../../lib/api"
 import { useFaireSyncColumns, FaireSyncRecord } from "./hooks/use-faire-sync-columns"
 
@@ -42,7 +42,7 @@ type Status = {
     connected: boolean
     brand: boolean
     wholesale_pricing: boolean
-    shipping_policy: boolean
+    taxonomy: boolean
     ready_to_publish: boolean
   }
 }
@@ -181,6 +181,9 @@ const FaireSettingsPage = () => {
             ))}
           </div>
         </Container>
+        {/* Nested @-routes (the @settings drawer) render here so they overlay
+            the list instead of replacing it. */}
+        <Outlet />
       </div>
     )
   }
@@ -334,6 +337,10 @@ const FaireSettingsPage = () => {
         </Drawer.Content>
       </Drawer>
 
+      {/* Nested routes (e.g. @settings drawer) render here so they overlay the
+          list instead of navigating away and blanking the page. */}
+      <Outlet />
+
       <Toaster />
     </div>
   )

package/src/admin/widgets/faire-product-widget.tsx

@@ -2,15 +2,24 @@ import { defineWidgetConfig } from "@medusajs/admin-sdk"
 import {
   Button,
   Container,
+  Drawer,
   Heading,
+  Input,
+  Label,
   Text,
   Alert,
+  Badge,
   StatusBadge,
   Tooltip,
+  clx,
+  toast,
 } from "@medusajs/ui"
 import { DetailWidgetProps, AdminProduct } from "@medusajs/framework/types"
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
-import { faireApi } from "../lib/api"
+import { useMemo, useState } from "react"
+import { faireApi, sdk } from "../lib/api"
+
+const MAX_RENDERED = 60
 
 const badgeColor = (status?: string): "green" | "red" | "orange" | "grey" => {
   switch (status) {
@@ -83,6 +92,72 @@ const FaireProductWidget = ({ data }: DetailWidgetProps<AdminProduct>) => {
 
   const notReady = connected && readiness && !readiness.ready_to_publish
 
+  // ── Faire category (taxonomy_type) picker ────────────────────────────────
+  // Faire requires a category per product. Sync resolves it in this order:
+  //   metadata.faire_taxonomy_type_id → metadata.faire_category →
+  //   product Type (by name) → account fallback. This panel pins an exact
+  //   `tt_…` id in metadata so the mapping is unambiguous.
+  const metadata: Record<string, any> = (data as any).metadata || {}
+  const productType: string | undefined = (data as any).type?.value
+
+  const [pickerOpen, setPickerOpen] = useState(false)
+  const [pickerSearch, setPickerSearch] = useState("")
+  // Local echo of the saved pin so the panel updates instantly (the parent
+  // product page's `data.metadata` only refreshes on its own refetch).
+  const [pinnedOverride, setPinnedOverride] = useState<string | null | undefined>(
+    undefined
+  )
+
+  const taxonomyQuery = useQuery({
+    queryKey: ["faire", "taxonomy"],
+    enabled: pickerOpen,
+    queryFn: async () => (await faireApi.taxonomy()).taxonomy ?? [],
+  })
+  const taxonomy = taxonomyQuery.data ?? []
+
+  const pinnedId: string | undefined =
+    pinnedOverride !== undefined
+      ? pinnedOverride ?? undefined
+      : metadata.faire_taxonomy_type_id
+  const pinnedName = useMemo(() => {
+    if (!pinnedId) return undefined
+    if (!/^tt_/.test(String(pinnedId))) return String(pinnedId)
+    return taxonomy.find((t: any) => t.id === pinnedId)?.name
+  }, [pinnedId, taxonomy])
+
+  // What the sync will actually use as the category source, for display.
+  const resolvedSource = pinnedId
+    ? { label: pinnedName || String(pinnedId), from: "pinned" as const }
+    : metadata.faire_category
+      ? { label: String(metadata.faire_category), from: "metadata" as const }
+      : productType
+        ? { label: productType, from: "type" as const }
+        : { label: "Account fallback", from: "fallback" as const }
+
+  const filteredTaxonomy = useMemo(() => {
+    const q = pickerSearch.trim().toLowerCase()
+    const list = q
+      ? taxonomy.filter((t: any) => t.name.toLowerCase().includes(q))
+      : taxonomy
+    return list.slice(0, MAX_RENDERED)
+  }, [taxonomy, pickerSearch])
+
+  const saveCategory = useMutation({
+    mutationFn: (value: string | null) =>
+      sdk.admin.product.update(data.id, {
+        metadata: { ...metadata, faire_taxonomy_type_id: value },
+      }),
+    onSuccess: (_res, value) => {
+      setPinnedOverride(value)
+      queryClient.invalidateQueries({ queryKey: ["product", data.id] })
+      setPickerOpen(false)
+      setPickerSearch("")
+      toast.success(value ? "Faire category set" : "Faire category cleared")
+    },
+    onError: (err: any) =>
+      toast.error("Failed to save category", { description: err?.message }),
+  })
+
   return (
     <Container className="divide-y p-0">
       <div className="flex items-center justify-between px-6 py-4">
@@ -150,6 +225,37 @@ const FaireProductWidget = ({ data }: DetailWidgetProps<AdminProduct>) => {
           </Alert>
         )}
 
+        {/* Faire category (taxonomy_type) */}
+        <div className="flex items-center justify-between gap-3 rounded-lg border px-3 py-2">
+          <div className="flex flex-col gap-0.5">
+            <div className="flex items-center gap-2">
+              <Text size="small" weight="plus">
+                Faire category
+              </Text>
+              <Badge size="2xsmall" color={resolvedSource.from === "fallback" ? "orange" : "grey"}>
+                {resolvedSource.from === "pinned"
+                  ? "Pinned"
+                  : resolvedSource.from === "type"
+                    ? "From Type"
+                    : resolvedSource.from === "metadata"
+                      ? "Metadata"
+                      : "Fallback"}
+              </Badge>
+            </div>
+            <Text size="small" className="text-ui-fg-subtle">
+              {resolvedSource.label}
+            </Text>
+          </div>
+          <Button
+            size="small"
+            variant="secondary"
+            disabled={!connected}
+            onClick={() => setPickerOpen(true)}
+          >
+            {pinnedId ? "Change" : "Set category"}
+          </Button>
+        </div>
+
         <div className="flex items-center gap-3">
           <Tooltip
             content={
@@ -169,6 +275,81 @@ const FaireProductWidget = ({ data }: DetailWidgetProps<AdminProduct>) => {
           </Tooltip>
         </div>
       </div>
+
+      {/* Category picker — searchable list from Faire's taxonomy API. */}
+      <Drawer open={pickerOpen} onOpenChange={setPickerOpen}>
+        <Drawer.Content>
+          <Drawer.Header>
+            <Drawer.Title>Pick a Faire category</Drawer.Title>
+            <Drawer.Description>
+              Search Faire's product taxonomy and pin an exact category to this
+              product.
+            </Drawer.Description>
+          </Drawer.Header>
+          <Drawer.Body className="flex flex-col gap-3 overflow-hidden">
+            <Input
+              type="search"
+              autoFocus
+              placeholder="Search categories…"
+              value={pickerSearch}
+              onChange={(e) => setPickerSearch(e.target.value)}
+            />
+            <div className="flex flex-col gap-1 overflow-y-auto">
+              {taxonomyQuery.isLoading ? (
+                <Text size="small" className="text-ui-fg-subtle px-1 py-2">
+                  Loading categories…
+                </Text>
+              ) : filteredTaxonomy.length === 0 ? (
+                <Text size="small" className="text-ui-fg-subtle px-1 py-2">
+                  No categories match “{pickerSearch}”.
+                </Text>
+              ) : (
+                filteredTaxonomy.map((t: any) => (
+                  <button
+                    key={t.id}
+                    type="button"
+                    onClick={() => saveCategory.mutate(t.id)}
+                    disabled={saveCategory.isPending}
+                    className={clx(
+                      "flex items-center justify-between rounded-md px-3 py-2 text-left text-sm",
+                      "hover:bg-ui-bg-base-hover",
+                      t.id === pinnedId && "bg-ui-bg-highlight"
+                    )}
+                  >
+                    <span>{t.name}</span>
+                    {t.id === pinnedId && (
+                      <Badge size="2xsmall" color="green">
+                        Current
+                      </Badge>
+                    )}
+                  </button>
+                ))
+              )}
+              {!taxonomyQuery.isLoading &&
+                taxonomy.length > filteredTaxonomy.length && (
+                  <Text size="xsmall" className="text-ui-fg-muted px-1 py-1">
+                    Showing {filteredTaxonomy.length} of {taxonomy.length} — refine
+                    your search to narrow down.
+                  </Text>
+                )}
+            </div>
+          </Drawer.Body>
+          <Drawer.Footer>
+            {pinnedId && (
+              <Button
+                variant="secondary"
+                onClick={() => saveCategory.mutate(null)}
+                isLoading={saveCategory.isPending}
+              >
+                Clear
+              </Button>
+            )}
+            <Drawer.Close asChild>
+              <Button variant="secondary">Cancel</Button>
+            </Drawer.Close>
+          </Drawer.Footer>
+        </Drawer.Content>
+      </Drawer>
     </Container>
   )
 }

package/src/api/admin/faire/status/route.ts

@@ -13,7 +13,7 @@ export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
   const hasMarkup =
     settings.default_wholesale_markup_percent != null &&
     settings.default_wholesale_markup_percent > 0
-  const hasShipping = !!settings.default_shipping_policy_id
+  const hasTaxonomy = !!settings.default_category
 
   res.json({
     connected,
@@ -40,8 +40,8 @@ export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
       connected,
       brand: hasBrand,
       wholesale_pricing: hasMarkup,
-      shipping_policy: hasShipping,
-      ready_to_publish: connected && hasBrand,
+      taxonomy: hasTaxonomy,
+      ready_to_publish: connected && hasBrand && hasTaxonomy,
     },
   })
 }

package/src/api/admin/faire/taxonomy/route.ts

@@ -0,0 +1,10 @@
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { FAIRE_SYNC_MODULE } from "../../../../modules/faire-sync"
+import FaireSyncService from "../../../../modules/faire-sync/service"
+
+// GET /admin/faire/taxonomy — taxonomy types from Faire's /products/types
+export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
+  const service: FaireSyncService = req.scope.resolve(FAIRE_SYNC_MODULE)
+  const types = await service.getTaxonomyTypes()
+  res.json({ taxonomy: types })
+}

package/src/lib/faire-client.ts

@@ -478,6 +478,33 @@ export class FaireClient {
    * 2026-07-09; the `limit` param is ignored). Cached per client.
    */
   private taxonomyTypesCache: Array<{ id: string; name: string }> | null = null
+  /**
+   * Fetch the full taxonomy types list from Faire (cached per client instance).
+   * Returns `[{ id, name }, …]` sorted by name or `[]` on error.
+   */
+  async getTaxonomyTypes(
+    accessToken: string
+  ): Promise<Array<{ id: string; name: string }>> {
+    if (!this.taxonomyTypesCache) {
+      try {
+        const data = await this.requestJson<any>(
+          `${this.apiBase}/products/types`,
+          { method: "GET", accessToken }
+        )
+        this.taxonomyTypesCache = (
+          data.taxonomy_types ??
+          data.product_types ??
+          data.types ??
+          data.results ??
+          []
+        ).map((t: any) => ({ id: String(t.id), name: String(t.name ?? "") }))
+      } catch {
+        this.taxonomyTypesCache = []
+      }
+    }
+    return this.taxonomyTypesCache ?? []
+  }
+
   async resolveTaxonomyTypeId(
     accessToken: string,
     nameOrId: string

package/src/modules/faire-sync/service.ts

@@ -253,6 +253,13 @@ class FaireSyncService extends MedusaService({
     return this.updateFaireSyncSettings({ id: settings.id, ...data } as any)
   }
 
+  async getTaxonomyTypes(): Promise<Array<{ id: string; name: string }>> {
+    const account = await this.getActiveAccount()
+    if (!account) return []
+    const client = this.getClient(account.auth_mode as "oauth" | "apiKey")
+    return client.getTaxonomyTypes(account.access_token)
+  }
+
   /**
    * High-water mark for incremental order polling. Returns the last successful
    * sync timestamp, or null if orders have never been polled (full backfill).

package/src/workflows/sync-product-to-faire.ts

@@ -6,7 +6,7 @@ import {
   WorkflowData,
   transform,
 } from "@medusajs/framework/workflows-sdk"
-import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
+import { ContainerRegistrationKeys, MedusaError, Modules } from "@medusajs/framework/utils"
 import type { Link } from "@medusajs/modules-sdk"
 import type { RemoteQueryFunction } from "@medusajs/types"
 import { FAIRE_SYNC_MODULE } from "../modules/faire-sync"
@@ -131,6 +131,7 @@ const prepareProductStep = createStep(
         "description",
         "status",
         "metadata",
+        "type.value",
         "tags.*",
         "variants.*",
         "variants.prices.*",
@@ -145,7 +146,10 @@ const prepareProductStep = createStep(
 
     const product: any = products?.[0]
     if (!product) {
-      throw new Error(`Product ${input.product_id} not found`)
+      throw new MedusaError(
+        MedusaError.Types.NOT_FOUND,
+        `Product ${input.product_id} not found`
+      )
     }
 
     // Resolve existing Faire product (from link)
@@ -235,11 +239,16 @@ const prepareProductStep = createStep(
 
     // Resolve taxonomy_type.id — REQUIRED by Faire create. Priority:
     //   product.metadata.faire_taxonomy_type_id (tt_… or a category name)
+    //   → product.metadata.faire_category (name)
+    //   → product.type.value (the native Medusa Product Type, matched by name)
     //   → settings.default_category (id or name) → error.
+    // Product Type is the natural per-product carrier; the product widget lets an
+    // operator pin an exact `tt_…` id in metadata when the type name is ambiguous.
     const client = service.getClient(input.auth_mode)
     const categoryHint =
       metadata.faire_taxonomy_type_id ||
       metadata.faire_category ||
+      product.type?.value ||
       settings.default_category ||
       ""
     const taxonomyTypeId = await client.resolveTaxonomyTypeId(
@@ -247,10 +256,11 @@ const prepareProductStep = createStep(
       String(categoryHint)
     )
     if (!taxonomyTypeId) {
-      throw new Error(
-        "Faire requires a product category (taxonomy_type). Set a Faire " +
-          "category in sync settings (default_category) or on the product " +
-          "(metadata.faire_taxonomy_type_id — a `tt_…` id or a category name)."
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        "Faire requires a product category (taxonomy_type). Set the product's " +
+          "Type to a Faire category name, pick one from the Faire panel on the " +
+          "product page, or set a fallback category in Faire sync settings."
       )
     }