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

package/src/lib/faire-client.ts

@@ -0,0 +1,436 @@
+import crypto from "crypto"
+import {
+  DEFAULT_API_BASE,
+  DEFAULT_AUTH_URL,
+  DEFAULT_TOKEN_URL,
+  FairePluginOptions,
+  BrandInfo,
+  CreateProductInput,
+  UpdateProductInput,
+  ProductResponse,
+  InventoryLevel,
+  FaireOrder,
+  TokenData,
+} from "./types"
+
+export class FaireApiError extends Error {
+  status: number
+  body: any
+  constructor(message: string, status: number, body: any) {
+    super(message)
+    this.name = "FaireApiError"
+    this.status = status
+    this.body = body
+  }
+}
+
+/**
+ * Faire External Platform API v2 client.
+ *
+ * Auth model:
+ *  - OAuth 2.0 authorization-code flow (no PKCE; Faire does not use PKCE).
+ *  - Scoped requests send `Authorization: Bearer <access_token>`.
+ *  - Faire's API-key mode (`X-FAIRE-ACCESS-TOKEN`) is not used here because the
+ *    plugin connects a brand account via OAuth redirect.
+ *
+ * NOTE: Faire's developer portal is access-gated. Endpoint paths, payload
+ * shapes and the webhook signature scheme below reflect the publicly documented
+ * v2 surface and standard OAuth2 conventions; adjust via options / env if your
+ * Faire app uses a different base or signing scheme.
+ */
+export class FaireClient {
+  private clientId: string
+  private clientSecret: string
+  private redirectUri: string
+  private apiBase: string
+  private authUrl: string
+  private tokenUrl: string
+  private scope: string
+
+  constructor(opts: FairePluginOptions) {
+    this.clientId = opts.clientId
+    this.clientSecret = opts.clientSecret
+    this.redirectUri = opts.redirectUri
+    this.apiBase = opts.apiBase || DEFAULT_API_BASE
+    this.authUrl = opts.authUrl || DEFAULT_AUTH_URL
+    this.tokenUrl = opts.tokenUrl || DEFAULT_TOKEN_URL
+    this.scope = opts.scope ?? ""
+  }
+
+  get redirectUriValue(): string {
+    return this.redirectUri
+  }
+
+  // ── OAuth ───────────────────────────────────────────────────────────────
+
+  /**
+   * Build the Faire OAuth authorize URL. The caller must persist `state`
+   * (keyed by it) for the callback verification.
+   */
+  getAuthorizationUrl(state: string): string {
+    const params = new URLSearchParams({
+      response_type: "code",
+      client_id: this.clientId,
+      redirect_uri: this.redirectUri,
+      state,
+    })
+    if (this.scope) params.set("scope", this.scope)
+    return `${this.authUrl}?${params.toString()}`
+  }
+
+  async exchangeCodeForToken(code: string): Promise<TokenData> {
+    const body = new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      redirect_uri: this.redirectUri,
+      code,
+    })
+    const data = await this.requestJson<any>(this.tokenUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString(),
+      auth: false,
+    })
+    return {
+      access_token: data.access_token,
+      refresh_token: data.refresh_token,
+      token_type: data.token_type || "Bearer",
+      expires_in: data.expires_in,
+      retrieved_at: Date.now(),
+    }
+  }
+
+  async refreshAccessToken(refresh_token: string): Promise<TokenData> {
+    const body = new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      refresh_token,
+    })
+    const data = await this.requestJson<any>(this.tokenUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString(),
+      auth: false,
+    })
+    return {
+      access_token: data.access_token,
+      refresh_token: data.refresh_token || refresh_token,
+      token_type: data.token_type || "Bearer",
+      expires_in: data.expires_in,
+      retrieved_at: Date.now(),
+    }
+  }
+
+  /**
+   * Resolve the brand the access token belongs to. Faire exposes the current
+   * brand via GET /api/v2/brand. Falls back gracefully if the shape differs.
+   */
+  async getBrand(accessToken: string): Promise<BrandInfo> {
+    const data = await this.requestJson<any>(`${this.apiBase}/brand`, {
+      method: "GET",
+      accessToken,
+    })
+    const brand =
+      data && typeof data === "object" && (data.brand_id || data.id)
+        ? data
+        : data?.brand ?? data?.results?.[0] ?? data
+    if (!brand?.brand_id && !brand?.id) {
+      throw new Error(
+        "No Faire brand found for the authorized account. Make sure you connected the brand owner."
+      )
+    }
+    return {
+      brand_id: String(brand.brand_id ?? brand.id),
+      brand_name: brand.name ?? brand.brand_name ?? "Faire Brand",
+      currency: brand.currency ?? brand.currency_code,
+      country: brand.country ?? brand.country_code,
+      raw: brand,
+    }
+  }
+
+  async fetchResource<T = any>(accessToken: string, url: string): Promise<T> {
+    return this.requestJson<T>(url, { method: "GET", accessToken })
+  }
+
+  // ── Products ────────────────────────────────────────────────────────────
+
+  async createProduct(
+    accessToken: string,
+    input: CreateProductInput
+  ): Promise<ProductResponse> {
+    const data = await this.requestJson<any>(`${this.apiBase}/products`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+      accessToken,
+    })
+    return this.mapProduct(data?.product ?? data)
+  }
+
+  async updateProduct(
+    accessToken: string,
+    productToken: string,
+    input: UpdateProductInput
+  ): Promise<ProductResponse> {
+    const data = await this.requestJson<any>(
+      `${this.apiBase}/products/${productToken}`,
+      {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+        accessToken,
+      }
+    )
+    return this.mapProduct(data?.product ?? data)
+  }
+
+  async getProduct(
+    accessToken: string,
+    productToken: string
+  ): Promise<ProductResponse> {
+    const data = await this.requestJson<any>(
+      `${this.apiBase}/products/${productToken}`,
+      { method: "GET", accessToken }
+    )
+    return this.mapProduct(data?.product ?? data)
+  }
+
+  async listProducts(
+    accessToken: string,
+    opts: { limit?: number; page?: number } = {}
+  ): Promise<{ count: number; results: ProductResponse[] }> {
+    const params = new URLSearchParams()
+    params.set("limit", String(opts.limit ?? 100))
+    if (opts.page != null) params.set("page", String(opts.page))
+    const data = await this.requestJson<any>(
+      `${this.apiBase}/products?${params.toString()}`,
+      { method: "GET", accessToken }
+    )
+    const results = (data.products ?? data.results ?? []).map((p: any) =>
+      this.mapProduct(p)
+    )
+    return { count: data.count ?? results.length, results }
+  }
+
+  // ── Inventory ───────────────────────────────────────────────────────────
+
+  async getInventory(
+    accessToken: string,
+    productToken?: string
+  ): Promise<InventoryLevel[]> {
+    const params = new URLSearchParams()
+    if (productToken) params.set("product_token", productToken)
+    const data = await this.requestJson<any>(
+      `${this.apiBase}/inventory?${params.toString()}`,
+      { method: "GET", accessToken }
+    )
+    const rows = data.inventory ?? data.results ?? []
+    return (Array.isArray(rows) ? rows : []).map((r: any) => ({
+      sku: String(r.sku ?? r.variant_id ?? ""),
+      product_token: r.product_token ? String(r.product_token) : undefined,
+      current_count: Number(r.current_count ?? r.inventory_count ?? 0),
+      raw: r,
+    }))
+  }
+
+  async updateInventory(
+    accessToken: string,
+    levels: Array<{ sku: string; current_count: number }>
+  ): Promise<any> {
+    return this.requestJson<any>(`${this.apiBase}/inventory`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ inventory: levels }),
+      accessToken,
+    })
+  }
+
+  // ── Orders ──────────────────────────────────────────────────────────────
+
+  async listOrders(
+    accessToken: string,
+    opts: { limit?: number; page?: number } = {}
+  ): Promise<{ count: number; results: FaireOrder[] }> {
+    const params = new URLSearchParams()
+    params.set("limit", String(opts.limit ?? 100))
+    if (opts.page != null) params.set("page", String(opts.page))
+    const data = await this.requestJson<any>(
+      `${this.apiBase}/orders?${params.toString()}`,
+      { method: "GET", accessToken }
+    )
+    const results = (data.orders ?? data.results ?? []).map((o: any) =>
+      this.mapOrder(o)
+    )
+    return { count: data.count ?? results.length, results }
+  }
+
+  async getOrder(accessToken: string, orderToken: string): Promise<FaireOrder> {
+    const data = await this.requestJson<any>(
+      `${this.apiBase}/orders/${orderToken}`,
+      { method: "GET", accessToken }
+    )
+    return this.mapOrder(data?.order ?? data)
+  }
+
+  async setOrderItemAvailability(
+    accessToken: string,
+    orderToken: string,
+    items: Array<{ item_id: string; availability: string }>
+  ): Promise<any> {
+    return this.requestJson<any>(
+      `${this.apiBase}/orders/${orderToken}/items/availability`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ items }),
+        accessToken,
+      }
+    )
+  }
+
+  // ── Webhooks ────────────────────────────────────────────────────────────
+
+  async registerWebhook(
+    accessToken: string,
+    payload: { url: string; events: string[] }
+  ): Promise<any> {
+    return this.requestJson<any>(`${this.apiBase}/webhooks`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      accessToken,
+    })
+  }
+
+  // ── Helpers ─────────────────────────────────────────────────────────────
+
+  /**
+   * Fetch a remote image URL into a Buffer (used when Faire requires binary
+   * image payloads rather than remote URLs).
+   */
+  static async fetchImageBuffer(url: string): Promise<{ buffer: Buffer; filename: string }> {
+    const res = await fetch(url)
+    if (!res.ok) {
+      throw new Error(`Failed to fetch image ${url}: ${res.status}`)
+    }
+    const arrayBuffer = await res.arrayBuffer()
+    const buffer = Buffer.from(arrayBuffer)
+    const filename = url.split("/").pop()?.split("?")[0] || "image.jpg"
+    return { buffer, filename }
+  }
+
+  private mapProduct(data: any): ProductResponse {
+    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,
+      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,
+    }
+  }
+
+  private mapOrder(data: any): FaireOrder {
+    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,
+      raw: data,
+    }
+  }
+
+  // ── Low-level request with rate-limit handling ──────────────────────────
+
+  private async requestJson<T>(
+    url: string,
+    init: {
+      method: string
+      body?: any
+      headers?: Record<string, string>
+      accessToken?: string
+      auth?: boolean
+    }
+  ): Promise<T> {
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      ...(init.headers || {}),
+    }
+    if (init.accessToken) {
+      headers["Authorization"] = `Bearer ${init.accessToken}`
+    }
+
+    let attempt = 0
+    const maxAttempts = 4
+    while (attempt < maxAttempts) {
+      attempt++
+      let res: Response
+      try {
+        res = await fetch(url, { method: init.method, headers, body: init.body })
+      } catch (err: any) {
+        if (attempt >= maxAttempts) throw err
+        await this.backoff(attempt)
+        continue
+      }
+
+      if (res.status === 429) {
+        const retryAfter = Number(res.headers.get("retry-after") || 1)
+        await this.sleep(Math.min(retryAfter * 1000, 10000))
+        continue
+      }
+
+      if (res.status === 401) {
+        throw new FaireApiError("Faire access token expired or invalid", 401, null)
+      }
+
+      if (res.status === 204) {
+        return undefined as T
+      }
+
+      const text = await res.text()
+      let body: any = null
+      if (text) {
+        try {
+          body = JSON.parse(text)
+        } catch {
+          body = text
+        }
+      }
+
+      if (!res.ok) {
+        const detail =
+          body?.error_description ||
+          body?.error ||
+          body?.message ||
+          (Array.isArray(body?.errors)
+            ? body.errors.map((e: any) => e?.message || e?.error || e).join("; ")
+            : undefined) ||
+          (typeof body === "string" && body ? body : undefined) ||
+          (body && typeof body === "object" ? JSON.stringify(body) : undefined)
+        const msg = detail
+          ? `Faire API ${res.status}: ${detail}`
+          : `Faire API error ${res.status}`
+        throw new FaireApiError(msg, res.status, body)
+      }
+
+      return body as T
+    }
+    throw new FaireApiError("Max retries exceeded", 599, null)
+  }
+
+  private async backoff(attempt: number): Promise<void> {
+    await this.sleep(Math.min(500 * Math.pow(2, attempt - 1), 8000))
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+}

