feat(SITES-43695): add defaultSiteId to Organization model and resolveSite endpoint

- Expose defaultSiteId in OrganizationDto.toJSON() for API responses
- Add PATCH /organizations/:id support for defaultSiteId (valid UUID or null)
- In resolveSite(), check org.defaultSiteId before falling back to getFirstEnrollment()
  so customers can pin a preferred domain without DB insertion-order dependence
- Cross-org and enrollment/tier validation guard the new resolution path
- OpenAPI schema updated to document the new field

Co-Authored-By: Claude <noreply@anthropic.com>

Author: prithipalpatwal

docs/openapi/schemas.yaml

@@ -385,6 +385,9 @@ Organization:
     imsOrgId:
       description: Optional. The ID of the Adobe IMS organization
       $ref: '#/ImsOrganizationId'
+    defaultSiteId:
+      description: Optional. The ID of the default site to resolve on login. When set, /sites-resolve returns this site instead of the insertion-order fallback.
+      $ref: '#/Id'
     config:
       description: Optional. The configuration of the organization
       $ref: '#/OrganizationConfig'

src/controllers/organizations.js

@@ -331,6 +331,15 @@ function OrganizationsController(ctx, env) {
       updates = true;
     }
 
+    if ('defaultSiteId' in requestBody) {
+      const { defaultSiteId } = requestBody;
+      if (defaultSiteId !== null && defaultSiteId !== undefined && !isValidUUID(defaultSiteId)) {
+        return badRequest('Invalid defaultSiteId: must be a valid UUID or null');
+      }
+      organization.setDefaultSiteId(defaultSiteId ?? undefined);
+      updates = true;
+    }
+
     if (updates) {
       const updatedOrganization = await organization.save();
       return ok(OrganizationDto.toJSON(updatedOrganization));

src/controllers/sites.js

@@ -1208,9 +1208,43 @@ function SitesController(ctx, log, env) {
         }
       }
 
