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

package/src/admin/routes/settings/faire/[id]/page.tsx

@@ -1,6 +1,5 @@
 import {
   Button,
-  Container,
   DropdownMenu,
   Heading,
   IconButton,
@@ -14,8 +13,11 @@ import { EllipsisHorizontal, ArrowPath, ArrowUpRightOnBox } from "@medusajs/icon
 import { useEffect, useState } from "react"
 import { useNavigate, useParams } from "react-router-dom"
 import { faireApi } from "../../../../lib/api"
+import { RouteFocusModal } from "../../../../components/route-focus-modal"
 import type { FaireSyncRecord } from "../hooks/use-faire-sync-columns"
 
+const PARENT = "/settings/faire"
+
 const STATUS_COLORS: Record<string, "green" | "red" | "orange" | "grey"> = {
   success: "green",
   failed: "red",
@@ -59,47 +61,23 @@ const FaireSyncDetailPage = () => {
     }
   }
 
-  if (loading) {
-    return (
-      <Container className="p-6">
-        <Skeleton className="h-7 w-12 rounded-md" />
-      </Container>
-    )
-  }
-
-  if (!record) {
-    return (
-      <Container className="p-6 flex flex-col gap-4">
-        <Heading level="h1">Sync record not found</Heading>
-        <Button size="small" variant="secondary" onClick={() => navigate("/settings/faire")}>
-          Back to Faire settings
-        </Button>
-      </Container>
-    )
-  }
-
-  const warnings: string[] = record.error_message
+  const warnings: string[] = record?.error_message
     ? record.error_message.split(" | ")
     : []
 
   return (
-    <div className="flex flex-col gap-4">
-      {error && (
-        <Container className="p-4">
-          <Text className="text-ui-tag-red-text">{error}</Text>
-        </Container>
-      )}
-
-      <Container className="divide-y p-0">
-        <div className="flex items-center justify-between px-6 py-4">
-          <div className="flex flex-col gap-1">
-            <Heading level="h1">Sync record</Heading>
-            <Text className="text-ui-fg-subtle font-mono text-xs">{record.id}</Text>
-          </div>
-          <div className="flex items-center gap-3">
+    <RouteFocusModal prev={PARENT}>
+      <RouteFocusModal.Header>
+        <div className="flex items-center gap-3">
+          <Heading level="h1">Sync record</Heading>
+          {record && (
             <StatusBadge color={STATUS_COLORS[record.status] || "grey"}>
               {record.status}
             </StatusBadge>
+          )}
+        </div>
+        {record && (
+          <div className="flex items-center gap-2">
             <DropdownMenu>
               <DropdownMenu.Trigger asChild>
                 <IconButton size="small" variant="transparent" disabled={retrying}>
@@ -127,38 +105,55 @@ const FaireSyncDetailPage = () => {
               </DropdownMenu.Content>
             </DropdownMenu>
           </div>
-        </div>
+        )}
+      </RouteFocusModal.Header>
 
-        <div className="px-6 py-4 grid grid-cols-2 gap-4">
-          <Detail label="Product" value={record.product_id} mono />
-          <Detail label="Action" value={record.action} />
-          <Detail label="Faire product token" value={record.product_token || "—"} mono />
-          <Detail label="State" value={record.product_state || "—"} />
-          <Detail label="Published" value={record.published ? "Yes" : "No"} />
-          <Detail
-            label="Synced at"
-            value={record.synced_at ? new Date(record.synced_at).toLocaleString() : "—"}
-          />
-        </div>
-      </Container>
+      <RouteFocusModal.Body className="flex flex-col gap-4 overflow-y-auto p-6">
+        {error && <Text className="text-ui-tag-red-text">{error}</Text>}
 
-      {warnings.length > 0 && (
-        <Container className="divide-y p-0">
-          <div className="px-6 py-4">
-            <Heading level="h2">Issues</Heading>
-          </div>
-          <div className="px-6 py-4 flex flex-col gap-2">
-            {warnings.map((w, i) => (
-              <Text key={i} className="text-ui-tag-red-text text-sm">
-                {w}
-              </Text>
+        {loading ? (
+          <div className="flex flex-col gap-3">
+            {Array.from({ length: 4 }).map((_, i) => (
+              <Skeleton key={i} className="h-10 w-full" />
             ))}
           </div>
-        </Container>
-      )}
+        ) : !record ? (
+          <div className="flex flex-col items-start gap-4">
+            <Heading level="h2">Sync record not found</Heading>
+            <Button size="small" variant="secondary" onClick={() => navigate(PARENT)}>
+              Back to Faire settings
+            </Button>
+          </div>
+        ) : (
+          <>
+            <div className="border-ui-border-base grid grid-cols-2 gap-4 rounded-lg border p-4">
+              <Detail label="Record id" value={record.id} mono />
+              <Detail label="Product" value={record.product_id} mono />
+              <Detail label="Action" value={record.action} />
+              <Detail label="Faire product token" value={record.product_token || "—"} mono />
+              <Detail label="State" value={record.product_state || "—"} />
+              <Detail label="Published" value={record.published ? "Yes" : "No"} />
+              <Detail
+                label="Synced at"
+                value={record.synced_at ? new Date(record.synced_at).toLocaleString() : "—"}
+              />
+            </div>
 
+            {warnings.length > 0 && (
+              <div className="border-ui-border-base flex flex-col gap-2 rounded-lg border p-4">
+                <Heading level="h2">Issues</Heading>
+                {warnings.map((w, i) => (
+                  <Text key={i} className="text-ui-tag-red-text text-sm">
+                    {w}
+                  </Text>
+                ))}
+              </div>
+            )}
+          </>
+        )}
+      </RouteFocusModal.Body>
       <Toaster />
-    </div>
+    </RouteFocusModal>
   )
 }
 

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

@@ -1,5 +1,5 @@
 import { defineRouteConfig } from "@medusajs/admin-sdk"
-import { BuildingStorefront } from "@medusajs/icons"
+import { BuildingStorefront, ChevronDownMini } from "@medusajs/icons"
 import {
   Alert,
   Button,
@@ -7,7 +7,10 @@ import {
   DataTable,
   DataTableFilteringState,
   DataTablePaginationState,
+  Drawer,
+  DropdownMenu,
   Heading,
+  Input,
   Label,
   Skeleton,
   StatusBadge,
@@ -53,6 +56,8 @@ const FaireSettingsPage = () => {
     pageSize: PAGE_SIZE,
   })
   const [filtering, setFiltering] = useState<DataTableFilteringState>({})
+  const [apiKeyOpen, setApiKeyOpen] = useState(false)
+  const [apiKey, setApiKey] = useState("")
 
   // ── Queries ───────────────────────────────────────────────────────────────
   const statusQuery = useQuery({
@@ -91,6 +96,20 @@ const FaireSettingsPage = () => {
       }),
   })
 
+  const apiKeyMutation = useMutation({
+    mutationFn: () => faireApi.connectApiKey(apiKey.trim()),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: STATUS_KEY })
+      setApiKeyOpen(false)
+      setApiKey("")
+      toast.success("Connected to Faire with API key")
+    },
+    onError: (err: any) =>
+      toast.error("Failed to connect with API key", {
+        description: err.message,
+      }),
+  })
+
   const disconnectMutation = useMutation({
     mutationFn: () => faireApi.disconnect(),
     onSuccess: () => {
@@ -211,13 +230,22 @@ const FaireSettingsPage = () => {
               </Button>
             </div>
           ) : (
-            <Button
-              size="small"
-              onClick={() => connectMutation.mutate()}
-              isLoading={connectMutation.isPending}
-            >
-              Connect Faire
-            </Button>
+            <DropdownMenu>
+              <DropdownMenu.Trigger asChild>
+                <Button size="small" isLoading={connectMutation.isPending}>
+                  Connect Faire
+                  <ChevronDownMini />
+                </Button>
+              </DropdownMenu.Trigger>
+              <DropdownMenu.Content>
+                <DropdownMenu.Item onClick={() => connectMutation.mutate()}>
+                  Connect with OAuth
+                </DropdownMenu.Item>
+                <DropdownMenu.Item onClick={() => setApiKeyOpen(true)}>
+                  Connect with API key (private)
+                </DropdownMenu.Item>
+              </DropdownMenu.Content>
+            </DropdownMenu>
           )}
         </div>
         {connected && status?.account && (
@@ -264,6 +292,48 @@ const FaireSettingsPage = () => {
         </DataTable>
       </Container>
 
+      {/* API-key connect (private integrations) */}
+      <Drawer open={apiKeyOpen} onOpenChange={setApiKeyOpen}>
+        <Drawer.Content>
+          <Drawer.Header>
+            <Drawer.Title>Connect with API key</Drawer.Title>
+          </Drawer.Header>
+          <Drawer.Body className="flex flex-col gap-y-3">
+            <Text className="text-ui-fg-subtle" size="small">
+              For private / unpublished Faire integrations, paste the API key
+              your Faire brand issued for this app. This connects without OAuth.
+            </Text>
+            <div className="flex flex-col gap-y-1">
+              <Label size="small">Faire API key</Label>
+              <Input
+                type="password"
+                placeholder="Paste the Faire API key…"
+                value={apiKey}
+                onChange={(e) => setApiKey(e.target.value)}
+                autoComplete="off"
+              />
+            </div>
+          </Drawer.Body>
+          <Drawer.Footer>
+            <Button
+              variant="secondary"
+              size="small"
+              onClick={() => setApiKeyOpen(false)}
+            >
+              Cancel
+            </Button>
+            <Button
+              size="small"
+              onClick={() => apiKeyMutation.mutate()}
+              isLoading={apiKeyMutation.isPending}
+              disabled={!apiKey.trim()}
+            >
+              Connect
+            </Button>
+          </Drawer.Footer>
+        </Drawer.Content>
+      </Drawer>
+
       <Toaster />
     </div>
   )

package/src/lib/faire-client.ts

@@ -81,12 +81,25 @@ export class FaireClient {
 
   // ── OAuth ───────────────────────────────────────────────────────────────
 
+  /**
+   * Normalise the configured scope into a list of individual scope tokens.
+   *
+   * `FAIRE_SCOPE` may be authored comma- OR space-separated (e.g.
+   * "READ_PRODUCTS WRITE_PRODUCTS" or "READ_PRODUCTS,WRITE_PRODUCTS"); split on
+   * either so each Faire scope enum is a distinct element. Passing the whole
+   * joined string as a single value makes Faire's authorize reject it with
+   * `scope.contains(null)` (it comma-splits, sees one unknown enum → null).
+   */
+  private scopeList(): string[] {
+    return this.scope ? this.scope.split(/[\s,]+/).filter(Boolean) : []
+  }
+
   /**
    * Build the Faire OAuth authorize URL.
    *
    * Faire's authorize endpoint takes `applicationId` (NOT client_id),
-   * `redirectUrl` (NOT redirect_uri) and a space-joined `scope`. `state` is
-   * round-tripped for CSRF protection.
+   * `redirectUrl` (NOT redirect_uri) and a COMMA-joined `scope` (Faire splits
+   * the scope param on commas). `state` is round-tripped for CSRF protection.
    */
   getAuthorizationUrl(state: string): string {
     const params = new URLSearchParams({
@@ -94,7 +107,8 @@ export class FaireClient {
       redirectUrl: this.redirectUri,
       state,
     })
-    if (this.scope) params.set("scope", this.scope)
+    const scopes = this.scopeList()
+    if (scopes.length) params.set("scope", scopes.join(","))
     return `${this.authUrl}?${params.toString()}`
   }
 
@@ -113,7 +127,7 @@ export class FaireClient {
       authorization_code: code,
       grant_type: "AUTHORIZATION_CODE",
       redirect_url: this.redirectUri,
-      scope: this.scope ? this.scope.split(/\s+/) : [],
+      scope: this.scopeList(),
     }
     const data = await this.requestJson<any>(this.tokenUrl, {
       method: "POST",
@@ -275,10 +289,15 @@ export class FaireClient {
     const results = (data.products ?? data.results ?? []).map((p: any) =>
       this.mapProduct(p)
     )
+    // Numeric 1-indexed `page`, no `next_page` cursor (see listOrders).
+    const limit = opts.limit ?? 100
+    const currentPage = Number(opts.page ?? data.page ?? 1)
+    const next_page =
+      results.length >= limit ? String(currentPage + 1) : undefined
     return {
       count: data.count ?? results.length,
       results,
-      next_page: data.next_page ?? data.pagination?.next_page,
+      next_page,
     }
   }
 
@@ -287,10 +306,11 @@ export class FaireClient {
   /**
    * Push inventory overrides to Faire by SKU.
    *
-   * Faire does NOT expose a `GET /inventory` you can poll for remote counts —
-   * inventory is write-only: `PATCH /product-inventory/by-skus` with an array
-   * of `{ sku, current_count }` rows. (A `by-product-variant-ids` variant
-   * exists for id-keyed overrides.)
+   * Inventory push is write-only: `PATCH /product-inventory/by-skus` with an
+   * array under `inventories`, each row `{ sku, on_hand_quantity }` (verified
+   * live 2026-07-09 — the writable field is `on_hand_quantity`, NOT
+   * `current_count`/`available_quantity`). A `by-product-variant-ids` variant
+   * exists for id-keyed overrides.
    */
   async updateInventory(
     accessToken: string,
@@ -332,10 +352,17 @@ export class FaireClient {
     const results = (data.orders ?? data.results ?? []).map((o: any) =>
       this.mapOrder(o)
     )
+    // Faire v2 paginates by a numeric 1-indexed `page` and returns NO
+    // `next_page` cursor (verified live 2026-07-09). A full page (rows ===
+    // limit) implies there may be another; a short/empty page is the last.
+    const limit = opts.limit ?? 100
+    const currentPage = Number(opts.page ?? data.page ?? 1)
+    const next_page =
+      results.length >= limit ? String(currentPage + 1) : undefined
     return {
       count: data.count ?? results.length,
       results,
-      next_page: data.next_page ?? data.pagination?.next_page,
+      next_page,
     }
   }
 
@@ -421,28 +448,97 @@ export class FaireClient {
   }
 
   private mapProduct(data: any): ProductResponse {
+    // v2 returns `id` (p_…) + `lifecycle_state` (DRAFT|PUBLISHED). Normalise
+    // lifecycle_state → the internal `state` used downstream for publish gating.
+    const lifecycle = data.lifecycle_state ?? data.state
+    const state =
+      lifecycle === "PUBLISHED" || data.state === "active"
+        ? "active"
+        : lifecycle === "DRAFT" || data.state === "draft"
+          ? "draft"
+          : data.state
     return {
       product_token: String(data.product_token ?? data.id ?? data.token),
       brand_id: data.brand_id != null ? String(data.brand_id) : undefined,
       name: data.name,
       description: data.description,
-      state: data.state,
+      state,
       url: data.url,
-      wholesale_price_cents: data.wholesale_price_cents,
-      retail_price_cents: data.retail_price_cents,
       variants: data.variants,
       images: data.images,
       raw: data,
     }
   }
 
+  /**
+   * Resolve a Faire taxonomy_type id (`tt_…`) from a category name (or pass a
+   * `tt_…` id straight through). Faire create REQUIRES `taxonomy_type.id`;
+   * `GET /products/types` returns all ~3k `{ id, name }` rows under the
+   * `taxonomy_types` key in a single unpaginated response (verified live
+   * 2026-07-09; the `limit` param is ignored). Cached per client.
+   */
+  private taxonomyTypesCache: Array<{ id: string; name: string }> | null = null
+  async resolveTaxonomyTypeId(
+    accessToken: string,
+    nameOrId: string
+  ): Promise<string | null> {
+    if (!nameOrId) return null
+    if (/^tt_/.test(nameOrId)) return nameOrId
+    if (!this.taxonomyTypesCache) {
+      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 ?? "") }))
+    }
+    const needle = nameOrId.trim().toLowerCase()
+    const list = this.taxonomyTypesCache ?? []
+    const exact = list.find((t) => t.name.toLowerCase() === needle)
+    if (exact) return exact.id
+    // Prefer a whole-word match (needle as its own token) over a loose
+    // substring — otherwise "Dress" would resolve to "Address Book" (contains
+    // "ad-dress"). Fall back to substring only if no word-boundary hit.
+    const wordRe = new RegExp(`\\b${needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`)
+    const word = list.find((t) => wordRe.test(t.name.toLowerCase()))
+    if (word) return word.id
+    const partial = list.find((t) => t.name.toLowerCase().includes(needle))
+    return partial?.id ?? null
+  }
+
   private mapOrder(data: any): FaireOrder {
+    // ExternalOrderV2 has no top-level currency/total/buyer — money is per-item
+    // ExternalMoneyV2 (`price.amount_minor`+`currency`) and the buyer is
+    // `customer { first_name, last_name }`. Derive them; keep `raw` for the
+    // ingest mapper which reads the full shape. Verified live 2026-07-09.
+    const items: any[] = Array.isArray(data.items) ? data.items : []
+    const firstCur = items
+      .map((it) => it?.price?.currency)
+      .find((c) => typeof c === "string" && c)
+    const totalCents = items.reduce(
+      (sum, it) =>
+        sum +
+        Number(it?.price?.amount_minor ?? it?.price_cents ?? 0) *
+          Math.max(1, Number(it?.quantity) || 1),
+      0
+    )
+    const buyer =
+      [data.customer?.first_name, data.customer?.last_name]
+        .filter(Boolean)
+        .join(" ") ||
+      data.address?.name ||
+      undefined
     return {
       order_token: String(data.order_token ?? data.id ?? data.token),
       state: data.state ?? data.status,
-      currency: data.currency ?? data.currency_code,
-      total_cents: data.total_cents ?? data.grand_total_cents,
-      buyer_name: data.buyer_name ?? data.customer?.name,
+      currency: firstCur ?? data.currency ?? data.currency_code,
+      total_cents: items.length ? totalCents : data.total_cents ?? data.grand_total_cents,
+      buyer_name: buyer,
       raw: data,
     }
   }

package/src/lib/types.ts

@@ -28,7 +28,11 @@ export interface FairePluginOptions {
   tokenUrl?: string
 }
 
-export const DEFAULT_API_BASE = "https://faire.com/external-api/v2"
+// MUST be the canonical www host. Bare `faire.com` 301-redirects to www, and a
+// 301 on a POST/PUT strips the request body (fetch/curl replay it without the
+// payload) — so writes (createProduct/updateProduct) silently no-op'd, coming
+// back as if they were `GET /products` (a product LIST). Verified live 2026-07-09.
+export const DEFAULT_API_BASE = "https://www.faire.com/external-api/v2"
 export const DEFAULT_AUTH_URL = "https://faire.com/oauth2/authorize"
 export const DEFAULT_TOKEN_URL = "https://www.faire.com/api/external-api-oauth2/token"
 // Faire OAuth scopes are coarse tokens like READ_ORDERS, WRITE_PRODUCTS. The
@@ -69,27 +73,59 @@ export interface ProductImage {
   url: string
 }
 
+/**
+ * Faire External API v2 create/update product contract (verified live
+ * 2026-07-09 against `POST https://www.faire.com/external-api/v2/products`).
+ *
+ * Money is `amount_minor` (integer minor units = cents) + `currency`. Each
+ * variant price is scoped to a geo (`country` ISO-2 OR a `country_group` enum
+ * like EUROPEAN_UNION). `taxonomy_type.id` (a `tt_…` id from GET /products/types)
+ * and per-entity `idempotence_token`s are REQUIRED — omitting either 400s.
+ */
+export type FaireLifecycleState = "DRAFT" | "PUBLISHED"
+
+export interface FaireGeoConstraint {
+  country?: string
+  country_group?: string
+}
+
+export interface FaireMoneyMinor {
+  amount_minor: number
+  currency: string
+}
+
+export interface FaireVariantPrice {
+  geo_constraint: FaireGeoConstraint
+  wholesale_price: FaireMoneyMinor
+  retail_price: FaireMoneyMinor
+}
+
+export interface FaireVariantOption {
+  name: string
+  value: string
+}
+
 export interface ProductVariantInput {
   sku: string
-  name?: string
-  wholesale_price_cents?: number
-  retail_price_cents?: number
-  inventory_count?: number
+  name: string
+  idempotence_token: string
+  options?: FaireVariantOption[]
+  available_quantity?: number
+  prices?: FaireVariantPrice[]
   images?: ProductImage[]
 }
 
 export interface CreateProductInput {
-  brand_id: string
   name: string
+  idempotence_token: string
+  lifecycle_state: FaireLifecycleState
+  taxonomy_type: { id: string }
   description?: string
-  wholesale_price_cents?: number
-  retail_price_cents?: number
-  images?: ProductImage[]
-  variants?: ProductVariantInput[]
-  tags?: string[]
-  shipping?: Record<string, any>
-  metadata?: Record<string, any>
   short_description?: string
+  variants: ProductVariantInput[]
+  images?: ProductImage[]
+  unit_multiplier?: number
+  minimum_order_quantity?: number
 }
 
 export type UpdateProductInput = Partial<CreateProductInput>
@@ -101,8 +137,6 @@ export interface ProductResponse {
   description?: string
   state?: ProductState
   url?: string
-  wholesale_price_cents?: number
-  retail_price_cents?: number
   variants?: any[]
   images?: ProductImage[]
   raw: Record<string, any>
@@ -116,12 +150,17 @@ export interface InventoryLevel {
 }
 
 /**
- * Payload for `PATCH /product-inventory/by-skus`. Faire ingests an array of
- * per-SKU overrides; each row carries the SKU and the new on-hand count.
+ * Payload row for `PATCH /product-inventory/by-skus`. Faire ingests an array
+ * under `inventories`; each row carries the SKU and the new on-hand count.
+ * The writable quantity field is `on_hand_quantity` (integer) — verified live
+ * 2026-07-09 against the docs (there is NO `current_count`/`available_quantity`
+ * on this endpoint; those belong to other inventory endpoints). `product_variant_id`
+ * is optional — Faire resolves the row by SKU when it's omitted.
  */
 export interface InventoryOverrideBySku {
   sku: string
-  current_count: number
+  on_hand_quantity: number
+  product_variant_id?: string
 }
 
 export interface FaireOrder {

package/src/modules/faire-sync/migrations/.snapshot-medusa-faire-sync.json

@@ -301,6 +301,25 @@
           "enumItems": [],
           "mappedType": "text"
         },
+        "auth_mode": {
+          "name": "auth_mode",
+          "type": "text",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "'oauth'",
+          "comment": null,
+          "enumItems": [
+            "oauth",
+            "apiKey"
+          ],
+          "mappedType": "enum"
+        },
         "access_token": {
           "name": "access_token",
           "type": "text",

package/src/modules/faire-sync/migrations/Migration20260709161201.ts

@@ -0,0 +1,13 @@
+import { Migration } from "@medusajs/framework/mikro-orm/migrations";
+
+export class Migration20260709161201 extends Migration {
+
+  override async up(): Promise<void> {
+    this.addSql(`alter table if exists "faire_sync_account" add column if not exists "auth_mode" text check ("auth_mode" in ('oauth', 'apiKey')) not null default 'oauth';`);
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table if exists "faire_sync_account" drop column if exists "auth_mode";`);
+  }
+
+}

package/src/modules/faire-sync/models/faire-sync-account.ts

@@ -6,6 +6,10 @@ const FaireSyncAccount = model.define("faire_sync_account", {
   brand_name: model.text(),
   currency: model.text().nullable(),
   country: model.text().nullable(),
+  // How this account authenticates to Faire: OAuth (published apps) or a
+  // brand-issued API key (private/single-merchant integrations). Drives which
+  // auth header the client sends, so both connection types can coexist.
+  auth_mode: model.enum(["oauth", "apiKey"]).default("oauth"),
   access_token: model.text(),
   refresh_token: model.text().nullable(),
   token_expires_at: model.dateTime().nullable(),