package/src/lib/types.ts

@@ -0,0 +1,117 @@
+export interface FairePluginOptions {
+  clientId: string
+  clientSecret: string
+  redirectUri: string
+  apiBase?: string
+  authUrl?: string
+  tokenUrl?: string
+  scope?: string
+  webhookSecret?: string
+}
+
+export const DEFAULT_API_BASE = "https://www.faire.com/api/v2"
+export const DEFAULT_AUTH_URL = "https://www.faire.com/oauth/authorize"
+export const DEFAULT_TOKEN_URL = "https://www.faire.com/oauth/token"
+// Faire OAuth currently exposes no granular scopes; the parameter is kept for
+// forward-compat and to match the OAuth2 authorize URL shape.
+export const DEFAULT_SCOPE = ""
+
+export interface TokenData {
+  access_token: string
+  refresh_token?: string
+  token_type: string
+  expires_in?: number
+  retrieved_at: number
+}
+
+export interface BrandInfo {
+  brand_id: string
+  brand_name: string
+  currency?: string
+  country?: string
+  raw: Record<string, any>
+}
+
+/**
+ * Faire returns money as integer cents in the brand's currency. Keep cents for
+ * transport/storage, but convert to decimal major units (cents / 100) at the
+ * boundary where amounts enter Medusa order/payment workflows — see
+ * faireMoney() in ingest-faire-order-support.ts.
+ */
+export interface FaireMoney {
+  amount_cents: number
+  currency_code?: string
+}
+
+export type ProductState = "active" | "inactive" | "sold_out" | "draft"
+
+export interface ProductImage {
+  url: string
+}
+
+export interface ProductVariantInput {
+  sku: string
+  name?: string
+  wholesale_price_cents?: number
+  retail_price_cents?: number
+  inventory_count?: number
+  images?: ProductImage[]
+}
+
+export interface CreateProductInput {
+  brand_id: string
+  name: 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
+}
+
+export type UpdateProductInput = Partial<CreateProductInput>
+
+export interface ProductResponse {
+  product_token: string
+  brand_id?: string
+  name: string
+  description?: string
+  state?: ProductState
+  url?: string
+  wholesale_price_cents?: number
+  retail_price_cents?: number
+  variants?: any[]
+  images?: ProductImage[]
+  raw: Record<string, any>
+}
+
+export interface InventoryLevel {
+  sku: string
+  product_token?: string
+  current_count: number
+  raw?: Record<string, any>
+}
+
+export interface FaireOrder {
+  order_token: string
+  state?: string
+  currency?: string
+  total_cents?: number
+  buyer_name?: string
+  raw: Record<string, any>
+}
+
+export interface PreparedProduct {
+  product: ProductResponse
+  published: boolean
+  warnings: string[]
+}
+
+export interface WebhookRegistration {
+  webhook_token?: string
+  url: string
+  events: string[]
+}

