feat(vtex): add schema parameter to Masterdata loaders and actions

vtex/actions/masterdata/createDocument.ts

@@ -5,6 +5,7 @@ import type { CreateNewDocument } from "../../utils/types.ts";
 export interface Props {
   data: Record<string, unknown>;
   acronym: string;
+  schema?: string;
   isPrivateEntity?: boolean;
 }
 
@@ -20,7 +21,7 @@ const action = async (
   /* no-explicit-any */
 ): Promise<CreateNewDocument> => {
   const { vcs, vcsDeprecated } = ctx;
-  const { data, acronym, isPrivateEntity } = props;
+  const { data, acronym, isPrivateEntity, schema } = props;
   const { cookie } = parseCookie(req.headers, ctx.account);
 
   const requestOptions = {
@@ -35,11 +36,11 @@ const action = async (
   const response =
     await (isPrivateEntity
       ? vcs[`POST /api/dataentities/:acronym/documents`](
-        { acronym },
+        schema ? { acronym, _schema: schema } : { acronym },
         requestOptions,
       )
       : vcsDeprecated[`POST /api/dataentities/:acronym/documents`](
-        { acronym },
+        schema ? { acronym, _schema: schema } : { acronym },
         requestOptions,
       ));
 

vtex/actions/masterdata/updateDocument.ts

@@ -10,6 +10,7 @@ export interface Props {
   acronym: string;
   data: Record<string, unknown>;
   createIfNotExists?: boolean;
+  schema?: string;
 }
 
 /**
@@ -24,7 +25,7 @@ const action = async (
   ctx: AppContext,
 ): Promise<unknown | IdHrefDocumentID> => {
   const { vcs } = ctx;
-  const { id, data, acronym, createIfNotExists } = props;
+  const { id, data, acronym, createIfNotExists, schema } = props;
   const { cookie } = parseCookie(req.headers, ctx.account);
 
   const requestOptions = {
@@ -39,11 +40,11 @@ const action = async (
   const response =
     await (createIfNotExists
       ? vcs["PATCH /api/dataentities/:acronym/documents"](
-        { acronym },
+        schema ? { acronym, _schema: schema } : { acronym },
         requestOptions,
       )
       : vcs["PATCH /api/dataentities/:acronym/documents/:id"](
-        { acronym, id },
+        schema ? { acronym, id, _schema: schema } : { acronym, id },
         requestOptions,
       ));
 

vtex/loaders/masterdata/searchDocuments.ts

@@ -16,6 +16,10 @@ interface Props {
    * @description Specification of filters.
    */
   where?: string;
+  /**
+   * @description Schema of the data entity.
+   */
+  schema?: string;
   /**
    * @description Inform a field name plus ASC to sort results by this field value in ascending order or DESC to sort by descending order.
    */
@@ -47,7 +51,7 @@ export default async function loader(
   ctx: AppContext,
 ): Promise<Document[]> {
   const { vcs } = ctx;
-  const { acronym, fields, where, sort, skip = 0, take = 10 } = props;
+  const { acronym, fields, where, sort, skip = 0, take = 10, schema } = props;
   const { cookie } = parseCookie(req.headers, ctx.account);
   const limits = resourceRange(skip, take);
 
@@ -56,6 +60,7 @@ export default async function loader(
     _fields: fields,
     _where: where,
     _sort: sort,
+    _schema: schema,
   }, {
     headers: {
       accept: "application/vnd.vtex.ds.v10+json",

vtex/utils/client.ts

@@ -289,6 +289,9 @@ export interface VTEXCommerceStable {
       };
     };
   "POST /api/dataentities/:acronym/documents": {
+    searchParams: {
+      _schema?: string;
+    };
     response: CreateNewDocument;
     body: Record<string, unknown>;
   };

vtex/utils/openapi/vcs.openapi.gen.ts

@@ -736,6 +736,10 @@ searchParams: {
  * Names of the fields that will be returned per document, separated by a comma `,`. It is possible to fetch all fields using `_all` as the value of this query parameter. However, in order to avoid permission errors, we strongly recommend informing only the names of the exact fields that will be used.
  */
 _fields?: string
+/**
+ * Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters.
+ */
+_schema?: string
 /**
  * Specification of filters.
  */
@@ -861,6 +865,12 @@ to?: number
  * Create a new document
  */
 "POST /api/dataentities/:acronym/documents": {
+searchParams: {
+/**
+ * Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters.
+ */
+_schema?: string
+}
 body: {
 anyProperty?: string
 }
@@ -890,6 +900,12 @@ DocumentId?: string
  * >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.
  */
 "PATCH /api/dataentities/:acronym/documents": {
+searchParams: {
+/**
+ * Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters.
+ */
+_schema?: string
+}
 body: {
 /**
  * Unique identifier of the document to be created.
@@ -927,6 +943,10 @@ searchParams: {
  * Names of the fields that will be returned per document, separated by a comma `,`. It is possible to fetch all fields using `_all` as the value of this query parameter. However, in order to avoid permission errors, we strongly recommend informing only the names of the exact fields that will be used.
  */
 _fields?: string
+/**
+ * Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters.
+ */
+_schema?: string
 }
 response: Document
 }
@@ -975,6 +995,12 @@ response: Document
  * >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.
  */
 "PUT /api/dataentities/:acronym/documents/:id": {
+searchParams: {
+/**
+ * Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters.
+ */
+_schema?: string
+}
 /**
  * Object with document fields and their respective values.
  */
@@ -1003,7 +1029,12 @@ body: {
  * >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.
  */
 "DELETE /api/dataentities/:acronym/documents/:id": {
-
+searchParams: {
+/**
+ * Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters.
+ */
+_schema?: string
+}
 }
 /**
  * Updates a subset of fields of a document, without impacting the other fields.
@@ -1025,6 +1056,12 @@ body: {
  * >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.
  */
 "PATCH /api/dataentities/:acronym/documents/:id": {
+searchParams: {
+/**
+ * Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters.
+ */
+_schema?: string
+}
 /**
  * Object with the fields to be updated and their respective values.
  */

vtex/utils/openapi/vcs.openapi.json

@@ -971,6 +971,17 @@
               "example": "email,firstName,document"
             }
           },
+          {
+            "name": "_schema",
+            "in": "query",
+            "description": "Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters.",
+            "required": false,
+            "style": "form",
+            "schema": {
+              "type": "string",
+              "example": "schema"
+            }
+          },
           {
             "name": "_where",
             "in": "query",
@@ -1557,6 +1568,17 @@
             "schema": {
               "type": "string"
             }
+          },
+          {
+            "name": "_schema",
+            "in": "query",
+            "description": "Name of the [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) that the document complies with.  This field is required when using `_where` or `_fields` query parameters.",
+            "required": false,
+            "style": "form",
+            "schema": {
+              "type": "string",
+              "example": "schema"
+            }
           }
         ],
         "requestBody": {
@@ -1614,6 +1636,9 @@
           },
           {
             "$ref": "#/components/parameters/acronym"
+          },
+          {
+            "$ref": "#/components/parameters/_schema"
           }
         ],
         "requestBody": {
@@ -1685,6 +1710,9 @@
           },
           {
             "$ref": "#/components/parameters/fields"
+          },
+          {
+            "$ref": "#/components/parameters/_schema"
           }
         ],
         "responses": {
@@ -1745,6 +1773,9 @@
           },
           {
             "$ref": "#/components/parameters/id"
+          },
+          {
+            "$ref": "#/components/parameters/_schema"
           }
         ],
         "requestBody": {
@@ -1810,6 +1841,9 @@
           },
           {
             "$ref": "#/components/parameters/id"
+          },
+          {
+            "$ref": "#/components/parameters/_schema"
           }
         ],
         "requestBody": {
@@ -1851,6 +1885,9 @@
           },
           {
             "$ref": "#/components/parameters/id"
+          },
+          {
+            "$ref": "#/components/parameters/_schema"
           }
         ],
         "responses": {