diff --git a/www/apps/api-reference/markdown/admin.mdx b/www/apps/api-reference/markdown/admin.mdx index a82e409a77..e5c6891d88 100644 --- a/www/apps/api-reference/markdown/admin.mdx +++ b/www/apps/api-reference/markdown/admin.mdx @@ -76,6 +76,21 @@ To obtain a JWT token, send a request to the [authentication route](#auth_postac + + + + +```js title="Obtain JWT token" +token = await sdk.auth.login("user", "emailpass", { + email, + password +}) +``` + + + + + ```bash title="Obtain JWT token" curl -X POST '{backend_url}/auth/user/emailpass' \ -H 'Content-Type: application/json' \ @@ -85,6 +100,10 @@ curl -X POST '{backend_url}/auth/user/emailpass' \ }' ``` + + + + @@ -117,14 +136,38 @@ If authenticated successfully, an object is returned in the response with the pr To use the JWT token, pass it in the authorization bearer header. +If you're using the JS SDK, call the `client.setToken` method, passing it the token. The JS SDK will automatically pass the token in the authorization header for subsequent requests. + + + +Make sure you've set the `auth.type` configuration of the JS SDK to `jwt` to use the JWT token. Learn more in the [JS SDK configurations](!resources!/js-sdk#js-sdk-configurations). + + + + + + + +```js title="Use JWT token" +sdk.client.setToken(jwt_token) +``` + + + + + ```bash title="Use JWT token" Authorization: Bearer {jwt_token} ``` + + + + @@ -161,6 +204,23 @@ An `api_key` object is returned in the response. You need its `token` property. + + + + +```js title="Create API token" +const { api_key } = await sdk.admin.apiKey.create({ + title: "My Token", + type: "secret" +}) + +console.log(api_key.token) +``` + + + + + ```bash title="Create API token" curl -X POST 'localhost:9000/admin/api-keys' \ -H 'Content-Type: application/json' \ @@ -171,6 +231,10 @@ curl -X POST 'localhost:9000/admin/api-keys' \ }' ``` + + + + @@ -195,6 +259,18 @@ When using the JS SDK, you only need to specify the API key token in the [config + + +```js +import Medusa from "@medusajs/js-sdk" + +export const sdk = new Medusa({ + // other options... + apiKey: "{api_key_token}", +}) +``` + + ```js @@ -235,7 +311,7 @@ When you authenticate a user and create a cookie session ID for them, the cookie ### How to Obtain the Cookie Session -To obtain a cookie session ID, you must have a [JWT token for bearer authentication](#bearer-authorization-with-jwt-tokens). +To obtain a cookie session ID, you must have a [JWT token for bearer authentication](#1-bearer-authorization-with-jwt-tokens). @@ -245,19 +321,35 @@ To obtain a cookie session ID, you must have a [JWT token for bearer authenticat -Then, send a request to the session authentication API route. +Then, if you're using the JS SDK, make sure the `auth.type` configuration is set to `session`, as explained in the [JS SDK configurations](!resources!/js-sdk#js-sdk-configurations) guide. After that, you only need to set the token using the `client.setToken` method, and the JS SDK will handle the rest. -To view the cookie session ID, pass the `-v` option to the `curl` command. +If you're not using the JS SDK, send a request to the [session authentication API route](#auth_postsession). To view the cookie session ID, pass the `-v` option to the `curl` command. + + + + +```js title="Obtain cookie session" +sdk.client.setToken(jwt_token) +``` + + + + + ```bash title="Obtain cookie session" curl -v -X POST '{backend_url}/auth/session' \ --header 'Authorization: Bearer {jwt_token}' ``` + + + + @@ -266,7 +358,7 @@ curl -v -X POST '{backend_url}/auth/session' \ -The headers will be logged in the terminal as well as the response. You +If you send the `cURL` request, the headers will be logged in the terminal as well as the response. You should find in the headers a Cookie header. @@ -287,7 +379,9 @@ Set-Cookie: connect.sid=s%3A2Bu8B...; #### How to Use the Cookie Session ID in cURL -Copy the value after `connect.sid` (without the `;` at the end) and pass +If you're using the JS SDK, it will pass the cookie session with every request automatically after you use the `client.setToken` method. + +If you're not using the JS SDK, copy the value after `connect.sid` (without the `;` at the end) and pass it as a cookie in subsequent requests. @@ -363,14 +457,37 @@ If you've enabled HTTP Compression in your Medusa configurations, and you want to disable it for some requests, you can pass the `x-no-compression` header in your requests. +If you're using the JS SDK, every method accepts a `headers` parameter as the last parameter. You can pass in it custom headers, including the `x-no-compression` header. + -```bash title="Enable HTTP compression" -x-no-compression: true + + + + +```js title="Disable HTTP compression" +sdk.store.product.list({ + limit, + offset, +}, { + "x-no-compression": "false", +}) ``` + + + + +```bash title="Disable HTTP compression" +x-no-compression: false +``` + + + + + @@ -415,11 +532,29 @@ Fields and relations are separated by a comma `,`. + + + + +```js title="Select fields" +sdk.admin.product.list({ + fields: "title,handle" +}) +``` + + + + + ```bash title="Select fields" curl 'localhost:9000/admin/products?fields=title,handle' \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + This returns only the `title` and `handle` fields of a product. @@ -455,11 +590,28 @@ To select a relation, pass to `fields` the relation name prefixed by `*`. + + + + +```js title="Select relations" +sdk.admin.product.list({ + fields: "*variants" +}) +``` + + + + + ```bash title="Select relations" curl 'localhost:9000/admin/products?fields=*variants' \ -H 'Authorization: Bearer {jwt_token}' ``` + + + This returns the variants of each product. @@ -490,11 +642,29 @@ To specify multiple fields, pass each of the fields with the `. + + + + +```js title="Select relation's fields" +sdk.admin.product.list({ + fields: "variants.title,variants.sku" +}) +``` + + + + + ```bash title="Select relation's fields" curl 'localhost:9000/admin/products?fields=variants.title,variants.sku' \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + This returns the variants of each product, but the variants only have their `id`, `title`, and `sku` fields. The `id` is always included. @@ -533,11 +703,29 @@ You can pass a string value in the form of `=`. + + + + +```js title="String filter" +sdk.admin.product.list({ + title: "Shirt" +}) +``` + + + + + ```bash title="String filter" curl "http://localhost:9000/admin/products?title=Shirt" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + @@ -547,12 +735,11 @@ curl "http://localhost:9000/admin/products?title=Shirt" \ If the string has any characters other than letters and numbers, you must -encode them. - - -For example, if the string has spaces, you can encode the space with `+` or +encode them. For example, if the string has spaces, you can encode the space with `+` or `%20`. +When using the JS SDK, you can pass the string directly to the query parameter. The JS SDK will encode the string for you. + You can use tools like [this one](https://www.urlencoder.org/) to learn how a value can be encoded. @@ -560,11 +747,29 @@ a value can be encoded. + + + + +```js title="Encoded string filter" +sdk.admin.product.list({ + title: "Blue Shirt" +}) +``` + + + + + ```bash title="Encoded string filter" curl "http://localhost:9000/admin/products?title=Blue%20Shirt" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + @@ -581,11 +786,29 @@ You can pass an integer value in the form of `=`. + + + + +```js title="Integer filter" +sdk.admin.product.list({ + offset: 1 +}) +``` + + + + + ```bash title="Integer filter" curl "http://localhost:9000/admin/products?offset=1" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + @@ -603,11 +826,28 @@ You can pass a boolean value in the form of `=`. + + + + +```js title="Boolean filter" +sdk.admin.product.list({ + is_giftcard: true +}) +``` + + + + + ```bash title="Boolean filter" curl "http://localhost:9000/admin/products?is_giftcard=true" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + @@ -626,11 +866,29 @@ must be in the format `YYYY-MM-DD`. + + + + +```js title="Date filter" +sdk.admin.product.list({ + created_at: { $lt: "2023-02-17" } +}) +``` + + + + + ```bash title="Date filter" curl -g "http://localhost:9000/admin/products?created_at[$lt]=2023-02-17" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + @@ -646,11 +904,29 @@ note that the `T` and `Z` here are fixed. + + + + +```js title="Date and time filter" +sdk.admin.product.list({ + created_at: { $lt: "2023-02-17T07:22:30Z" } +}) +``` + + + + + ```bash title="Date and time filter" curl -g "http://localhost:9000/admin/products?created_at[$lt]=2023-02-17T07:22:30Z" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + @@ -667,15 +943,26 @@ Array filters can be passed either as: - `[]=&[]=`, passing each value as a separate query parameter. You can also specify the index of each parameter in the brackets `[0]=`. +When using the JS SDK, you can pass the array directly to the query parameter. The JS SDK will handle the rest. + + + +```js title="Array filter" +sdk.admin.product.list({ + sales_channel_id: ["sc_123", "sc_456"] +}) +``` + + ```bash -curl -g "http://localhost:9000/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7,sc_234PGVB42PZ7N3YQEP2WDM7PC7" \ +curl -g "http://localhost:9000/admin/products?sales_channel_id[]=sc_123,sc_456" \ -H 'Authorization: Bearer {jwt_token}' ``` @@ -683,7 +970,7 @@ curl -g "http://localhost:9000/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7 ```bash -curl -g "http://localhost:9000/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7" \ +curl -g "http://localhost:9000/admin/products?sales_channel_id[]=sc_123&sales_channel_id[]=sc_456" \ -H 'Authorization: Bearer {jwt_token}' ``` @@ -708,15 +995,36 @@ for using the brackets. Read more Object parameters must be passed as separate query parameters in the form `[]=`. +When using the JS SDK, you can pass the object directly to the query parameter. The JS SDK will handle the rest. + + + + + +```js title="Object filter" +sdk.admin.product.list({ + created_at: { $lt: "2023-02-17", $gt: "2022-09-17" } +}) +``` + + + + + ```bash title="Object filter" curl -g "http://localhost:9000/admin/products?created_at[$lt]=2023-02-17&created_at[$gt]=2022-09-17" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + + @@ -768,11 +1076,30 @@ Use the `offset` query parameter to change between pages. For example, if the li + + + + +```js title="Pagination query parameters" +sdk.admin.product.list({ + limit: 5, + offset: 0 +}) +``` + + + + + ```bash title="Pagination query parameters" -curl "http://localhost:9000/admin/products?limit=5" \ +curl "http://localhost:9000/admin/products?limit=5&offset=0" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + @@ -814,11 +1141,29 @@ sort the retrieved items by a field of that item. + + + + +```js title="Ascending sort by a field" +sdk.admin.product.list({ + order: "created_at" +}) +``` + + + + + ```bash title="Ascending sort by a field" curl "http://localhost:9000/admin/products?order=created_at" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + This sorts the products by their `created_at` field in the ascending order. @@ -836,11 +1181,29 @@ descending, pass a dash (`-`) before the field name. + + + + +```js title="Descending sort by a field" +sdk.admin.product.list({ + order: "-created_at" +}) +``` + + + + + ```bash title="Descending sort by a field" curl "http://localhost:9000/admin/products?order=-created_at" \ -H 'Authorization: Bearer {jwt_token}' ``` + + + + This sorts the products by their `created_at` field in the descending order. diff --git a/www/apps/api-reference/markdown/store.mdx b/www/apps/api-reference/markdown/store.mdx index 2b2174e99d..95ce134284 100644 --- a/www/apps/api-reference/markdown/store.mdx +++ b/www/apps/api-reference/markdown/store.mdx @@ -76,6 +76,21 @@ To obtain a JWT token, send a request to the [authentication route](#auth_postac + + + + +```js title="Obtain JWT token" +token = await sdk.auth.login("customer", "emailpass", { + email, + password +}) +``` + + + + + ```bash title="Obtain JWT token" curl -X POST '{backend_url}/auth/customer/emailpass' \ -H 'Content-Type: application/json' \ @@ -85,6 +100,10 @@ curl -X POST '{backend_url}/auth/customer/emailpass' \ }' ``` + + + + @@ -117,14 +136,38 @@ If authenticated successfully, an object is returned in the response with the pr To use the JWT token, pass it in the authorization bearer header. +If you're using the JS SDK, call the `client.setToken` method, passing it the token. The JS SDK will automatically pass the token in the authorization header for subsequent requests. + + + +Make sure you've set the `auth.type` configuration of the JS SDK to `jwt` to use the JWT token. Learn more in the [JS SDK configurations](!resources!/js-sdk#js-sdk-configurations). + + + + + + + +```js title="Use JWT token" +sdk.client.setToken(jwt_token) +``` + + + + + ```bash title="Use JWT token" Authorization: Bearer {jwt_token} ``` + + + + @@ -139,9 +182,7 @@ When you authenticate a customer and create a cookie session ID for them, the co ### How to Obtain the Cookie Session -To obtain a cookie session ID, you must have a [JWT token for bearer authentication](#bearer-authorization-with-jwt-tokens). - -{/* TODO add a link to the session authentication route. */} +To obtain a cookie session ID, you must have a [JWT token for bearer authentication](#1-bearer-authorization-with-jwt-tokens). @@ -151,19 +192,35 @@ To obtain a cookie session ID, you must have a [JWT token for bearer authenticat -Then, send a request to the session authentication API route. +Then, if you're using the JS SDK, make sure the `auth.type` configuration is set to `session`, as explained in the [JS SDK configurations](!resources!/js-sdk#js-sdk-configurations) guide. After that, you only need to set the token using the `client.setToken` method, and the JS SDK will handle the rest. -To view the cookie session ID, pass the `-v` option to the `curl` command. +If you're not using the JS SDK, send a request to the [session authentication API route](#auth_postsession). To view the cookie session ID, pass the `-v` option to the `curl` command. + + + + +```js title="Obtain cookie session" +sdk.client.setToken(jwt_token) +``` + + + + + ```bash title="Obtain cookie session" curl -v -X POST '{backend_url}/auth/session' \ --header 'Authorization: Bearer {jwt_token}' ``` + + + + @@ -172,7 +229,7 @@ curl -v -X POST '{backend_url}/auth/session' \ -The headers will be logged in the terminal as well as the response. You +If you send the `cURL` request, the headers will be logged in the terminal as well as the response. You should find in the headers a Cookie header. @@ -193,7 +250,9 @@ Set-Cookie: connect.sid=s%3A2Bu8B...; #### How to Use the Cookie Session ID in cURL -Copy the value after `connect.sid` (without the `;` at the end) and pass +If you're using the JS SDK, it will pass the cookie session with every request automatically after you use the `client.setToken` method. + +If you're not using the JS SDK, copy the value after `connect.sid` (without the `;` at the end) and pass it as a cookie in subsequent requests. @@ -267,9 +326,7 @@ and associate placed orders with the specified sales channel. ### How to Create a Publishable API Key -{/* TODO add v2 links */} - -Create a publishable API key either using the [admin REST APIs](https://docs.medusajs.com/api/admin#api-keys_postapikeys), or using the Medusa Admin. +Create a publishable API key either using the [admin REST APIs](https://docs.medusajs.com/api/admin#api-keys_postapikeys), or using the [Medusa Admin](!user-guide!/settings/developer/publishable-api-keys#create-publishable-api-key). ### How to Use a Publishable API Key @@ -281,18 +338,41 @@ Create a publishable API key either using the [admin REST APIs](https://docs.med -You pass the publishable API key in the header `x-publishable-api-key` in all your requests to the store APIs. +If you're using the JS SDK, set the publishable API key in the JS SDK's configurations. + +If you're not using the JS SDK, pass the publishable API key in the header `x-publishable-api-key` in all your requests to the store APIs. + + + + +```js title="Use publishable API key" +import Medusa from "@medusajs/js-sdk" + +export const sdk = new Medusa({ + // other configurations... + publishableKey: "{your_publishable_api_key}", +}) +``` + + + + + ```bash title="Use publishable API key" curl 'http://localhost:9000/store/products' \ -H 'x-publishable-api-key: {your_publishable_api_key}' ``` -Where `{your_publishable_api_key}` is the token of the publishable API key. + + + + +Where `{your_publishable_api_key}` is the token of the publishable API key. When using the JS SDK, set the value as an environment variable. @@ -335,14 +415,37 @@ If you've enabled HTTP Compression in your Medusa configurations, and you want to disable it for some requests, you can pass the `x-no-compression` header in your requests. +If you're using the JS SDK, every method accepts a `headers` parameter as the last parameter. You can pass in it custom headers, including the `x-no-compression` header. + -```bash title="Enable HTTP compression" -x-no-compression: true + + + + +```js title="Disable HTTP compression" +sdk.store.product.list({ + limit, + offset, +}, { + "x-no-compression": "false", +}) ``` + + + + +```bash title="Disable HTTP compression" +x-no-compression: false +``` + + + + + @@ -387,10 +490,28 @@ Fields and relations are separated by a comma `,`. + + + + +```js title="Select fields" +sdk.store.product.list({ + fields: "title,handle" +}) +``` + + + + + ```bash title="Select fields" curl 'localhost:9000/store/products?fields=title,handle' ``` + + + + This returns only the `title` and `handle` fields of a product. @@ -426,10 +547,28 @@ To select a relation, pass to `fields` the relation name prefixed by `*`. + + + + +```js title="Select relations" +sdk.store.product.list({ + fields: "*variants" +}) +``` + + + + + ```bash title="Select relations" curl 'localhost:9000/store/products?fields=*variants' ``` + + + + This returns the variants of each product. @@ -460,10 +599,28 @@ To specify multiple fields, pass each of the fields with the `. + + + + +```js title="Select relation's fields" +sdk.store.product.list({ + fields: "variants.title,variants.sku" +}) +``` + + + + + ```bash title="Select relation's fields" curl 'localhost:9000/store/products?fields=variants.title,variants.sku' ``` + + + + This returns the variants of each product, but the variants only have their `id`, `title`, and `sku` fields. The `id` is always included. @@ -517,10 +674,28 @@ You can pass a string value in the form of `=`. + + + + +```js title="String filter" +sdk.store.product.list({ + title: "Shirt" +}) +``` + + + + + ```bash title="String filter" curl "http://localhost:9000/store/products?title=Shirt" ``` + + + + @@ -530,12 +705,11 @@ curl "http://localhost:9000/store/products?title=Shirt" If the string has any characters other than letters and numbers, you must -encode them. - - -For example, if the string has spaces, you can encode the space with `+` or +encode them. For example, if the string has spaces, you can encode the space with `+` or `%20`. +When using the JS SDK, you can pass the string directly to the query parameter. The JS SDK will encode the string for you. + You can use tools like [this one](https://www.urlencoder.org/) to learn how a value can be encoded. @@ -543,10 +717,28 @@ a value can be encoded. + + + + +```js title="Encoded string filter" +sdk.store.product.list({ + title: "Blue Shirt" +}) +``` + + + + + ```bash title="Encoded string filter" curl "http://localhost:9000/store/products?title=Blue%20Shirt" ``` + + + + @@ -563,10 +755,28 @@ You can pass an integer value in the form of `=`. + + + + +```js title="Integer filter" +sdk.store.product.list({ + offset: 1 +}) +``` + + + + + ```bash title="Integer filter" curl "http://localhost:9000/store/products?offset=1" ``` + + + + @@ -584,10 +794,28 @@ You can pass a boolean value in the form of `=`. + + + + +```js title="Boolean filter" +sdk.store.product.list({ + is_giftcard: true +}) +``` + + + + + ```bash title="Boolean filter" curl "http://localhost:9000/store/products?is_giftcard=true" ``` + + + + @@ -606,10 +834,28 @@ must be in the format `YYYY-MM-DD`. + + + + +```js title="Date filter" +sdk.store.product.list({ + created_at: { $lt: "2023-02-17" } +}) +``` + + + + + ```bash title="Date filter" curl -g "http://localhost:9000/store/products?created_at[$lt]=2023-02-17" ``` + + + + @@ -625,10 +871,28 @@ note that the `T` and `Z` here are fixed. + + + + +```js title="Date and time filter" +sdk.store.product.list({ + created_at: { $lt: "2023-02-17T07:22:30Z" } +}) +``` + + + + + ```bash title="Date and time filter" curl -g "http://localhost:9000/store/products?created_at[$lt]=2023-02-17T07:22:30Z" ``` + + + + @@ -645,22 +909,33 @@ Array filters can be passed either as: - `[]=&[]=`, passing each value as a separate query parameter. You can also specify the index of each parameter in the brackets `[0]=`. +When using the JS SDK, you can pass the array directly to the query parameter. The JS SDK will handle the rest. + + + +```js title="Array filter" +sdk.store.product.list({ + sales_channel_id: ["sc_123", "sc_456"] +}) +``` + + ```bash -curl -g "http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7,sc_234PGVB42PZ7N3YQEP2WDM7PC7" +curl -g "http://localhost:9000/store/products?sales_channel_id[]=sc_123,sc_456" ``` ```bash -curl -g "http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7" +curl -g "http://localhost:9000/store/products?sales_channel_id[]=sc_123&sales_channel_id[]=sc_456" ``` @@ -684,14 +959,34 @@ for using the brackets. Read more Object parameters must be passed as separate query parameters in the form `[]=`. +When using the JS SDK, you can pass the object directly to the query parameter. The JS SDK will handle the rest. + + + + + +```js title="Object filter" +sdk.store.product.list({ + created_at: { $lt: "2023-02-17", $gt: "2022-09-17" } +}) +``` + + + + + ```bash title="Object filter" curl -g "http://localhost:9000/store/products?created_at[$lt]=2023-02-17&created_at[$gt]=2022-09-17" ``` + + + + @@ -744,10 +1039,29 @@ Use the `offset` query parameter to change between pages. For example, if the li + + + + +```js title="Pagination query parameters" +sdk.store.product.list({ + limit: 5, + offset: 0 +}) +``` + + + + + ```bash title="Pagination query parameters" curl "http://localhost:9000/store/products?limit=5&offset=0" ``` + + + + @@ -789,10 +1103,28 @@ sort the retrieved items by a field of that item. + + + + +```js title="Ascending sort by a field" +sdk.store.product.list({ + order: "created_at" +}) +``` + + + + + ```bash title="Ascending sort by a field" curl "http://localhost:9000/store/products?order=created_at" ``` + + + + This sorts the products by their `created_at` field in the ascending order. @@ -810,10 +1142,28 @@ descending, pass a dash (`-`) before the field name. + + + + +```js title="Descending sort by a field" +sdk.store.product.list({ + order: "-created_at" +}) +``` + + + + + ```bash title="Descending sort by a field" curl "http://localhost:9000/store/products?order=-created_at" ``` + + + + This sorts the products by their `created_at` field in the descending order.