onboarding: Add separate submit for review endpoint

We store the details and call the specific endpoint when the user is submitting their org for review.
This is hidden from the external API.

Author: Yopi

clients/apps/web/src/components/Settings/OrganizationProfileSettings.tsx

@@ -1,6 +1,7 @@
 import { useAuth } from '@/hooks'
 import { useOrganizationKYC } from '@/hooks/queries/org'
 import { useUpdateOrganization } from '@/hooks/queries'
+import { api } from '@/utils/client'
 import { useAutoSave } from '@/hooks/useAutoSave'
 import { useURLValidation } from '@/hooks/useURLValidation'
 import { setValidationErrors } from '@/utils/api/errors'
@@ -646,13 +647,59 @@ const OrganizationProfileSettings: React.FC<
       return
     }
 
-    reset({
-      ...data,
-      default_presentment_currency:
-        data.default_presentment_currency as schemas['PresentmentCurrency'],
-      country: data.country as schemas['CountryAlpha2Input'] | undefined,
-      socials: [...(data.socials || []), ...emptySocials],
-    })
+    if (inKYCMode) {
+      const submitReviewResult = await api.POST(
+        '/v1/organizations/{id}/submit-review',
+        {
+          params: { path: { id: organization.id } },
+        },
+      )
+      const { data: submittedOrganization, error: submitError } =
+        submitReviewResult
+
+      if (submitError) {
+        const errorMessage = Array.isArray(submitError.detail)
+          ? submitError.detail[0]?.msg ||
+            'An error occurred while submitting the organization for review'
+          : typeof submitError.detail === 'string'
+            ? submitError.detail
+            : 'An error occurred while submitting the organization for review'
+
+        if (isValidationError(submitError.detail)) {
+          setValidationErrors(submitError.detail, setError)
+        } else {
+          setError('root', { message: errorMessage })
+        }
+
+        toast({
+          title: 'Review Submission Failed',
+          description: errorMessage,
+        })
+
+        return
+      }
+
+      reset({
+        ...submittedOrganization,
+        default_presentment_currency:
+          submittedOrganization.default_presentment_currency as schemas['PresentmentCurrency'],
+        country: submittedOrganization.country as
+          | schemas['CountryAlpha2Input']
+          | undefined,
+        socials: [...(submittedOrganization.socials || []), ...emptySocials],
+        details: cleanedBody.details,
+      })
+    }
+
+    if (!inKYCMode) {
+      reset({
+        ...data,
+        default_presentment_currency:
+          data.default_presentment_currency as schemas['PresentmentCurrency'],
+        country: data.country as schemas['CountryAlpha2Input'] | undefined,
+        socials: [...(data.socials || []), ...emptySocials],
+      })
+    }
 
     // Refresh the router to get the updated organization data from the server
     router.refresh()

clients/packages/client/src/v1.ts

@@ -698,6 +698,28 @@ export interface paths {
     patch?: never
     trace?: never
   }
