fix(medusa,js-sdk,types): Add basic draft order operations to js-sdk (#11514)

**What**
- Exposes `sdk.admin.draftOrder.create/update/retrieve/list` functions from the js-sdk
- Implements the necessary types in the types package.
- Adds missing endpoints to admin API.

packages/core/js-sdk/src/admin/draft-order.ts

@@ -0,0 +1,205 @@
+import { HttpTypes } from "@medusajs/types"
+
+import { Client } from "../client"
+import { ClientHeaders } from "../types"
+
+export class DraftOrder {
+  /**
+   * @ignore
+   */
+  private client: Client
+  /**
+   * @ignore
+   */
+  constructor(client: Client) {
+    this.client = client
+  }
+
+  /**
+   * This method retrieves a draft order by its ID. It sends a request to the
+   * [Get Draft Order](https://docs.medusajs.com/api/admin#draft-orders_getdraftordersid)
+   * API route.
+   *
+   * @param id - The draft order's ID.
+   * @param query - Configure the fields to retrieve in the draft order.
+   * @param headers - Headers to pass in the request
+   * @returns The draft order's details.
+   *
+   * @example
+   * To retrieve a draft order by its ID:
+   *
+   * ```ts
+   * sdk.admin.draftOrder.retrieve("draft_order_123")
+   * .then(({ draft_order }) => {
+   *   console.log(draft_order)
+   * })
+   * ```
+   *
+   * To specify the fields and relations to retrieve:
+   *
+   * ```ts
+   * sdk.admin.draftOrder.retrieve("draft_order_123", {
+   *   fields: "id,*items"
+   * })
+   * .then(({ draft_order }) => {
+   *   console.log(draft_order)
+   * })
+   * ```
+   *
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
+  async retrieve(
+    id: string,
+    query?: HttpTypes.AdminDraftOrderParams,
+    headers?: ClientHeaders
+  ) {
+    return await this.client.fetch<HttpTypes.AdminDraftOrderResponse>(
+      `/admin/draft-orders/${id}`,
+      {
+        query,
+        headers,
+      }
+    )
+  }
+
+  /**
+   * This method retrieves a paginated list of draft orders. It sends a request to the
+   * [List Draft Orders](https://docs.medusajs.com/api/admin#draft-orders_getdraftorders) API route.
+   *
+   * @param queryParams - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of draft orders.
+   *
+   * @example
+   * To retrieve the list of draft orders:
+   *
+   * ```ts
+   * sdk.admin.draftOrder.list()
+   * .then(({ draft_orders, count, limit, offset }) => {
+   *   console.log(draft_orders)
+   * })
+   * ```
+   *
+   * To configure the pagination, pass the `limit` and `offset` query parameters.
+   *
+   * For example, to retrieve only 10 items and skip 10 items:
+   *
+   * ```ts
+   * sdk.admin.draftOrder.list({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ draft_orders, count, limit, offset }) => {
+   *   console.log(draft_orders)
+   * })
+   * ```
+   *
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each draft order:
+   *
+   * ```ts
+   * sdk.admin.draftOrder.list({
+   *   fields: "id,*items"
+   * })
+   * .then(({ draft_orders, count, limit, offset }) => {
+   *   console.log(draft_orders)
+   * })
+   * ```
+   *
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
+  async list(
+    queryParams?: HttpTypes.AdminDraftOrderListParams,
+    headers?: ClientHeaders
+  ) {
+    return await this.client.fetch<HttpTypes.AdminDraftOrderListResponse>(
+      `/admin/draft-orders`,
+      {
+        query: queryParams,
+        headers,
+      }
+    )
+  }
+
+  /**
+   * This method creates a draft order. It sends a request to the
+   * [Create Draft Order](https://docs.medusajs.com/api/admin#draft-orders_postdraftorders) API route.
+   *
+   * @param body - The data to create the draft order.
+   * @param query - Configure the fields to retrieve in the draft order.
+   * @param headers - Headers to pass in the request.
+   *
+   * @example
+   * To create a draft order:
+   *
+   * ```ts
+   * sdk.admin.draftOrder.create({
+   *   email: "test@test.com",
+   *   items: [
+   *     {
+   *       variant_id: "variant_123",
+   *       quantity: 1,
+   *     },
+   *   ],
+   *   region_id: "region_123",
+   *   sales_channel_id: "sales_channel_123",
+   * })
+   * .then(({ draft_order }) => {
+   *   console.log(draft_order)
+   * })
+   * ```
+   */
+  async create(
+    body: HttpTypes.AdminCreateDraftOrder,
+    query?: HttpTypes.AdminDraftOrderParams,
+    headers?: ClientHeaders
+  ) {
+    return await this.client.fetch<HttpTypes.AdminDraftOrderResponse>(
+      `/admin/draft-orders`,
+      {
+        method: "POST",
+        body,
+        query,
+        headers,
+      }
+    )
+  }
+
+  /**
+   * This method updates a draft order. It sends a request to the
+   * [Update Draft Order](https://docs.medusajs.com/api/admin#draft-orders_postdraftordersid) API route.
+   *
+   * @param id - The draft order's ID.
+   * @param body - The data to update the draft order.
+   * @param query - Configure the fields to retrieve in the draft order.
+   * @param headers - Headers to pass in the request.
+   *
+   * @example
+   * To update a draft order:
+   *
+   * ```ts
+   * sdk.admin.draftOrder.update("draft_order_123", {
+   *   email: "test@test.com",
+   * })
+   * .then(({ draft_order }) => {
+   *   console.log(draft_order)
+   * })
+   * ```
+   */
+  async update(
+    id: string,
+    body: HttpTypes.AdminUpdateDraftOrder,
+    query?: HttpTypes.AdminDraftOrderParams,
+    headers?: ClientHeaders
+  ) {
+    return await this.client.fetch<HttpTypes.AdminDraftOrderResponse>(
+      `/admin/draft-orders/${id}`,
+      {
+        method: "POST",
+        body,
+        query,
+        headers,
+      }
+    )
+  }
+}

packages/core/js-sdk/src/admin/index.ts

@@ -5,6 +5,7 @@ import { Claim } from "./claim"
 import { Currency } from "./currency"
 import { Customer } from "./customer"
 import { CustomerGroup } from "./customer-group"
+import { DraftOrder } from "./draft-order"
 import { Exchange } from "./exchange"
 import { Fulfillment } from "./fulfillment"
 import { FulfillmentProvider } from "./fulfillment-provider"
@@ -126,6 +127,10 @@ export class Admin {
    * @tags order
    */
   public order: Order
+  /**
+   * @tags draft order
+   */
+  public draftOrder: DraftOrder
   /**
    * @tags order
    */

packages/core/types/src/http/draft-order/admin/entities.ts

@@ -0,0 +1,3 @@
+import { AdminOrder } from "../../order"
+
+export interface AdminDraftOrder extends AdminOrder {}

packages/core/types/src/http/draft-order/admin/index.ts

@@ -0,0 +1,4 @@
+export * from "./entities"
+export * from "./payloads"
+export * from "./queries"
+export * from "./responses"

packages/core/types/src/http/draft-order/admin/payloads.ts

@@ -0,0 +1,111 @@
+import { OrderAddress } from "../../order"
+
+export interface AdminCreateDraftOrderItem {
+  /**
+   * The item's title.
+   */
+  title?: string | null
+  /**
+   * The item's variant SKU.
+   */
+  variant_sku?: string | null
+  /**
+   * The item's variant barcode.
+   */
+  variant_barcode?: string | null
+  /**
+   * The ID of the item's variant.
+   */
+  variant_id?: string | null
+  /**
+   * The item's unit price.
+   */
+  unit_price?: number | null
+  /**
+   * The item's quantity.
+   */
+  quantity: number
+  /**
+   * The item's metadata.
+   */
+  metadata?: Record<string, unknown> | null
+}
+
+export interface AdminCreateDraftOrderShippingMethod {
+  /**
+   * The ID of the shipping option.
+   */
+  shipping_option_id: string
+}
+
+export interface AdminCreateDraftOrder {
+  /**
+   * The draft order's email.
+   *
+   * Either email or customer_id must be provided.
+   */
+  email?: string | null
+  /**
+   * The ID of the customer to associate the draft order with.
+   *
+   * Either customer_id or email must be provided.
+   */
+  customer_id?: string | null
+  /**
+   * The ID of the region to associate the draft order with.
+   */
+  region_id: string
+  /**
+   * The currency code to use for the draft order.
+   *
+   * If not provided, the currency from the region will be used.
+   */
+  currency_code?: string | null
+  /**
+   * The promotions to apply to the draft order.
+   */
+  promo_codes?: string[]
+  /**
+   * The draft order's shipping address.
+   */
+  shipping_address?: OrderAddress | string
+  /**
+   * The draft order's billing address.
+   */
+  billing_address?: OrderAddress | string
+  /**
+   * The draft order's items.
+   */
+  items?: AdminCreateDraftOrderItem[]
+  /**
+   * The draft order's shipping methods.
+   */
+  shipping_methods?: AdminCreateDraftOrderShippingMethod[]
+  /**
+   * Whether to notify the customer about the draft order.
+   */
+  no_notification_order?: boolean
+  /**
+   * The draft order's metadata.
+   */
+  metadata?: Record<string, unknown> | null
+}
+
+export interface AdminUpdateDraftOrder {
+  /**
+   * The draft order's email.
+   */
+  email?: string
+  /**
+   * The draft order's shipping address.
+   */
+  shipping_address?: OrderAddress
+  /**
+   * The draft order's billing address.
+   */
+  billing_address?: OrderAddress
+  /**
+   * The draft order's metadata.
+   */
+  metadata?: Record<string, unknown> | null
+}

packages/core/types/src/http/draft-order/admin/queries.ts

@@ -0,0 +1,37 @@
+import { BaseFilterable, OperatorMap } from "../../../dal"
+import { FindParams, SelectParams } from "../../common"
+
+export interface AdminDraftOrderParams extends SelectParams {}
+
+export interface AdminDraftOrderListParams
+  extends FindParams,
+    BaseFilterable<AdminDraftOrderListParams> {
+  /**
+   * Filter by draft order ID(s).
+   */
+  id?: string | string[]
+  /**
+   * Query or keywords to filter the draft order's searchable fields.
+   */
+  q?: string
+  /**
+   * Filter by region IDs to retrieve their associated draft orders.
+   */
+  region_id?: string[] | string
+  /**
+   * Filter by customer IDs to retrieve their associated draft orders.
+   */
+  customer_id?: string[] | string
+  /**
+   * Filter by sales channel IDs to retrieve their associated draft orders.
+   */
+  sales_channel_id?: string[]
+  /**
+   * Apply filters on the draft order's creation date.
+   */
+  created_at?: OperatorMap<string>
+  /**
+   * Apply filters on the draft order's update date.
+   */
+  updated_at?: OperatorMap<string>
+}

packages/core/types/src/http/draft-order/admin/responses.ts

@@ -0,0 +1,11 @@
+import { PaginatedResponse } from "../../common"
+import { AdminDraftOrder } from "./entities"
+
+export interface AdminDraftOrderResponse {
+  draft_order: AdminDraftOrder
+}
+
+export interface AdminDraftOrderListResponse
+  extends PaginatedResponse<{
+    draft_orders: AdminDraftOrder[]
+  }> {}

packages/core/types/src/http/draft-order/index.ts

@@ -0,0 +1 @@
+export * from "./admin"

packages/core/types/src/http/index.ts

@@ -9,6 +9,7 @@ export * from "./common"
 export * from "./currency"
 export * from "./customer"
 export * from "./customer-group"
+export * from "./draft-order"
 export * from "./exchange"
 export * from "./file"
 export * from "./fulfillment"

packages/core/types/src/http/order/admin/responses.ts

@@ -40,11 +40,3 @@ export interface AdminOrderPreviewResponse {
    */
   order: AdminOrderPreview
 }
-
-export interface AdminDraftOrderResponse {
-  draft_order: AdminOrder
-}
-
-export type AdminDraftOrderListResponse = PaginatedResponse<{
-  draft_orders: AdminOrder[]
-}>