@jytextiles/medusa-plugin-faire-store-sync 0.1.0

package/src/subscribers/faire-order-lifecycle.ts

@@ -0,0 +1,81 @@
+import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
+import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
+import { cancelOrderWorkflow } from "@medusajs/medusa/core-flows"
+import { FAIRE_SYNC_MODULE } from "../modules/faire-sync"
+import FaireSyncService from "../modules/faire-sync/service"
+
+/**
+ * Follow a Faire order's lifecycle onto the Medusa order we created for it:
+ *   order.canceled → cancel the Medusa order
+ *   order.shipped  → stamp fulfillment status = shipped
+ *   order.delivered→ stamp fulfillment status = delivered
+ *
+ * The order must already exist (created on order.placed); if it doesn't yet we
+ * simply skip.
+ */
+export default async function faireOrderLifecycleHandler({
+  event,
+  container,
+}: SubscriberArgs<{ resource?: any; resource_url?: string }>) {
+  const logger: any = container.resolve(ContainerRegistrationKeys.LOGGER)
+  const service: FaireSyncService = container.resolve(FAIRE_SYNC_MODULE)
+
+  let order: any = event.data?.resource
+  if (!order && event.data?.resource_url) {
+    try {
+      const account = await service.ensureFreshToken()
+      order = await service
+        .getClient()
+        .fetchResource((account as any).access_token, event.data.resource_url)
+    } catch {
+      return
+    }
+  }
+  const orderToken =
+    order?.order_token != null ? String(order.order_token) : null
+  if (!orderToken) return
+
+  const [mapRow] = await service
+    .listFaireOrders({ order_token: orderToken } as any)
+    .catch(() => [])
+  const orderId = (mapRow as any)?.order_id
+  if (!orderId) return
+
+  const orderService: any = container.resolve(Modules.ORDER)
+
+  try {
+    if (event.name === "faire.order_canceled") {
+      await cancelOrderWorkflow(container).run({ input: { order_id: orderId } })
+      await service.updateFaireOrders({ id: (mapRow as any).id, status: "canceled" } as any)
+      logger?.info?.(`[faire-order] canceled Medusa order ${orderId} (Faire ${orderToken})`)
+      return
+    }
+
+    const fulfillmentStatus =
+      event.name === "faire.order_delivered" ? "delivered" : "shipped"
+
+    const existing = await orderService
+      .retrieveOrder(orderId, { select: ["id", "metadata"] })
+      .catch(() => null)
+    const metadata = {
+      ...((existing?.metadata as any) || {}),
+      faire_fulfillment_status: fulfillmentStatus,
+    }
+    await orderService.updateOrders([{ id: orderId, metadata }])
+    await service.updateFaireOrders({
+      id: (mapRow as any).id,
+      status: fulfillmentStatus,
+    } as any)
+    logger?.info?.(
+      `[faire-order] order ${orderId} fulfillment → ${fulfillmentStatus} (Faire ${orderToken})`
+    )
+  } catch (err: any) {
+    logger?.warn?.(
+      `[faire-order] lifecycle ${event.name} failed for order ${orderId}: ${err?.message}`
+    )
+  }
+}
+
+export const config: SubscriberConfig = {
+  event: ["faire.order_canceled", "faire.order_shipped", "faire.order_delivered"],
+}

package/src/subscribers/faire-product-status-sync.ts

