Add metadata to organizations and users (#1241)

## Description

Supports passing metadata on updating and creation of both as well.

Right now the API doesn't always return metadata, but it will eventually
always return empty object if there is none, and so I've made it so that
users and organizations will always have a metadata object after
deserialization.

## Documentation

Does this require changes to the WorkOS Docs? E.g. the [API
Reference](https://workos.com/docs/reference) or code snippets need
updates.

```
[ ] Yes
```

If yes, link a related docs PR and add a docs maintainer as a reviewer.
Their approval is required.

Author: ericroberts

src/actions/actions.spec.ts

@@ -127,6 +127,7 @@ describe('Actions', () => {
           createdAt: '2024-10-22T17:12:50.746Z',
           updatedAt: '2024-10-22T17:12:50.746Z',
           externalId: null,
+          metadata: {},
         },
         ipAddress: '50.141.123.10',
         userAgent: 'Mozilla/5.0',
@@ -142,6 +143,7 @@ describe('Actions', () => {
           createdAt: '2024-10-22T17:12:50.746Z',
           updatedAt: '2024-10-22T17:12:50.746Z',
           externalId: null,
+          metadata: {},
         },
         organizationMembership: {
           object: 'organization_membership',

src/organizations/fixtures/get-organization.json

@@ -12,5 +12,6 @@
       "verification_strategy": "dns",
       "verification_token": "xB8SeACdKJQP9DP4CahU4YuQZ"
     }
-  ]
+  ],
+  "metadata": {}
 }

src/organizations/interfaces/create-organization-options.interface.ts

@@ -5,6 +5,7 @@ export interface CreateOrganizationOptions {
   name: string;
   domainData?: DomainData[];
   externalId?: string | null;
+  metadata?: Record<string, string>;
 
   /**
    * @deprecated If you need to allow sign-ins from any email domain, contact [email protected].
@@ -20,6 +21,7 @@ export interface SerializedCreateOrganizationOptions {
   name: string;
   domain_data?: DomainData[];
   external_id?: string | null;
+  metadata?: Record<string, string>;
 
   /**
    * @deprecated If you need to allow sign-ins from any email domain, contact [email protected].

src/organizations/interfaces/organization.interface.ts

@@ -13,6 +13,7 @@ export interface Organization {
   createdAt: string;
   updatedAt: string;
   externalId: string | null;
+  metadata: Record<string, string>;
 }
 
 export interface OrganizationResponse {
@@ -25,4 +26,5 @@ export interface OrganizationResponse {
   created_at: string;
   updated_at: string;
   external_id?: string | null;
+  metadata?: Record<string, string>;
 }

src/organizations/interfaces/update-organization-options.interface.ts

@@ -6,6 +6,7 @@ export interface UpdateOrganizationOptions {
   domainData?: DomainData[];
   stripeCustomerId?: string | null;
   externalId?: string | null;
+  metadata?: Record<string, string>;
 
   /**
    * @deprecated If you need to allow sign-ins from any email domain, contact [email protected].
@@ -22,6 +23,7 @@ export interface SerializedUpdateOrganizationOptions {
   domain_data?: DomainData[];
   stripe_customer_id?: string | null;
   external_id?: string | null;
+  metadata?: Record<string, string>;
 
   /**
    * @deprecated If you need to allow sign-ins from any email domain, contact [email protected].

src/organizations/organizations.spec.ts

@@ -187,6 +187,19 @@ describe('Organizations', () => {
           expect(subject.domains).toHaveLength(1);
         });
       });
+
+      it('adds metadata to the request', async () => {
+        fetchOnce(createOrganization, { status: 201 });
+
+        await workos.organizations.createOrganization({
+          name: 'My organization',
+          metadata: { key: 'value' },
+        });
+
+        expect(fetchBody()).toMatchObject({
+          metadata: { key: 'value' },
+        });
+      });
     });
 
     describe('with an invalid payload', () => {
@@ -316,6 +329,19 @@ describe('Organizations', () => {
           expect(subject.domains).toHaveLength(1);
         });
       });
+
+      it('adds metadata to the request', async () => {
+        fetchOnce(updateOrganization, { status: 201 });
+
+        await workos.organizations.updateOrganization({
+          organization: 'org_01EHT88Z8J8795GZNQ4ZP1J81T',
+          metadata: { key: 'value' },
+        });
+
+        expect(fetchBody()).toEqual({
+          metadata: { key: 'value' },
+        });
+      });
     });
 
     describe('when given `stripeCustomerId`', () => {

src/organizations/serializers/create-organization-options.serializer.ts

@@ -11,4 +11,5 @@ export const serializeCreateOrganizationOptions = (
   domain_data: options.domainData,
   domains: options.domains,
   external_id: options.externalId,
+  metadata: options.metadata,
 });

src/organizations/serializers/organization.serializer.spec.ts

@@ -0,0 +1,36 @@
+import { deserializeOrganization } from './organization.serializer';
+import organizationFixture from '../fixtures/get-organization.json';
+
+const organizationResponse = {
+  ...organizationFixture,
+  object: 'organization' as const,
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+  domains: [],
+};
+
+describe('deserializeOrganization', () => {
+  it('includes metadata if present', () => {
+    const metadata = { key: 'value' };
+
+    expect(
+      deserializeOrganization({
+        ...organizationResponse,
+        metadata,
+      }),
+    ).toMatchObject({
+      metadata,
+    });
+  });
+
+  it('coerces missing metadata to empty object', () => {
+    const { metadata, ...organizationResponseWithoutMetadata } =
+      organizationResponse;
+
+    expect(
+      deserializeOrganization(organizationResponseWithoutMetadata),
+    ).toMatchObject({
+      metadata: {},
+    });
+  });
+});

src/organizations/serializers/organization.serializer.ts

@@ -16,4 +16,5 @@ export const deserializeOrganization = (
   createdAt: organization.created_at,
   updatedAt: organization.updated_at,
   externalId: organization.external_id ?? null,
+  metadata: organization.metadata ?? {},
 });

src/organizations/serializers/update-organization-options.serializer.ts

@@ -12,4 +12,5 @@ export const serializeUpdateOrganizationOptions = (
   domains: options.domains,
   stripe_customer_id: options.stripeCustomerId,
   external_id: options.externalId,
+  metadata: options.metadata,
 });