feat(console): introduce system limit error toast (#7931)

Author: xiaoyijun

packages/console/src/cloud/types/router.ts

@@ -15,6 +15,10 @@ export type TenantUsageAddOnSkus = GuardedResponse<
   GetRoutes['/api/tenants/:tenantId/subscription/add-on-skus']
 >;
 
+export type SystemLimit = Required<
+  GuardedResponse<GetRoutes['/api/tenants/my/subscription']>
+>['systemLimit'];
+
 /* ===== Use `New` in the naming to avoid confusion with legacy types ===== */
 export type NewSubscriptionUsageResponse = GuardedResponse<
   GetRoutes['/api/tenants/:tenantId/subscription-usage']

packages/console/src/ds-components/Toast/ToastWithAction.tsx

@@ -0,0 +1,64 @@
+import { type AdminConsoleKey } from '@logto/phrases';
+import classNames from 'classnames';
+import { toast } from 'react-hot-toast';
+
+import Error from '@/assets/icons/toast-error.svg?react';
+import Success from '@/assets/icons/toast-success.svg?react';
+import TextLink from '@/ds-components/TextLink';
+
+import DynamicT from '../DynamicT';
+
+import styles from './index.module.scss';
+
+type ToastVariant = 'success' | 'error';
+
+type ToastWithActionProps = {
+  readonly message: string;
+  readonly variant: ToastVariant;
+  readonly actionText: AdminConsoleKey;
+  readonly actionHref: string;
+};
+
+/**
+ * A generic toast component with an action link.
+ * Can be used for success or error toasts that require user interaction.
+ */
+function ToastWithAction({ message, variant, actionText, actionHref }: ToastWithActionProps) {
+  const icon = variant === 'success' ? <Success /> : <Error />;
+
+  return (
+    <div className={classNames(styles.toast, styles[variant], styles.withAction)}>
+      <div className={styles.image}>{icon}</div>
+      <div className={styles.message}>{message}</div>
+      <TextLink href={actionHref} className={styles.action}>
+        <DynamicT forKey={actionText} />
+      </TextLink>
+    </div>
+  );
+}
+
+/**
+ * Display a toast with an action link.
+ *
+ * @example
+ * ```tsx
+ * // Error toast with contact link
+ * toastWithAction({
+ *   message: 'You have reached your quota limit',
+ *   actionText: 'Contact us',
+ *   actionHref: contactEmailLink,
+ *   variant: 'error',
+ * });
+ *
+ * // Success toast with custom action
+ * toastWithAction({
+ *   message: 'Update available',
+ *   actionText: 'Download',
+ *   actionHref: '/downloads',
+ *   variant: 'success',
+ * });
+ * ```
+ */
+export const toastWithAction = (props: ToastWithActionProps) => {
+  toast.custom(() => <ToastWithAction {...props} />);
+};

packages/console/src/ds-components/Toast/index.module.scss

@@ -35,4 +35,20 @@ div.toast {
     background-color: var(--color-danger-toast-background);
     white-space: pre-line;
   }
+
+  &.withAction {
+    .message {
+      margin-right: _.unit(3);
+    }
+
+    .action {
+      flex-shrink: 0;
+      font: var(--font-label-2);
+      color: var(--color-text-link);
+
+      &:hover {
+        text-decoration: none;
+      }
+    }
+  }
 }

packages/console/src/hooks/use-api.ts

@@ -19,15 +19,17 @@ import { useCallback, useContext, useMemo } from 'react';
 import { toast } from 'react-hot-toast';
 import { useTranslation } from 'react-i18next';
 
-import { requestTimeout } from '@/consts';
+import { requestTimeout, contactEmailLink } from '@/consts';
 import { isCloud } from '@/consts/env';
 import { AppDataContext } from '@/contexts/AppDataProvider';
 import { SubscriptionDataContext } from '@/contexts/SubscriptionDataProvider';
 import { TenantsContext } from '@/contexts/TenantsProvider';
+import { toastWithAction } from '@/ds-components/Toast/ToastWithAction';
 import { useConfirmModal } from '@/hooks/use-confirm-modal';
 import useRedirectUri from '@/hooks/use-redirect-uri';
 
 import useSignOut from './use-sign-out';