@@ -0,0 +1,76 @@
+import { SubscriberArgs, type SubscriberConfig } from "@medusajs/framework"
+import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
+import type { Link } from "@medusajs/modules-sdk"
+import { FAIRE_SYNC_MODULE } from "../modules/faire-sync"
+import FaireSyncService from "../modules/faire-sync/service"
+import { syncProductToFaireWorkflow } from "../workflows/sync-product-to-faire"
+
+/**
+ * Keep an already-synced Faire product in step with its Medusa product's status
+ * (the draft → published transition the user cares about).
+ *
+ * This is an internal Medusa event (Faire has its own outbound webhooks for
+ * product changes, handled separately). `product.updated` is high-frequency,
+ * so we guard hard to avoid burning Faire's per-second / daily quota:
+ *   - only products that are ALREADY linked (i.e. synced at least once),
+ *   - only when `follow_product_status` is on, and
+ *   - only when the Medusa status ACTUALLY changed since the last sync
+ *     (compared against `product_status` stored on the link metadata).
+ *
+ * The sync workflow does not mutate the Medusa product, so this cannot loop.
+ */
+export default async function faireProductStatusSyncHandler({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  if (!data?.id) return
+
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER) as any
+  const service: FaireSyncService = container.resolve(FAIRE_SYNC_MODULE)
+
+  const account = await service.getActiveAccount()
+  if (!account) return
+
+  const settings = await service.getSettings()
+  if ((settings as any).follow_product_status === false) return
+
+  const remoteLink = container.resolve(ContainerRegistrationKeys.LINK) as Link
+  let row: any
+  try {
+    const rows = await remoteLink.list({
+      [Modules.PRODUCT]: { product_id: data.id },
+      [FAIRE_SYNC_MODULE]: { faire_sync_account_id: account.id },
+    })
+    row = (rows as any[])?.[0]
+  } catch {
+    return
+  }
+  if (!row?.faire_product_token) return
+
+  const query = container.resolve(ContainerRegistrationKeys.QUERY) as any
+  const { data: products } = await query.graph({
+    entity: "product",
+    fields: ["id", "status"],
+    filters: { id: data.id },
+  })
+  const status: string | undefined = products?.[0]?.status
+  if (!status) return
+  if (status === row?.metadata?.product_status) return
+
+  try {
+    logger?.info?.(
+      `[faire] product ${data.id} status → "${status}" (was "${row?.metadata?.product_status ?? "unknown"}"); re-syncing product ${row.faire_product_token}`
+    )
+    await syncProductToFaireWorkflow(container).run({
+      input: { product_id: data.id },
+    })
+  } catch (err: any) {
+    logger?.warn?.(
+      `[faire] auto re-sync failed for product ${data.id}: ${err?.message || err}`
+    )
+  }
+}
+
+export const config: SubscriberConfig = {
+  event: "product.updated",
+}

package/src/workflows/index.ts

@@ -0,0 +1,4 @@
+export * from "./sync-product-to-faire"
+export * from "./sync-products-to-faire"
+export * from "./refresh-faire-token"
+export * from "./ingest-faire-orders-bulk"

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

@@ -0,0 +1,96 @@
+// Pure mapping from a Faire order → the pieces createOrderWorkflow needs.
+// Kept side-effect-free so it can be unit-tested without a container.
+
+// Faire sends money as integer minor units in *_cents fields (2-decimal
+// currencies). Medusa v2 order line-item unit_price and payment-collection
+// amounts are decimal MAJOR units (e.g. 49.99, not 4999) — same contract the
+// sibling Etsy plugin honours via etsyMoney(). Divide by 100 so orders are not
+// created at 100× the real total.
+export const faireMoney = (cents?: number): number => {
+  const n = Number(cents)
+  return Number.isFinite(n) ? n / 100 : 0
+}
+
+const splitName = (name?: string): { first: string; last: string } => {
+  const parts = String(name || "").trim().split(/\s+/).filter(Boolean)
+  if (!parts.length) return { first: "Faire", last: "Buyer" }
+  if (parts.length === 1) return { first: parts[0], last: "" }
+  return { first: parts[0], last: parts.slice(1).join(" ") }
+}
+
+export type MappedFaireOrder = {
+  order_token: string
+  email: string
+  buyer_name: string | null
+  currency_code: string
+  total: number
+  shipping_address: Record<string, any>
+  items: Array<{
+    title: string
+    quantity: number
+    unit_price: number
+    metadata: Record<string, any>
+  }>
+}
+
+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 buyerName =
+    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
+  // synthetic, non-deliverable address keyed by order token so the guest
+  // customer is stable and we never accidentally email a real inbox.
+  const email =
+    (typeof order?.buyer_email === "string" && order.buyer_email) ||
+    (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 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 ?? "",
+    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,
+  }
+
+  return {
+    order_token: orderToken,
+    email,
+    buyer_name: buyerName || null,
+    currency_code: currency,
+    total: faireMoney(order?.total_cents ?? order?.grand_total_cents),
+    shipping_address,
+    items: mappedItems,
+  }
+}

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

