@medusajs/js-sdk 2.22.0-snapshot-20261020204851 → 2.22.0

package/AGENTS.md

@@ -0,0 +1,89 @@
+# @medusajs/js-sdk
+
+Typed HTTP client for Medusa's Store, Admin, and Auth API routes, used by storefronts, admin customizations, and the Medusa Admin dashboard itself (`packages/admin/dashboard/src/lib/client/client.ts`). Runs in browsers and Node (native `fetch`).
+
+## Using this package
+
+- Install `@medusajs/js-sdk` (and `@medusajs/types` for `HttpTypes`). Default export is the `Medusa` class.
+- Docs: https://docs.medusajs.com/resources/js-sdk.md, auth: https://docs.medusajs.com/resources/js-sdk/auth/overview.md
+
+```ts
+import Medusa from "@medusajs/js-sdk"
+
+export const sdk = new Medusa({
+  baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,
+  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
+  auth: { type: "session" },
+})
+
+const { products } = await sdk.store.product.list({ limit: 10 })
+const { cart } = await sdk.store.cart.create({ region_id: "reg_123" })
+```
+
+- `Config` options (`src/types.ts`): `baseUrl`, `publishableKey`, `apiKey`, `globalHeaders`, `auth.type` (`"jwt" | "session"`), `auth.jwtTokenStorageKey` (default `medusa_auth_token`), `auth.jwtTokenStorageMethod` (`"local" | "session" | "memory" | "custom" | "nostore"`), `auth.storage` (custom storage with `getItem`/`setItem`/`removeItem`, sync or async), `auth.fetchCredentials`, `logger`, `debug`.
+- `publishableKey` is sent as `x-publishable-api-key` on every request; store routes require it.
+- `apiKey` (admin secret API key) is sent as `Authorization: Basic base64(apiKey + ":")`. Server-side only; never ship it to a browser.
+- Namespaces: `sdk.store.*` (`region`, `collection`, `category`, `productOption`, `product`, `cart`, `fulfillment`, `payment`, `order`, `customer`, `locale`), `sdk.admin.*` (one class per resource in `src/admin/`, e.g. `sdk.admin.product`, `sdk.admin.order`), `sdk.auth.*`.
+
+### Auth
+
+```ts
+const result = await sdk.auth.login("customer", "emailpass", {
+  email,
+  password,
+})
+if (typeof result !== "string") {
+  // { location } for OAuth redirect, or mfa_required / verification_required
+}
+const { customer } = await sdk.store.customer.retrieve()
+await sdk.auth.logout()
+```
+
+- `login(actor, method, payload)` returns the token string, `{ location }` (OAuth redirect), `{ mfa_required, mfa_challenge, token }`, or `{ verification_required, verification, token }`.
+- `auth.type: "session"`: after login the SDK POSTs the token to `/auth/session` to get a cookie, sends no `Authorization` header, and uses `credentials: "include"` (overridable via `fetchCredentials`). Otherwise the token is stored and sent as `Bearer`.
+- `register()` stores the token but does not start a session: the token has no actor yet. Create the actor (e.g. `sdk.store.customer.create`), then call `sdk.auth.login` again or `sdk.auth.refresh()`.
+- OAuth: `sdk.auth.callback(actor, provider, queryParams)` then `sdk.auth.refresh()` once the actor exists.
+- Also: `sdk.auth.resetPassword`, `updateProvider`, `listProviders`, `createUser`, `sdk.auth.mfa.*`, `sdk.auth.verification.*`.
+
+### Custom routes
+
+```ts
+const data = await sdk.client.fetch<{ brands: Brand[] }>("/store/brands", {
+  method: "POST",
+  body: { name: "Acme" },
+  query: { fields: "id,name" },
+})
+```
+
+- `body` objects are JSON-stringified, `query` is serialized with `qs` (`skipNulls`), and auth / publishable-key / locale headers are added.
+- Responses are parsed as JSON only when the request `accept` header contains `application/json` (the default). For files, set `headers: { accept: "application/pdf" }` and read the returned raw `Response`.
+- Status `>= 300` throws `FetchError` with `status`, `statusText`, and `message` (from the JSON body's `message`).
+- `sdk.client.fetchStream(path, init)` returns `{ stream, abort }` for server-sent events.
+- `sdk.setLocale(locale)` stores the locale in `localStorage` and sends `x-medusa-locale`; it logs a warning on the server, where you must pass the header yourself.
+
+## Architecture
+
+- `src/index.ts`: `Medusa` class wiring `Client`, `Admin`, `Store`, `Auth`.
+- `src/client.ts`: `Client` (`fetch`, `fetchStream`, `setToken`/`getToken`/`clearToken`, header merging, URL building relative to `baseUrl` path).
+- `src/admin/<resource>.ts`: one class per admin resource, registered in `src/admin/index.ts`. `src/store/index.ts`: a single `Store` class with object namespaces. `src/auth/index.ts`: `Auth`.
+- Method convention: `(id?, body?, query?, headers?)` calling `this.client.fetch<HttpTypes.XResponse>(path, { method, headers, body, query })`, with request/response types from `@medusajs/types` `HttpTypes`.
+
+## Development
+
+```bash
+yarn workspace @medusajs/js-sdk build   # CJS (tsconfig.json) + ESM (tsconfig.esm.json)
+yarn workspace @medusajs/js-sdk test
+cd packages/core/js-sdk && ../../../node_modules/.bin/jest src/__tests__/client.spec.ts
+```
+
+- Tests in `src/__tests__/` mock the network with `msw` (`setupServer`), no backend needed.
+- New methods need TSDoc with an `@example` (the JS SDK reference docs are generated from it; use the `writing-tsdocs` skill).
+
+## Gotchas
+
+- Relative imports in `src/` must end in `.js` (e.g. `from "../client.js"`); `src/__tests__/esm-import-specifiers.spec.ts` fails otherwise (the ESM build in `dist/esm` needs explicit extensions).
+- Header values of `null` delete the header. File uploads rely on this: `admin/upload.ts` and `admin/product.ts` pass `"content-type": null` with a `FormData` body so `fetch` sets the multipart boundary.
+- Header precedence: defaults (`content-type`, `accept`, API key, publishable key) < `globalHeaders` < JWT `Authorization` < per-call `headers`.
+- Without `auth.jwtTokenStorageMethod`, the token goes to `localStorage` if available, else `nostore` (not persisted) on the server. `"local"`/`"session"` throw outside the browser; `"custom"` throws without `auth.storage`.
+- `credentials` is only set when `Request.prototype` supports it (omitted on some server runtimes); for `jwt` it is `"omit"`.
+- The Medusa Admin dashboard depends on this package, so changes to `Client`/`Auth` behavior affect it too.

package/README.md

@@ -0,0 +1,102 @@
+<p align="center">
+  <a href="https://www.medusajs.com">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    </picture>
+  </a>
+</p>
+<h1 align="center">
+  @medusajs/js-sdk
+</h1>
+
+<h4 align="center">
+  <a href="https://docs.medusajs.com">Documentation</a> |
+  <a href="https://www.medusajs.com">Website</a>
+</h4>
+
+<p align="center">
+  Building blocks for digital commerce
+</p>
+<p align="center">
+  <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
+  </a>
+  <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
+    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
+  </a>
+  <a href="https://discord.gg/xpCwq3Kfn8">
+    <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
+  </a>
+  <a href="https://twitter.com/intent/follow?screen_name=medusajs">
+    <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
+  </a>
+</p>
+
+Medusa JS SDK: a JavaScript/TypeScript client for the Medusa Store and Admin API routes. Use it in storefronts, admin customizations, or any JavaScript app that sends requests to a Medusa application, including your custom API routes.
+
+## At a glance
+
+| | |
+| --- | --- |
+| Package | `@medusajs/js-sdk` |
+| Type | Core library |
+| Import from | `@medusajs/js-sdk` (default export `Medusa`) |
+| Entry points | ESM (`import`) and CommonJS (`require`) builds |
+
+## Features
+
+- `sdk.store` methods for the Store API routes, such as products, carts, and customers.
+- `sdk.admin` methods for the Admin API routes.
+- `sdk.auth` methods to register, log in, log out, and reset passwords for any actor type, such as `customer` or `user`.
+- `sdk.client.fetch` to send requests to custom API routes with the configured headers and authentication.
+- `sdk.setLocale` to send the `x-medusa-locale` header with every request.
+
+## Installation
+
+```bash
+npm install @medusajs/js-sdk @medusajs/types
+```
+
+`@medusajs/types` is optional and provides the request and response types.
+
+## Usage
+
+```ts
+import Medusa from "@medusajs/js-sdk"
+
+export const sdk = new Medusa({
+  baseUrl: "http://localhost:9000",
+  debug: process.env.NODE_ENV === "development",
+  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
+})
+
+const { products } = await sdk.store.product.list()
+```
+
+## Configuration
+
+| Option | Type | Description | Default |
+| --- | --- | --- | --- |
+| `baseUrl` | `string` | URL of the Medusa application. Required. | - |
+| `publishableKey` | `string` | Publishable API key, sent in the `x-publishable-api-key` header. Required for Store API routes. | - |
+| `apiKey` | `string` | Secret API key, sent as Basic authentication. Use only on the server for Admin API routes. | - |
+| `globalHeaders` | `ClientHeaders` | Headers to send with every request. | - |
+| `auth.type` | `"jwt" \| "session"` | How to authenticate. See [Authentication types](#authentication-types). | `"jwt"` |
+| `auth.jwtTokenStorageMethod` | `"local" \| "session" \| "memory" \| "custom" \| "nostore"` | Where to store the JWT token. | `"local"` in browsers, `"nostore"` otherwise |
+| `auth.jwtTokenStorageKey` | `string` | Storage key of the JWT token. | `"medusa_auth_token"` |
+| `auth.storage` | `CustomStorage` | Object with `getItem`, `setItem`, and `removeItem` methods. Required when `jwtTokenStorageMethod` is `"custom"`. | - |
+| `auth.fetchCredentials` | `"include" \| "omit" \| "same-origin"` | `credentials` of fetch requests when `auth.type` is `"session"`. | `"include"` |
+| `logger` | `Logger` | Logger with `error`, `warn`, `info`, and `debug` methods. | `console` |
+| `debug` | `boolean` | Whether to log debug messages. | `false` |
+
+### Authentication types
+
+- `"jwt"` (default): after login, the SDK stores the JWT token based on `auth.jwtTokenStorageMethod` and sends it in the `Authorization: Bearer` header. Fetch requests use `credentials: "omit"`.
+- `"session"`: after login, the SDK exchanges the JWT token for a cookie session using the `/auth/session` API route, and sends requests with `auth.fetchCredentials`. Logging out deletes the session. Use it for the Medusa Admin and admin customizations.
+
+## Resources
+
+- [JS SDK](https://docs.medusajs.com/resources/js-sdk)
+- [JS SDK authentication](https://docs.medusajs.com/resources/js-sdk/auth/overview)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medusajs/js-sdk",
-  "version": "2.22.0-snapshot-20261020204851",
+  "version": "2.22.0",
   "description": "SDK for the Medusa API",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",
@@ -25,14 +25,18 @@
   },
   "files": [
     "dist",
+    "AGENTS.md",
     "!dist/**/__tests__",
     "!dist/**/__mocks__",
     "!dist/**/__fixtures__"
   ],
+  "llms": "https://docs.medusajs.com/llms.txt",
+  "llmsFull": "https://docs.medusajs.com/llms-full.txt",
+  "mcpServer": "https://docs.medusajs.com/mcp",
   "author": "Medusa",
   "license": "SEE LICENSE IN LICENSE",
   "devDependencies": {
-    "@medusajs/types": "2.22.0-snapshot-20261020204851"
+    "@medusajs/types": "2.22.0"
   },
   "dependencies": {
     "fetch-event-stream": "^0.1.5",