+import { useSystemLimitErrorMessage } from './use-system-limit-error-message';
 
 export class RequestError extends Error {
   constructor(
@@ -50,6 +52,7 @@ const useGlobalRequestErrorHandler = (toastDisabledErrorCodes?: LogtoErrorCode[]
   const { signOut } = useSignOut();
   const { show } = useConfirmModal();
   const { t } = useTranslation(undefined, { keyPrefix: 'admin_console' });
+  const { parseSystemLimitErrorMessage } = useSystemLimitErrorMessage();
 
   const postSignOutRedirectUri = useRedirectUri('signOut');
 
@@ -83,6 +86,17 @@ const useGlobalRequestErrorHandler = (toastDisabledErrorCodes?: LogtoErrorCode[]
           return;
         }
 
+        // Toast system limit exceeded error
+        if (data.code === 'system_limit.limit_exceeded') {
+          toastWithAction({
+            message: parseSystemLimitErrorMessage(data),
+            actionText: 'general.contact_us_action',
+            actionHref: contactEmailLink,
+            variant: 'error',
+          });
+          return;
+        }
+
         // Skip showing toast for specific error codes.
         if (toastDisabledErrorCodes?.includes(data.code)) {
           return;
@@ -93,7 +107,14 @@ const useGlobalRequestErrorHandler = (toastDisabledErrorCodes?: LogtoErrorCode[]
         toast.error(httpCodeToMessage[response.status] ?? fallbackErrorMessage);
       }
     },
-    [t, toastDisabledErrorCodes, signOut, postSignOutRedirectUri.href, show]
+    [
+      t,
+      toastDisabledErrorCodes,
+      signOut,
+      postSignOutRedirectUri.href,
+      show,
+      parseSystemLimitErrorMessage,
+    ]
   );
 
   return {

packages/console/src/hooks/use-system-limit-error-message.ts

@@ -0,0 +1,82 @@
+import { type AdminConsoleKey } from '@logto/phrases';
+import { type RequestErrorBody } from '@logto/schemas';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+import { z } from 'zod';
+
+import { type SystemLimit } from '@/cloud/types/router';
+
+type SystemLimitKey = keyof SystemLimit;
+
+const systemLimitKeyGuard = z.enum([
+  'applicationsLimit',
+  'thirdPartyApplicationsLimit',
+  'scopesPerResourceLimit',
+  'socialConnectorsLimit',
+  'userRolesLimit',
+  'machineToMachineRolesLimit',
+  'scopesPerRoleLimit',
+  'hooksLimit',
+  'machineToMachineLimit',
+  'resourcesLimit',
+  'enterpriseSsoLimit',
+  'tenantMembersLimit',
+  'organizationsLimit',
+  'samlApplicationsLimit',
+  'usersPerOrganizationLimit',
+  'organizationUserRolesLimit',
+  'organizationMachineToMachineRolesLimit',
+  'organizationScopesLimit',
+]) satisfies z.ZodEnum<[SystemLimitKey, ...SystemLimitKey[]]>;
+
+const errorBodyGuard = z.object({
+  key: systemLimitKeyGuard,
+});
+
+const systemLimitEntityPhrases: Record<SystemLimitKey, AdminConsoleKey> = {
+  applicationsLimit: 'system_limit.entities.application',
+  thirdPartyApplicationsLimit: 'system_limit.entities.third_party_application',
+  scopesPerResourceLimit: 'system_limit.entities.scope_per_resource',
+  socialConnectorsLimit: 'system_limit.entities.social_connector',
+  userRolesLimit: 'system_limit.entities.user_role',
+  machineToMachineRolesLimit: 'system_limit.entities.machine_to_machine_role',
+  scopesPerRoleLimit: 'system_limit.entities.scope_per_role',
+  hooksLimit: 'system_limit.entities.hook',
+  machineToMachineLimit: 'system_limit.entities.machine_to_machine',
+  resourcesLimit: 'system_limit.entities.resource',
+  enterpriseSsoLimit: 'system_limit.entities.enterprise_sso',
+  tenantMembersLimit: 'system_limit.entities.tenant_member',
+  organizationsLimit: 'system_limit.entities.organization',
+  samlApplicationsLimit: 'system_limit.entities.saml_application',
+  usersPerOrganizationLimit: 'system_limit.entities.user_per_organization',
+  organizationUserRolesLimit: 'system_limit.entities.organization_user_role',
+  organizationMachineToMachineRolesLimit:
+    'system_limit.entities.organization_machine_to_machine_role',
+  organizationScopesLimit: 'system_limit.entities.organization_scope',
+};
+
+export const useSystemLimitErrorMessage = () => {
+  const { t } = useTranslation(undefined, { keyPrefix: 'admin_console' });
+  const parseSystemLimitErrorMessage = useCallback(
+    (errorBody: RequestErrorBody): string => {
+      if (errorBody.code !== 'system_limit.limit_exceeded') {
+        return t('general.unknown_error');
+      }
+
+      const result = errorBodyGuard.safeParse(errorBody.data);
+      if (!result.success) {
+        return t('general.unknown_error');
+      }
+
+      const { key } = result.data;
+
+      const entity = t(systemLimitEntityPhrases[key]);
+      return t('system_limit.limit_exceeded', { entity });
+    },
+    [t]
+  );
+
+  return {
+    parseSystemLimitErrorMessage,
+  };
+};

packages/phrases/src/locales/ar/translation/admin-console/index.ts

@@ -36,6 +36,7 @@ import session_expired from './session-expired.js';
 import sign_in_exp from './sign-in-exp/index.js';
 import signing_keys from './signing-keys.js';
 import subscription from './subscription/index.js';
+import system_limit from './system-limit.js';
 import tab_sections from './tab-sections.js';
 import tabs from './tabs.js';
 import tenant_members from './tenant-members.js';
@@ -90,6 +91,7 @@ const admin_console = {
   tenant_members,
   topbar,
   subscription,
+  system_limit,
   upsell,
   guide,
   mfa,

packages/phrases/src/locales/ar/translation/admin-console/system-limit.ts

@@ -0,0 +1,25 @@
+const system_limit = {
+  limit_exceeded: 'وصل هذا المستأجر إلى حد {{entity}} وفقًا لسياسة حد الكيان الخاصة بـ Logto.',
+  entities: {
+    application: 'التطبيق',
+    third_party_application: 'تطبيق الطرف الثالث',
+    scope_per_resource: 'الإذن لكل مورد',
+    social_connector: 'موصل اجتماعي',
+    user_role: 'دور المستخدم',
+    machine_to_machine_role: 'دور الآلة إلى الآلة',
+    scope_per_role: 'الإذن لكل دور',
+    hook: 'webhook',
+    machine_to_machine: 'تطبيق الآلة إلى الآلة',
+    resource: 'مورد API',
+    enterprise_sso: 'تسجيل الدخول الموحد للمؤسسة',
+    tenant_member: 'عضو المستأجر',
+    organization: 'المنظمة',
+    saml_application: 'تطبيق SAML',
+    user_per_organization: 'المستخدم لكل منظمة',
+    organization_user_role: 'دور مستخدم المنظمة',
+    organization_machine_to_machine_role: 'دور الآلة إلى الآلة للمنظمة',
+    organization_scope: 'إذن المنظمة',
+  },
+};
+
+export default Object.freeze(system_limit);

packages/phrases/src/locales/de/translation/admin-console/index.ts

@@ -36,6 +36,7 @@ import session_expired from './session-expired.js';
 import sign_in_exp from './sign-in-exp/index.js';
 import signing_keys from './signing-keys.js';
 import subscription from './subscription/index.js';
+import system_limit from './system-limit.js';
 import tab_sections from './tab-sections.js';
 import tabs from './tabs.js';
 import tenant_members from './tenant-members.js';
@@ -90,6 +91,7 @@ const admin_console = {
   tenant_members,
   topbar,
   subscription,
+  system_limit,
   upsell,
   guide,
   mfa,

packages/phrases/src/locales/de/translation/admin-console/system-limit.ts

@@ -0,0 +1,26 @@
+const system_limit = {
+  limit_exceeded:
+    'Dieser Mandant hat das {{entity}}-Limit gemäß Logtos Entitätslimitrichtlinie erreicht.',
+  entities: {
+    application: 'Anwendung',
+    third_party_application: 'Drittanbieter-Anwendung',
+    scope_per_resource: 'Berechtigung pro Ressource',
+    social_connector: 'Social Connector',
+    user_role: 'Benutzerrolle',
+    machine_to_machine_role: 'Maschine-zu-Maschine-Rolle',
+    scope_per_role: 'Berechtigung pro Rolle',
+    hook: 'Webhook',
+    machine_to_machine: 'Maschine-zu-Maschine-Anwendung',
+    resource: 'API-Ressource',
+    enterprise_sso: 'Enterprise SSO',
+    tenant_member: 'Mandantenmitglied',
+    organization: 'Organisation',
+    saml_application: 'SAML-Anwendung',
+    user_per_organization: 'Benutzer pro Organisation',
+    organization_user_role: 'Organisationsbenutzerrolle',
+    organization_machine_to_machine_role: 'Organisations-Maschine-zu-Maschine-Rolle',
+    organization_scope: 'Organisationsberechtigung',
+  },
+};
+
+export default Object.freeze(system_limit);

packages/phrases/src/locales/en/translation/admin-console/index.ts

@@ -36,6 +36,7 @@ import session_expired from './session-expired.js';
 import sign_in_exp from './sign-in-exp/index.js';
 import signing_keys from './signing-keys.js';
 import subscription from './subscription/index.js';
+import system_limit from './system-limit.js';
 import tab_sections from './tab-sections.js';
 import tabs from './tabs.js';
 import tenant_members from './tenant-members.js';
@@ -90,6 +91,7 @@ const admin_console = {
   tenant_members,
   topbar,
   subscription,
+  system_limit,
   upsell,
   guide,
   mfa,