@@ -0,0 +1,212 @@
+import {
+  createStep,
+  createWorkflow,
+  StepResponse,
+  WorkflowResponse,
+  WorkflowData,
+} from "@medusajs/framework/workflows-sdk"
+import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
+import {
+  createOrderWorkflow,
+  createOrderPaymentCollectionWorkflow,
+  markPaymentCollectionAsPaid,
+} from "@medusajs/medusa/core-flows"
+import { FAIRE_SYNC_MODULE } from "../modules/faire-sync"
+import FaireSyncService from "../modules/faire-sync/service"
+import { mapFaireOrderToOrder } from "./ingest-faire-order-support"
+
+export const INGEST_FAIRE_ORDER = "faire-ingest-order"
+
+export type IngestFaireOrderInput = {
+  order: any
+  order_token?: string | null
+}
+
+/**
+ * Best-effort inventory decrement for a sold Faire order. Off by default — set
+ * FAIRE_DECREMENT_INVENTORY=true to enable. Resolves product → variant →
+ * inventory item from the product token (via sync records) and adjusts the
+ * level with the most stock down by the sold quantity.
+ */
+async function decrementInventory(
+  container: any,
+  items: Array<{ quantity: number; metadata: Record<string, any> }>,
+  service: FaireSyncService,
+  logger: any
+) {
+  const query: any = container.resolve(ContainerRegistrationKeys.QUERY)
+  const inventory: any = container.resolve(Modules.INVENTORY)
+
+  for (const item of items) {
+    const productToken = item.metadata?.faire_product_token
+    if (!productToken) continue
+    try {
+      const [records] = await service.listSyncRecords(
+        { product_token: String(productToken) },
+        1,
+        0
+      )
+      const productId = (records as any[])?.[0]?.product_id
+      if (!productId) continue
+
+      const { data: products } = await query.graph({
+        entity: "product",
+        fields: [
+          "id",
+          "variants.inventory_items.inventory_item_id",
+          "variants.inventory_items.inventory.location_levels.location_id",
+          "variants.inventory_items.inventory.location_levels.stocked_quantity",
+        ],
+        filters: { id: productId },
+      })
+
+      const invItem = (products?.[0]?.variants || [])
+        .flatMap((v: any) => v.inventory_items || [])
+        .find((ii: any) => ii?.inventory_item_id)
+      const levels = invItem?.inventory?.location_levels || []
+      const level = [...levels].sort(
+        (a: any, b: any) => Number(b.stocked_quantity) - Number(a.stocked_quantity)
+      )[0]
+      if (!invItem?.inventory_item_id || !level?.location_id) continue
+
+      await inventory.adjustInventory(
+        invItem.inventory_item_id,
+        level.location_id,
+        -Math.abs(item.quantity)
+      )
+      logger?.info?.(
+        `[faire-order] decremented inventory ${invItem.inventory_item_id} by ${item.quantity}`
+      )
+    } catch (err: any) {
+      logger?.warn?.(
+        `[faire-order] inventory decrement skipped for product ${productToken}: ${err?.message}`
+      )
+    }
+  }
+}
+
+const ingestStep = createStep(
+  "faire-ingest-order-step",
+  async (
+    input: IngestFaireOrderInput,
+    { container }
+  ): Promise<StepResponse<{ order_id: string | null; skipped?: string }>> => {
+    const logger: any = container.resolve(ContainerRegistrationKeys.LOGGER)
+    const query: any = container.resolve(ContainerRegistrationKeys.QUERY)
+    const service: FaireSyncService = container.resolve(FAIRE_SYNC_MODULE)
+
+    const mapped = mapFaireOrderToOrder(input.order)
+    if (!mapped.order_token) {
+      return new StepResponse({ order_id: null, skipped: "no_order_token" })
+    }
+    if (!mapped.items.length) {
+      return new StepResponse({ order_id: null, skipped: "no_items" })
+    }
+
+    // Idempotency — never create a second order for the same Faire order token.
+    const existing = await service
+      .listFaireOrders({ order_token: mapped.order_token } as any)
+      .catch(() => [])
+    const priorWithOrder = (existing as any[])?.find((e) => e.order_id)
+    if (priorWithOrder) {
+      return new StepResponse({ order_id: priorWithOrder.order_id, skipped: "duplicate" })
+    }
+
+    const { data: regions } = await query.graph({
+      entity: "region",
+      fields: ["id", "currency_code"],
+    })
+    const region =
+      (regions as any[]).find(
+        (r) => String(r.currency_code).toLowerCase() === mapped.currency_code
+      ) || (regions as any[])[0]
+    if (!region) {
+      throw new Error("No Medusa region configured to place the Faire order")
+    }
+
+    let salesChannelId: string | undefined
+    const { data: stores } = await query.graph({
+      entity: "store",
+      fields: ["id", "default_sales_channel_id"],
+    })
+    salesChannelId = (stores as any[])?.[0]?.default_sales_channel_id
+    if (!salesChannelId) {
+      const { data: channels } = await query.graph({
+        entity: "sales_channel",
+        fields: ["id"],
+      })
+      salesChannelId = (channels as any[])?.[0]?.id
+    }
+
+    const orderMetadata = {
+      source: "faire",
+      faire_order_token: mapped.order_token,
+      faire_buyer_name: mapped.buyer_name,
+    }
+
+    const { result: order } = await createOrderWorkflow(container).run({
+      input: {
+        region_id: region.id,
+        currency_code: mapped.currency_code,
+        sales_channel_id: salesChannelId,
+        email: mapped.email,
+        items: mapped.items as any,
+        shipping_address: mapped.shipping_address as any,
+        metadata: orderMetadata,
+      } as any,
+    })
+
+    const orderId = (order as any).id
+
+    // Payment: Faire already collected it → record the collection and mark paid
+    // so the Medusa order shows payment_status = captured.
+    try {
+      const { result: pcRes }: any = await createOrderPaymentCollectionWorkflow(
+        container
+      ).run({ input: { order_id: orderId, amount: mapped.total as any } })
+      const paymentCollectionId = Array.isArray(pcRes) ? pcRes[0]?.id : pcRes?.id
+      if (paymentCollectionId) {
+        await markPaymentCollectionAsPaid(container).run({
+          input: {
+            payment_collection_id: paymentCollectionId,
+            order_id: orderId,
+            captured_by: "faire-webhook",
+          } as any,
+        })
+      }
+    } catch (err: any) {
+      logger?.warn?.(
+        `[faire-order] order ${orderId} created but marking payment paid failed: ${err?.message}`
+      )
+    }
+
+    if (process.env.FAIRE_DECREMENT_INVENTORY === "true") {
+      await decrementInventory(container, mapped.items, service, logger)
+    }
+
+    await service
+      .createFaireOrders({
+        order_token: mapped.order_token,
+        order_id: orderId,
+        status: "created",
+        currency: mapped.currency_code,
+        total: String(mapped.total),
+        buyer_name: mapped.buyer_name,
+        raw: input.order,
+      } as any)
+      .catch(() => {})
+
+    logger?.info?.(
+      `[faire-order] created Medusa order ${orderId} from Faire order ${mapped.order_token}`
+    )
+
+    return new StepResponse({ order_id: orderId })
+  }
+)
+
+export const ingestFaireOrderWorkflow = createWorkflow(
+  INGEST_FAIRE_ORDER,
+  (input: WorkflowData<IngestFaireOrderInput>) => {
+    return new WorkflowResponse(ingestStep(input))
+  }
+)

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