+      // Resolves the org's defaultSiteId if set, validating it belongs to the org and is enrolled.
+      // Returns the resolved data object or null to fall through to getFirstEnrollment().
+      const resolveOrgDefaultSite = async (org) => {
+        const defaultSiteId = org.getDefaultSiteId?.();
+        if (!hasText(defaultSiteId) || !isValidUUID(defaultSiteId)) {
+          return null;
+        }
+
+        const defaultSite = await Site.findById(defaultSiteId);
+        if (!defaultSite || defaultSite.getOrganizationId() !== org.getId()) {
+          return null;
+        }
+
+        const siteTierClient = await TierClient.createForSite(context, defaultSite, productCode);
+        const { entitlement, enrollments } = await siteTierClient.getAllEnrollment();
+
+        const tierVisible = entitlement && CUSTOMER_VISIBLE_TIERS.includes(entitlement.getTier());
+        if (!tierVisible || !enrollments?.length) {
+          return null;
+        }
+
+        const isSummitPlgEnabled = await getIsSummitPlgEnabled(defaultSite, context);
+        return {
+          organization: OrganizationDto.toJSON(org),
+          site: SiteDto.toJSON(defaultSite),
+          isSummitPlgEnabled,
+        };
+      };
+
       if (hasText(organizationId) && isValidUUID(organizationId)) {
         organization = await Organization.findById(organizationId);
         if (organization && await accessControlUtil.hasAccess(organization)) {
+          const defaultData = await resolveOrgDefaultSite(organization);
+          if (defaultData) {
+            return ok({ data: defaultData });
+          }
+
           const tierClient = TierClient.createForOrg(context, organization, productCode);
           const { entitlement: orgEntitlement, site: enrolledSite } = await tierClient
             .getFirstEnrollment();
@@ -1230,6 +1264,11 @@ function SitesController(ctx, log, env) {
       } else if (hasText(imsOrg)) {
         organization = await Organization.findByImsOrgId(imsOrg);
         if (organization && await accessControlUtil.hasAccess(organization)) {
+          const defaultData = await resolveOrgDefaultSite(organization);
+          if (defaultData) {
+            return ok({ data: defaultData });
+          }
+
           const tierClient = TierClient.createForOrg(context, organization, productCode);
           const { entitlement: imsOrgEntitlement, site: enrolledSite } = await tierClient
             .getFirstEnrollment();

src/dto/organization.js

@@ -26,6 +26,7 @@ export const OrganizationDto = {
     id: organization.getId(),
     name: organization.getName(),
     imsOrgId: organization.getImsOrgId(),
+    defaultSiteId: organization.getDefaultSiteId(),
     createdAt: organization.getCreatedAt(),
     updatedAt: organization.getUpdatedAt(),
     config: Config.toDynamoItem(organization.getConfig()),

test/controllers/organizations.test.js

@@ -439,6 +439,57 @@ describe('Organizations Controller', () => {
     expect(error).to.have.property('message', 'No updates provided');
   });
 
+  it('updates organization defaultSiteId with a valid UUID', async () => {
+    const validSiteId = '550e8400-e29b-41d4-a716-446655440001';
+    organizations[0].save = sinon.stub().resolves(organizations[0]);
+    organizations[0].setDefaultSiteId = sinon.stub();
+    organizations[0].getDefaultSiteId = sinon.stub().returns(validSiteId);
+    mockDataAccess.Organization.findById.resolves(organizations[0]);
+
+    const response = await organizationsController.updateOrganization({
+      params: { organizationId: '9033554c-de8a-44ac-a356-09b51af8cc28' },
+      data: { defaultSiteId: validSiteId },
+      ...context,
+    });
+
+    expect(organizations[0].setDefaultSiteId).to.have.been.calledWith(validSiteId);
+    expect(organizations[0].save).to.have.been.calledOnce;
+    expect(response.status).to.equal(200);
+  });
+
+  it('clears organization defaultSiteId when null is provided', async () => {
+    organizations[0].save = sinon.stub().resolves(organizations[0]);
+    organizations[0].setDefaultSiteId = sinon.stub();
+    organizations[0].getDefaultSiteId = sinon.stub().returns(undefined);
+    mockDataAccess.Organization.findById.resolves(organizations[0]);
+
+    const response = await organizationsController.updateOrganization({
+      params: { organizationId: '9033554c-de8a-44ac-a356-09b51af8cc28' },
+      data: { defaultSiteId: null },
+      ...context,
+    });
+
+    expect(organizations[0].setDefaultSiteId).to.have.been.calledWith(undefined);
+    expect(organizations[0].save).to.have.been.calledOnce;
+    expect(response.status).to.equal(200);
+  });
+
+  it('returns bad request when updating defaultSiteId with an invalid UUID', async () => {
+    organizations[0].save = sinon.stub().resolves(organizations[0]);
+    mockDataAccess.Organization.findById.resolves(organizations[0]);
+
+    const response = await organizationsController.updateOrganization({
+      params: { organizationId: '9033554c-de8a-44ac-a356-09b51af8cc28' },
+      data: { defaultSiteId: 'not-a-uuid' },
+      ...context,
+    });
+
+    expect(organizations[0].save).to.not.have.been.called;
+    expect(response.status).to.equal(400);
+    const error = await response.json();
+    expect(error).to.have.property('message', 'Invalid defaultSiteId: must be a valid UUID or null');
+  });
+
   it('gets all organizations', async () => {
     mockDataAccess.Organization.all.resolves(organizations);
 

test/controllers/sites.test.js

@@ -5087,6 +5087,94 @@ describe('Sites Controller', () => {
       const body = await response.json();
       expect(body.message).to.include('No site found for the provided parameters');
     });
+
+    describe('defaultSiteId resolution', () => {
+      it('should resolve defaultSiteId for organizationId path and skip getFirstEnrollment', async () => {
+        sandbox.stub(testOrganizations[0], 'getDefaultSiteId').returns(SITE_IDS[0]);
+        context.data = { organizationId: testOrganizations[0].getId() };
+        mockDataAccess.Organization.findById.resolves(testOrganizations[0]);
+        mockDataAccess.Site.findById.resolves(testSites[0]);
+        mockTierClientStub.getAllEnrollment.resolves({
+          entitlement: { getTier: () => 'FREE_TRIAL' },
+          enrollments: [{ getId: () => 'enrollment-1' }],
+        });
+
+        const response = await sitesController.resolveSite(context);
+
+        expect(response.status).to.equal(200);
+        const body = await response.json();
+        expect(body.data.site.id).to.equal(SITE_IDS[0]);
+        expect(mockTierClientStub.getFirstEnrollment).to.not.have.been.called;
+      });
+
+      it('should resolve defaultSiteId for imsOrg path and skip getFirstEnrollment', async () => {
+        sandbox.stub(testOrganizations[0], 'getDefaultSiteId').returns(SITE_IDS[0]);
+        context.data = { imsOrg: testOrganizations[0].getImsOrgId() };
+        mockDataAccess.Organization.findByImsOrgId.resolves(testOrganizations[0]);
+        mockDataAccess.Site.findById.resolves(testSites[0]);
+        mockTierClientStub.getAllEnrollment.resolves({
+          entitlement: { getTier: () => 'FREE_TRIAL' },
+          enrollments: [{ getId: () => 'enrollment-1' }],
+        });
+
+        const response = await sitesController.resolveSite(context);
+
+        expect(response.status).to.equal(200);
+        const body = await response.json();
+        expect(body.data.site.id).to.equal(SITE_IDS[0]);
+        expect(mockTierClientStub.getFirstEnrollment).to.not.have.been.called;
+      });
+
+      it('should fall through to getFirstEnrollment if defaultSiteId site does not belong to org', async () => {
+        // testSites[1] belongs to testOrganizations[3], not testOrganizations[0]
+        sandbox.stub(testOrganizations[0], 'getDefaultSiteId').returns(SITE_IDS[1]);
+        context.data = { organizationId: testOrganizations[0].getId() };
+        mockDataAccess.Organization.findById.resolves(testOrganizations[0]);
+        mockDataAccess.Site.findById.resolves(testSites[1]);
+        mockTierClientStub.getFirstEnrollment.resolves({
+          entitlement: { getTier: () => 'FREE_TRIAL' },
+          site: testSites[0],
+        });
+
+        await sitesController.resolveSite(context);
+
+        expect(mockTierClientStub.getFirstEnrollment).to.have.been.called;
+      });
+
+      it('should fall through to getFirstEnrollment if defaultSiteId site is not found', async () => {
+        sandbox.stub(testOrganizations[0], 'getDefaultSiteId').returns(SITE_IDS[0]);
+        context.data = { organizationId: testOrganizations[0].getId() };
+        mockDataAccess.Organization.findById.resolves(testOrganizations[0]);
+        mockDataAccess.Site.findById.resolves(null);
+        mockTierClientStub.getFirstEnrollment.resolves({
+          entitlement: { getTier: () => 'FREE_TRIAL' },
+          site: testSites[0],
+        });
+
+        await sitesController.resolveSite(context);
+
+        expect(mockTierClientStub.getFirstEnrollment).to.have.been.called;
+      });
+
+      it('should fall through to getFirstEnrollment if defaultSiteId site has no valid enrollment', async () => {
+        sandbox.stub(testOrganizations[0], 'getDefaultSiteId').returns(SITE_IDS[0]);
+        context.data = { organizationId: testOrganizations[0].getId() };
+        mockDataAccess.Organization.findById.resolves(testOrganizations[0]);
+        mockDataAccess.Site.findById.resolves(testSites[0]);
+        mockTierClientStub.getAllEnrollment.resolves({
+          entitlement: { getTier: () => 'FREE_TRIAL' },
+          enrollments: [],
+        });
+        mockTierClientStub.getFirstEnrollment.resolves({
+          entitlement: { getTier: () => 'FREE_TRIAL' },
+          site: testSites[0],
+        });
+
+        await sitesController.resolveSite(context);
+
+        expect(mockTierClientStub.getFirstEnrollment).to.have.been.called;
+      });
+    });
   });
 
   describe('getBrandProfile', () => {