PAPI-3321: Add information about cursor pagination support by metafield endpoints (#1235)

Author: bc-tayvs

package-lock.json

@@ -866,6 +866,8 @@ paths:
         - $ref: '#/components/parameters/MetafieldKeyParam'
         - $ref: '#/components/parameters/MetafieldNamespaceParam'
         - $ref: '#/components/parameters/DirectionParam'
+        - $ref: '#/components/parameters/BeforeCursorParam'
+        - $ref: '#/components/parameters/AfterCursorParam'
       responses:
         '200':
           description: |
@@ -1109,6 +1111,8 @@ paths:
         - $ref: '#/components/parameters/date_modified_max'
         - $ref: '#/components/parameters/date_created_min'
         - $ref: '#/components/parameters/date_created_max'
+        - $ref: '#/components/parameters/BeforeCursorParam'
+        - $ref: '#/components/parameters/AfterCursorParam'
     post:
       summary: Create multiple Metafields
       tags:
@@ -1290,6 +1294,101 @@ paths:
                 $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE'
 components:
   schemas:
+    Pagination:
+      type: object
+      description: Data about the response, including pagination and collection totals.
+      title: Pagination
+      properties:
+        total:
+          type: integer
+          description: |
+            Total number of items in the result set.
+          example: 36
+        count:
+          type: integer
+          description: |
+            Total number of items in the collection response.
+          example: 36
+        per_page:
+          type: integer
+          description: |
+            The amount of items returned in the collection per page, controlled by the limit parameter.
+          example: 50
+        current_page:
+          type: integer
+          description: |
+            The page you are currently on within the collection.
+          example: 1
+        total_pages:
+          type: integer
+          description: |
+            The total number of pages in the collection.
+          example: 1
+        links:
+          type: object
+          description: |
+            Pagination links for the previous and next parts of the whole collection.
+          properties:
+            previous:
+              type: string
+              description: |
+                Link to the previous page returned in the response.
+            current:
+              type: string
+              description: |
+                Link to the current page returned in the response.
+              example: '?page=1&limit=50'
+            next:
+              type: string
+              description: |
+                Link to the next page returned in the response.
+      x-internal: false
+    CursorPagination:
+      type: object
+      description: Data about the response, including cursor pagination and collection totals.
+      title: CursorPagination
+      properties:
+        count:
+          type: integer
+          description: |
+            Total number of items in the collection response.
+          example: 36
+        per_page:
+          type: integer
+          description: |
+            The amount of items returned in the collection per page, controlled by the limit parameter.
+          example: 50
+        start_cursor:
+          type: string
+          description: |
+            Cursor that is referring to a start of current page.
+          example: "aWQ6Nw=="
+        end_cursor:
+          type: string
+          description: |
+            Cursor that is referring to a end of current page. Should be used to fetch next page.
+          example: "aWQ6Nw=="
+        links:
+          type: object
+          description: |
+            Pagination links for the previous and next parts of the whole collection.
+          properties:
+            previous:
+              type: string
+              description: |
+                Cursor to the previous page returned in the response.
+              example: '?page=1&after=aWQ6Nw%3D%3D'
+            current:
+              type: string
+              description: |
+                Cursor to the current page returned in the response.
+              example: '?page=1&after=aWQ6Nw%3D%3D'
+            next:
+              type: string
+              description: |
+                Cursor to the next page returned in the response.
+              example: '?page=1&after=aWQ6Nw%3D%3D'
+      x-internal: false
     CartUpdateRequest:
       type: object
       properties:
@@ -3667,53 +3766,9 @@ components:
       description: Data about the response, including pagination and collection totals.
       properties:
         pagination:
-          type: object
-          description: Data about the response, including pagination and collection totals.
-          title: Pagination
-          properties:
-            total:
-              type: integer
-              description: |
-                Total number of items in the result set.
-              example: 36
-            count:
-              type: integer
-              description: |
-                Total number of items in the collection response.
-              example: 36
-            per_page:
-              type: integer
-              description: |
-                The amount of items returned in the collection per page, controlled by the limit parameter.
-              example: 50
-            current_page:
-              type: integer
-              description: |
-                The page you are currently on within the collection.
-              example: 1
-            total_pages:
-              type: integer
-              description: |
-                The total number of pages in the collection.
-              example: 1
-            links:
-              type: object
-              description: |
-                Pagination links for the previous and next parts of the whole collection.
-              properties:
-                previous:
-                  type: string
-                  description: |
-                    Link to the previous page returned in the response.
-                current:
-                  type: string
-                  description: |
-                    Link to the current page returned in the response.
-                  example: '?page=1&limit=50'
-                next:
-                  type: string
-                  description: |
-                    Link to the next page returned in the response.
+          $ref: '#/components/schemas/Pagination'
+        cursor_pagination:
+          $ref: '#/components/schemas/CursorPagination'
       additionalProperties: true
       title: Collection Meta
       x-internal: false
@@ -3779,6 +3834,20 @@ components:
                 meta:
                   $ref: '#/components/schemas/metaCollection_open'
   parameters:
+    BeforeCursorParam:
+      name: 'before'
+      description: 'A cursor indicating where to start retrieving the previous page of results. Use this parameter to paginate backward. Not required for the initial request. For subsequent requests, use the end_cursor value returned in meta.cursor_pagination from the previous response. Works with limit, direction, and other supported query parameters. When specified, offset-based pagination (page) is ignored. Cannot be used in combination with the after parameter.'
+      in: query
+      required: false
+      schema:
+        type: string
+    AfterCursorParam:
+      name: 'after'
+      description: 'A cursor indicating where to start retrieving the next page of results. Use this parameter to paginate forward. Not required for the initial request. For subsequent requests, use the start_cursor value returned in meta.cursor_pagination from the previous response. Works with limit, direction, and other supported query parameters. When specified, offset-based pagination (page) is ignored. Cannot be used in combination with the before parameter.'
+      in: query
+      required: false
+      schema:
+        type: string
     Accept:
       name: Accept
       in: header