medusa-strapi-plugin 0.0.13 → 0.0.16

package/src/modules/strapi/service.ts

@@ -0,0 +1,576 @@
+import {
+  Logger,
+  ProductCategoryDTO,
+  ProductCollectionDTO,
+  ProductDTO,
+  ProductVariantDTO,
+} from "@medusajs/framework/types";
+import { MedusaError } from "@medusajs/framework/utils";
+import qs from "qs";
+import { ModuleOptions } from "./loader/create-content-models";
+
+type InjectedDependencies = {
+  logger: Logger;
+};
+
+type EntryProps = {
+  documentId: string;
+  [key: string]: unknown;
+};
+
+enum StrapiEntity {
+  PRODUCT = "products",
+  VARIANT = "product-variants",
+  CATEGORY = "categories",
+  COLLECTION = "collections",
+  CATEGORY_ATTRIBUTE_DESCRIPTION = "category-attribute-descriptions",
+}
+
+export default class StrapiModuleService {
+  private options: ModuleOptions;
+  protected logger: Logger;
+  private systemIdKey: string;
+
+  constructor({ logger }: InjectedDependencies, options: ModuleOptions) {
+    this.logger = logger;
+    this.options = {
+      ...options,
+      default_locale: options.default_locale || "en",
+      system_id_key: options.system_id_key || "systemId",
+    };
+
+    this.systemIdKey = (this.options.system_id_key ?? "systemId").trim();
+  }
+
+  static validateOptions(options: ModuleOptions) {
+    if (!options.base_url || !options.api_key) {
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        "Strapi base URL and API key are required",
+      );
+    }
+  }
+
+  /**
+   * Makes an API request to Strapi.
+   */
+  private async makeRequest<T>(
+    endpoint: string,
+    options: Omit<RequestInit, "headers"> = {},
+  ): Promise<T> {
+    const url = `${this.options.base_url}/${endpoint}`;
+    try {
+      const response = await fetch(url, {
+        headers: {
+          Authorization: `Bearer ${this.options.api_key}`,
+          "Content-Type": "application/json",
+        },
+        ...options,
+      });
+
+      if (!response.ok) {
+        let errorDetails = `HTTP ${response.status} ${response.statusText}`;
+        try {
+          const errorResponse = await response.json();
+          if (errorResponse.error) {
+            errorDetails += ` - ${JSON.stringify(errorResponse.error)}`;
+            this.logger.error(
+              `Strapi API request failed for ${url}:`,
+              errorResponse,
+            );
+          }
+        } catch (parseError) {
+          this.logger.error(
+            "Failed to parse error response from Strapi",
+            parseError as Error,
+          );
+        }
+        throw new Error(errorDetails);
+      }
+
+      const responseData = await response.json();
+      const { data, error } = responseData;
+
+      if (error) {
+        this.logger.error(`Strapi API returned error for ${url}:`, error);
+        this.logger.error("Full response:", responseData);
+        throw new Error(error.message || JSON.stringify(error));
+      }
+
+      return data as T;
+    } catch (error) {
+      this.logger.error(`API request failed: ${url}`, error as Error);
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        `API request failed: ${(error as Error).message || error}`,
+      );
+    }
+  }
+
+  /**
+   * Fetches an entity by its system ID.
+   */
+  private async getEntityBySystemId<T = Pick<EntryProps, "documentId">>(
+    entity: string,
+    systemId: string,
+    options?: Record<string, unknown>,
+    draftAndPublish: boolean = true,
+  ): Promise<T | undefined> {
+    this.logger.debug(`Fetching entity ${entity} with systemId: ${systemId}`);
+
+    try {
+      const params = qs.stringify({
+        filters: { [this.systemIdKey]: { $eq: systemId } },
+        fields: ["documentId"],
+        ...(draftAndPublish ? { status: "draft" } : {}),
+        ...options,
+      });
+
+      const result = await this.makeRequest<EntryProps[]>(
+        `${entity}?${params}`,
+      );
+
+      return result?.[0] as T;
+    } catch (error) {
+      this.logger.error(
+        `Failed to fetch ${entity} with systemId: ${systemId}`,
+        error as Error,
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Creates a new entry in the specified Strapi entity.
+   */
+  private async createEntry(
+    entity: string,
+    payload: Record<
+      string,
+      string | number | boolean | null | undefined | string[]
+    >,
+    draftAndPublish: boolean = true,
+  ): Promise<EntryProps> {
+    this.logger.debug(`Creating ${entity} in Strapi`);
+
+    try {
+      const queryString = draftAndPublish
+        ? `?${qs.stringify({ status: "draft" })}`
+        : "";
+
+      return await this.makeRequest<EntryProps>(`${entity}${queryString}`, {
+        method: "POST",
+        body: JSON.stringify({
+          data: {
+            ...payload,
+          },
+        }),
+      });
+    } catch (error) {
+      this.logger.error(`Failed to create ${entity} in Strapi`, error as Error);
+      throw error;
+    }
+  }
+
+  /**
+   * Updates an existing entry in the specified Strapi entity.
+   */
+  private async updateEntry(
+    entity: string,
+    documentId: string,
+    payload: Record<
+      string,
+      string | number | boolean | null | undefined | string[]
+    >,
+  ): Promise<EntryProps> {
+    this.logger.debug(`Updating ${entity} with documentId: ${documentId}`);
+
+    try {
+      return await this.makeRequest<EntryProps>(`${entity}/${documentId}`, {
+        method: "PUT",
+        body: JSON.stringify({ data: payload }),
+      });
+    } catch (error) {
+      this.logger.error(`Failed to update ${entity} in Strapi`, error as Error);
+      throw error;
+    }
+  }
+
+  /**
+   * Deletes an entry in the specified Strapi entity.
+   */
+  /**
+   * Deletes an entry in the specified Strapi entity.
+   */
+  async deleteEntry(entity: string, documentId: string) {
+    try {
+      return await this.makeRequest(`${entity}/${documentId}`, {
+        method: "DELETE",
+      });
+    } catch (error) {
+      this.logger.error(`Failed to delete ${entity} in Strapi`, error as Error);
+      throw error;
+    }
+  }
+
+  /**
+   * Generic method to upsert an entity
+   */
+  async upsertEntity(
+    entity: string,
+    systemId: string,
+    createPayload: Record<
+      string,
+      string | number | boolean | null | undefined | string[]
+    >,
+    updatePayload: Record<
+      string,
+      string | number | boolean | null | undefined | string[]
+    >,
+    draftAndPublish: boolean = true,
+  ): Promise<EntryProps> {
+    const entry = await this.getEntityBySystemId(
+      entity,
+      systemId,
+      undefined,
+      draftAndPublish,
+    );
+
+    if (!entry) {
+      this.logger.debug(`No ${entity} found with ID: ${systemId}, creating it`);
+      return await this.createEntry(entity, createPayload, draftAndPublish);
+    }
+
+    this.logger.debug(`Updating ${entity} with ID: ${systemId}`);
+    return await this.updateEntry(entity, entry.documentId, updatePayload);
+  }
+
+  /**
+   * Auto-populates attribute description relations on a category if they don't exist
+   */
+  async populateCategoryOverrides(
+    categoryDocumentId: string,
+    attributeValueDocumentIds: string[],
+  ): Promise<void> {
+    if (!attributeValueDocumentIds.length) return;
+
+    try {
+      // 1. Fetch the category with its current descriptions populated
+      const category: any = await this.makeRequest(
+        `${StrapiEntity.CATEGORY}/${categoryDocumentId}?populate=attribute_descriptions.attribute_value`,
+      );
+
+      if (!category) return;
+
+      const existingDescriptions = category.attribute_descriptions || [];
+
+      // 2. Determine which attribute values are missing
+      const existingAttributeValueIds = existingDescriptions
+        .map((desc: any) => desc.attribute_value?.documentId)
+        .filter(Boolean);
+
+      const missingAttributeValueIds = attributeValueDocumentIds.filter(
+        (id) => !existingAttributeValueIds.includes(id),
+      );
+
+      if (missingAttributeValueIds.length === 0) {
+        this.logger.debug(
+          `No new descriptions needed for category ${categoryDocumentId}`,
+        );
+        return;
+      }
+
+      // 3. Create missing relations individually instead of updating the whole Category
+      await Promise.all(
+        missingAttributeValueIds.map((missingId) =>
+          this.createEntry(StrapiEntity.CATEGORY_ATTRIBUTE_DESCRIPTION, {
+            category: categoryDocumentId,
+            attribute_value: missingId,
+          }),
+        ),
+      );
+
+      this.logger.debug(
+        `Added ${missingAttributeValueIds.length} missing attribute descriptions to category ${categoryDocumentId}`,
+      );
+    } catch (error) {
+      this.logger.error(
+        `Failed to populate descriptions for category ${categoryDocumentId}`,
+        error as Error,
+      );
+    }
+  }
+
+  /**
+   * Lists entities based on the provided filter.
+   */
+  async list(filter: {
+    productId?: string | string[];
+    collectionId?: string | string[];
+    categoryId?: string | string[];
+    variantId?: string | string[];
+    context?: {
+      locale?: string;
+    };
+  }) {
+    let entity = StrapiEntity.PRODUCT;
+    let systemKey = "productId";
+    let systemId = filter.productId;
+
+    if (filter.collectionId) {
+      entity = StrapiEntity.COLLECTION;
+      systemKey = "collectionId";
+      systemId = filter.collectionId;
+    }
+    if (filter.categoryId) {
+      entity = StrapiEntity.CATEGORY;
+      systemKey = "categoryId";
+      systemId = filter.categoryId;
+    }
+
+    if (filter.variantId) {
+      entity = StrapiEntity.VARIANT;
+      systemKey = "variantId";
+      systemId = filter.variantId;
+    }
+
+    const systemIdFilter = Array.isArray(systemId) ? systemId : [systemId];
+    this.logger.debug(`Fetching entity ${entity} with ID: ${systemIdFilter}`);
+
+    if (!systemIdFilter.length) {
+      this.logger.debug(
+        `No system IDs provided for ${entity}, returning empty array`,
+      );
+      return [];
+    }
+
+    const params = qs.stringify({
+      filters: { [this.systemIdKey]: { $in: systemIdFilter } },
+      // locale: filter.context?.locale || this.options.default_locale,
+    });
+
+    const entries = await this.makeRequest<any[]>(`${entity}?${params}`);
+
+    return entries.map(({ [this.systemIdKey]: systemId, ...rest }) => ({
+      ...rest,
+      [systemKey]: systemId,
+    }));
+  }
+
+  /**
+   * Upserts a product in Strapi.
+   */
+  async upsertProduct(product: ProductDTO) {
+    const createPayload = {
+      [this.systemIdKey]: product.id,
+      title: product.title || "",
+      handle: product.handle || "",
+      productType: product.type?.value || "",
+    };
+
+    const updatePayload = {
+      handle: product.handle || "",
+      productType: product.type?.value || "",
+    };
+
+    const entry = await this.upsertEntity(
+      StrapiEntity.PRODUCT,
+      product.id,
+      createPayload,
+      updatePayload,
+    );
+
+    // Create variants if they exist
+    if (product.variants?.length) {
+      await this.upsertProductVariants(product.variants, entry);
+    }
+
+    return entry;
+  }
+
+  /**
+   * Deletes a product in Strapi.
+   */
+  async deleteProduct(productId: string) {
+    const productEntry = await this.getEntityBySystemId<EntryProps>(
+      StrapiEntity.PRODUCT,
+      productId,
+      { populate: "variants", fields: ["*"] },
+    );
+
+    if (!productEntry) {
+      this.logger.log(`No product found in Strapi ${productId}`);
+      return null;
+    }
+
+    await this.deleteEntry(StrapiEntity.PRODUCT, productEntry.documentId);
+
+    if (Array.isArray(productEntry.variants)) {
+      // Delete variants in parallel
+      await Promise.all(
+        productEntry.variants.map((v: EntryProps) =>
+          this.deleteEntry(StrapiEntity.VARIANT, v.documentId),
+        ),
+      );
+    }
+
+    return productId;
+  }
+
+  /**
+   * Upserts product variants for a given product entry.
+   */
+  private async upsertProductVariants(
+    variants: ProductVariantDTO[],
+    productEntry: EntryProps,
+  ) {
+    // Process variants in parallel
+    await Promise.all(
+      variants.map(async (variant) => {
+        const createPayload = {
+          [this.systemIdKey]: variant.id,
+          title: variant.title || "",
+          product: productEntry.documentId,
+          sku: variant.sku || "",
+        };
+
+        const updatePayload = {
+          product: productEntry.documentId,
+          sku: variant.sku || "",
+        };
+
+        await this.upsertEntity(
+          StrapiEntity.VARIANT,
+          variant.id,
+          createPayload,
+          updatePayload,
+        );
+      }),
+    );
+  }
+
+  /**
+   * Upserts a product variant in Strapi.
+   */
+  async upsertProductVariant(variant: ProductVariantDTO) {
+    const entry = await this.getEntityBySystemId(
+      StrapiEntity.VARIANT,
+      variant.id,
+    );
+
+    if (!entry) {
+      const productEntry = await this.getEntityBySystemId(
+        StrapiEntity.PRODUCT,
+        variant.product_id as string,
+      );
+
+      if (!productEntry) {
+        this.logger.log(
+          `No product found in Strapi (ID: ${variant.product_id}) — skipping creation of variant ${variant.id}`,
+        );
+        return null;
+      }
+
+      return await this.createEntry(StrapiEntity.VARIANT, {
+        [this.systemIdKey]: variant.id,
+        title: variant.title || "",
+        product: productEntry.documentId,
+        sku: variant.sku || "",
+      });
+    }
+
+    return await this.updateEntry(StrapiEntity.VARIANT, entry.documentId, {
+      sku: variant.sku || "",
+    });
+  }
+
+  /**
+   * Deletes a product variant in Strapi.
+   */
+  async deleteProductVariant(variantId: string) {
+    const entry = await this.getEntityBySystemId(
+      StrapiEntity.VARIANT,
+      variantId,
+    );
+
+    if (!entry) {
+      this.logger.log(`No product variant found in Strapi ${variantId}`);
+      return null;
+    }
+
+    await this.deleteEntry(StrapiEntity.VARIANT, entry.documentId);
+    return variantId;
+  }
+
+  /**
+   * Upserts a collection in Strapi.
+   */
+  async upsertCollection(collection: ProductCollectionDTO) {
+    return await this.upsertEntity(
+      StrapiEntity.COLLECTION,
+      collection.id,
+      {
+        [this.systemIdKey]: collection.id,
+        title: collection.title || "",
+        handle: collection.handle || "",
+      },
+      {
+        handle: collection.handle || "",
+      },
+    );
+  }
+
+  /**
+   * Deletes a collection in Strapi.
+   */
+  async deleteCollection(collectionId: string) {
+    const entry = await this.getEntityBySystemId(
+      StrapiEntity.COLLECTION,
+      collectionId,
+    );
+
+    if (!entry) {
+      this.logger.log(`No collection found in Strapi ${collectionId}`);
+      return null;
+    }
+
+    await this.deleteEntry(StrapiEntity.COLLECTION, entry.documentId);
+    return collectionId;
+  }
+
+  /**
+   * Upserts a product category in Strapi.
+   */
+  async upsertCategory(category: ProductCategoryDTO) {
+    return await this.upsertEntity(
+      StrapiEntity.CATEGORY,
+      category.id,
+      {
+        [this.systemIdKey]: category.id,
+        title: category.name || "",
+        handle: category.handle || "",
+      },
+      {
+        handle: category.handle || "",
+      },
+    );
+  }
+
+  /**
+   * Deletes a product category in Strapi.
+   */
+  async deleteCategory(categoryId: string) {
+    const entry = await this.getEntityBySystemId(
+      StrapiEntity.CATEGORY,
+      categoryId,
+    );
+
+    if (!entry) {
+      this.logger.log(`No category found in Strapi ${categoryId}`);
+      return null;
+    }
+
+    await this.deleteEntry(StrapiEntity.CATEGORY, entry.documentId);
+    return categoryId;
+  }
+}

package/src/providers/README.md

@@ -0,0 +1,30 @@
+## Module Providers
+
+You can create module providers, such as Notification or File Module Providers, under a sub-directory of this directory. For example, `src/providers/my-notification`.
+
+Then, you register them in the Medusa application as `plugin-name/providers/my-notification`:
+
+```ts
+module.exports = defineConfig({
+  // ...
+  modules: [
+    {
+      resolve: "@medusajs/medusa/notification",
+      options: {
+        providers: [
+          {
+            resolve: "@myorg/plugin-name/providers/my-notification",
+            id: "my-notification",
+            options: {
+              channels: ["email"],
+              // provider options...
+            },
+          },
+        ],
+      },
+    },
+  ],
+});
+```
+
+Learn more in [this documentation](https://docs.medusajs.com/learn/fundamentals/plugins/create).

package/src/subscribers/README.md

@@ -0,0 +1,54 @@
+# Custom Subscribers
+
+Subscribers handle events emitted in the Medusa application.
+
+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/src/subscribers/create-category.ts

@@ -0,0 +1,25 @@
+import {
+  type SubscriberArgs,
+  type SubscriberConfig,
+} from "@medusajs/framework";
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils";
+import { upsertCategoriesStrapiWorkflow } from "../workflows/upsert-categories-strapi";
+
+export default async function handleCategoryCreate({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER);
+
+  await upsertCategoriesStrapiWorkflow(container as any).run({
+    input: {
+      category_ids: [data.id],
+    },
+  });
+
+  logger.log("Category created in Strapi");
+}
+
+export const config: SubscriberConfig = {
+  event: "product-category.created",
+};

package/src/subscribers/create-collection.ts

@@ -0,0 +1,25 @@
+import {
+  type SubscriberArgs,
+  type SubscriberConfig,
+} from "@medusajs/framework";
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils";
+import { upsertCollectionsStrapiWorkflow } from "../workflows/upsert-collections-strapi";
+
+export default async function handleCollectionCreate({
+  event: { data },
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER);
+
+  await upsertCollectionsStrapiWorkflow(container as any).run({
+    input: {
+      collection_ids: [data.id],
+    },
+  });
+
+  logger.log("Collection created in Strapi");
+}
+
+export const config: SubscriberConfig = {
+  event: "product-collection.created",
+};