@salifbiaye/create-boutique 0.1.1

package/templates/backend/src/scripts/seed.ts

@@ -0,0 +1,418 @@
+/**
+ * Seed idempotent, lancé à chaque démarrage du container backend (docker/entrypoint.sh).
+ * Lit config/project.json et crée seulement ce qui manque :
+ *  - devises du store, une région par devise (un pays = une devise), régions de taxe ;
+ *  - entrepôt, zone de livraison « Monde », options Standard / Express par devise ;
+ *  - 1 sales channel + 1 publishable key par boutique, clé écrite dans KEYS_DIR/<slug> ;
+ *  - produits de seed/products.csv (par handle) et images de seed/images.
+ * Aucun SQL : uniquement les workflows et services Medusa.
+ */
+import fs from "node:fs"
+import path from "node:path"
+import { parse } from "csv-parse/sync"
+import { CreateInventoryLevelInput, CreateProductWorkflowInputDTO, ExecArgs } from "@medusajs/framework/types"
+import { ContainerRegistrationKeys, Modules, ProductStatus } from "@medusajs/framework/utils"
+import {
+  createApiKeysWorkflow,
+  createInventoryLevelsWorkflow,
+  createPriceListsWorkflow,
+  createProductsWorkflow,
+  createRegionsWorkflow,
+  createSalesChannelsWorkflow,
+  createShippingOptionsWorkflow,
+  createShippingProfilesWorkflow,
+  createStockLocationsWorkflow,
+  createTaxRegionsWorkflow,
+  linkProductsToSalesChannelWorkflow,
+  linkSalesChannelsToApiKeyWorkflow,
+  linkSalesChannelsToStockLocationWorkflow,
+  updateRegionsWorkflow,
+  updateShippingOptionsWorkflow,
+  updateStoresWorkflow,
+  uploadFilesWorkflow,
+} from "@medusajs/medusa/core-flows"
+import { CONFIG_DIR, KEYS_DIR, SEED_DIR, countriesByCurrency, readProject, shippingRates } from "../lib/project"
+import { CAMPAIGN_MODULE } from "../modules/campaign"
+import CampaignModuleService from "../modules/campaign/service"
+import { CampaignFile, CampaignInput } from "../modules/campaign/validators"
+import { upsertCampaignWorkflow } from "../workflows/upsert-campaign"
+
+const LOCATION_NAME = "Entrepôt principal"
+const FULFILLMENT_SET_NAME = "Livraison"
+const SERVICE_ZONE_NAME = "Monde"
+
+export default async function seed({ container }: ExecArgs) {
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
+  const link = container.resolve(ContainerRegistrationKeys.LINK)
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+  const storeService = container.resolve(Modules.STORE)
+  const regionService = container.resolve(Modules.REGION)
+  const taxService = container.resolve(Modules.TAX)
+  const fulfillment = container.resolve(Modules.FULFILLMENT)
+  const salesChannels = container.resolve(Modules.SALES_CHANNEL)
+  const apiKeys = container.resolve(Modules.API_KEY)
+  const stockLocations = container.resolve(Modules.STOCK_LOCATION)
+  const productService = container.resolve(Modules.PRODUCT)
+
+  const project = readProject()
+  const currencies = [...new Set([project.defaultCurrency, ...project.boutiques.map((b) => b.currency)])]
+  logger.info(`[seed] projet ${project.project} : ${project.boutiques.length} boutique(s), devises ${currencies.join(", ")}`)
+
+  // ---------- Store : devises ----------
+  const [store] = await storeService.listStores({}, { relations: ["supported_currencies"] })
+  const knownCurrencies = new Set(store.supported_currencies?.map((c) => c.currency_code))
+  if (currencies.some((c) => !knownCurrencies.has(c)) || !store.supported_currencies?.find((c) => c.is_default && c.currency_code === project.defaultCurrency)) {
+    await updateStoresWorkflow(container).run({
+      input: {
+        selector: { id: store.id },
+        update: {
+          name: project.boutiques[0].storeName,
+          supported_currencies: currencies.map((c) => ({ currency_code: c, is_default: c === project.defaultCurrency })),
+        },
+      },
+    })
+  }
+
+  // ---------- Régions : une par devise ----------
+  const allCountries = (await regionService.listCountries({}, { take: 500 })).map((c) => c.iso_2)
+  const target = countriesByCurrency(project, allCountries)
+  const paymentProviders = ["pp_system_default", ...(process.env.STRIPE_API_KEY ? ["pp_stripe_stripe"] : [])]
+  const existing = await regionService.listRegions({}, { relations: ["countries"] })
+  const managed = new Map(existing.filter((r) => currencies.includes(r.currency_code) && r.name === r.currency_code.toUpperCase()).map((r) => [r.currency_code, r]))
+
+  // Pays pris par une région que le seed ne gère pas : erreur claire plutôt qu'un échec obscur.
+  for (const r of existing) {
+    if (managed.get(r.currency_code)?.id === r.id) continue
+    const taken = (r.countries ?? []).map((c) => c.iso_2).filter((c) => [...target.values()].some((s) => s.has(c)))
+    if (taken.length) {
+      throw new Error(`la région « ${r.name} » (non gérée par le seed) contient ${taken.join(", ")} : retirez ces pays dans l'admin ou supprimez la région.`)
+    }
+  }
+
+  // 1) rétrécir les régions existantes (libère les pays qui changent de devise), 2) compléter / créer.
+  for (const [currency, region] of managed) {
+    const keep = (region.countries ?? []).map((c) => c.iso_2).filter((c) => target.get(currency)?.has(c))
+    if (keep.length !== (region.countries ?? []).length) {
+      await updateRegionsWorkflow(container).run({ input: { selector: { id: region.id }, update: { countries: keep } } })
+    }
+  }
+  for (const [currency, countries] of target) {
+    const region = managed.get(currency)
+    if (region) {
+      await updateRegionsWorkflow(container).run({
+        input: { selector: { id: region.id }, update: { countries: [...countries], payment_providers: paymentProviders } },
+      })
+    } else {
+      await createRegionsWorkflow(container).run({
+        input: { regions: [{ name: currency.toUpperCase(), currency_code: currency, countries: [...countries], payment_providers: paymentProviders }] },
+      })
+    }
+    logger.info(`[seed] région ${currency.toUpperCase()} : ${countries.size} pays`)
+  }
+  const shippedCountries = [...target.values()].flatMap((s) => [...s])
+
+  // ---------- Taxes : une région de taxe par pays (0 % par défaut, réglable dans l'admin) ----------
+  const taxed = new Set((await taxService.listTaxRegions({}, { take: 5000 })).filter((t) => !t.parent_id).map((t) => t.country_code))
+  const untaxed = shippedCountries.filter((c) => !taxed.has(c))
+  if (untaxed.length) {
+    await createTaxRegionsWorkflow(container).run({ input: untaxed.map((country_code) => ({ country_code, provider_id: "tp_system" })) })
+  }
+
+  // ---------- Entrepôt ----------
+  let [location] = await stockLocations.listStockLocations({ name: LOCATION_NAME })
+  if (!location) {
+    const { result } = await createStockLocationsWorkflow(container).run({
+      input: { locations: [{ name: LOCATION_NAME, address: { country_code: project.boutiques[0].country.toUpperCase(), address_1: "" } }] },
+    })
+    location = result[0]
+    await link.create({ [Modules.STOCK_LOCATION]: { stock_location_id: location.id }, [Modules.FULFILLMENT]: { fulfillment_provider_id: "manual_manual" } })
+    await updateStoresWorkflow(container).run({ input: { selector: { id: store.id }, update: { default_location_id: location.id } } })
+  }
+
+  // ---------- Livraison : zone « Monde » + options par devise ----------
+  let [profile] = await fulfillment.listShippingProfiles({ type: "default" })
+  if (!profile) {
+    const { result } = await createShippingProfilesWorkflow(container).run({ input: { data: [{ name: "Default Shipping Profile", type: "default" }] } })
+    profile = result[0]
+  }
+  let [fset] = await fulfillment.listFulfillmentSets({ name: FULFILLMENT_SET_NAME }, { relations: ["service_zones", "service_zones.geo_zones"] })
+  if (!fset) {
+    fset = await fulfillment.createFulfillmentSets({ name: FULFILLMENT_SET_NAME, type: "shipping", service_zones: [{ name: SERVICE_ZONE_NAME, geo_zones: [] }] })
+    await link.create({ [Modules.STOCK_LOCATION]: { stock_location_id: location.id }, [Modules.FULFILLMENT]: { fulfillment_set_id: fset.id } })
+    ;[fset] = await fulfillment.listFulfillmentSets({ id: fset.id }, { relations: ["service_zones", "service_zones.geo_zones"] })
+  }
+  const zone = fset.service_zones[0]
+  const zoned = new Set(zone.geo_zones.map((g) => g.country_code))
+  const missingZones = shippedCountries.filter((c) => !zoned.has(c))
+  if (missingZones.length) {
+    await fulfillment.createGeoZones(missingZones.map((country_code) => ({ service_zone_id: zone.id, country_code, type: "country" as const })))
+  }
+
+  const { data: options } = await query.graph({
+    entity: "shipping_option",
+    fields: ["id", "name", "prices.*"],
+    filters: { service_zone_id: zone.id },
+  })
+  const rules = [
+    { attribute: "enabled_in_store", value: "true", operator: "eq" as const },
+    { attribute: "is_return", value: "false", operator: "eq" as const },
+  ]
+  for (const [i, name, code, description] of [
+    [0, "Standard", "standard", "3-7 business days"],
+    [1, "Express", "express", "1-3 business days"],
+  ] as const) {
+    // Prix liés via le module Pricing : demandés par query.graph mais absents du type généré.
+    const option = options.find((o) => o.name === name) as
+      | { id: string; prices?: { id: string; amount: number; currency_code: string }[] }
+      | undefined
+    if (!option) {
+      await createShippingOptionsWorkflow(container).run({
+        input: [
+          {
+            name,
+            price_type: "flat",
+            provider_id: "manual_manual",
+            service_zone_id: zone.id,
+            shipping_profile_id: profile.id,
+            type: { label: name, description, code },
+            prices: currencies.map((c) => ({ currency_code: c, amount: shippingRates(c)[i] })),
+            rules,
+          },
+        ],
+      })
+    } else {
+      const priced = new Set((option.prices ?? []).map((p) => p.currency_code))
+      const add = currencies.filter((c) => !priced.has(c))
+      if (add.length) {
+        await updateShippingOptionsWorkflow(container).run({
+          input: [
+            {
+              id: option.id,
+              prices: [
+                ...(option.prices ?? []).map((p) => ({ id: p.id, amount: p.amount })),
+                ...add.map((c) => ({ currency_code: c, amount: shippingRates(c)[i] })),
+              ],
+            },
+          ],
+        })
+      }
+    }
+  }
+
+  // ---------- Boutiques : sales channel + publishable key ----------
+  fs.mkdirSync(KEYS_DIR, { recursive: true })
+  const channelIds: Record<string, string> = {}
+  for (const b of project.boutiques) {
+    let [channel] = await salesChannels.listSalesChannels({ name: b.slug })
+    if (!channel) {
+      const { result } = await createSalesChannelsWorkflow(container).run({
+        input: { salesChannelsData: [{ name: b.slug, description: `${b.storeName} — ${b.theme}` }] },
+      })
+      channel = result[0]
+      await linkSalesChannelsToStockLocationWorkflow(container).run({ input: { id: location.id, add: [channel.id] } })
+      // Boutique ajoutée à un projet existant : elle reçoit tout le catalogue déjà en base
+      // (le marchand retire ensuite dans l'admin ce qu'il ne veut pas y vendre).
+      const existingProducts = await productService.listProducts({}, { select: ["id"], take: 10000 })
+      if (existingProducts.length) {
+        await linkProductsToSalesChannelWorkflow(container).run({
+          input: { id: channel.id, add: existingProducts.map((pr) => pr.id) },
+        })
+        logger.info(`[seed] boutique ${b.slug} : ${existingProducts.length} produit(s) existant(s) ajouté(s)`)
+      }
+      logger.info(`[seed] boutique ${b.slug} : sales channel créé`)
+    }
+    channelIds[b.slug] = channel.id
+
+    let [key] = await apiKeys.listApiKeys({ title: b.slug, type: "publishable" })
+    if (!key) {
+      const { result } = await createApiKeysWorkflow(container).run({
+        input: { api_keys: [{ title: b.slug, type: "publishable", created_by: "" }] },
+      })
+      key = result[0]
+      await linkSalesChannelsToApiKeyWorkflow(container).run({ input: { id: key.id, add: [channel.id] } })
+    }
+    fs.writeFileSync(path.join(KEYS_DIR, b.slug), key.token)
+  }
+  if (!store.default_sales_channel_id) {
+    await updateStoresWorkflow(container).run({
+      input: { selector: { id: store.id }, update: { default_sales_channel_id: channelIds[project.boutiques[0].slug] } },
+    })
+  }
+
+  // ---------- Campagnes : valeur initiale depuis config/campaigns/<slug>.json ----------
+  // Importée seulement si la boutique n'a pas encore de campagne : une campagne modifiée
+  // dans l'admin (source de vérité = base) n'est jamais écrasée.
+  const campaigns: CampaignModuleService = container.resolve(CAMPAIGN_MODULE)
+  const withCampaign = new Set(
+    (await campaigns.listBoutiqueCampaigns({ sales_channel_id: Object.values(channelIds) })).map((c) => c.sales_channel_id)
+  )
+  for (const b of project.boutiques) {
+    if (withCampaign.has(channelIds[b.slug])) continue
+    const file = path.join(CONFIG_DIR, "campaigns", `${b.slug}.json`)
+    if (!fs.existsSync(file)) {
+      logger.warn(`[seed] ${b.slug} : pas de fichier de campagne (${file})`)
+      continue
+    }
+    const raw = CampaignFile.parse(JSON.parse(fs.readFileSync(file, "utf8")))
+    // Images du fichier (seed/images/<nom> ou URL) envoyées au stockage.
+    const { image, ...hero } = raw.hero ?? {}
+    const { image: promoFile, ...promo } = raw.promo ?? {}
+    const upload = (name?: string) => (name ? uploadSeedImage(container, name) : Promise.resolve(undefined))
+    const campaign = CampaignInput.parse({
+      ...raw,
+      hero: raw.hero ? hero : undefined,
+      promo: raw.promo ? promo : undefined,
+      heroImage: await upload(image),
+      promoImage: await upload(promoFile),
+      logo: await upload(raw.logo),
+    })
+    await upsertCampaignWorkflow(container).run({ input: { sales_channel_id: channelIds[b.slug], campaign } })
+    logger.info(`[seed] ${b.slug} : campagne importée`)
+  }
+
+  // ---------- Produits : seed/products.csv ----------
+  await importProducts({ container, logger, currencies, channelIds, locationId: location.id, profileId: profile.id, productService })
+
+  logger.info("[seed] terminé")
+}
+
+/** Envoie seed/images/<nom> au stockage et renvoie son URL (URL http(s) renvoyée telle quelle). */
+async function uploadSeedImage(container: ExecArgs["container"], name: string): Promise<string | undefined> {
+  if (/^https?:\/\//.test(name)) return name
+  const file = path.join(SEED_DIR, "images", path.basename(name))
+  if (!fs.existsSync(file)) return undefined
+  const ext = path.extname(file).slice(1).toLowerCase()
+  const { result } = await uploadFilesWorkflow(container).run({
+    input: {
+      files: [
+        {
+          filename: path.basename(file),
+          mimeType: `image/${ext === "jpg" ? "jpeg" : ext}`,
+          content: fs.readFileSync(file).toString("base64"),
+          access: "public",
+        },
+      ],
+    },
+  })
+  return result[0].url
+}
+
+type Row = Record<string, string>
+
+async function importProducts({
+  container,
+  logger,
+  currencies,
+  channelIds,
+  locationId,
+  profileId,
+  productService,
+}: {
+  container: ExecArgs["container"]
+  logger: { info: (m: string) => void; warn: (m: string) => void }
+  currencies: string[]
+  channelIds: Record<string, string>
+  locationId: string
+  profileId: string
+  productService: { listProducts: (f: { handle: string[] }, c: { select: string[] }) => Promise<{ handle: string }[]> }
+}) {
+  const csvFile = path.join(SEED_DIR, "products.csv")
+  if (!fs.existsSync(csvFile)) {
+    logger.info("[seed] pas de seed/products.csv : aucun produit importé")
+    return
+  }
+  const rows: Row[] = parse(fs.readFileSync(csvFile, "utf8"), { columns: true, skip_empty_lines: true, trim: true, bom: true })
+  const existing = new Set((await productService.listProducts({ handle: rows.map((r) => r.handle) }, { select: ["handle"] })).map((p) => p.handle))
+  const toCreate = rows.filter((r) => r.handle && !existing.has(r.handle))
+  if (!toCreate.length) return
+
+  // Images : fichiers de seed/images envoyés au stockage ; URL http(s) gardées telles quelles.
+  const uploaded = new Map<string, string>()
+  const imageUrl = async (name: string): Promise<string | undefined> => {
+    if (uploaded.has(name)) return uploaded.get(name)
+    const url = await uploadSeedImage(container, name)
+    if (url) uploaded.set(name, url)
+    else logger.warn(`[seed] image introuvable : ${path.join(SEED_DIR, "images", path.basename(name))}`)
+    return url
+  }
+
+  const salePrices: { variantKey: string; currency_code: string; amount: number }[] = []
+  const products: CreateProductWorkflowInputDTO[] = []
+  for (const r of toCreate) {
+    const missing = currencies.filter((c) => !r[`price_${c}`])
+    if (missing.length) logger.warn(`[seed] ${r.handle} : pas de prix en ${missing.join(", ")} (colonne price_<devise>) — invisible dans ces boutiques`)
+
+    const images = (await Promise.all((r.images || "").split("|").filter(Boolean).map(imageUrl))).filter((u): u is string => !!u)
+    const optionTitle = r.variant_option || "Default option"
+    const values = r.variant_values ? r.variant_values.split("|").map((v) => v.trim()) : ["Default option value"]
+    const boutiques = r.boutiques ? r.boutiques.split("|").map((s) => s.trim()) : Object.keys(channelIds)
+
+    const prices = Object.keys(r)
+      .filter((k) => /^price_[a-z]{3}$/.test(k) && r[k])
+      .map((k) => {
+        const currency_code = k.slice(6)
+        const price = Number(r[k])
+        const compareAt = Number(r[`compare_at_price_${currency_code}`] || 0)
+        // Prix barré : le prix de base est le prix « avant », le prix réel passe par une price list « sale ».
+        if (compareAt > price) {
+          for (const v of values) salePrices.push({ variantKey: `${r.handle}::${v}`, currency_code, amount: price })
+          return { currency_code, amount: compareAt }
+        }
+        return { currency_code, amount: price }
+      })
+
+    products.push({
+      title: r.title,
+      handle: r.handle,
+      description: r.description,
+      status: ProductStatus.PUBLISHED,
+      shipping_profile_id: profileId,
+      thumbnail: images[0],
+      images: images.map((url) => ({ url })),
+      options: [{ title: optionTitle, values }],
+      variants: values.map((v) => ({
+        title: v,
+        sku: `${r.handle}-${v}`.toUpperCase().replace(/[^A-Z0-9]+/g, "-"),
+        options: { [optionTitle]: v },
+        manage_inventory: true,
+        prices,
+      })),
+      sales_channels: boutiques.filter((s) => channelIds[s]).map((s) => ({ id: channelIds[s] })),
+    })
+  }
+
+  const { result: created } = await createProductsWorkflow(container).run({ input: { products } })
+  logger.info(`[seed] ${created.length} produit(s) importé(s)`)
+
+  // Stock initial (colonne stock, 100 par défaut)
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+  const { data: variants } = await query.graph({
+    entity: "product_variant",
+    fields: ["id", "title", "product.handle", "inventory_items.inventory_item_id"],
+    filters: { product_id: created.map((p) => p.id) },
+  })
+  const stockOf = new Map(toCreate.map((r) => [r.handle, Number(r.stock || 100)]))
+  const levels: CreateInventoryLevelInput[] = variants.flatMap((v) =>
+    (v.inventory_items ?? []).map((i) => ({ location_id: locationId, inventory_item_id: i!.inventory_item_id, stocked_quantity: stockOf.get(v.product!.handle) ?? 100 }))
+  )
+  if (levels.length) await createInventoryLevelsWorkflow(container).run({ input: { inventory_levels: levels } })
+
+  // Prix promo (compare_at_price_*) : une price list « sale » pour les produits importés
+  if (salePrices.length) {
+    const variantId = new Map(variants.map((v) => [`${v.product!.handle}::${v.title}`, v.id]))
+    await createPriceListsWorkflow(container).run({
+      input: {
+        price_lists_data: [
+          {
+            title: `Promotions (import ${new Date().toISOString().slice(0, 10)})`,
+            description: "Prix barrés importés depuis seed/products.csv",
+            status: "active",
+            prices: salePrices
+              .filter((p) => variantId.has(p.variantKey))
+              .map((p) => ({ variant_id: variantId.get(p.variantKey)!, currency_code: p.currency_code, amount: p.amount })),
+          },
+        ],
+      },
+    })
+  }
+}

package/templates/backend/src/scripts/storage.ts

@@ -0,0 +1,63 @@
+/**
+ * Stockage des images (RustFS, compatible S3) : crée le bucket s'il manque et le rend
+ * lisible publiquement (lecture seule ; l'écriture exige les identifiants du backend).
+ * Idempotent, lancé par docker/entrypoint.sh avant le seed. Sans S3_ENDPOINT : rien à faire.
+ */
+import { ExecArgs } from "@medusajs/framework/types"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+import {
+  CreateBucketCommand,
+  HeadBucketCommand,
+  PutBucketPolicyCommand,
+  S3Client,
+} from "@aws-sdk/client-s3"
+
+export default async function storage({ container }: ExecArgs) {
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
+  const endpoint = process.env.S3_ENDPOINT
+  if (!endpoint) {
+    logger.info("[storage] S3_ENDPOINT absent : stockage local, rien à préparer")
+    return
+  }
+
+  const bucket = process.env.S3_BUCKET || "medusa"
+  const s3 = new S3Client({
+    endpoint,
+    region: process.env.S3_REGION || "us-east-1",
+    forcePathStyle: true,
+    credentials: {
+      accessKeyId: process.env.S3_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
+    },
+  })
+
+  // Le stockage peut démarrer un peu après le backend : quelques essais avant d'abandonner.
+  for (let attempt = 1; ; attempt++) {
+    try {
+      await s3.send(new HeadBucketCommand({ Bucket: bucket }))
+      break
+    } catch (e) {
+      const status = (e as { $metadata?: { httpStatusCode?: number } }).$metadata?.httpStatusCode
+      if (status === 404) {
+        await s3.send(new CreateBucketCommand({ Bucket: bucket }))
+        logger.info(`[storage] bucket ${bucket} créé`)
+        break
+      }
+      if (attempt >= 20) throw e
+      await new Promise((r) => setTimeout(r, 2000))
+    }
+  }
+
+  await s3.send(
+    new PutBucketPolicyCommand({
+      Bucket: bucket,
+      Policy: JSON.stringify({
+        Version: "2012-10-17",
+        Statement: [
+          { Effect: "Allow", Principal: { AWS: ["*"] }, Action: ["s3:GetObject"], Resource: [`arn:aws:s3:::${bucket}/*`] },
+        ],
+      }),
+    })
+  )
+  logger.info(`[storage] bucket ${bucket} : lecture publique des fichiers`)
+}

package/templates/backend/src/subscribers/README.md

@@ -0,0 +1,61 @@
+# Custom subscribers
+
+Subscribers handle events emitted in the Medusa application.
+
+> Learn more about Subscribers in [this documentation](https://docs.medusajs.com/learn/fundamentals/events-and-subscribers).
+
+The subscriber is created in a TypeScript or JavaScript file under the `src/subscribers` directory.
+
+For example, create the file `src/subscribers/product-created.ts` with the following content:
+
+```ts
+import {
+  type SubscriberConfig,
+} from "@medusajs/framework"
+
+// subscriber function
+export default async function productCreateHandler() {
+  console.log("A product was created")
+}
+
+// subscriber config
+export const config: SubscriberConfig = {
+  event: "product.created",
+}
+```
+
+A subscriber file must export:
+
+- The subscriber function that is an asynchronous function executed whenever the associated event is triggered.
+- A configuration object defining the event this subscriber is listening to.
+
+## Subscriber Parameters
+
+A subscriber receives an object having the following properties:
+
+- `event`: An object holding the event's details. It has a `data` property, which is the event's data payload.
+- `container`: The Medusa container. Use it to resolve modules' main services and other registered resources.
+
+```ts
+import type {
+  SubscriberArgs,
+  SubscriberConfig,
+} from "@medusajs/framework"
+
+export default async function productCreateHandler({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const productId = data.id
+
+  const productModuleService = container.resolve("product")
+
+  const product = await productModuleService.retrieveProduct(productId)
+
+  console.log(`The product ${product.title} was created`)
+}
+
+export const config: SubscriberConfig = {
+  event: "product.created",
+}
+```

package/templates/backend/src/subscribers/account-emails.ts

@@ -0,0 +1,27 @@
+import { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { Modules } from "@medusajs/framework/utils"
+import { adminUrl, sendAccountEmail } from "../lib/notify"
+
+type Payload = { entity_id?: string; actor_type?: string; token?: string; id?: string }
+
+/**
+ * Mot de passe oublié (admin) et invitation d'un membre de l'équipe.
+ * Medusa crée le jeton et émet l'événement ; ce subscriber envoie l'e-mail avec le lien.
+ */
+export default async function accountEmails({ event: { name, data }, container }: SubscriberArgs<Payload>) {
+  if (name === "auth.password_reset") {
+    // Les comptes clients des boutiques n'ont pas de page de réinitialisation : admin uniquement.
+    if (data.actor_type !== "user" || !data.entity_id || !data.token) return
+    await sendAccountEmail(container, data.entity_id, "password_reset", `${adminUrl()}/app/reset-password?token=${encodeURIComponent(data.token)}`)
+    return
+  }
+
+  if ((name === "invite.created" || name === "invite.resent") && data.id) {
+    const invite = await container.resolve(Modules.USER).retrieveInvite(data.id)
+    await sendAccountEmail(container, invite.email, "team_invite", `${adminUrl()}/app/invite?token=${encodeURIComponent(invite.token)}`)
+  }
+}
+
+export const config: SubscriberConfig = {
+  event: ["auth.password_reset", "invite.created", "invite.resent"],
+}

package/templates/backend/src/subscribers/fulfillment-emails.ts

@@ -0,0 +1,42 @@
+import { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+import { emailLabel } from "../lib/emails"
+import { sendOrderEmail } from "../lib/notify"
+import { readProject } from "../lib/project"
+
+/** Expédition créée (colis en route, avec suivi) ou livraison confirmée. */
+export default async function fulfillmentEmails({
+  event: { name, data },
+  container,
+}: SubscriberArgs<{ id: string; no_notification?: boolean }>) {
+  if (data.no_notification) return
+
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+  const { data: fulfillments } = await query.graph({
+    entity: "fulfillment",
+    fields: ["id", "labels.tracking_number", "labels.tracking_url", "order.id"],
+    filters: { id: data.id },
+  })
+  const f = fulfillments[0] as
+    | { order?: { id: string }; labels?: { tracking_number?: string; tracking_url?: string }[] }
+    | undefined
+  const orderId = f?.order?.id
+  if (!orderId) return
+
+  if (name === "delivery.created") {
+    await sendOrderEmail(container, orderId, "order_delivered")
+    return
+  }
+
+  const label = f.labels?.[0]
+  const language = readProject().language
+  const trackingUrl = label?.tracking_url && /^https?:\/\//.test(label.tracking_url) ? label.tracking_url : undefined
+  await sendOrderEmail(container, orderId, "order_shipped", {
+    extra: label?.tracking_number ? emailLabel(language, "order_shipped", "tracking").replace("{code}", label.tracking_number) : undefined,
+    button: trackingUrl ? { label: emailLabel(language, "order_shipped", "track"), url: trackingUrl } : undefined,
+  })
+}
+
+export const config: SubscriberConfig = {
+  event: ["shipment.created", "delivery.created"],
+}

package/templates/backend/src/subscribers/order-emails.ts

@@ -0,0 +1,12 @@
+import { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { sendOrderEmail } from "../lib/notify"
+
+/** Commande passée / annulée : e-mail au client (+ au marchand pour une nouvelle commande). */
+export default async function orderEmails({ event: { name, data }, container }: SubscriberArgs<{ id: string }>) {
+  if (name === "order.placed") await sendOrderEmail(container, data.id, "order_placed", { withItems: true })
+  if (name === "order.canceled") await sendOrderEmail(container, data.id, "order_canceled")
+}
+
+export const config: SubscriberConfig = {
+  event: ["order.placed", "order.canceled"],
+}

package/templates/backend/src/subscribers/return-refund-emails.ts

@@ -0,0 +1,50 @@
+import { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+import { sendOrderEmail } from "../lib/notify"
+import { readProject } from "../lib/project"
+
+type Payload = { id?: string; order_id?: string; return_id?: string }
+
+/** Retour demandé / reçu, remboursement effectué. */
+export default async function returnRefundEmails({ event: { name, data }, container }: SubscriberArgs<Payload>) {
+  if (name === "order.return_requested" && data.order_id) {
+    await sendOrderEmail(container, data.order_id, "return_requested")
+    return
+  }
+  if (name === "order.return_received" && data.order_id) {
+    await sendOrderEmail(container, data.order_id, "return_received")
+    return
+  }
+  if (name !== "payment.refunded" || !data.id) return
+
+  // Paiement → collection de paiement → commande ; montant = dernier remboursement.
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+  const { data: payments } = await query.graph({
+    entity: "payment",
+    fields: ["id", "currency_code", "refunds.amount", "refunds.created_at", "payment_collection.order.id"],
+    filters: { id: data.id },
+  })
+  const p = payments[0] as
+    | {
+        currency_code: string
+        refunds?: { amount: number; created_at: string }[]
+        payment_collection?: { order?: { id: string } }
+      }
+    | undefined
+  const orderId = p?.payment_collection?.order?.id
+  if (!orderId) return
+
+  const last = [...(p.refunds ?? [])].sort((a, b) => Date.parse(b.created_at) - Date.parse(a.created_at))[0]
+  const project = readProject()
+  const amount = last
+    ? new Intl.NumberFormat(`${project.language}-${project.boutiques[0].country.toUpperCase()}`, {
+        style: "currency",
+        currency: p.currency_code,
+      }).format(Number(last.amount))
+    : ""
+  await sendOrderEmail(container, orderId, "refund", { vars: { amount } })
+}
+
+export const config: SubscriberConfig = {
+  event: ["order.return_requested", "order.return_received", "payment.refunded"],
+}