fix(backend): correct createOrganizationInvitationBulk return type to PaginatedResourceResponse

[VihAMBR]

Description

Fixes #8740

clerkClient.organizations.createOrganizationInvitationBulk() is typed as returning Promise<OrganizationInvitation[]>, but the Backend API endpoint it wraps returns a paginated { data, total_count } envelope. The request goes through the same deserializer as every other list endpoint, so at runtime the method already resolves to { data, totalCount } — only the type was wrong, which made the declared type impossible to use correctly.

This aligns the return type with PaginatedResourceResponse<OrganizationInvitation[]>, matching the sibling getOrganizationInvitationList() method directly above it.

Verification of the API shape — confirmed against the Backend API OpenAPI spec rather than assuming. The CreateOrganizationInvitationBulk operation's 200 response references the OrganizationInvitations component, which is:

type: object
properties:
  data:
    type: array
    items:
      $ref: '#/components/schemas/OrganizationInvitation'
  total_count:
    type: integer

(Note: this is intentionally different from the instance-level invitations.createInvitationBulk(), whose response is a bare array — see #7702 — which is why the two bulk methods have different return types.)

This is consistent with the prior return-type corrections shipped as patches, e.g. getOrganizationMembershipList() (#2681) and JwtTemplatesApi.list (#7868).

Note on impact

The runtime value is unchanged; this only corrects the static type. It is technically a type-level breaking change for anyone who wrote code against the old (non-functional) OrganizationInvitation[] type — but since that type never matched the value returned at runtime, such code could not have worked. Consumers now access the invitations via .data and the count via .totalCount, the same as the sibling list methods.

How to test

A unit test was added at packages/backend/src/api/__tests__/OrganizationApi.test.ts that:

• mocks the bulk endpoint returning a { data, total_count } payload,
• asserts the SDK forwards the invitations as a snake_cased array body,
• asserts the response is surfaced as { data, totalCount }, and
• asserts (via expectTypeOf) the return type equals PaginatedResourceResponse<OrganizationInvitation[]> (this assertion fails type-check without the fix).

Full pnpm test for @clerk/backend passes across all three environments (node, edge-runtime, miniflare) and pnpm build succeeds.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[vercel]

@VihAMBR is attempting to deploy a commit to the Clerk Production Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

🦋 Changeset detected

Latest commit: e767fa2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@clerk/backend	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR fixes a type mismatch in createOrganizationInvitationBulk() where the TypeScript return type was declared as OrganizationInvitation[] but the Backend API actually returns { data, totalCount }. The implementation is updated to return PaginatedResourceResponse<OrganizationInvitation[]>, matching the paginated response envelope. A new test suite validates request transformation to snake_cased fields and runtime deserialization. A changeset documents the patch release for @clerk/backend.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title accurately and specifically describes the main change: correcting the return type of createOrganizationInvitationBulk to PaginatedResourceResponse.
Linked Issues check	✅ Passed	The pull request fully addresses issue #8740 by correcting the TypeScript return type to PaginatedResourceResponse<OrganizationInvitation[]>, adding comprehensive tests, and verifying against the Backend API OpenAPI spec.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing the return type of createOrganizationInvitationBulk: the changeset documentation, the test suite, and the API implementation update.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The pull request description is clearly related to the changeset. It explains the bug (incorrect return type), the fix (aligning to PaginatedResourceResponse), and provides verification against the Backend API spec, test details, and impact analysis.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}