chore!: simplify api handler (#6910)

Removes PayloadRequestWithData in favour of just PayloadRequest with
optional types for `data` and `locale`

`addDataAndFileToRequest` and `addLocalesToRequestFromData` now takes in
a single argument instead of an object

```ts
// before
await addDataAndFileToRequest({ request: req })
addLocalesToRequestFromData({ request: req })

// current
await addDataAndFileToRequest(req)
addLocalesToRequestFromData(req)
```

---------

Co-authored-by: Paul Popus <paul@nouance.io>

Author: JarrodMFlesch

docs/rest-api/overview.mdx

@@ -598,15 +598,37 @@ export const Orders: CollectionConfig = {
     {
       path: '/:id/tracking',
       method: 'get',
-      handler: async (req, res, next) => {
+      handler: (req) => {
         const tracking = await getTrackingInfo(req.params.id)
-        if (tracking) {
-          res.status(200).send({ tracking })
-        } else {
-          res.status(404).send({ error: 'not found' })
+
+        if (!tracking) {
+          return Response.json({ error: 'not found' }, { status: 404})
         }
+
+        return Response.json({
+          message: `Hello ${req.routeParams.name as string} @ ${req.routeParams.group as string}`,
+        })
       },
     },
+    {
+      path: '/:id/tracking',
+      method: 'post',
+      handler: (req) => {
+        // `data` is not automatically appended to the request
+        // if you would like to read the body of the request
+        // you can use `data = await req.json()`
+        const data = await req.json()
+        await req.payload.update({
+          collection: 'tracking',
+          data: {
+            // data to update the document with
+          }
+        })
+        return Response.json({
+          message: 'successfully updated tracking info'
+        })
+      }
+    }
   ],
   // highlight-end
 }
@@ -619,6 +641,56 @@ export const Orders: CollectionConfig = {
   calls like req.payload.find() that will make use of access control and hooks.
 </Banner>
 
+#### Helpful tips
+`req.data`
+
+Data is not automatically appended to the request. You can read the body data by calling `await req.json()`.
+
+Or you could use our helper function that mutates the request and appends data and file if found.
+
+```ts
+import { addDataAndFileToRequest } from '@payloadcms/next/utilities'
+
+// custom endpoint example
+{
+  path: '/:id/tracking',
+  method: 'post',
+  handler: (req) => {
+    await addDataAndFileToRequest(req)
+    await req.payload.update({
+      collection: 'tracking',
+      data: {
+        // data to update the document with
+      }
+    })
+    return Response.json({
+      message: 'successfully updated tracking info'
+    })
+  }
+}
+```
+
+`req.locale` & `req.fallbackLocale`
+
+The locale and the fallback locale are not automatically appended to custom endpoint requests. If you would like to add them you can use this helper function.
+
+```ts
+import { addLocalesToRequestFromData } from '@payloadcms/next/utilities'
+
+// custom endpoint example
+{
+  path: '/:id/tracking',
+  method: 'post',
+  handler: (req) => {
+    await addLocalesToRequestFromData(req)
+    // you now can access req.locale & req.fallbackLocale
+    return Response.json({ message: 'success' })
+  }
+}
+```
+
+
+
 ## Method Override for GET Requests
 
 Payload supports a method override feature that allows you to send GET requests using the HTTP POST method. This can be particularly useful in scenarios when the query string in a regular GET request is too long.

examples/auth/payload/src/app/(app)/_components/HydrateClientUser/index.tsx

@@ -1,15 +1,15 @@
 'use client'
 
 import type { Permissions } from 'payload/auth'
-import type { PayloadRequestWithData } from 'payload/types'
+import type { PayloadRequest } from 'payload/types'
 
 import { useEffect } from 'react'
 
 import { useAuth } from '../../_providers/Auth'
 
 export const HydrateClientUser: React.FC<{
   permissions: Permissions
-  user: PayloadRequestWithData['user']
+  user: PayloadRequest['user']
 }> = ({ permissions, user }) => {
   const { setPermissions, setUser } = useAuth()
 

packages/db-mongodb/src/count.ts

@@ -1,5 +1,5 @@
 import type { QueryOptions } from 'mongoose'
-import type { Count, PayloadRequestWithData } from 'payload'
+import type { Count, PayloadRequest } from 'payload'
 
 import { flattenWhereToOperators } from 'payload'
 
@@ -9,7 +9,7 @@ import { withSession } from './withSession.js'
 
 export const count: Count = async function count(
   this: MongooseAdapter,
-  { collection, locale, req = {} as PayloadRequestWithData, where },
+  { collection, locale, req = {} as PayloadRequest, where },
 ) {
   const Model = this.collections[collection]
   const options: QueryOptions = withSession(this, req.transactionID)

packages/db-mongodb/src/create.ts

@@ -1,4 +1,4 @@
-import type { Create, Document, PayloadRequestWithData } from 'payload'
+import type { Create, Document, PayloadRequest } from 'payload'
 
 import type { MongooseAdapter } from './index.js'
 
@@ -7,7 +7,7 @@ import { withSession } from './withSession.js'
 
 export const create: Create = async function create(
   this: MongooseAdapter,
-  { collection, data, req = {} as PayloadRequestWithData },
+  { collection, data, req = {} as PayloadRequest },
 ) {
   const Model = this.collections[collection]
   const options = withSession(this, req.transactionID)

packages/db-mongodb/src/createGlobal.ts

@@ -1,4 +1,4 @@
-import type { CreateGlobal, PayloadRequestWithData } from 'payload'
+import type { CreateGlobal, PayloadRequest } from 'payload'
 
 import type { MongooseAdapter } from './index.js'
 
@@ -7,7 +7,7 @@ import { withSession } from './withSession.js'
 
 export const createGlobal: CreateGlobal = async function createGlobal(
   this: MongooseAdapter,
-  { slug, data, req = {} as PayloadRequestWithData },
+  { slug, data, req = {} as PayloadRequest },
 ) {
   const Model = this.globals
   const global = {

packages/db-mongodb/src/createGlobalVersion.ts

@@ -1,20 +1,12 @@
-import type { CreateGlobalVersion, Document, PayloadRequestWithData } from 'payload'
+import type { CreateGlobalVersion, Document, PayloadRequest } from 'payload'
 
 import type { MongooseAdapter } from './index.js'
 
 import { withSession } from './withSession.js'
 
 export const createGlobalVersion: CreateGlobalVersion = async function createGlobalVersion(
   this: MongooseAdapter,
-  {
-    autosave,
-    createdAt,
-    globalSlug,
-    parent,
-    req = {} as PayloadRequestWithData,
-    updatedAt,
-    versionData,
-  },
+  { autosave, createdAt, globalSlug, parent, req = {} as PayloadRequest, updatedAt, versionData },
 ) {
   const VersionModel = this.versions[globalSlug]
   const options = withSession(this, req.transactionID)

packages/db-mongodb/src/createVersion.ts

@@ -1,4 +1,4 @@
-import type { CreateVersion, Document, PayloadRequestWithData } from 'payload'
+import type { CreateVersion, Document, PayloadRequest } from 'payload'
 
 import type { MongooseAdapter } from './index.js'
 
@@ -11,7 +11,7 @@ export const createVersion: CreateVersion = async function createVersion(
     collectionSlug,
     createdAt,
     parent,
-    req = {} as PayloadRequestWithData,
+    req = {} as PayloadRequest,
     updatedAt,
     versionData,
   },

packages/db-mongodb/src/deleteMany.ts

@@ -1,12 +1,12 @@
-import type { DeleteMany, PayloadRequestWithData } from 'payload'
+import type { DeleteMany, PayloadRequest } from 'payload'
 
 import type { MongooseAdapter } from './index.js'
 
 import { withSession } from './withSession.js'
 
 export const deleteMany: DeleteMany = async function deleteMany(
   this: MongooseAdapter,
-  { collection, req = {} as PayloadRequestWithData, where },
+  { collection, req = {} as PayloadRequest, where },
 ) {
   const Model = this.collections[collection]
   const options = {

packages/db-mongodb/src/deleteOne.ts

@@ -1,4 +1,4 @@
-import type { DeleteOne, Document, PayloadRequestWithData } from 'payload'
+import type { DeleteOne, Document, PayloadRequest } from 'payload'
 
 import type { MongooseAdapter } from './index.js'
 
@@ -7,7 +7,7 @@ import { withSession } from './withSession.js'
 
 export const deleteOne: DeleteOne = async function deleteOne(
   this: MongooseAdapter,
-  { collection, req = {} as PayloadRequestWithData, where },
+  { collection, req = {} as PayloadRequest, where },
 ) {
   const Model = this.collections[collection]
   const options = withSession(this, req.transactionID)

packages/db-mongodb/src/deleteVersions.ts

@@ -1,12 +1,12 @@
-import type { DeleteVersions, PayloadRequestWithData } from 'payload'
+import type { DeleteVersions, PayloadRequest } from 'payload'
 
 import type { MongooseAdapter } from './index.js'
 
 import { withSession } from './withSession.js'
 
 export const deleteVersions: DeleteVersions = async function deleteVersions(
   this: MongooseAdapter,
-  { collection, locale, req = {} as PayloadRequestWithData, where },
+  { collection, locale, req = {} as PayloadRequest, where },
 ) {
   const VersionsModel = this.versions[collection]
   const options = {