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

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

@@ -92,7 +92,15 @@ class FaireSyncService extends MedusaService({
     this.options_ = resolveFaireOptions(options)
   }
 
-  getClient(): FaireClient {
+  /**
+   * Build a Faire client. Pass `authModeOverride` (e.g. an account's `auth_mode`)
+   * to force the auth header for that connection type; without it, the plugin's
+   * configured default is used (cached).
+   */
+  getClient(authModeOverride?: "oauth" | "apiKey"): FaireClient {
+    if (authModeOverride) {
+      return new FaireClient({ ...this.options_, authMode: authModeOverride })
+    }
     if (!this.client_) {
       this.client_ = new FaireClient(this.options_)
     }
@@ -128,7 +136,11 @@ class FaireSyncService extends MedusaService({
     }
   }
 
-  async saveAccount(token: TokenData, brand: BrandInfo) {
+  async saveAccount(
+    token: TokenData,
+    brand: BrandInfo,
+    authMode: "oauth" | "apiKey" = "oauth"
+  ) {
     const existing = await this.getActiveAccount()
     const expiresAt =
       token.expires_in != null
@@ -139,6 +151,7 @@ class FaireSyncService extends MedusaService({
       brand_name: brand.brand_name,
       currency: brand.currency ?? null,
       country: brand.country ?? null,
+      auth_mode: authMode,
       access_token: encryptSecret(token.access_token),
       refresh_token: encryptSecret(token.refresh_token ?? null),
       token_expires_at: expiresAt,
@@ -163,8 +176,9 @@ class FaireSyncService extends MedusaService({
     // Best-effort: a failed revoke must not block local disconnect.
     try {
       const accessToken = decryptSecret((account as any).access_token)
-      if (accessToken && this.options_.authMode !== "apiKey") {
-        await this.getClient().revokeToken(accessToken)
+      // Only OAuth tokens are revocable; a brand-issued API key is not.
+      if (accessToken && (account as any).auth_mode !== "apiKey") {
+        await this.getClient("oauth").revokeToken(accessToken)
       }
     } catch (err: any) {
       // eslint-disable-next-line no-console
@@ -254,12 +268,8 @@ class FaireSyncService extends MedusaService({
   }
 
   async startOAuth(): Promise<{ authorization_url: string; state: string }> {
-    if (this.options_.authMode === "apiKey") {
-      throw new MedusaError(
-        MedusaError.Types.INVALID_DATA,
-        "Faire is configured in API-key mode — use /admin/faire/auth/api-key to connect, not OAuth."
-      )
-    }
+    // Both connection types are available per-account, so OAuth is always
+    // offered here; the API-key path is a separate entry point.
     try {
       const state = crypto.randomUUID()
       await this.updateSettings({
@@ -268,7 +278,7 @@ class FaireSyncService extends MedusaService({
           created_at: Date.now(),
         },
       })
-      const client = this.getClient()
+      const client = this.getClient("oauth")
       return {
         authorization_url: client.getAuthorizationUrl(state),
         state,
@@ -290,14 +300,16 @@ class FaireSyncService extends MedusaService({
       )
     }
     try {
-      const client = this.getClient()
+      // Force API-key auth (X-FAIRE-ACCESS-TOKEN) for this connection regardless
+      // of the plugin's default mode, and persist it so later API calls use it.
+      const client = this.getClient("apiKey")
       const brand = await client.getBrand(accessToken)
       const token: TokenData = {
         access_token: accessToken,
         token_type: "Bearer",
         retrieved_at: Date.now(),
       }
-      const account = await this.saveAccount(token, brand)
+      const account = await this.saveAccount(token, brand, "apiKey")
       await this.updateSettings({
         account_id: account.id,
         default_brand_id: brand.brand_id,
@@ -312,18 +324,26 @@ class FaireSyncService extends MedusaService({
   async completeOAuth(code: string, state: string) {
     const settings = await this.getSettings()
     const pending: any = settings.pending_oauth
+    // eslint-disable-next-line no-console
+    console.info(
+      `[faire-sync] completeOAuth: received code=${code ? code.slice(0, 6) + "…" : "<none>"} ` +
+        `state=${state ? state.slice(0, 8) + "…" : "<none>"} ` +
+        `pending=${pending ? "state:" + String(pending.state).slice(0, 8) + "…" : "<none>"} ` +
+        `match=${!!pending && pending.state === state}`
+    )
     if (!pending || pending.state !== state) {
       throw new MedusaError(
         MedusaError.Types.INVALID_DATA,
-        "Invalid or expired OAuth state. Please start the Faire connection again."
+        `Invalid or expired OAuth state (received "${state}", ` +
+          `pending ${pending ? `"${pending.state}"` : "<none>"}). Please start the Faire connection again.`
       )
     }
     let token: TokenData | undefined
     try {
-      const client = this.getClient()
+      const client = this.getClient("oauth")
       token = await client.exchangeCodeForToken(code)
       const brand = await client.getBrand(token.access_token)
-      const account = await this.saveAccount(token, brand)
+      const account = await this.saveAccount(token, brand, "oauth")
       await this.updateSettings({
         account_id: account.id,
         default_brand_id: brand.brand_id,
@@ -331,6 +351,12 @@ class FaireSyncService extends MedusaService({
       })
       return { account, brand }
     } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error(
+        "[faire-sync] completeOAuth failed during exchange/brand/save:",
+        (err as any)?.message || err,
+        (err as any)?.body ? `| faire body: ${JSON.stringify((err as any).body)}` : ""
+      )
       // Self-heal a dropped OAuth so the next attempt starts clean:
       //  1. clear the pending state (otherwise it sticks and confuses retries), and
       //  2. if the code exchange succeeded but a later step failed, REVOKE the

package/src/workflows/ingest-faire-order-support.ts

@@ -18,6 +18,31 @@ const splitName = (name?: string): { first: string; last: string } => {
   return { first: parts[0], last: parts.slice(1).join(" ") }
 }
 
+// Faire ExternalMoneyV2 = { amount_minor, currency }. Returns integer minor
+// units + ISO currency, or null when the field is absent/not a money object.
+const moneyOf = (m: any): { minor: number; currency: string } | null =>
+  m && typeof m === "object" && m.amount_minor != null
+    ? { minor: Number(m.amount_minor) || 0, currency: String(m.currency || "") }
+    : null
+
+// Faire order addresses carry ISO-3 `country_code` ("CAN") + a full `country`
+// name ("Canada"); Medusa wants a lowercase ISO-2. Map the ISO-3 codes for the
+// regions Faire operates in; pass through anything already 2-letter.
+const ISO3_TO_ISO2: Record<string, string> = {
+  USA: "us", CAN: "ca", GBR: "gb", AUS: "au", NZL: "nz", DEU: "de", FRA: "fr",
+  ITA: "it", ESP: "es", PRT: "pt", NLD: "nl", BEL: "be", LUX: "lu", AUT: "at",
+  IRL: "ie", CHE: "ch", SWE: "se", DNK: "dk", FIN: "fi", NOR: "no", POL: "pl",
+  CZE: "cz", GRC: "gr", HUN: "hu", ROU: "ro", BGR: "bg", HRV: "hr", SVK: "sk",
+  SVN: "si", EST: "ee", LVA: "lv", LTU: "lt", CYP: "cy", MLT: "mt",
+}
+const faireCountryToIso2 = (raw?: string): string | undefined => {
+  const s = String(raw ?? "").trim()
+  if (!s) return undefined
+  if (s.length === 2) return s.toLowerCase()
+  const iso2 = ISO3_TO_ISO2[s.toUpperCase()]
+  return iso2 ?? undefined // full country names ("Canada") can't be mapped safely
+}
+
 export type MappedFaireOrder = {
   order_token: string
   email: string
@@ -37,12 +62,31 @@ export function mapFaireOrderToOrder(order: any): MappedFaireOrder {
   const orderToken = String(order?.order_token ?? order?.id ?? order?.token ?? "")
 
   const address = order?.address ?? order?.shipping_address ?? {}
-  const currency = String(order?.currency ?? order?.currency_code ?? "usd").toLowerCase()
+  const items: any[] = Array.isArray(order?.items) ? order.items : []
 
+  // ExternalOrderV2 has NO top-level currency/total. Currency comes off any
+  // item's ExternalMoneyV2 `price` (fall back to the payout currency, then the
+  // legacy top-level fields for back-compat). See docs verified 2026-07-09.
+  const itemMoney = items.map((it) => moneyOf(it?.price)).find(Boolean)
+  const currency = String(
+    itemMoney?.currency ||
+      moneyOf(order?.payout_costs?.total_payout)?.currency ||
+      order?.currency ||
+      order?.currency_code ||
+      "usd"
+  ).toLowerCase()
+
+  // Buyer name: ExternalOrderV2.customer { first_name, last_name }, else the
+  // recipient name on the address. (`address.company_name`/`retailer_id` is the
+  // wholesale store, not the person.) Legacy fields kept as fallbacks.
+  const customer = order?.customer ?? {}
   const buyerName =
-    order?.buyer_name ??
-    order?.customer_name ??
-    [address?.first_name, address?.last_name].filter(Boolean).join(" ")
+    [customer?.first_name, customer?.last_name].filter(Boolean).join(" ") ||
+    address?.name ||
+    order?.buyer_name ||
+    order?.customer_name ||
+    [address?.first_name, address?.last_name].filter(Boolean).join(" ") ||
+    ""
   const { first, last } = splitName(buyerName)
 
   // Faire usually does NOT expose the retailer's email via API — fall back to a
@@ -53,35 +97,58 @@ export function mapFaireOrderToOrder(order: any): MappedFaireOrder {
     (typeof order?.email === "string" && order.email) ||
     `faire+${orderToken}@marketplace.invalid`
 
-  const items: any[] = Array.isArray(order?.items) ? order.items : []
-  const mappedItems = items.map((it) => {
-    const unitCents = Number(it?.wholesale_price_cents ?? it?.unit_price_cents ?? 0)
-    return {
-      title: String(it?.product_name ?? it?.name ?? it?.title ?? "Faire item").slice(0, 250),
-      quantity: Math.max(1, Number(it?.quantity ?? it?.qty) || 1),
-      unit_price: faireMoney(unitCents),
-      metadata: {
-        faire_order_token: orderToken,
-        faire_item_id: it?.id != null ? String(it.id) : null,
-        faire_product_token:
-          it?.product_token != null ? String(it.product_token) : null,
-        faire_sku: it?.sku ?? null,
-        faire_variant_id:
-          it?.variant_id != null ? String(it.variant_id) : null,
-      },
-    }
-  })
+  const unitMinorOf = (it: any): number => {
+    const m = moneyOf(it?.price)
+    return m
+      ? m.minor
+      : Number(it?.price_cents ?? it?.wholesale_price_cents ?? it?.unit_price_cents ?? 0)
+  }
+
+  const mappedItems = items.map((it) => ({
+    title: String(it?.product_name ?? it?.name ?? it?.title ?? "Faire item").slice(0, 250),
+    quantity: Math.max(1, Number(it?.quantity ?? it?.qty) || 1),
+    unit_price: faireMoney(unitMinorOf(it)),
+    metadata: {
+      faire_order_token: orderToken,
+      faire_item_id: it?.id != null ? String(it.id) : null,
+      faire_product_token:
+        it?.product_id != null
+          ? String(it.product_id)
+          : it?.product_token != null
+            ? String(it.product_token)
+            : null,
+      faire_sku: it?.sku ?? null,
+      faire_variant_id: it?.variant_id != null ? String(it.variant_id) : null,
+    },
+  }))
+
+  // No order-level total exists — sum line values (unit price × qty). Honour an
+  // explicit total_cents/grand_total_cents if a caller ever supplies one.
+  const explicitTotalCents = order?.total_cents ?? order?.grand_total_cents
+  const total =
+    explicitTotalCents != null
+      ? faireMoney(explicitTotalCents)
+      : faireMoney(
+          items.reduce(
+            (sum, it) =>
+              sum + unitMinorOf(it) * Math.max(1, Number(it?.quantity ?? it?.qty) || 1),
+            0
+          )
+        )
 
   const shipping_address = {
     first_name: address?.first_name ?? first,
     last_name: address?.last_name ?? last,
-    address_1: address?.street1 ?? address?.address1 ?? address?.address_1 ?? "",
-    address_2: address?.street2 ?? address?.address2 ?? address?.address_2 ?? "",
+    company: address?.company_name ?? undefined,
+    address_1:
+      address?.address1 ?? address?.address_1 ?? address?.street1 ?? "",
+    address_2:
+      address?.address2 ?? address?.address_2 ?? address?.street2 ?? "",
     city: address?.city ?? "",
-    province: address?.state ?? address?.province ?? "",
-    postal_code: address?.zip ?? address?.postal_code ?? "",
-    country_code: String(address?.country ?? address?.country_code ?? "").toLowerCase() || undefined,
-    phone: address?.phone ?? undefined,
+    province: address?.state_code ?? address?.state ?? address?.province ?? "",
+    postal_code: address?.postal_code ?? address?.zip ?? "",
+    country_code: faireCountryToIso2(address?.country_code ?? address?.country),
+    phone: address?.phone_number ?? address?.phone ?? undefined,
   }
 
   return {
@@ -89,7 +156,7 @@ export function mapFaireOrderToOrder(order: any): MappedFaireOrder {
     email,
     buyer_name: buyerName || null,
     currency_code: currency,
-    total: faireMoney(order?.total_cents ?? order?.grand_total_cents),
+    total,
     shipping_address,
     items: mappedItems,
   }

package/src/workflows/ingest-faire-orders-bulk.ts

@@ -70,7 +70,7 @@ const processBatchStep = createStep(
   ): Promise<StepResponse<{ synced: number; failed: number }>> => {
     const service: FaireSyncService = container.resolve(FAIRE_SYNC_MODULE)
     const account = await service.ensureFreshToken()
-    const client = service.getClient()
+    const client = service.getClient((account as any).auth_mode)
 
     // Resolve the incremental window. Precedence:
     //   explicit input > persisted high-water mark > full backfill (undefined).

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

@@ -26,7 +26,9 @@ type ResolvedConfig = {
   account_id: string
   brand_id: string
   access_token: string
+  auth_mode: "oauth" | "apiKey"
   currency: string | null
+  country: string | null
   settings: any
 }
 
@@ -54,6 +56,31 @@ const productDisplayUrl = (product: ProductResponse): string | null => {
   return `https://www.faire.com/brand/products/${product.product_token}`
 }
 
+/**
+ * Faire variant prices are geo-scoped (`geo_constraint`). Derive a sensible
+ * default from the brand's currency (and country when known). Eurozone brands
+ * map to the EUROPEAN_UNION country_group; otherwise scope to a single country.
+ */
+const geoForCurrency = (
+  currency: string,
+  country: string | null
+): { country?: string; country_group?: string } => {
+  switch (currency) {
+    case "EUR":
+      return { country_group: "EUROPEAN_UNION" }
+    case "GBP":
+      return { country: "GB" }
+    case "USD":
+      return { country: "US" }
+    case "CAD":
+      return { country: "CA" }
+    case "AUD":
+      return { country: "AU" }
+    default:
+      return country ? { country } : { country_group: "EUROPEAN_UNION" }
+  }
+}
+
 // ── Step 1: resolve account (fresh token) + settings ─────────────────────
 
 const resolveFaireConfigStep = createStep(
@@ -66,7 +93,9 @@ const resolveFaireConfigStep = createStep(
       account_id: account.id,
       brand_id: account.brand_id,
       access_token: account.access_token,
+      auth_mode: (account.auth_mode as "oauth" | "apiKey") ?? "oauth",
       currency: account.currency ?? null,
+      country: account.country ?? null,
       settings,
     })
   }
@@ -77,7 +106,15 @@ const resolveFaireConfigStep = createStep(
 const prepareProductStep = createStep(
   "faire-prepare-product-step",
   async (
-    input: { product_id: string; settings: any; brand_id: string },
+    input: {
+      product_id: string
+      settings: any
+      brand_id: string
+      currency: string | null
+      country: string | null
+      access_token: string
+      auth_mode: "oauth" | "apiKey"
+    },
     { container }
   ): Promise<StepResponse<PreparedProduct>> => {
     const query = container.resolve(
@@ -97,6 +134,8 @@ const prepareProductStep = createStep(
         "tags.*",
         "variants.*",
         "variants.prices.*",
+        "variants.options.*",
+        "variants.options.option.*",
         "variants.inventory_items.*",
         "images.*",
         "variants.sku",
@@ -129,64 +168,121 @@ const prepareProductStep = createStep(
     const metadata = product.metadata || {}
     const variants: any[] = product.variants || []
 
-    // Medusa v2 stores money as a whole decimal in the price's currency (NOT
-    // minor units). Faire wants integer cents, so round to cents.
-    const toCents = (amount: any): number => Math.round(Number(amount || 0) * 100)
+    // ── Currency + geo constraint (Faire prices are geo-scoped) ────────────
+    // Prefer the brand's own currency; fall back to the price currency Medusa
+    // stored, then EUR. Currency picks the price row + drives the geo default.
+    const currency = String(
+      metadata.faire_currency ||
+        input.currency ||
+        (variants.flatMap((v) => v.prices || [])[0]?.currency_code ?? "EUR")
+    ).toUpperCase()
+    const geoConstraint: { country?: string; country_group?: string } =
+      metadata.faire_geo_constraint && typeof metadata.faire_geo_constraint === "object"
+        ? metadata.faire_geo_constraint
+        : geoForCurrency(currency, input.country)
+
+    // Medusa v2 stores money as a whole decimal in the price's currency; Faire
+    // wants integer minor units (cents), so round.
+    const toMinor = (amount: any): number => Math.round(Number(amount || 0) * 100)
 
     const markupPercent =
       Number(metadata.faire_wholesale_markup_percent ?? settings.default_wholesale_markup_percent) ||
       0
 
-    const buildVariant = (v: any) => {
-      const prices: any[] = v.prices || []
-      const retail = prices[0] ?? prices.find(Boolean)
-      const retailCents = retail ? toCents(retail.amount) : 0
-      const wholesaleCents =
+    // Pick the price row matching the chosen currency (fall back to first).
+    const pickPrice = (prices: any[]): any =>
+      prices.find((p) => String(p.currency_code || "").toUpperCase() === currency) ??
+      prices[0] ??
+      null
+
+    const buildVariant = (v: any, idx: number) => {
+      const retail = pickPrice(v.prices || [])
+      const retailMinor = retail ? toMinor(retail.amount) : 0
+      const wholesaleMinor =
         markupPercent > 0
-          ? Math.round((retailCents * (100 - markupPercent)) / 100)
-          : retailCents
+          ? Math.round((retailMinor * (100 - markupPercent)) / 100)
+          : retailMinor
+      const sku = v.sku || v.id
+      const options =
+        (v.options || [])
+          .map((o: any) => ({
+            name: String(o.option?.title || o.title || "Option"),
+            value: String(o.value ?? ""),
+          }))
+          .filter((o: any) => o.value) || []
       return {
-        sku: v.sku || v.id,
-        name: v.title || undefined,
-        retail_price_cents: retailCents || undefined,
-        wholesale_price_cents: wholesaleCents || undefined,
-        inventory_count: Number(v.inventory_quantity) || 0,
+        sku,
+        name: v.title || sku,
+        idempotence_token: `${product.id}:${v.id || sku}`,
+        options: options.length ? options : undefined,
+        available_quantity: Number(v.inventory_quantity) || 0,
+        prices:
+          retailMinor > 0
+            ? [
+                {
+                  geo_constraint: geoConstraint,
+                  wholesale_price: { amount_minor: wholesaleMinor, currency },
+                  retail_price: { amount_minor: retailMinor, currency },
+                },
+              ]
+            : undefined,
       }
     }
 
-    // Aggregate retail/wholesale from min-variant for the product-level price.
-    const allPrices = variants.flatMap((v) => v.prices || [])
-    const minRetail =
-      allPrices
-        .map((p) => toCents(p.amount))
-        .filter((a) => a > 0)
-        .sort((a, b) => a - b)[0] ?? 0
-    const minWholesale =
-      markupPercent > 0
-        ? Math.round((minRetail * (100 - markupPercent)) / 100)
-        : minRetail
-
-    const tags = (product.tags || [])
-      .map((t: any) => t.value)
-      .filter(Boolean)
-
     const images = (product.images || [])
       .map((img: any) => ({ url: img.url }))
       .filter((i: any) => i.url)
 
+    // Resolve taxonomy_type.id — REQUIRED by Faire create. Priority:
+    //   product.metadata.faire_taxonomy_type_id (tt_… or a category name)
+    //   → settings.default_category (id or name) → error.
+    const client = service.getClient(input.auth_mode)
+    const categoryHint =
+      metadata.faire_taxonomy_type_id ||
+      metadata.faire_category ||
+      settings.default_category ||
+      ""
+    const taxonomyTypeId = await client.resolveTaxonomyTypeId(
+      input.access_token,
+      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)."
+      )
+    }
+
+    const lifecycle_state: "DRAFT" | "PUBLISHED" =
+      settings.follow_product_status !== false && product.status === "published"
+        ? "PUBLISHED"
+        : "DRAFT"
+
+    const builtVariants = (variants.length ? variants : [null]).map((v, i) =>
+      v
+        ? buildVariant(v, i)
+        : {
+            // Single-variant fallback for products with no explicit variants.
+            sku: product.id,
+            name: product.title || "Default",
+            idempotence_token: `${product.id}:default`,
+            available_quantity: 0,
+          }
+    )
+
     const product_input: CreateProductInput = {
-      brand_id: input.brand_id,
       name: (product.title || "Untitled Product").slice(0, 140),
+      idempotence_token: product.id,
+      lifecycle_state,
+      taxonomy_type: { id: taxonomyTypeId },
       description: product.description || "",
-      wholesale_price_cents: minWholesale || undefined,
-      retail_price_cents: minRetail || undefined,
-      images,
-      variants: variants.length ? variants.map(buildVariant) : undefined,
-      tags,
       short_description:
         typeof metadata.faire_short_description === "string"
           ? metadata.faire_short_description
           : undefined,
+      images,
+      variants: builtVariants,
     }
 
     return new StepResponse({
@@ -211,7 +307,7 @@ const syncProductStep = createStep(
     { container }
   ): Promise<StepResponse<SyncResult>> => {
     const service: FaireSyncService = container.resolve(FAIRE_SYNC_MODULE)
-    const client = service.getClient()
+    const client = service.getClient(input.config.auth_mode)
     const { access_token, settings } = input.config
     const { product_input, existing_product_token, product_status } =
       input.prepared
@@ -224,9 +320,11 @@ const syncProductStep = createStep(
         product = await client.updateProduct(access_token, existing_product_token, {
           name: product_input.name,
           description: product_input.description,
+          short_description: product_input.short_description,
+          lifecycle_state: product_input.lifecycle_state,
+          taxonomy_type: product_input.taxonomy_type,
           images: product_input.images,
           variants: product_input.variants,
-          tags: product_input.tags,
         })
       } else {
         product = await client.createProduct(access_token, product_input)
@@ -242,7 +340,7 @@ const syncProductStep = createStep(
       try {
         const levels = product_input.variants.map((v) => ({
           sku: v.sku,
-          current_count: v.inventory_count ?? 0,
+          on_hand_quantity: v.available_quantity ?? 0,
         }))
         await client.updateInventory(access_token, levels)
       } catch (err: any) {
@@ -346,6 +444,10 @@ export const syncProductToFaireWorkflow = createWorkflow(
         product_id: data.input.product_id,
         settings: data.config.settings,
         brand_id: data.config.brand_id,
+        currency: data.config.currency,
+        country: data.config.country,
+        access_token: data.config.access_token,
+        auth_mode: data.config.auth_mode,
       }))
     )