@@ -0,0 +1,168 @@
+import {
+  createStep,
+  createWorkflow,
+  StepResponse,
+  WorkflowResponse,
+  WorkflowData,
+  transform,
+} from "@medusajs/framework/workflows-sdk"
+import { FAIRE_SYNC_MODULE } from "../modules/faire-sync"
+import FaireSyncService from "../modules/faire-sync/service"
+import { ingestFaireOrderWorkflow } from "./ingest-faire-order"
+
+export const INGEST_FAIRE_ORDERS_BULK = "faire-ingest-orders-bulk"
+
+export type IngestFaireOrdersBulkInput = {
+  // When omitted, pulls all available orders from Faire (paged).
+  limit?: number
+}
+
+// Faire enforces a modest per-second request budget. Each order ingest fans
+// out to several Medusa calls (create order + payment + optional inventory),
+// so we pace *orders* conservatively and let the client's 429 retry-after
+// backoff absorb bursts.
+const BASE_DELAY_MS = 600
+const MAX_DELAY_MS = 10_000
+const PROGRESS_EVERY = 5
+const PAGE_SIZE = 50
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+// ── Step 1 (inline): open the batch so the HTTP caller gets an id to poll ──
+
+const openBatchStep = createStep(
+  "faire-ingest-orders-open-batch-step",
+  async (
+    _input: IngestFaireOrdersBulkInput,
+    { container, context }
+  ): Promise<StepResponse<{ batch_id: string }>> => {
+    const service: FaireSyncService = container.resolve(FAIRE_SYNC_MODULE)
+
+    const account = await service.getActiveAccount()
+    if (!account) {
+      throw new Error("Faire account is not connected")
+    }
+
+    const batch = await service.createFaireSyncBatches({
+      transaction_id: context.transactionId,
+      status: "processing",
+      total_products: 0, // populated as we discover orders (generic counter)
+      synced_count: 0,
+      failed_count: 0,
+      error_log: {},
+      started_at: new Date(),
+    } as any)
+
+    return new StepResponse({ batch_id: (batch as any).id })
+  }
+)
+
+// ── Step 2 (async, background): page through Faire orders + ingest each ─────
+
+const processBatchStep = createStep(
+  "faire-ingest-orders-process-batch-step",
+  async (
+    input: { batch_id: string; limit?: number },
+    { container }
+  ): Promise<StepResponse<{ synced: number; failed: number }>> => {
+    const service: FaireSyncService = container.resolve(FAIRE_SYNC_MODULE)
+    const account = await service.ensureFreshToken()
+    const client = service.getClient()
+
+    let synced = 0
+    let failed = 0
+    let total = 0
+    let delay = BASE_DELAY_MS
+    const errors: Record<string, string> = {}
+
+    const persistProgress = async () => {
+      await service
+        .updateFaireSyncBatches({
+          id: input.batch_id,
+          total_products: total,
+          synced_count: synced,
+          failed_count: failed,
+          error_log: errors,
+        } as any)
+        .catch(() => {})
+    }
+
+    try {
+      let page = 1
+      let stop = false
+      while (!stop) {
+        const { results } = await client.listOrders(account.access_token, {
+          limit: PAGE_SIZE,
+          page,
+        })
+        if (!results.length) break
+        total += results.length
+
+        for (const order of results) {
+          const token = order.order_token
+          try {
+            await ingestFaireOrderWorkflow(container).run({
+              input: { order: order.raw, order_token: token },
+            })
+            // Skip === duplicate is still a successful no-op.
+            synced++
+            delay = Math.max(BASE_DELAY_MS, Math.floor(delay / 2))
+          } catch (err: any) {
+            failed++
+            errors[token] = err?.message || "Unknown error"
+            if (/429|rate limit/i.test(errors[token])) {
+              delay = Math.min(delay * 2, MAX_DELAY_MS)
+            }
+          }
+
+          if ((synced + failed) % PROGRESS_EVERY === 0) {
+            await persistProgress()
+          }
+          await sleep(delay)
+        }
+
+        // Honor an explicit limit on total orders processed.
+        if (input.limit != null && total >= input.limit) {
+          stop = true
+        }
+        // Stop if the last page was short (no more pages).
+        if (results.length < PAGE_SIZE) {
+          stop = true
+        }
+        page++
+      }
+    } catch (err: any) {
+      errors["__fetch__"] = err?.message || "Failed to list Faire orders"
+    }
+
+    await service.updateFaireSyncBatches({
+      id: input.batch_id,
+      total_products: total,
+      status: failed === total && total > 0 ? "failed" : "completed",
+      synced_count: synced,
+      failed_count: failed,
+      error_log: errors,
+      completed_at: new Date(),
+    } as any)
+
+    return new StepResponse({ synced, failed })
+  }
+)
+
+export const ingestFaireOrdersBulkWorkflow = createWorkflow(
+  INGEST_FAIRE_ORDERS_BULK,
+  (input: WorkflowData<IngestFaireOrdersBulkInput>) => {
+    const opened = openBatchStep(input)
+
+    // Long-running: the HTTP request returns as soon as the batch is opened;
+    // the actual per-order ingest runs in the background workflow engine.
+    processBatchStep(
+      transform({ input, opened }, (data) => ({
+        batch_id: data.opened.batch_id,
+        limit: data.input.limit,
+      }))
+    ).config({ async: true, backgroundExecution: true })
+
+    return new WorkflowResponse({ batch_id: opened.batch_id })
+  }
+)

package/src/workflows/refresh-faire-token.ts

@@ -0,0 +1,28 @@
+import {
+  createStep,
+  createWorkflow,
+  StepResponse,
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { FAIRE_SYNC_MODULE } from "../modules/faire-sync"
+import FaireSyncService from "../modules/faire-sync/service"
+
+export const REFRESH_FAIRE_TOKEN = "faire-refresh-token"
+
+const refreshFaireTokenStep = createStep(
+  "faire-refresh-token-step",
+  async (_, { container }): Promise<StepResponse<{ refreshed: boolean }>> => {
+    const service: FaireSyncService = container.resolve(FAIRE_SYNC_MODULE)
+    const account = await service.getActiveAccount()
+    if (!account) {
+      return new StepResponse({ refreshed: false })
+    }
+    await service.ensureFreshToken(account)
+    return new StepResponse({ refreshed: true })
+  }
+)
+
+export const refreshFaireTokenWorkflow = createWorkflow(REFRESH_FAIRE_TOKEN, () => {
+  const result = refreshFaireTokenStep()
+  return new WorkflowResponse(result)
+})