feat(oas): declare x-expanded-relations - Store #3482

patrick-medusajs · 2023-03-15T12:57:19Z

What

Declare x-expanded-relations on store responses

Why

Allows our codegen to alter generated types to better represent the shape of models included in responses when the backend augments the models with relations and/or calculated totals.

How

Consider defaultRelations in route bootstrapping. Include as relations.
Consider relations passes to services in controllers. Move to a defaultRelations const. Include as relations.
Consider relations in service sub-processes. Include as implicit.
Consider eager relations in TypeORM models. Include as eager.
Consider decoratedTotals fields. Include as totals

Extra scope:

Fix responses that are not respecting OAS response contract.

Tests

Run yarn install
Run yarn build
Open generated types in packages/generated/client-types/src/lib/models
Expect types decorate with x-expanded-relations to be mutated using SetRelation.
Expect Merge for be used for deeply nested relations.

vercel · 2023-03-15T12:57:23Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated
medusa-docs	✅ Ready (Inspect)	Visit Preview	💬 Add your feedback	Mar 15, 2023 at 8:39PM (UTC)

changeset-bot · 2023-03-15T12:57:38Z

🦋 Changeset detected

Latest commit: 1620375

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@medusajs/client-types	Patch
@medusajs/medusa	Patch
@medusajs/inventory	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

patrick-medusajs

self-review: highlighting noteworthy code changes

patrick-medusajs · 2023-03-15T13:00:48Z

packages/medusa/src/api/routes/store/auth/create-session.ts

