feat(backend-core): Add public_metadata to invitation create API

Invitations can optionally carry metadata that will eventually end up in the created user once they sign up.
The metadata must be a well-formed JSON object. In order to add metadata to an invitation, you can use the
public_metadata property when the invitation is created:

https://docs.clerk.dev/popular-guides/invitations#invitation-metadata

packages/backend-core/src/__tests__/apis/InvitationApi.test.ts

@@ -76,6 +76,42 @@ test('createInvitation() accepts a redirectUrl', async () => {
   );
 });
 
+test('createInvitation() accepts publicMetadata', async () => {
+  const emailAddress = 'test@example.com';
+  const publicMetadata = {
+    hello: 'world',
+  };
+  const resJSON = {
+    object: 'invitation',
+    id: 'inv_randomid',
+    email_address: emailAddress,
+    public_metadata: publicMetadata,
+    created_at: 1611948436,
+    updated_at: 1611948436,
+  };
+
+  nock('https://api.clerk.dev')
+    .post('/v1/invitations', {
+      email_address: emailAddress,
+      public_metadata: publicMetadata,
+    })
+    .reply(200, resJSON);
+
+  const invitation = await TestBackendAPIClient.invitations.createInvitation({
+    emailAddress,
+    publicMetadata,
+  });
+  expect(invitation).toEqual(
+    new Invitation({
+      id: resJSON.id,
+      emailAddress,
+      publicMetadata,
+      createdAt: resJSON.created_at,
+      updatedAt: resJSON.updated_at,
+    })
+  );
+});
+
 test('revokeInvitation() revokes an invitation', async () => {
   const id = 'inv_randomid';
   const resJSON = {

packages/backend-core/src/api/collection/InvitationApi.ts

@@ -6,6 +6,7 @@ const basePath = '/invitations';
 type CreateParams = {
   emailAddress: string;
   redirectUrl?: string;
+  publicMetadata?: Record<string, unknown>;
 };
 
 export class InvitationApi extends AbstractApi {

packages/backend-core/src/api/resources/Invitation.ts

@@ -9,7 +9,7 @@ interface InvitationPayload extends InvitationProps {}
 export interface Invitation extends InvitationPayload {}
 
 export class Invitation {
-  static attributes = ['id', 'emailAddress', 'createdAt', 'updatedAt'];
+  static attributes = ['id', 'emailAddress', 'publicMetadata', 'createdAt', 'updatedAt'];
 
   static defaults = [];
 

packages/backend-core/src/api/resources/Props.ts

@@ -59,6 +59,7 @@ export interface IdentificationLinkProps extends ClerkProps {
 
 export interface InvitationProps extends ClerkProps {
   emailAddress: string;
+  publicMetadata?: Record<string, unknown>;
   createdAt: number;
   updatedAt: number;
 }