+  '/v1/organizations/{id}/submit-review': {
+    parameters: {
+      query?: never
+      header?: never
+      path?: never
+      cookie?: never
+    }
+    get?: never
+    put?: never
+    /**
+     * Submit Organization for Review
+     * @description Submit an organization's saved details for review.
+     *
+     *     **Scopes**: `organizations:write`
+     */
+    post: operations['organizations:submit_review']
+    delete?: never
+    options?: never
+    head?: never
+    patch?: never
+    trace?: never
+  }
   '/v1/organizations/{id}/payment-status': {
     parameters: {
       query?: never
@@ -2770,7 +2792,7 @@ export interface paths {
     }
     /**
      * Get Member by External ID
-     * @description Get a member by external ID.
+     * @description Get a member by external ID. One of customer_id or external_customer_id must be specified.
      *
      *     **Scopes**: `members:read` `members:write`
      */
@@ -2779,7 +2801,7 @@ export interface paths {
     post?: never
     /**
      * Delete Member by External ID
-     * @description Delete a member by external ID.
+     * @description Delete a member by external ID. One of customer_id or external_customer_id must be specified.
      *
      *     **Scopes**: `members:write`
      */
@@ -2788,7 +2810,7 @@ export interface paths {
     head?: never
     /**
      * Update Member by External ID
-     * @description Update a member by external ID.
+     * @description Update a member by external ID. One of customer_id or external_customer_id must be specified.
      *
      *     **Scopes**: `members:write`
      */
@@ -30884,6 +30906,46 @@ export interface operations {
       }
     }
   }
+  'organizations:submit_review': {
+    parameters: {
+      query?: never
+      header?: never
+      path: {
+        id: string
+      }
+      cookie?: never
+    }
+    requestBody?: never
+    responses: {
+      /** @description Organization submitted for review. */
+      200: {
+        headers: {
+          [name: string]: unknown
+        }
+        content: {
+          'application/json': components['schemas']['Organization']
+        }
+      }
+      /** @description Organization not found. */
+      404: {
+        headers: {
+          [name: string]: unknown
+        }
+        content: {
+          'application/json': components['schemas']['ResourceNotFound']
+        }
+      }
+      /** @description Validation Error */
+      422: {
+        headers: {
+          [name: string]: unknown
+        }
+        content: {
+          'application/json': components['schemas']['HTTPValidationError']
+        }
+      }
+    }
+  }
   'organizations:get_payment_status': {
     parameters: {
       query?: never
@@ -37200,7 +37262,12 @@ export interface operations {
   }
   'members:get_member_by_external_id': {
     parameters: {
-      query?: never
+      query?: {
+        /** @description The customer ID. */
+        customer_id?: string | null
+        /** @description The customer external ID. */
+        external_customer_id?: string | null
+      }
       header?: never
       path: {
         /** @description The member external ID. */
@@ -37241,7 +37308,12 @@ export interface operations {
   }
   'members:delete_member_by_external_id': {
     parameters: {
-      query?: never
+      query?: {
+        /** @description The customer ID. */
+        customer_id?: string | null
+        /** @description The customer external ID. */
+        external_customer_id?: string | null
+      }
       header?: never
       path: {
         /** @description The member external ID. */
@@ -37280,7 +37352,12 @@ export interface operations {
   }
   'members:update_member_by_external_id': {
     parameters: {
-      query?: never
+      query?: {
+        /** @description The customer ID. */
+        customer_id?: string | null
+        /** @description The customer external ID. */
+        external_customer_id?: string | null
+      }
       header?: never
       path: {
         /** @description The member external ID. */

server/polar/organization/endpoints.py

@@ -244,6 +244,30 @@ async def update(
     return await organization_service.update(session, organization, organization_update)
 
 
+@router.post(
+    "/{id}/submit-review",
+    response_model=OrganizationSchema,
+    summary="Submit Organization for Review",
+    responses={
+        200: {"description": "Organization submitted for review."},
+        404: OrganizationNotFound,
+    },
+    tags=[APITag.private],
+)
+async def submit_review(
+    id: OrganizationID,
+    auth_subject: auth.OrganizationsWrite,
+    session: AsyncSession = Depends(get_db_session),
+) -> Organization:
+    """Submit an organization's saved details for review."""
+    organization = await organization_service.get(session, auth_subject, id)
+
+    if organization is None:
+        raise ResourceNotFound()
+
+    return await organization_service.submit_for_review(session, organization)
+
+
 @router.delete(
     "/{id}",
     response_model=OrganizationDeletionResponse,

server/polar/organization/service.py

@@ -1,3 +1,4 @@
+import builtins
 import uuid
 from collections.abc import Sequence
 from datetime import UTC, datetime
@@ -14,7 +15,12 @@
 from polar.config import Environment, settings
 from polar.customer.repository import CustomerRepository
 from polar.enums import InvoiceNumbering
-from polar.exceptions import NotPermitted, PolarError, PolarRequestValidationError
+from polar.exceptions import (
+    NotPermitted,
+    PolarError,
+    PolarRequestValidationError,
+    ValidationError,
+)
 from polar.integrations.loops.service import loops as loops_service
 from polar.integrations.plain.service import plain as plain_service
 from polar.integrations.polar.service import polar_self as polar_self_service
@@ -354,23 +360,96 @@ async def update(
             },
         )
 
-        # Only store details once to avoid API overrides later w/o review
-        # We do allow initial details being set upon creation that will still require review,
-        # so upon creation we set details but not details_submitted_at
-        # so details_submitted_at effectively doubles as a "submit for review"
-        # timestamp, for now. We'll revisit this soon enough. @pieterbeulque
-        if not organization.details_submitted_at and update_schema.details:
+        if update_schema.details:
             organization.details = cast(
                 OrganizationDetails, update_schema.details.model_dump()
             )
+
+        organization = await repository.update(organization, update_dict=update_dict)
+
+        await self._after_update(session, organization)
+        return organization
+
+    def _validate_review_submission(
+        self, organization: Organization
+    ) -> builtins.list[ValidationError]:
+        errors: builtins.list[ValidationError] = []
+
+        if not organization.name or not organization.name.strip():
+            errors.append(
+                {
+                    "loc": ("body", "name"),
+                    "msg": "Organization name is required.",
+                    "type": "value_error",
+                    "input": organization.name,
+                }
+            )
+
+        if not organization.website:
+            errors.append(
+                {
+                    "loc": ("body", "website"),
+                    "msg": "Website is required.",
+                    "type": "value_error",
+                    "input": organization.website,
+                }
+            )
+
+        if not organization.email:
+            errors.append(
+                {
+                    "loc": ("body", "email"),
+                    "msg": "Support email is required.",
+                    "type": "value_error",
+                    "input": organization.email,
+                }
+            )
+
+        if not any(
+            social.get("url", "").strip() for social in (organization.socials or [])
+        ):
+            errors.append(
+                {
+                    "loc": ("body", "socials"),
+                    "msg": "At least one social media link is required.",
+                    "type": "value_error",
+                    "input": organization.socials,
+                }
+            )
+
+        product_description = (organization.details or {}).get("product_description")
+        if (
+            not isinstance(product_description, str)
+            or len(product_description.strip()) < 30
+        ):
+            errors.append(
+                {
+                    "loc": ("body", "details", "product_description"),
+                    "msg": "Please provide at least 30 characters.",
+                    "type": "value_error",
+                    "input": product_description,
+                }
+            )
+
+        return errors
+
+    async def submit_for_review(
+        self, session: AsyncSession, organization: Organization
+    ) -> Organization:
+        errors = self._validate_review_submission(organization)
+
+        if errors:
+            raise PolarRequestValidationError(errors)
+
+        if organization.details_submitted_at is None:
             organization.details_submitted_at = datetime.now(UTC)
             enqueue_job(
                 "organization_review.run_agent",
                 organization_id=organization.id,
                 context=ReviewContext.SUBMISSION,
             )
 
-        organization = await repository.update(organization, update_dict=update_dict)
+        session.add(organization)
 
         await self._after_update(session, organization)
         return organization
@@ -968,8 +1047,8 @@ async def get_ai_review(
     ) -> OrganizationReview | None:
         """Get the existing AI review for an organization, if any.
 
-        The actual AI review is now triggered asynchronously via a background
-        task when organization details are first submitted (see update()).
+        The actual AI review is triggered asynchronously via a background
+        task when organization details are submitted for review.
         """
         repository = OrganizationReviewRepository.from_session(session)
         return await repository.get_by_organization(organization.id)