v2.2.0

<!-- 
![image](https://github.com/user-attachments/assets/90cbba1f-c965-4c15-8fe2-c73db007263f)

# v2.2.0

This release improves the developer experience around building modules by generating container types of custom module services.

CMS_BREAK -->

## Highlights

### Passing custom callback to Oauth providers

> [!WARNING]  
Breaking changes

The callback URL for Oauth providers can now be passed in the payload of the authentication request to support use cases like different login pages based on the actor. 

For example, you might have a `user/github/callback` page and a `customer/github/callback` page, and where you redirect to would depend on which actor is doing the authentication.

The request would look as follows:
```
POST http://localhost:9000/customer/auth/github

{ callback_url: "<some url>" }
```

This change also adds the `state` parameter as defined in the Oauth protocol.

### Passing Query Parameters in Callback Validation

Previously, you only passed the `code` from the third-party provider (For example, Google) to the callback route. It's now required to pass all query parameters received from the third-party, including `state` or `error`.

**Required actions**

If you have overridden the auth module definition in `medusa-config.ts`, you will need to pass `Modules.CACHE` as a dependency, as the `state` is stored temporarily in cache when carrying out the authentication flow:
```ts
module.exports = defineConfig({
 ...
  modules: [
    {
      resolve: "@medusajs/medusa/auth",
      dependencies: [Modules.CACHE, ContainerRegistrationKeys.LOGGER],
      options: {
        providers: [ ... ],
      },
    },
  ],
})
```

If you have a storefront implementation of third-party authentication, make sure to pass all query parameters to the validate callback route. You can also refer to the following updated documentation pages to learn more:

- [Storefront Development Guide: Implement Third-Party Social Login](https://docs.medusajs.com/resources/storefront-development/customers/third-party-login)
- [Conceptual Guide: Third-Party Service Authentication Flow](https://docs.medusajs.com/resources/commerce-modules/auth/authentication-route#2-third-party-service-authenticate-flow)

### Custom module types

Container mappings types are generated for modules by inspecting the registered modules. The types are generated and written to your local project in `.medusa/types/module-bindings.d.ts`. To generate the types, the module needs be functionally correct, registered in `medusa-config.ts`, and the server needs to be started in development mode. 

Once the types are generated, your IDEs intellisense should pick them up, e.g. when creating an API Route:
```ts
import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"

export const GET = (req: MedusaRequest, res: MedusaResponse) => {

  const brandModule = req.scope.resolve("brand")

  await brandModule. // <-------------- Autocompletion should appear

  ...
}
```

If you experience issues with generating types for custom modules, please submit an issue, so we can look into it. 

### Deprecated APIs

Some APIs have been deprecated and/or renamed as part of a housekeeping task in order to be more consistent with naming across tools and modules.

These are:
- `remoteLink` -> `link` (deprecated and renamed)
- `remoteQueryConfig` -> `queryConfig` (deprecated and renamed)
- `remote-query-entry-points.d.ts` -> `query-entry-points.d.ts` (renaming)

There are no breaking changes in this release, but the deprecated APIs will be removed in a later release, so we recommend updating your code to use the new APIs as soon as possible.

### Order cancelation

Canceling an order will also cancel its payments. If the payments are captured, we will attempt to refund an amount equal to the captured amount. If the payments are not captured, they will be canceled immediately.

### Other changes

The relationship between stock location and stock location address has been changed to a one-to-one. This change involves a migration, so please apply the latest migrations when upgrading.

**Required actions**

Run migrations to ensure your server functions as expected after upgrading:

```
npx medusa db:migrate
```

### Features
* feat(medusa): Add health endpoint for all running modes of medusa by @sradevski in https://github.com/medusajs/medusa/pull/10737
* feat(create-medusa-app): allow passing project name on command line by @shahednasser in https://github.com/medusajs/medusa/pull/10755
* feat: deprecate remote link by @thetutlage in https://github.com/medusajs/medusa/pull/10768
* feat: deprecate remoteQueryConfig in favor of queryConfig by @thetutlage in https://github.com/medusajs/medusa/pull/10773
* feat: generate modules mappings at runtime by @thetutlage in https://github.com/medusajs/medusa/pull/10791
* feat(create-medusa-app): improve by adding depth to clone commands by @shahednasser in https://github.com/medusajs/medusa/pull/10812
* feat(auth-google,auth-github): Allow passing a custom callbackUrl to … by @sradevski in https://github.com/medusajs/medusa/pull/10829
* feat(dashboard,core-flows,types,utils,medusa): Order cancelations will refund payments by @riqwan in https://github.com/medusajs/medusa/pull/10667

### Bugs
* fix(fulfillment): export schema types by @shahednasser in https://github.com/medusajs/medusa/pull/10700
* fix: pluralization of words ending in y, where y follows a vowel by @thetutlage in https://github.com/medusajs/medusa/pull/10697
* fix(medusa,types,js-sdk): fix request query parameter types for store product routes by @shahednasser in https://github.com/medusajs/medusa/pull/10707
* fix(core-flows): export updateTaxRegionsStep by @shahednasser in https://github.com/medusajs/medusa/pull/10732
* fix(pricing): pricing context calculations only takes into account existing rule attributes by @riqwan in https://github.com/medusajs/medusa/pull/10771
* Fix/product variants filter by @thetutlage in https://github.com/medusajs/medusa/pull/10808
* fix(): Workflow cancellation + gracefully handle non serializable state by @adrien2p in https://github.com/medusajs/medusa/pull/10674
* fix(core-flow): invalid update quantity in update line item in cart workflow by @daykrm in https://github.com/medusajs/medusa/pull/10405
* fix(promotion): don't evaluate rule condition if conditions to evaluate is empty by @riqwan in https://github.com/medusajs/medusa/pull/10795
* fix(stock-location,core-flows,types): updates existing address when updating stock location by @riqwan in https://github.com/medusajs/medusa/pull/10832
* feat(core-flows,fulfillment, fulfillment-manual, types): make fulfillment typings more specific by @fPolic in https://github.com/medusajs/medusa/pull/10677
* fix(create-medusa-app): add default storefront url to auth CORS by @shahednasser in https://github.com/medusajs/medusa/pull/10853
* fix(dashboard): cancel order notifications by @fPolic in https://github.com/medusajs/medusa/pull/10858


### Documentation
* docs: integrate shipstation guide by @shahednasser in https://github.com/medusajs/medusa/pull/10623
* docs: update typedoc, convert packages to esm, generate references by @shahednasser in https://github.com/medusajs/medusa/pull/10699
* docs: fix typo in CmsModuleService by @shahednasser in https://github.com/medusajs/medusa/pull/10702
* docs-util: fix links in references to current page by @shahednasser in https://github.com/medusajs/medusa/pull/10703
* docs-util: fix query params not retrieved correctly for some routes by @shahednasser in https://github.com/medusajs/medusa/pull/10708
* docs: split commerce modules sidebars by @shahednasser in https://github.com/medusajs/medusa/pull/10705
* docs: fix typo in extend core flow by @shahednasser in https://github.com/medusajs/medusa/pull/10709
* docs: split events reference across modules by @shahednasser in https://github.com/medusajs/medusa/pull/10711
* docs: split admin widget zone to pages by @shahednasser in https://github.com/medusajs/medusa/pull/10719
* docs: improve link docs for commerce modules by @shahednasser in https://github.com/medusajs/medusa/pull/10726
* docs: fix multiple typos in customization chapters by @shahednasser in https://github.com/medusajs/medusa/pull/10727
* docs: add workflow / step tags by @shahednasser in https://github.com/medusajs/medusa/pull/10731
* docs: revise commerce modules overview pages by @shahednasser in https://github.com/medusajs/medusa/pull/10738
* docs: add JS SDK to commerce modules sidebars by @shahednasser in https://github.com/medusajs/medusa/pull/10740
* chore: improve payment provider tsdocs + generate reference by @shahednasser in https://github.com/medusajs/medusa/pull/10742
* docs: fix and improve details on sending authenticated requests with API token by @shahednasser in https://github.com/medusajs/medusa/pull/10744
* docs-util: add publishable api key header parameter to store routes OAS by @shahednasser in https://github.com/medusajs/medusa/pull/10747
* docs: document how to calculate shipping prices in storefront by @shahednasser in https://github.com/medusajs/medusa/pull/10748
* docs: allow scroll with keys by @shahednasser in https://github.com/medusajs/medusa/pull/10752
* docs: update and fix UI props docs by @shahednasser in https://github.com/medusajs/medusa/pull/10754
* docs: document missing events in reference by @shahednasser in https://github.com/medusajs/medusa/pull/10779
* docs: update fulfillment provider module docs to reflect CalculatedShippingOptionPrice by @ranjithkumar8352 in https://github.com/medusajs/medusa/pull/10778
* docs: fix code tabs in production by @shahednasser in https://github.com/medusajs/medusa/pull/10784
* docs: fix selected variant in storefront guide by @shahednasser in https://github.com/medusajs/medusa/pull/10785
* chore: fix links to contribution guidelines by @shahednasser in https://github.com/medusajs/medusa/pull/10792
* docs: fix highlights in checkout storefront guide by @shahednasser in https://github.com/medusajs/medusa/pull/10793
* docs: fix cross-project link for Card components by @shahednasser in https://github.com/medusajs/medusa/pull/10794
* docs: handle product deletion in digital products recipe by @shahednasser in https://github.com/medusajs/medusa/pull/10811
* docs: fix storefront sections in digital product recipe by @shahednasser in https://github.com/medusajs/medusa/pull/10833
* docs: update next.js storefront snippets by @shahednasser in https://github.com/medusajs/medusa/pull/10840
* docs: update storefront development snippets for next.js 15 compatibility by @shahednasser in https://github.com/medusajs/medusa/pull/10843
* Update page.mdx by @DivineStudio in https://github.com/medusajs/medusa/pull/10847
* docs: document registering user with existing email by @shahednasser in https://github.com/medusajs/medusa/pull/10859

### Chores
* chore(ui,icons): Add React 19/19-rc to peer dependencies by @kasperkristensen in https://github.com/medusajs/medusa/pull/10458
* chore(js-sdk): add tags to js-sdk by @shahednasser in https://github.com/medusajs/medusa/pull/10739
* chore: small tsdoc changes for remoteLink and remoteQueryConfig by @shahednasser in https://github.com/medusajs/medusa/pull/10837
* chore(ui): general updates and fixes to TSDocs and types by @shahednasser in https://github.com/medusajs/medusa/pull/10753
* chore: fix version number in tsdocs by @shahednasser in https://github.com/medusajs/medusa/pull/10856
* chore: rename remote-query-entry-points.d.ts to query-entry-points.d.ts by @thetutlage in https://github.com/medusajs/medusa/pull/10831

### Other Changes
* fix(medusa-cli): fix medusa develop command crashing on file change on windows by @ranjithkumar8352 in https://github.com/medusajs/medusa/pull/10717
* docs: use correct env variable for medusa admin in server mode deployment by @ranjithkumar8352 in https://github.com/medusajs/medusa/pull/10764
* docs: update desktop nav menu item title by @ahrbil in https://github.com/medusajs/medusa/pull/10125
* Update README.md by @MedusaNick in https://github.com/medusajs/medusa/pull/10825

## New Contributors
* @ranjithkumar8352 made their first contribution in https://github.com/medusajs/medusa/pull/10717
* @daykrm made their first contribution in https://github.com/medusajs/medusa/pull/10405
* @DivineStudio made their first contribution in https://github.com/medusajs/medusa/pull/10847

**Full Changelog**: https://github.com/medusajs/medusa/compare/v2.1.3...v2.2.0