@@ -91,7 +92,7 @@ export default async (req, res) => {

  const customerService: CustomerService = req.scope.resolve("customerService")
  const customer = await customerService.retrieve(result.customer?.id || "", {
-    relations: ["orders", "orders.items"],
+    relations: defaultRelations,


Will also include shipping_addresses in order to harmonize the responses shaped with get-session.

patrick-medusajs · 2023-03-15T13:06:28Z

packages/medusa/src/api/routes/store/collections/index.ts

@@ -22,11 +22,12 @@ export default (app) => {
  return app
 }

-export const defaultStoreCollectionRelations = ["products"]
+export const defaultStoreCollectionRelations = []


defaultStoreCollectionRelations is not used and is not passed to services in controllers. To avoid confusion, product has been moves to allowedFields. This change should have no effect.

patrick-medusajs · 2023-03-15T13:08:36Z

packages/medusa/src/api/routes/store/collections/list-collections.ts

+ *     name: handle
+ *     style: form
+ *     explode: false
+ *     description: Filter by the collection handle
+ *     schema:
+ *       type: array
+ *       items:
+ *         type: string


Missing OAS for query param.

medusa/packages/medusa/src/api/routes/store/collections/list-collections.ts

Lines 121 to 124 in d9d046a

export class StoreGetCollectionsParams {

@IsOptional()

@IsArray()

handle?: string[]

patrick-medusajs · 2023-03-15T13:13:01Z

packages/medusa/src/api/routes/store/carts/index.ts

+ *   implicit:
+ *      - items
+ *      - items.variant
+ *      - items.variant.product
+ *      - items.tax_lines
+ *      - items.adjustments
+ *      - gift_cards
+ *      - discounts
+ *      - discounts.rule
+ *      - shipping_methods
+ *      - shipping_methods.tax_lines
+ *      - shipping_address
+ *      - region
+ *      - region.tax_rates


Relations from decorateTotals subprocess.

medusa/packages/medusa/src/services/cart.ts

Lines 2771 to 2789 in d9d046a

private getTotalsRelations(config: FindConfig<Cart>): string[] {

const relationSet = new Set(config.relations)

relationSet.add("items")

relationSet.add("items.variant")

relationSet.add("items.variant.product")

relationSet.add("items.tax_lines")

relationSet.add("items.adjustments")

relationSet.add("gift_cards")

relationSet.add("discounts")

relationSet.add("discounts.rule")

relationSet.add("shipping_methods")

relationSet.add("shipping_methods.tax_lines")

relationSet.add("shipping_address")

relationSet.add("region")

relationSet.add("region.tax_rates")

return Array.from(relationSet.values())

}

patrick-medusajs · 2023-03-15T13:16:45Z

packages/medusa/src/api/routes/store/customers/index.ts

@@ -124,9 +129,103 @@ export type StoreCustomersRes = {
  customer: Omit<Customer, "password_hash">
 }

+/**
+ * @schema StoreCustomersResetPasswordRes


customer model in reset password response will not include expanded-relations from StoreCustomersRes. Creating a separate response for reset password endpoint.

patrick-medusajs · 2023-03-15T13:51:04Z

packages/medusa/src/api/routes/store/variants/index.ts

+ *   relations:
+ *     - prices
+ *     - options
+ *     - product


medusa/packages/medusa/src/api/routes/store/variants/index.ts

Line 21 in d41c3d4

export const defaultStoreVariantRelations = ["prices", "options", "product"]

patrick-medusajs · 2023-03-15T13:51:11Z

packages/medusa/src/api/routes/store/variants/index.ts

+ *   relations:
+ *     - prices
+ *     - options
+ *     - product


medusa/packages/medusa/src/api/routes/store/variants/index.ts

Line 21 in d41c3d4

export const defaultStoreVariantRelations = ["prices", "options", "product"]

patrick-medusajs · 2023-03-15T13:51:45Z

packages/medusa/src/api/routes/store/variants/index.ts

 * required:
 *   - variant
 * properties:
 *   variant:
 *     $ref: "#/components/schemas/PricedVariant"
 */
 export type StoreVariantsRes = {
-  variant: ProductVariant
+  variant: PricedVariant


Controller calls PricingService.setVariantPrices

patrick-medusajs · 2023-03-15T13:51:53Z

packages/medusa/src/api/routes/store/variants/index.ts

@@ -46,7 +57,7 @@ export type StoreVariantsRes = {
 *       $ref: "#/components/schemas/PricedVariant"
 */
 export type StoreVariantsListRes = {
-  variants: ProductVariant[]
+  variants: PricedVariant[]


Controller calls PricingService.setVariantPrices

patrick-medusajs · 2023-03-15T13:53:20Z

packages/medusa/src/types/pricing.ts

@@ -31,6 +31,35 @@ export type ShippingOptionPricing = {
  tax_amount: number
 }

+/** @schema PricedShippingOption


missing OAS

medusa/packages/medusa/src/types/pricing.ts

Lines 28 to 32 in d41c3d4

export type ShippingOptionPricing = {

price_incl_tax: number | null

tax_rates: TaxServiceRate[] | null

tax_amount: number

}

shahednasser

LGTM!

Not sure if you already considered this, so feel free to ignore if you did: maybe we should consider creating something like a schema in OAS for relations (for example, defaultRelations). The only reason I'm thinking about that is ensuring the solution is maintainable in the long run.

shahednasser · 2023-03-15T18:06:22Z

packages/medusa/src/types/pricing.ts

+ *   - type: object
+ *     properties:
+ *       price_incl_tax:
+ *         type: number
+ *         description: Price including taxes
+ *       tax_rates:
+ *         type: array
+ *         description: An array of applied tax rates
+ *         items:
+ *           type: object
+ *           properties:
+ *             rate:
+ *               type: number
+ *               description: The tax rate value
+ *             name:
+ *               type: string
+ *               description: The name of the tax rate
+ *             code:
+ *               type: string
+ *               description: The code of the tax rate
+ *       tax_amount:
+ *         type: number
+ *         description: The taxes applied.


suggestion: should we specify anything as required here?

I don't believe so. I followed the same pattern as PriceVariant.

patrick-medusajs · 2023-03-15T18:32:10Z

Not sure if you already considered this, so feel free to ignore if you did: maybe we should consider creating something like a schema in OAS for relations (for example, defaultRelations). The only reason I'm thinking about that is ensuring the solution is maintainable in the long run.

I hear you. Maintainability was top of mind when designing this solution. OAS not as a good as TypeScript when it comes to mutating definitions using composition. In the end, I settled on using the same definition pattern as the one used by the controllers, services, and repositories. I believe we will be able to improvement maintainability by fully deprecating eager loaded relations and also by making implicit relations more explicit. For example, decoratedTotals relations could be exposed as an array that can then be explicitly merged with const defaultRelations = ["foobar", ...totalsRelations].

olivermrbl

Nice work @patrick-medusajs!

olivermrbl · 2023-03-15T18:50:57Z

packages/medusa/src/api/routes/store/collections/index.ts

 export const allowedFields = [
  "id",
  "title",
  "handle",
+  "product",


Suggested change

"product",

"products",

😅 Fixed in 9945163

olivermrbl · 2023-03-15T18:54:07Z

packages/medusa/src/api/routes/store/payment-collections/authorize-batch-payment-sessions.ts

@@ -37,7 +37,7 @@ import { PaymentCollectionService } from "../../../../services"
 * tags:
 *   - Payment Collections
 * responses:
- *   200:
+ *   207:


todo: This must have slipped through at some point. We don't use any other success codes than 200 and 201. I'll create a follow-up ticket.

Unless you want to tackle it now? I believe its a minor change.

patrick-medusajs · 2023-03-15T19:46:20Z

packages/medusa/src/api/routes/store/payment-collections/authorize-batch-payment-sessions.ts

@@ -72,7 +72,7 @@ export default async (req, res) => {
      req.request_context
    )

-  res.status(207).json({ payment_collection })
+  res.status(200).json({ payment_collection })


@olivermrbl Fixed

patrick-medusajs · 2023-03-16T12:39:54Z

We can see the result of the these changes on the generated types on this commit (0bee564) from a future PR.

feat(oas): declare x-expanded-relations - Store

92f2480

patrick-medusajs self-assigned this Mar 15, 2023

fixup! feat(oas): declare x-expanded-relations - Store

d9d046a

vercel bot deployed to Preview March 15, 2023 13:10 View deployment

fixup! feat(oas): declare x-expanded-relations - Store

197d6cb

vercel bot deployed to Preview March 15, 2023 13:41 View deployment

fixup! feat(oas): declare x-expanded-relations - Store

d41c3d4

vercel bot deployed to Preview March 15, 2023 13:49 View deployment

fixup! feat(oas): declare x-expanded-relations - Store

e68e8b0

patrick-medusajs commented Mar 15, 2023

View reviewed changes

patrick-medusajs added 2 commits March 15, 2023 09:57

chore(changeset): patch

cd19fc1

fix(tests): update store auth integration test

292c14b

vercel bot deployed to Preview March 15, 2023 14:31 View deployment

patrick-medusajs marked this pull request as ready for review March 15, 2023 14:33

patrick-medusajs requested a review from a team as a code owner March 15, 2023 14:33

patrick-medusajs requested a review from shahednasser March 15, 2023 14:35

shahednasser approved these changes Mar 15, 2023

View reviewed changes

olivermrbl requested changes Mar 15, 2023

View reviewed changes

fix: pr feedback

9945163

patrick-medusajs commented Mar 15, 2023

View reviewed changes

Merge branch 'develop' into feat/x-expanded-relations-store

a359699

vercel bot deployed to Preview March 15, 2023 19:59 View deployment

fix(test): match response code

1620375

vercel bot deployed to Preview March 15, 2023 20:39 View deployment

olivermrbl approved these changes Mar 16, 2023

View reviewed changes

olivermrbl merged commit 522e306 into develop Mar 16, 2023

olivermrbl deleted the feat/x-expanded-relations-store branch March 16, 2023 08:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(oas): declare x-expanded-relations - Store #3482

feat(oas): declare x-expanded-relations - Store #3482

patrick-medusajs commented Mar 15, 2023 •

edited

Loading

vercel bot commented Mar 15, 2023 •

edited

Loading

changeset-bot bot commented Mar 15, 2023 •

edited

Loading

patrick-medusajs left a comment

patrick-medusajs Mar 15, 2023

patrick-medusajs Mar 15, 2023

patrick-medusajs Mar 15, 2023

patrick-medusajs Mar 15, 2023

patrick-medusajs Mar 15, 2023

patrick-medusajs Mar 15, 2023

patrick-medusajs Mar 15, 2023

patrick-medusajs Mar 15, 2023

patrick-medusajs Mar 15, 2023

patrick-medusajs Mar 15, 2023

shahednasser left a comment

shahednasser Mar 15, 2023

patrick-medusajs Mar 15, 2023

patrick-medusajs commented Mar 15, 2023

olivermrbl left a comment

olivermrbl Mar 15, 2023

patrick-medusajs Mar 15, 2023

olivermrbl Mar 15, 2023 •

edited

Loading

patrick-medusajs Mar 15, 2023

patrick-medusajs commented Mar 16, 2023

	export class StoreGetCollectionsParams {
	@IsOptional()
	@IsArray()
	handle?: string[]

	private getTotalsRelations(config: FindConfig<Cart>): string[] {
	const relationSet = new Set(config.relations)

	relationSet.add("items")
	relationSet.add("items.variant")
	relationSet.add("items.variant.product")
	relationSet.add("items.tax_lines")
	relationSet.add("items.adjustments")
	relationSet.add("gift_cards")
	relationSet.add("discounts")
	relationSet.add("discounts.rule")
	relationSet.add("shipping_methods")
	relationSet.add("shipping_methods.tax_lines")
	relationSet.add("shipping_address")
	relationSet.add("region")
	relationSet.add("region.tax_rates")

	return Array.from(relationSet.values())
	}

	export type ShippingOptionPricing = {
	price_incl_tax: number \| null
	tax_rates: TaxServiceRate[] \| null
	tax_amount: number
	}

feat(oas): declare x-expanded-relations - Store #3482

feat(oas): declare x-expanded-relations - Store #3482

Conversation

patrick-medusajs commented Mar 15, 2023 • edited Loading

What

Why

How

Tests

vercel bot commented Mar 15, 2023 • edited Loading

changeset-bot bot commented Mar 15, 2023 • edited Loading

🦋 Changeset detected

patrick-medusajs left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shahednasser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

patrick-medusajs commented Mar 15, 2023

olivermrbl left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

olivermrbl Mar 15, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

patrick-medusajs commented Mar 16, 2023

patrick-medusajs commented Mar 15, 2023 •

edited

Loading

vercel bot commented Mar 15, 2023 •

edited

Loading

changeset-bot bot commented Mar 15, 2023 •

edited

Loading

olivermrbl Mar 15, 2023 •

edited

Loading