Add reason code type to team capabilities response

Author: jnsdls

.changeset/fuzzy-bars-wish.md

@@ -0,0 +1,5 @@
+---
+"@thirdweb-dev/service-utils": patch
+---
+
+add reason code type into team capabilities response

apps/dashboard/src/@/storybook/stubs.ts

@@ -74,6 +74,12 @@ export function teamStub(id: string, billingPlan: Team["billingPlan"]): Team {
       rpc: {
         enabled: true,
         rateLimit: 1000,
+        websockets: {
+          enabled: false,
+          reasonCode: "enterprise_plan_required",
+          maxConnections: 0,
+          maxSubscriptions: 0,
+        },
       },
       storage: {
         download: {

packages/service-utils/src/core/api.ts

@@ -55,71 +55,73 @@ export type ApiResponse = {
 
 /**
  * Stores service-specific capabilities.
- * This type should match the schema from API server.
+ * These types should match the schema from API server.
  */
+export type ReasonCode =
+  | "free_limit_exceeded"
+  | "subscription_required"
+  | "invoice_past_due"
+  | "enterprise_plan_required"
+  | "other";
+type EnabledWithReason<T> = T &
+  ({ enabled: true } | { enabled: false; reasonCode: ReasonCode });
 type TeamCapabilities = {
   platform: {
     auditLogs: boolean;
     ecosystemWallets: boolean;
     seats: boolean;
   };
-  rpc: {
-    enabled: boolean;
+  rpc: EnabledWithReason<{
     rateLimit: number;
-  };
-  insight: {
-    enabled: boolean;
+    websockets: EnabledWithReason<{
+      maxConnections: number;
+      maxSubscriptions: number;
+    }>;
+  }>;
+  insight: EnabledWithReason<{
     rateLimit: number;
     webhooks: boolean;
-  };
-  storage: {
-    enabled: boolean;
+  }>;
+  storage: EnabledWithReason<{
     download: {
       rateLimit: number;
     };
     upload: {
       totalFileSizeBytesLimit: number;
       rateLimit: number;
     };
-  };
-  nebula: {
-    enabled: boolean;
+  }>;
+  nebula: EnabledWithReason<{
     rateLimit: {
       perSecond: number;
       perMinute: number;
     };
-  };
-  bundler: {
-    enabled: boolean;
+  }>;
+  bundler: EnabledWithReason<{
     mainnetEnabled: boolean;
     rateLimit: number;
-  };
-  embeddedWallets: {
-    enabled: boolean;
+  }>;
+  embeddedWallets: EnabledWithReason<{
     customAuth: boolean;
     customBranding: boolean;
     sms: {
       domestic: boolean;
       international: boolean;
     };
-  };
-  engineCloud: {
-    enabled: boolean;
+  }>;
+  engineCloud: EnabledWithReason<{
     mainnetEnabled: boolean;
     rateLimit: number;
-  };
-  pay: {
-    enabled: boolean;
+  }>;
+  pay: EnabledWithReason<{
     rateLimit: number;
-  };
-  mcp: {
-    enabled: boolean;
+  }>;
+  mcp: EnabledWithReason<{
     rateLimit: number;
-  };
-  gateway: {
-    enabled: boolean;
+  }>;
+  gateway: EnabledWithReason<{
     rateLimit: number;
-  };
+  }>;
 };
 
 type TeamPlan =

packages/service-utils/src/core/authorize/index.ts

@@ -1,6 +1,7 @@
 import {
   type CoreServiceConfig,
   fetchTeamAndProject,
+  type ReasonCode,
   type TeamAndProjectResponse,
   type TeamResponse,
 } from "../api.js";
@@ -139,20 +140,55 @@ export async function authorize(
     };
   }
   // check if the service is maybe disabled for the team (usually due to a billing issue / exceeding the free plan limit)
-  if (
-    !isServiceEnabledForTeam(
-      serviceConfig.serviceScope,
-      teamAndProjectResponse.team.capabilities,
-    )
-  ) {
-    return {
-      authorized: false,
-      errorCode: "SERVICE_TEMPORARILY_DISABLED",
-      errorMessage:
-        "You currently do not have access to this service. Please check if your subscription includes this service and is active.",
-      status: 403,
-    };
+  const disabledReason = getServiceDisabledReason(
+    serviceConfig.serviceScope,
+    teamAndProjectResponse.team.capabilities,
+  );
+  if (disabledReason) {
+    switch (disabledReason) {
+      case "enterprise_plan_required": {
+        return {
+          authorized: false,
+          errorCode: "ENTERPRISE_PLAN_REQUIRED",
+          errorMessage: `You currently do not have access to this feature. Please reach out to us to upgrade your plan to enable this feature: https://thirdweb.com/team/${teamAndProjectResponse.team.slug}/~/support`,
+          status: 402,
+        };
+      }
+      case "free_limit_exceeded": {
+        return {
+          authorized: false,
+          errorCode: "FREE_LIMIT_EXCEEDED",
+          errorMessage: `You have exceeded the free limit for this service. Find a plan that suits your needs to continue using this feature: https://thirdweb.com/team/${teamAndProjectResponse.team.slug}/~/billing?showPlans=true&highlight=growth`,
+          status: 402,
+        };
+      }
+      case "subscription_required": {
+        return {
+          authorized: false,
+          errorCode: "SUBSCRIPTION_REQUIRED",
+          errorMessage: `You need a subscription to use this feature. Find a plan that suits your needs to continue using this feature: https://thirdweb.com/team/${teamAndProjectResponse.team.slug}/~/billing?showPlans=true&highlight=growth`,
+          status: 402,
+        };
+      }
+      case "invoice_past_due": {
+        return {
+          authorized: false,
+          errorCode: "INVOICE_PAST_DUE",
+          errorMessage: `Please pay any outstanding invoices to continue using this feature: https://thirdweb.com/team/${teamAndProjectResponse.team.slug}/~/billing/invoices`,
+          status: 402,
+        };
+      }
+      default: {
+        return {
+          authorized: false,
+          errorCode: "SERVICE_TEMPORARILY_DISABLED",
+          errorMessage: `Access to this feature is temporarily restricted. Please reach out to us to resolve this issue: https://thirdweb.com/team/${teamAndProjectResponse.team.slug}/~/support`,
+          status: 403,
+        };
+      }
+    }
   }
+
   // now we can validate the key itself
   const clientAuth = authorizeClient(authData, teamAndProjectResponse);
 
@@ -186,25 +222,45 @@ export async function authorize(
   };
 }
 
-function isServiceEnabledForTeam(
+function getServiceDisabledReason(
   scope: CoreServiceConfig["serviceScope"],
   teamCapabilities: TeamResponse["capabilities"],
-): boolean {
+): ReasonCode | null {
   switch (scope) {
     case "rpc":
-      return teamCapabilities.rpc.enabled;
+      return teamCapabilities.rpc.enabled
+        ? null
+        : teamCapabilities.rpc.reasonCode;
     case "bundler":
-      return teamCapabilities.bundler.enabled;
+      return teamCapabilities.bundler.enabled
+        ? null
+        : teamCapabilities.bundler.reasonCode;
     case "storage":
-      return teamCapabilities.storage.enabled;
+      return teamCapabilities.storage.enabled
+        ? null
+        : teamCapabilities.storage.reasonCode;
     case "insight":
-      return teamCapabilities.insight.enabled;
+      return teamCapabilities.insight.enabled
+        ? null
+        : teamCapabilities.insight.reasonCode;
     case "nebula":
-      return teamCapabilities.nebula.enabled;
+      return teamCapabilities.nebula.enabled
+        ? null
+        : teamCapabilities.nebula.reasonCode;
     case "embeddedWallets":
-      return teamCapabilities.embeddedWallets.enabled;
+      return teamCapabilities.embeddedWallets.enabled
+        ? null
+        : teamCapabilities.embeddedWallets.reasonCode;
+    case "engineCloud":
+      return teamCapabilities.engineCloud.enabled
+        ? null
+        : teamCapabilities.engineCloud.reasonCode;
+    case "pay":
+      return teamCapabilities.pay.enabled
+        ? null
+        : teamCapabilities.pay.reasonCode;
     default:
-      // always return true for any legacy / un-named services
-      return true;
+      // always return null for any legacy / un-named services
+      return null;
   }
 }

packages/service-utils/src/mocks.ts

@@ -92,6 +92,12 @@ export const validTeamResponse: TeamResponse = {
     rpc: {
       enabled: true,
       rateLimit: 1000,
+      websockets: {
+        enabled: false,
+        reasonCode: "enterprise_plan_required",
+        maxConnections: 0,
+        maxSubscriptions: 0,
+      },
     },
     storage: {
       download: {