package/src/lib/webhook.ts

@@ -0,0 +1,85 @@
+import crypto from "crypto"
+
+/**
+ * Verify an inbound Faire webhook.
+ *
+ * Faire signs each delivery with an HMAC-SHA256 of the raw request body using
+ * the webhook signing secret shared at registration time. The signature is sent
+ * in the `X-Faire-Webhook-Signature` header, typically as a hex digest. Some
+ * deployments send a base64 digest, so we accept both. The header may also
+ * carry several space-separated `v1,<sig>` entries (Svix-style); any match
+ * passes.
+ *
+ * NOTE: Faire's developer portal is access-gated; if your app uses a different
+ * header name or digest encoding, adjust the headers passed in or the
+ * `encoding` option accordingly.
+ */
+
+export type FaireWebhookHeaders = {
+  signature?: string
+  timestamp?: string
+}
+
+const TOLERANCE_SECONDS = 5 * 60
+
+const isHex = (s: string): boolean => /^[0-9a-fA-F]+$/.test(s) && s.length % 2 === 0
+
+const safeEqual = (a: Buffer, b: Buffer): boolean => {
+  if (a.length !== b.length) return false
+  return crypto.timingSafeEqual(a, b)
+}
+
+export function verifyFaireWebhook(opts: {
+  secret: string
+  headers: FaireWebhookHeaders
+  rawBody: string
+  encoding?: "hex" | "base64"
+  toleranceSeconds?: number
+  now?: number
+}): { valid: boolean; reason?: string } {
+  const { secret, headers, rawBody } = opts
+  const { signature, timestamp } = headers
+
+  if (!secret) return { valid: false, reason: "no signing secret configured" }
+  if (!signature) {
+    return { valid: false, reason: "missing webhook signature header" }
+  }
+
+  // Optional replay guard — only enforced when a timestamp is present.
+  if (timestamp) {
+    const ts = Number(timestamp)
+    const now = Math.floor((opts.now ?? Date.now()) / 1000)
+    const tolerance = opts.toleranceSeconds ?? TOLERANCE_SECONDS
+    if (Number.isFinite(ts) && Math.abs(now - ts) > tolerance) {
+      return { valid: false, reason: "timestamp outside tolerance" }
+    }
+  }
+
+  const key = Buffer.from(secret, "utf8")
+  const computed = crypto
+    .createHmac("sha256", key)
+    .update(rawBody, "utf8")
+    .digest()
+
+  const candidates = signature
+    .split(" ")
+    .map((part) => (part.includes(",") ? part.split(",")[1] : part))
+    .filter(Boolean)
+
+  let passed = false
+  for (const sig of candidates) {
+    const encoding = opts.encoding || (isHex(sig) ? "hex" : "base64")
+    let provided: Buffer
+    try {
+      provided = Buffer.from(sig, encoding)
+    } catch {
+      continue
+    }
+    if (provided.length && safeEqual(provided, computed)) {
+      passed = true
+      break
+    }
+  }
+
+  return passed ? { valid: true } : { valid: false, reason: "signature mismatch" }
+}

