docs: oas (#197)

Adds OpenAPI specification of Storefront and Admin APIs.
Updates docs project.

docs-util/fixture-gen/__tests__/admin/collection.js

@@ -0,0 +1,69 @@
+const { dropDatabase } = require("pg-god");
+const path = require("path");
+
+const setupServer = require("../../../helpers/setup-server");
+const { useApi } = require("../../../helpers/use-api");
+const { initDb } = require("../../../helpers/use-db");
+
+const adminSeeder = require("../../helpers/admin-seeder");
+const productSeeder = require("../../helpers/product-seeder");
+
+const fixtureWriter = require("../../utils/write-fixture").default;
+
+jest.setTimeout(30000);
+
+describe("/admin/collections", () => {
+  let medusaProcess;
+  let dbConnection;
+
+  beforeAll(async () => {
+    const cwd = path.resolve(path.join(__dirname, "..", ".."));
+    dbConnection = await initDb({ cwd });
+    medusaProcess = await setupServer({ cwd });
+  });
+
+  afterAll(async () => {
+    await dbConnection.close();
+    await dropDatabase({ databaseName: "medusa-fixtures" });
+
+    medusaProcess.kill();
+  });
+
+  describe("POST /admin/products", () => {
+    beforeEach(async () => {
+      try {
+        await adminSeeder(dbConnection);
+      } catch (err) {
+        console.log(err);
+        throw err;
+      }
+    });
+
+    afterEach(async () => {
+      const manager = dbConnection.manager;
+      await manager.query(`DELETE FROM "user"`);
+    });
+
+    it("creates a product", async () => {
+      const api = useApi();
+
+      const payload = {
+        title: "Summer Collection",
+        handle: "summer-collection",
+      };
+
+      const response = await api
+        .post("/admin/collections", payload, {
+          headers: {
+            Authorization: "Bearer test_token",
+          },
+        })
+        .catch((err) => {
+          console.log(err);
+        });
+      expect(response.status).toEqual(200);
+
+      fixtureWriter.addFixture("product_collection", response.data.collection);
+    });
+  });
+});

docs-util/fixture-gen/__tests__/admin/customer.js

@@ -0,0 +1,78 @@
+const path = require("path");
+const { dropDatabase } = require("pg-god");
+const { Customer, Address } = require("@medusajs/medusa");
+
+const setupServer = require("../../../helpers/setup-server");
+const { useApi } = require("../../../helpers/use-api");
+const { initDb } = require("../../../helpers/use-db");
+
+const adminSeeder = require("../../helpers/admin-seeder");
+
+const fixtureWriter = require("../../utils/write-fixture").default;
+
+jest.setTimeout(30000);
+
+describe("/admin/customers", () => {
+  let medusaProcess;
+  let dbConnection;
+
+  beforeAll(async () => {
+    const cwd = path.resolve(path.join(__dirname, "..", ".."));
+    dbConnection = await initDb({ cwd });
+    medusaProcess = await setupServer({ cwd });
+  });
+
+  afterAll(async () => {
+    await dbConnection.close();
+    await dropDatabase({ databaseName: "medusa-fixtures" });
+
+    medusaProcess.kill();
+  });
+
+  describe("GET /admin/customers", () => {
+    let id;
+
+    beforeEach(async () => {
+      try {
+        await adminSeeder(dbConnection);
+        const manager = dbConnection.manager;
+
+        const created = manager.create(Customer, {
+          email: "test1@email.com",
+        });
+
+        const newly = await manager.save(created);
+
+        id = newly.id;
+      } catch (err) {
+        console.log(err);
+        throw err;
+      }
+    });
+
+    afterEach(async () => {
+      const manager = dbConnection.manager;
+      await manager.query(`DELETE FROM "address"`);
+      await manager.query(`DELETE FROM "customer"`);
+      await manager.query(`DELETE FROM "user"`);
+    });
+
+    it("lists customers and query count", async () => {
+      const api = useApi();
+
+      const response = await api
+        .get(`/admin/customers/${id}`, {
+          headers: {
+            Authorization: "Bearer test_token",
+          },
+        })
+        .catch((err) => {
+          console.log(err);
+        });
+
+      expect(response.status).toEqual(200);
+
+      fixtureWriter.addFixture("customer", response.data.customer);
+    });
+  });
+});

docs-util/fixture-gen/__tests__/admin/discount.js

@@ -0,0 +1,82 @@
+const { dropDatabase } = require("pg-god");
+const path = require("path");
+const { Region } = require("@medusajs/medusa");
+
+const setupServer = require("../../../helpers/setup-server");
+const { useApi } = require("../../../helpers/use-api");
+const { initDb } = require("../../../helpers/use-db");
+
+const adminSeeder = require("../../helpers/admin-seeder");
+
+const fixtureWriter = require("../../utils/write-fixture").default;
+
+jest.setTimeout(30000);
+
+describe("/discounts", () => {
+  let medusaProcess;
+  let dbConnection;
+
+  beforeAll(async () => {
+    const cwd = path.resolve(path.join(__dirname, "..", ".."));
+    dbConnection = await initDb({ cwd });
+    medusaProcess = await setupServer({ cwd });
+  });
+
+  afterAll(async () => {
+    dbConnection.close();
+    await dropDatabase({ databaseName: "medusa-fixtures" });
+
+    medusaProcess.kill();
+  });
+
+  describe("POST /store/carts", () => {
+    let regId;
+    beforeEach(async () => {
+      await adminSeeder(dbConnection);
+      const manager = dbConnection.manager;
+      const created = manager.create(Region, {
+        id: "region",
+        name: "Test Region",
+        currency_code: "usd",
+        tax_rate: 0,
+      });
+      const newReg = await manager.save(created);
+      regId = newReg.id;
+    });
+
+    afterEach(async () => {
+      const manager = dbConnection.manager;
+      await manager.query(`DELETE FROM "discount"`);
+      await manager.query(`DELETE FROM "discount_rule"`);
+      await manager.query(`DELETE FROM "region"`);
+      await manager.query(`DELETE FROM "user"`);
+    });
+
+    it("creates a cart", async () => {
+      const api = useApi();
+
+      const getRes = await api.post(
+        `/admin/discounts`,
+        {
+          code: "10DISC",
+          rule: {
+            description: "10 Percent",
+            type: "percentage",
+            allocation: "total",
+            value: 10,
+          },
+          regions: [regId],
+        },
+        {
+          headers: {
+            Authorization: "Bearer test_token",
+          },
+        }
+      );
+      expect(getRes.status).toEqual(200);
+
+      fixtureWriter.addFixture("discount", getRes.data.discount);
+      fixtureWriter.addFixture("discount_rule", getRes.data.discount.rule);
+    });
+  });
+});

docs-util/fixture-gen/__tests__/admin/gift-card.js

@@ -0,0 +1,75 @@
+const { dropDatabase } = require("pg-god");
+const path = require("path");
+const { Region } = require("@medusajs/medusa");
+
+const setupServer = require("../../../helpers/setup-server");
+const { useApi } = require("../../../helpers/use-api");
+const { initDb } = require("../../../helpers/use-db");
+
+const adminSeeder = require("../../helpers/admin-seeder");
+
+const fixtureWriter = require("../../utils/write-fixture").default;
+
+jest.setTimeout(30000);
+
+describe("/discounts", () => {
+  let medusaProcess;
+  let dbConnection;
+
+  beforeAll(async () => {
+    const cwd = path.resolve(path.join(__dirname, "..", ".."));
+    dbConnection = await initDb({ cwd });
+    medusaProcess = await setupServer({ cwd });
+  });
+
+  afterAll(async () => {
+    dbConnection.close();
+    await dropDatabase({ databaseName: "medusa-fixtures" });
+
+    medusaProcess.kill();
+  });
+
+  describe("POST /admin/gift-cards", () => {
+    let regId;
+    beforeEach(async () => {
+      await adminSeeder(dbConnection);
+      const manager = dbConnection.manager;
+      const created = manager.create(Region, {
+        name: "Test Region",
+        currency_code: "usd",
+        tax_rate: 0,
+      });
+      const newReg = await manager.save(created);
+      regId = newReg.id;
+    });
+
+    afterEach(async () => {
+      const manager = dbConnection.manager;
+      await manager.query(`DELETE FROM "discount"`);
+      await manager.query(`DELETE FROM "discount_rule"`);
+      await manager.query(`DELETE FROM "gift_card"`);
+      await manager.query(`DELETE FROM "region"`);
+      await manager.query(`DELETE FROM "user"`);
+    });
+
+    it("creates a cart", async () => {
+      const api = useApi();
+
+      const getRes = await api.post(
+        `/admin/gift-cards`,
+        {
+          value: 1000,
+          region_id: regId,
+        },
+        {
+          headers: {
+            Authorization: "Bearer test_token",
+          },
+        }
+      );
+      expect(getRes.status).toEqual(200);
+
+      fixtureWriter.addFixture("gift_card", getRes.data.gift_card);
+    });
+  });
+});

docs-util/fixture-gen/__tests__/admin/notification.js

@@ -0,0 +1,73 @@
+const { dropDatabase } = require("pg-god");
+const path = require("path");
+const { Notification } = require("@medusajs/medusa");
+
+const setupServer = require("../../../helpers/setup-server");
+const { useApi } = require("../../../helpers/use-api");
+const { initDb } = require("../../../helpers/use-db");
+
+const orderSeeder = require("../../helpers/order-seeder");
+const adminSeeder = require("../../helpers/admin-seeder");
+
+const fixtureWriter = require("../../utils/write-fixture").default;
+
+jest.setTimeout(30000);
+
+describe("/admin/orders", () => {
+  let medusaProcess;
+  let dbConnection;
+
+  beforeAll(async () => {
+    const cwd = path.resolve(path.join(__dirname, "..", ".."));
+    dbConnection = await initDb({ cwd });
+    medusaProcess = await setupServer({ cwd });
+  });
+
+  afterAll(async () => {
+    await dbConnection.close();
+    await dropDatabase({ databaseName: "medusa-fixtures" });
+
+    medusaProcess.kill();
+  });
+
+  describe("GET /notifications", () => {
+    beforeEach(async () => {
+      try {
+        await adminSeeder(dbConnection);
+        const manager = dbConnection.manager;
+
+        const noti = manager.create(Notification, {
+          event_name: "order.placed",
+          resource_type: "order",
+          resource_id: "order_01F0BF66ZBXNJ98WDQ9SCWH8Y7",
+          provider_id: "test-not",
+          data: {},
+          to: "test@email.com",
+        });
+        await manager.save(noti);
+      } catch (err) {
+        console.log(err);
+        throw err;
+      }
+    });
+
+    afterEach(async () => {
+      const manager = dbConnection.manager;
+      await manager.query(`DELETE FROM "notification"`);
+      await manager.query(`DELETE FROM "user"`);
+    });
+
+    it("creates a claim", async () => {
+      const api = useApi();
+
+      const response = await api.get(`/admin/notifications`, {
+        headers: {
+          authorization: "Bearer test_token",
+        },
+      });
+      expect(response.status).toEqual(200);
+
+      fixtureWriter.addFixture("notification", response.data.notifications[0]);
+    });
+  });
+});

docs-util/fixture-gen/__tests__/admin/order.js

@@ -0,0 +1,164 @@
+const { dropDatabase } = require("pg-god");
+const path = require("path");
+
+const setupServer = require("../../../helpers/setup-server");
+const { useApi } = require("../../../helpers/use-api");
+const { initDb } = require("../../../helpers/use-db");
+
+const orderSeeder = require("../../helpers/order-seeder");
+const adminSeeder = require("../../helpers/admin-seeder");
+
+const fixtureWriter = require("../../utils/write-fixture").default;
+
+jest.setTimeout(30000);
+
+describe("/admin/orders", () => {
+  let medusaProcess;
+  let dbConnection;
+
+  beforeAll(async () => {
+    const cwd = path.resolve(path.join(__dirname, "..", ".."));
+    dbConnection = await initDb({ cwd });
+    medusaProcess = await setupServer({ cwd });
+  });
+
+  afterAll(async () => {
+    await dbConnection.close();
+    await dropDatabase({ databaseName: "medusa-fixtures" });
+
+    medusaProcess.kill();
+  });
+
+  describe("GET /admin/orders/:id", () => {
+    let id;
+    beforeEach(async () => {
+      try {
+        await adminSeeder(dbConnection);
+        const order = await orderSeeder(dbConnection);
+        id = order.id;
+      } catch (err) {
+        console.log(err);
+        throw err;
+      }
+    });
+
+    afterEach(async () => {
+      const manager = dbConnection.manager;
+      await manager.query(`DELETE FROM "cart"`);
+      await manager.query(`DELETE FROM "fulfillment_item"`);
+      await manager.query(`DELETE FROM "fulfillment"`);
+      await manager.query(`DELETE FROM "swap"`);
+      await manager.query(`DELETE FROM "return"`);
+      await manager.query(`DELETE FROM "claim_image"`);
+      await manager.query(`DELETE FROM "claim_tag"`);
+      await manager.query(`DELETE FROM "claim_item"`);
+      await manager.query(`DELETE FROM "shipping_method"`);
+      await manager.query(`DELETE FROM "line_item"`);
+      await manager.query(`DELETE FROM "claim_order"`);
+      await manager.query(`DELETE FROM "money_amount"`);
+      await manager.query(`DELETE FROM "product_option_value"`);
+      await manager.query(`DELETE FROM "product_option"`);
+      await manager.query(`DELETE FROM "product_variant"`);
+      await manager.query(`DELETE FROM "product"`);
+      await manager.query(`DELETE FROM "shipping_option"`);
+      await manager.query(`DELETE FROM "discount"`);
+      await manager.query(`DELETE FROM "payment"`);
+      await manager.query(`DELETE FROM "order"`);
+      await manager.query(`DELETE FROM "customer"`);
+      await manager.query(
+        `UPDATE "country" SET region_id=NULL WHERE iso_2 = 'us'`
+      );
+      await manager.query(`DELETE FROM "region"`);
+      await manager.query(`DELETE FROM "user"`);
+    });
+
+    it("creates a claim", async () => {
+      const api = useApi();
+
+      const response = await api.get(`/admin/orders/${id}`, {
+        headers: {
+          authorization: "Bearer test_token",
+        },
+      });
+      expect(response.status).toEqual(200);
+
+      fixtureWriter.addFixture("order", response.data.order);
+    });
+  });
+
+  describe("POST /admin/orders/:id/returns", () => {
+    let id;
+    beforeEach(async () => {
+      try {
+        await adminSeeder(dbConnection);
+        const order = await orderSeeder(dbConnection);
+        id = order.id;
+      } catch (err) {
+        console.log(err);
+        throw err;
+      }
+    });
+
+    afterEach(async () => {
+      const manager = dbConnection.manager;
+      await manager.query(`DELETE FROM "cart"`);
+      await manager.query(`DELETE FROM "fulfillment_item"`);
+      await manager.query(`DELETE FROM "fulfillment"`);
+      await manager.query(`DELETE FROM "swap"`);
+      await manager.query(`DELETE FROM "return_item"`);
+      await manager.query(`DELETE FROM "return"`);
+      await manager.query(`DELETE FROM "claim_image"`);
+      await manager.query(`DELETE FROM "claim_tag"`);
+      await manager.query(`DELETE FROM "claim_item"`);
+      await manager.query(`DELETE FROM "shipping_method"`);
+      await manager.query(`DELETE FROM "line_item"`);
+      await manager.query(`DELETE FROM "claim_order"`);
+      await manager.query(`DELETE FROM "money_amount"`);
+      await manager.query(`DELETE FROM "product_option_value"`);
+      await manager.query(`DELETE FROM "product_option"`);
+      await manager.query(`DELETE FROM "product_variant"`);
+      await manager.query(`DELETE FROM "product"`);
+      await manager.query(`DELETE FROM "shipping_option"`);
+      await manager.query(`DELETE FROM "discount"`);
+      await manager.query(`DELETE FROM "payment"`);
+      await manager.query(`DELETE FROM "order"`);
+      await manager.query(`DELETE FROM "customer"`);
+      await manager.query(
+        `UPDATE "country" SET region_id=NULL WHERE iso_2 = 'us'`
+      );
+      await manager.query(`DELETE FROM "region"`);
+      await manager.query(`DELETE FROM "user"`);
+    });
+
+    it("creates a return", async () => {
+      const api = useApi();
+
+      const { data } = await api.get(`/admin/orders/${id}`, {
+        headers: {
+          authorization: "Bearer test_token",
+        },
+      });
+      const order = data.order;
+
+      const response = await api.post(
+        `/admin/orders/${id}/return`,
+        {
+          items: [
+            {
+              item_id: order.items[0].id,
+              quantity: 1,
+            },
+          ],
+        },
+        {
+          headers: {
+            authorization: "Bearer test_token",
+          },
+        }
+      );
+      expect(response.status).toEqual(200);
+
+      fixtureWriter.addFixture("return", response.data.order.returns[0]);
+    });
+  });
+});

docs-util/fixture-gen/__tests__/admin/product.js

@@ -0,0 +1,110 @@
+const { dropDatabase } = require("pg-god");
+const path = require("path");
+
+const setupServer = require("../../../helpers/setup-server");
+const { useApi } = require("../../../helpers/use-api");
+const { initDb } = require("../../../helpers/use-db");
+
+const adminSeeder = require("../../helpers/admin-seeder");
+const productSeeder = require("../../helpers/product-seeder");
+
+const fixtureWriter = require("../../utils/write-fixture").default;
+
+jest.setTimeout(30000);
+
+describe("/admin/products", () => {
+  let medusaProcess;
+  let dbConnection;
+
+  beforeAll(async () => {
+    const cwd = path.resolve(path.join(__dirname, "..", ".."));
+    dbConnection = await initDb({ cwd });
+    medusaProcess = await setupServer({ cwd });
+  });
+
+  afterAll(async () => {
+    await dbConnection.close();
+    await dropDatabase({ databaseName: "medusa-fixtures" });
+
+    medusaProcess.kill();
+  });
+
+  describe("POST /admin/products", () => {
+    beforeEach(async () => {
+      try {
+        await productSeeder(dbConnection);
+        await adminSeeder(dbConnection);
+      } catch (err) {
+        console.log(err);
+        throw err;
+      }
+    });
+
+    afterEach(async () => {
+      const manager = dbConnection.manager;
+      await manager.query(`DELETE FROM "product_option_value"`);
+      await manager.query(`DELETE FROM "product_option"`);
+      await manager.query(`DELETE FROM "money_amount"`);
+      await manager.query(`DELETE FROM "product_variant"`);
+      await manager.query(`DELETE FROM "product"`);
+      await manager.query(`DELETE FROM "product_collection"`);
+      await manager.query(`DELETE FROM "product_tag"`);
+      await manager.query(`DELETE FROM "product_type"`);
+      await manager.query(
+        `UPDATE "country" SET region_id=NULL WHERE iso_2 = 'us'`
+      );
+      await manager.query(`DELETE FROM "region"`);
+      await manager.query(`DELETE FROM "user"`);
+    });
+
+    it("creates a product", async () => {
+      const api = useApi();
+
+      const payload = {
+        title: "Test product",
+        description: "test-product-description",
+        type: { value: "test-type" },
+        collection_id: "test-collection",
+        tags: [{ value: "123" }, { value: "456" }],
+        options: [{ title: "size" }, { title: "color" }],
+        variants: [
+          {
+            title: "Test variant",
+            inventory_quantity: 10,
+            prices: [{ currency_code: "usd", amount: 100 }],
+            options: [{ value: "large" }, { value: "green" }],
+          },
+        ],
+      };
+
+      const response = await api
+        .post("/admin/products", payload, {
+          headers: {
+            Authorization: "Bearer test_token",
+          },
+        })
+        .catch((err) => {
+          console.log(err);
+        });
+      expect(response.status).toEqual(200);
+
+      fixtureWriter.addFixture("product", response.data.product);
+      fixtureWriter.addFixture(
+        "product_variant",
+        response.data.product.variants[0]
+      );
+      fixtureWriter.addFixture(
+        "product_option",
+        response.data.product.options[0]
+      );
+      fixtureWriter.addFixture(
+        "product_option_value",
+        response.data.product.variants[0].options[0]
+      );
+      fixtureWriter.addFixture(
+        "money_amount",
+        response.data.product.variants[0].prices[0]
+      );
+    });
+  });
+});

docs-util/fixture-gen/__tests__/admin/shipping-option.js

@@ -0,0 +1,87 @@
+const { dropDatabase } = require("pg-god");
+const path = require("path");
+const { Region } = require("@medusajs/medusa");
+
+const setupServer = require("../../../helpers/setup-server");
+const { useApi } = require("../../../helpers/use-api");
+const { initDb } = require("../../../helpers/use-db");
+
+const adminSeeder = require("../../helpers/admin-seeder");
+
+const fixtureWriter = require("../../utils/write-fixture").default;
+
+jest.setTimeout(30000);
+
+describe("/shipping-options", () => {
+  let medusaProcess;
+  let dbConnection;
+
+  beforeAll(async () => {
+    const cwd = path.resolve(path.join(__dirname, "..", ".."));
+    dbConnection = await initDb({ cwd });
+    medusaProcess = await setupServer({ cwd });
+  });
+
+  afterAll(async () => {
+    dbConnection.close();
+    await dropDatabase({ databaseName: "medusa-fixtures" });
+
+    medusaProcess.kill();
+  });
+
+  describe("POST /admin/shipping-options", () => {
+    let regId;
+    beforeEach(async () => {
+      await adminSeeder(dbConnection);
+      const manager = dbConnection.manager;
+      const created = manager.create(Region, {
+        name: "Test Region",
+        currency_code: "usd",
+        tax_rate: 0,
+        fulfillment_providers: [
+          {
+            id: "test-ful",
+          },
+        ],
+      });
+      const newReg = await manager.save(created);
+      regId = newReg.id;
+    });
+
+    afterEach(async () => {
+      const manager = dbConnection.manager;
+      await manager.query(`DELETE FROM "shipping_option"`);
+      await manager.query(`DELETE FROM "region"`);
+      await manager.query(`DELETE FROM "user"`);
+    });
+
+    it("creates a cart", async () => {
+      const api = useApi();
+
+      const getRes = await api.post(
+        `/admin/shipping-options`,
+        {
+          name: "Free Shipping",
+          region_id: regId,
+          provider_id: "test-ful",
+          data: {},
+          price_type: "flat_rate",
+          amount: 100,
+        },
+        {
+          headers: {
+            Authorization: "Bearer test_token",
+          },
+        }
+      );
+      expect(getRes.status).toEqual(200);
+
+      fixtureWriter.addFixture("region", getRes.data.shipping_option.region);
+      fixtureWriter.addFixture("shipping_option", getRes.data.shipping_option);
+      fixtureWriter.addFixture(
+        "shipping_profile",
+        getRes.data.shipping_option.shipping_profile
+      );
+    });
+  });
+});