Add a type-safe way to define custom methods in @payloadcms/sdk

[vqhdev]

It would be useful if @payloadcms/sdk had a built-in way to define custom, fully typed methods on top of sdk.request().

Right now, custom endpoints can be called with sdk.request(), which works well as a low-level API:

const result = await sdk.request({
  method: 'POST',
  path: '/send-invite',
  json: {
    email: 'test@example.com',
    role: 'admin',
  },
})

The problem is that every call site needs to know the exact path, method, and request body expected by the endpoint.

For custom endpoints, TypeScript also does not know the expected request body unless the consumer defines and applies those types manually. This makes mistakes like these easy to introduce:

await sdk.request({
  method: 'POST',
  path: '/send-invte', // typo
  json: {
    email: 'test@example.com',
    // missing "role"
  },
})

From TypeScript's point of view, this can still be a valid sdk.request() call even though it does not match what the custom endpoint expects.

It would be nice to define that contract once and expose it as a normal SDK method:

await sdk.sendInvite({
  email: 'test@example.com',
  role: 'admin',
})

Then TypeScript could immediately catch invalid calls:

await sdk.sendInvite({
  email: 'test@example.com',
})
// Error: Property "role" is missing

await sdk.sendInvite({
  email: 'test@example.com',
  role: 'owner',
})
// Error: "owner" is not assignable to "admin" | "editor"

The endpoint path and HTTP method would also live in one place instead of being repeated throughout the application.

There are a couple of APIs that could support this.

Option 1: Define custom methods in the constructor

const sdk = new PayloadSDK<Config>({
  baseURL: '.../api',

  extend: ({ request }) => ({
    sendInvite: (args: SendInviteArgs) =>
      request({
        method: 'POST',
        path: '/send-invite',
        json: args,
      }),

    getSomething: (id: string) =>
      request({
        method: 'GET',
        path: `/something/${id}`,
      }),
    users: {
      banned: (id: string) =>
        request({
          method: 'GET',
          path: `/banned/${id}`,
        }),
    }
  }),
})

Usage:

const result = await sdk.sendInvite({
  email: 'test@example.com',
  role: 'admin',
})
const result1 = await sdk.users.banned('user-id')

Option 2: Add an .extend() method

const sdk = new PayloadSDK<Config>({
  baseURL: '/api',
}).extend(({ request }) => ({
  sendInvite: (args: SendInviteArgs) =>
    request({
      method: 'POST',
      path: '/send-invite',
      json: args,
    }),

  getSomething: (id: string) =>
    request({
      method: 'GET',
      path: `/something/${id}`,
    }),
  users: {
    banned: (id: string) =>
      request({
        method: 'GET',
        path: `/banned/${id}`,
      }),
  }
}))

Usage would be the same:

const result = await sdk.sendInvite({
  email: 'test@example.com',
  role: 'admin',
})
const result1 = await sdk.users.banned('user-id')

The .extend() approach could also make reusable groups of methods possible:

const sdk = new PayloadSDK<Config>({
  baseURL: '/api',
})
  .extend(userMethods)
  .extend(orderMethods)

The main idea is not to replace sdk.request(). It would still be useful as the low-level escape hatch.

This would provide a higher-level API for custom endpoints where the path, HTTP method, request type, and response type can be defined once. Consumers could then call custom endpoints like regular SDK methods and get TypeScript errors immediately when an argument is missing or has the wrong type.

I think this would make custom endpoints safer to use and reduce duplicated request definitions across an application.

Would something like this make sense for @payloadcms/sdk?