package/src/links/product-faire-sync-link.ts

@@ -0,0 +1,56 @@
+import ProductModule from "@medusajs/medusa/product"
+import FaireSyncModule from "../modules/faire-sync"
+import { defineLink } from "@medusajs/framework/utils"
+
+/**
+ * Link between Product and Faire account, storing the *current* per-product
+ * sync state. Historical sync attempts live in the faire_sync_record table.
+ *
+ * extraColumns:
+ * - faire_product_token: Faire product token once created
+ * - faire_url: public Faire product URL
+ * - sync_status: pending | synced | failed | out_of_sync
+ * - last_synced_at: last successful sync
+ * - sync_error: last error message
+ */
+export default defineLink(
+  {
+    linkable: ProductModule.linkable.product,
+    isList: true,
+  },
+  {
+    linkable: FaireSyncModule.linkable.faireSyncAccount,
+    isList: false,
+  },
+  {
+    database: {
+      extraColumns: {
+        faire_product_token: {
+          type: "text",
+          nullable: true,
+        },
+        faire_url: {
+          type: "text",
+          nullable: true,
+        },
+        sync_status: {
+          type: "text",
+          defaultValue: "'pending'",
+          nullable: false,
+        },
+        last_synced_at: {
+          type: "datetime",
+          nullable: true,
+        },
+        sync_error: {
+          type: "text",
+          nullable: true,
+        },
+        metadata: {
+          type: "json",
+          nullable: true,
+        },
+      },
+    },
+  }
+)

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

@@ -0,0 +1,11 @@
+import { Module } from "@medusajs/framework/utils"
+import FaireSyncService from "./service"
+
+export const FAIRE_SYNC_MODULE = "faireSync"
+
+const FaireSyncModule = Module(FAIRE_SYNC_MODULE, {
+  service: FaireSyncService,
+})
+
+export default FaireSyncModule
+export { FaireSyncService }