Update Domain Import Practices and Enhance Documentation

- Added a new script to check domain imports, promoting better import hygiene across the codebase.
- Refactored multiple domain index files to remove unnecessary type re-exports, streamlining the module structure.
- Expanded documentation on import patterns and validation processes to provide clearer guidance for developers.
- Included an architecture diagram to illustrate the relationships between the Portal, BFF, and Domain packages.

.cursorrules

@@ -0,0 +1,530 @@
+# Customer Portal - AI Agent Coding Rules
+
+This document defines the coding standards, architecture patterns, and conventions for the Customer Portal project. AI agents (Cursor, Copilot, etc.) must follow these rules when generating or modifying code.
+
+---
+
+## 📚 Documentation First
+
+**Before writing any code, read and understand the relevant documentation:**
+
+- Start from `docs/README.md` for navigation
+- Check `docs/development/` for implementation patterns
+- Review `docs/architecture/` for system design
+- Check `docs/integrations/` for external API details
+
+**Never guess API response structures or endpoint signatures.** Always read the documentation or existing implementations first.
+
+---
+
+## 🏗️ Monorepo Architecture
+
+```
+apps/
+  portal/              # Next.js 15 frontend (React 19)
+  bff/                 # NestJS 11 Backend-for-Frontend
+packages/
+  domain/              # Pure domain types/schemas/utils (isomorphic)
+```
+
+### Technology Stack
+
+- **Frontend**: Next.js 15, React 19, Tailwind CSS 4, shadcn/ui, TanStack Query, Zustand
+- **Backend**: NestJS 11, Prisma 6, PostgreSQL 17, Redis 7, Pino
+- **Integrations**: Salesforce (jsforce + Pub/Sub API), WHMCS, Freebit
+- **Validation**: Zod (shared between frontend and backend)
+
+---
+
+## 📦 Domain Package (`@customer-portal/domain`)
+
+The domain package is the **single source of truth** for all types and validation.
+
+### Structure
+
+```
+packages/domain/
+├── {domain}/
+│   ├── contract.ts              # Normalized types (provider-agnostic)
+│   ├── schema.ts                # Zod schemas + derived types
+│   ├── constants.ts             # Domain constants
+│   ├── providers/               # Provider-specific adapters (BFF only!)
+│   │   └── {provider}/
+│   │       ├── raw.types.ts     # Raw API response types
+│   │       └── mapper.ts        # Transform raw → domain
+│   └── index.ts                 # Public exports
+├── common/                      # Shared types (ApiResponse, pagination)
+└── toolkit/                     # Utilities (formatting, validation helpers)
+```
+
+### Import Rules
+
+```typescript
+// ✅ CORRECT: Import from domain module
+import type { Invoice, InvoiceList } from "@customer-portal/domain/billing";
+import { invoiceSchema, invoiceListSchema } from "@customer-portal/domain/billing";
+
+// ✅ CORRECT (BFF only): Import provider mappers
+import { Providers } from "@customer-portal/domain/billing/providers";
+
+// ❌ WRONG: Never import from domain root
+import { Invoice } from "@customer-portal/domain";
+
+// ❌ WRONG: Never deep-import internals
+import { Invoice } from "@customer-portal/domain/billing/contract";
+import { mapper } from "@customer-portal/domain/billing/providers/whmcs/mapper";
+
+// ❌ WRONG: Portal must NEVER import providers
+// (in apps/portal/**)
+import { Providers } from "@customer-portal/domain/billing/providers"; // FORBIDDEN
+```
+
+### Schema-First Approach
+
+Always define Zod schemas first, then derive TypeScript types:
+
+```typescript
+// ✅ CORRECT: Schema-first
+export const invoiceSchema = z.object({
+  id: z.number(),
+  status: z.enum(["Paid", "Unpaid", "Cancelled"]),
+  total: z.number(),
+});
+export type Invoice = z.infer<typeof invoiceSchema>;
+
+// ❌ WRONG: Type-only (no runtime validation)
+export interface Invoice {
+  id: number;
+  status: string;
+  total: number;
+}
+```
+
+---
+
+## 🖥️ BFF (NestJS Backend)
+
+### Directory Structure
+
+```
+apps/bff/src/
+├── modules/              # Feature-aligned modules
+│   └── {feature}/
+│       ├── {feature}.controller.ts
+│       ├── {feature}.module.ts
+│       └── services/
+│           ├── {feature}-orchestrator.service.ts
+│           └── {feature}.service.ts
+├── integrations/         # External system clients
+│   └── {provider}/
+│       ├── services/
+│       │   ├── {provider}-connection.service.ts
+│       │   └── {provider}-{entity}.service.ts
+│       ├── utils/
+│       │   └── {entity}-query-builder.ts
+│       └── {provider}.module.ts
+├── core/                 # Framework setup (guards, filters, config)
+├── infra/                # Infrastructure (Redis, queues, logging)
+└── main.ts
+```
+
+### Controller Pattern
+
+Controllers use Zod DTOs via `createZodDto()` and the global `ZodValidationPipe`:
+
+```typescript
+import { Controller, Get, Query, Request } from "@nestjs/common";
+import { createZodDto, ZodResponse } from "nestjs-zod";
+import type { RequestWithUser } from "@bff/modules/auth/auth.types.js";
+import type { InvoiceList } from "@customer-portal/domain/billing";
+import {
+  invoiceListQuerySchema,
+  invoiceListSchema,
+} from "@customer-portal/domain/billing";
+
+class InvoiceListQueryDto extends createZodDto(invoiceListQuerySchema) {}
+class InvoiceListDto extends createZodDto(invoiceListSchema) {}
+
+@Controller("invoices")
+export class InvoicesController {
+  constructor(private readonly orchestrator: InvoicesOrchestratorService) {}
+
+  @Get()
+  @ZodResponse({ description: "List invoices", type: InvoiceListDto })
+  async getInvoices(
+    @Request() req: RequestWithUser,
+    @Query() query: InvoiceListQueryDto
+  ): Promise<InvoiceList> {
+    return this.orchestrator.getInvoices(req.user.id, query);
+  }
+}
+```
+
+**Controller Rules:**
+- ❌ Never import `zod` directly in controllers
+- ✅ Use schemas from `@customer-portal/domain/{module}`
+- ✅ Use `createZodDto(schema)` for DTO classes
+- ✅ Delegate all business logic to orchestrator services
+
+### Integration Service Pattern
+
+Integration services handle external API communication:
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { SalesforceConnection } from "./salesforce-connection.service";
+import { buildOrderSelectFields } from "../utils/order-query-builder";
+import {
+  Providers,
+  type OrderDetails,
+} from "@customer-portal/domain/orders";
+
+@Injectable()
+export class SalesforceOrderService {
+  constructor(private readonly sf: SalesforceConnection) {}
+
+  async getOrderById(orderId: string): Promise<OrderDetails | null> {
+    // 1. Build query (infrastructure concern)
+    const fields = buildOrderSelectFields().join(", ");
+    const soql = `SELECT ${fields} FROM Order WHERE Id = '${orderId}'`;
+
+    // 2. Execute query
+    const result = await this.sf.query(soql);
+    if (!result.records?.[0]) return null;
+
+    // 3. Transform with domain mapper (SINGLE transformation!)
+    return Providers.Salesforce.transformOrderDetails(result.records[0], []);
+  }
+}
+```
+
+**Integration Service Rules:**
+- ✅ Build queries in utils (query builders)
+- ✅ Execute API calls
+- ✅ Use domain mappers for transformation
+- ✅ Return domain types
+- ❌ Never add business logic
+- ❌ Never create wrapper/transformer services
+- ❌ Never transform data twice
+
+### Error Handling
+
+**Never expose sensitive information to customers:**
+
+```typescript
+// ✅ CORRECT: Generic user-facing message
+throw new HttpException(
+  "Unable to process your request. Please try again.",
+  HttpStatus.BAD_REQUEST
+);
+
+// ❌ WRONG: Exposes internal details
+throw new HttpException(
+  `WHMCS API error: ${error.message}`,
+  HttpStatus.BAD_REQUEST
+);
+```
+
+Log detailed errors server-side, return generic messages to clients.
+
+---
+
+## 🌐 Portal (Next.js Frontend)
+
+### Directory Structure
+
+```
+apps/portal/src/
+├── app/                          # Next.js App Router (thin route wrappers)
+│   ├── (public)/                 # Marketing + auth routes
+│   ├── (authenticated)/          # Signed-in portal routes
+│   └── api/                      # API routes
+├── components/                   # Shared UI (design system)
+│   ├── ui/                       # Atoms (Button, Input, Card)
+│   ├── layout/                   # Layout components
+│   └── common/                   # Molecules (DataTable, SearchBar)
+├── features/                     # Feature modules
+│   └── {feature}/
+│       ├── components/           # Feature-specific UI
+│       ├── hooks/                # React Query hooks
+│       ├── services/             # API service functions
+│       ├── views/                # Page-level views
+│       └── index.ts              # Public exports
+├── lib/                          # Core utilities
+│   ├── api/                      # HTTP client
+│   ├── hooks/                    # Shared hooks
+│   ├── services/                 # Shared services
+│   └── utils/                    # Utility functions
+└── styles/                       # Global styles
+```
+
+### Feature Module Pattern
+
+```typescript
+// features/billing/hooks/use-invoices.ts
+import { useQuery } from "@tanstack/react-query";
+import type { InvoiceList } from "@customer-portal/domain/billing";
+import { billingService } from "../services";
+
+export function useInvoices(params?: { status?: string }) {
+  return useQuery<InvoiceList>({
+    queryKey: ["invoices", params],
+    queryFn: () => billingService.getInvoices(params),
+  });
+}
+
+// features/billing/services/billing.service.ts
+import { apiClient } from "@/lib/api";
+import type { InvoiceList } from "@customer-portal/domain/billing";
+
+export const billingService = {
+  async getInvoices(params?: { status?: string }): Promise<InvoiceList> {
+    const response = await apiClient.get("/invoices", { params });
+    return response.data;
+  },
+};
+
+// features/billing/index.ts
+export * from "./hooks";
+export * from "./components";
+```
+
+### Page Component Rules
+
+Pages are thin shells that compose features:
+
+```typescript
+// app/(authenticated)/billing/page.tsx
+import { InvoicesView } from "@/features/billing";
+
+export default function BillingPage() {
+  return <InvoicesView />;
+}
+```
+
+**Frontend Rules:**
+- ✅ Pages delegate to feature views
+- ✅ Data fetching lives in feature hooks
+- ✅ Business logic lives in feature services
+- ✅ Use `@/` path aliases
+- ❌ Never call APIs directly in page components
+- ❌ Never import provider types (only domain contracts)
+
+### Import Patterns
+
+```typescript
+// Feature imports
+import { LoginForm, useAuth } from "@/features/auth";
+
+// Component imports
+import { Button, Input } from "@/components/ui";
+import { DataTable } from "@/components/common";
+
+// Type imports (domain types only!)
+import type { Invoice } from "@customer-portal/domain/billing";
+
+// Utility imports
+import { apiClient } from "@/lib/api";
+```
+
+---
+
+## ✅ Validation Patterns
+
+### Query Parameters
+
+Use `z.coerce` for URL query strings:
+
+```typescript
+// ✅ CORRECT: Coerce string to number
+export const paginationSchema = z.object({
+  page: z.coerce.number().int().positive().optional(),
+  limit: z.coerce.number().int().positive().max(100).optional(),
+});
+
+// ❌ WRONG: Will fail on URL strings
+export const paginationSchema = z.object({
+  page: z.number().optional(), // "1" !== 1
+});
+```
+
+### Request Body Validation
+
+```typescript
+// In domain schema
+export const createOrderRequestSchema = z.object({
+  items: z.array(orderItemSchema).min(1),
+  shippingAddressId: z.string().uuid(),
+});
+export type CreateOrderRequest = z.infer<typeof createOrderRequestSchema>;
+```
+
+### Form Validation (Frontend)
+
+```typescript
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { loginRequestSchema, type LoginRequest } from "@customer-portal/domain/auth";
+
+function LoginForm() {
+  const form = useForm<LoginRequest>({
+    resolver: zodResolver(loginRequestSchema),
+  });
+  // ...
+}
+```
+
+---
+
+## 🎨 UI Design Guidelines
+
+Follow minimal, clean UI design principles:
+
+- **Avoid excessive animations** - Use subtle, purposeful transitions
+- **Clean typography** - Use system fonts or carefully chosen web fonts
+- **Consistent spacing** - Follow the design system tokens
+- **Accessibility first** - Proper ARIA labels, keyboard navigation
+- **Mobile responsive** - Test on all breakpoints
+
+Use shadcn/ui components and Tailwind CSS utilities.
+
+---
+
+## 🔒 Security Rules
+
+1. **Never expose sensitive data** in error messages or responses
+2. **Validate all inputs** at API boundaries (Zod schemas)
+3. **Use parameterized queries** (Prisma handles this)
+4. **Sanitize user content** before display
+5. **Check authorization** in every endpoint
+
+---
+
+## 📝 Naming Conventions
+
+### Files
+
+- **Components**: PascalCase (`InvoiceCard.tsx`)
+- **Hooks**: camelCase with `use` prefix (`useInvoices.ts`)
+- **Services**: kebab-case (`billing.service.ts`)
+- **Types/Schemas**: kebab-case (`invoice.schema.ts`)
+- **Utils**: kebab-case (`format-currency.ts`)
+
+### Code
+
+- **Types/Interfaces**: PascalCase (`Invoice`, `OrderDetails`)
+- **Schemas**: camelCase with `Schema` suffix (`invoiceSchema`)
+- **Constants**: SCREAMING_SNAKE_CASE (`INVOICE_STATUS`)
+- **Functions**: camelCase (`getInvoices`, `transformOrder`)
+- **React Components**: PascalCase (`InvoiceList`)
+
+### Services
+
+- ❌ Avoid `V2` suffix in service names
+- ✅ Use clear, descriptive names (`InvoicesOrchestratorService`)
+
+---
+
+## 🚫 Anti-Patterns to Avoid
+
+### Domain Layer
+
+- ❌ Framework-specific imports (no React/NestJS in domain)
+- ❌ Circular dependencies
+- ❌ Exposing raw provider types to application code
+
+### BFF
+
+- ❌ Business logic in controllers
+- ❌ Direct Zod imports in controllers (use schemas from domain)
+- ❌ Creating transformer/wrapper services
+- ❌ Multiple data transformations
+- ❌ Exposing internal error details
+
+### Portal
+
+- ❌ API calls in page components
+- ❌ Business logic in UI components
+- ❌ Importing provider types/mappers
+- ❌ Duplicate type definitions
+- ❌ Using `window.location` for navigation (use `next/link` or `useRouter`)
+
+### General
+
+- ❌ Using `any` type (especially in public APIs)
+- ❌ Unsafe type assertions
+- ❌ Console.log in production code (use proper logger)
+- ❌ Guessing API response structures
+
+---
+
+## 🔄 Data Flow Summary
+
+### Inbound (External API → Application)
+
+```
+External API Response
+      ↓
+Raw Provider Types (domain/*/providers/*/raw.types.ts)
+      ↓
+Provider Mapper (domain/*/providers/*/mapper.ts) [BFF only]
+      ↓
+Zod Schema Validation (domain/*/schema.ts)
+      ↓
+Domain Contract (domain/*/contract.ts)
+      ↓
+Application Code (BFF services, Portal hooks)
+```
+
+### Outbound (Application → External API)
+
+```
+Application Intent
+      ↓
+Domain Contract
+      ↓
+Provider Mapper (BFF only)
+      ↓
+Raw Provider Payload
+      ↓
+External API Request
+```
+
+---
+
+## 📋 Checklist for New Features
+
+1. [ ] Define types in `packages/domain/{feature}/contract.ts`
+2. [ ] Add Zod schemas in `packages/domain/{feature}/schema.ts`
+3. [ ] Export from `packages/domain/{feature}/index.ts`
+4. [ ] (If provider needed) Add raw types and mapper in `providers/{provider}/`
+5. [ ] Create BFF module in `apps/bff/src/modules/{feature}/`
+6. [ ] Create controller with Zod DTOs
+7. [ ] Create orchestrator service
+8. [ ] Create portal feature in `apps/portal/src/features/{feature}/`
+9. [ ] Add hooks, services, and components
+10. [ ] Create page in `apps/portal/src/app/`
+
+---
+
+## 🛠️ Development Commands
+
+```bash
+# Development
+pnpm dev              # Start all apps
+pnpm dev:bff          # Start BFF only
+pnpm dev:portal       # Start Portal only
+
+# Type checking
+pnpm typecheck        # Check all packages
+pnpm lint             # Run ESLint
+
+# Database
+pnpm db:migrate       # Run migrations
+pnpm db:generate      # Generate Prisma client
+```
+
+---
+
+**Last Updated**: December 2025
+

docs/development/domain/import-hygiene.md

@@ -14,6 +14,44 @@
 - **BFF-only (integration/infrastructure)**:
   - `@customer-portal/domain/<module>/providers`
 
+## Quick Reference
+
+| Context                 | Import Pattern                     | Example                                                             |
+| ----------------------- | ---------------------------------- | ------------------------------------------------------------------- |
+| Portal/BFF domain types | `@customer-portal/domain/<module>` | `import { Invoice } from "@customer-portal/domain/billing"`         |
+| BFF provider adapters   | `.../<module>/providers`           | `import { Whmcs } from "@customer-portal/domain/billing/providers"` |
+| Toolkit utilities       | `@customer-portal/domain/toolkit`  | `import { Formatting } from "@customer-portal/domain/toolkit"`      |
+
+## Architecture Diagram
+
+```mermaid
+graph TD
+    subgraph Portal [Portal App]
+        PC[PortalComponents]
+    end
+
+    subgraph BFF [BFF App]
+        BC[BFFControllers]
+        BI[BFFIntegrations]
+    end
+
+    subgraph Domain [Domain Package]
+        DM[ModuleEntrypoints]
+        DP[ProviderEntrypoints]
+        DT[Toolkit]
+    end
+
+    PC -->|allowed| DM
+    PC -->|allowed| DT
+    PC -.->|BLOCKED| DP
+
+    BC -->|allowed| DM
+    BC -->|allowed| DT
+    BI -->|allowed| DM
+    BI -->|allowed| DP
+    BI -->|allowed| DT
+```
+
 ### Never
 
 - `@customer-portal/domain/<module>/**` (anything deeper than the module entrypoint)
@@ -51,3 +89,11 @@ Where to export it:
 - No `@customer-portal/domain/*/*` imports (except exact `.../<module>/providers` in BFF).
 - Portal has **zero** `.../providers` imports.
 - No wildcard subpath exports added to `packages/domain/package.json#exports`.
+
+## Validation
+
+After changes:
+
+1. Run `pnpm lint`
+2. Run `pnpm type-check`
+3. Run `pnpm build`

package.json

@@ -24,6 +24,7 @@
     "format:check": "prettier -c .",
     "prepare": "husky",
     "type-check": "pnpm --filter @customer-portal/domain run type-check && pnpm --filter @customer-portal/bff --filter @customer-portal/portal run type-check",
+    "check:imports": "node scripts/check-domain-imports.mjs",
     "clean": "pnpm --recursive run clean",
     "dev:start": "./scripts/dev/manage.sh start",
     "dev:stop": "./scripts/dev/manage.sh stop",

packages/domain/billing/index.ts

@@ -12,21 +12,3 @@ export * from "./constants.js";
 
 // Schemas (includes derived types)
 export * from "./schema.js";
-
-// Re-export types for convenience
-export type {
-  Currency,
-  InvoiceStatus,
-  InvoiceItem,
-  Invoice,
-  InvoiceIdParam,
-  InvoicePagination,
-  InvoiceList,
-  InvoiceSsoLink,
-  PaymentInvoiceRequest,
-  BillingSummary,
-  InvoiceQueryParams,
-  InvoiceListQuery,
-  InvoiceSsoQuery,
-  InvoicePaymentLinkQuery,
-} from "./schema.js";

packages/domain/mappings/index.ts

@@ -5,12 +5,3 @@
 export * from "./contract.js";
 export * from "./schema.js";
 export * from "./validation.js";
-
-// Re-export types for convenience
-export type {
-  MappingSearchFilters,
-  MappingStats,
-  BulkMappingOperation,
-  BulkMappingResult,
-} from "./schema.js";
-export type { MappingValidationResult } from "./contract.js";

packages/domain/orders/index.ts

@@ -58,28 +58,6 @@ export {
   calculateOrderTotals,
   formatScheduledDate,
 } from "./helpers.js";
-// Re-export types for convenience
-export type {
-  // Order item types
-  OrderItemSummary,
-  OrderItemDetails,
-  // Order types
-  OrderSummary,
-  OrderDetails,
-  // Query and creation types
-  OrderQueryParams,
-  OrderConfigurationsAddress,
-  OrderConfigurations,
-  CreateOrderRequest,
-  OrderBusinessValidation,
-  SfOrderIdParam,
-  OrderListResponse,
-  // Display types
-  OrderDisplayItem,
-  OrderDisplayItemCategory,
-  OrderDisplayItemCharge,
-  OrderDisplayItemChargeKind,
-} from "./schema.js";
 
 // Provider adapters
 // NOTE: Provider adapters are intentionally not exported from the module root.

packages/domain/payments/index.ts

@@ -11,13 +11,3 @@ export { PAYMENT_METHOD_TYPE, PAYMENT_GATEWAY_TYPE } from "./contract.js";
 
 // Schemas (includes derived types)
 export * from "./schema.js";
-
-// Re-export types for convenience
-export type {
-  PaymentMethodType,
-  PaymentMethod,
-  PaymentMethodList,
-  PaymentGatewayType,
-  PaymentGateway,
-  PaymentGatewayList,
-} from "./schema.js";

packages/domain/services/index.ts

@@ -11,28 +11,5 @@ export { type PricingTier, type CatalogPriceInfo } from "./contract.js";
 // Schemas (includes derived types)
 export * from "./schema.js";
 
-// Re-export types for convenience
-export type {
-  CatalogProductBase,
-  CatalogPricebookEntry,
-  // Internet products
-  InternetCatalogProduct,
-  InternetPlanTemplate,
-  InternetPlanCatalogItem,
-  InternetInstallationCatalogItem,
-  InternetAddonCatalogItem,
-  InternetEligibilityStatus,
-  InternetEligibilityDetails,
-  InternetEligibilityRequest,
-  InternetEligibilityRequestResponse,
-  // SIM products
-  SimCatalogProduct,
-  SimActivationFeeCatalogItem,
-  // VPN products
-  VpnCatalogProduct,
-  // Union type
-  CatalogProduct,
-} from "./schema.js";
-
 // Utilities
 export * from "./utils.js";

packages/domain/sim/index.ts

@@ -25,62 +25,5 @@ export {
   getSimPlanLabel,
   buildSimFeaturesUpdatePayload,
 } from "./helpers.js";
-
-// Re-export types for convenience
-export type {
-  SimStatus,
-  SimType,
-  SimDetails,
-  RecentDayUsage,
-  SimUsage,
-  SimTopUpHistoryEntry,
-  SimTopUpHistory,
-  SimInfo,
-  // Portal-facing DTOs
-  SimAvailablePlan,
-  SimAvailablePlanArray,
-  SimCancellationMonth,
-  SimCancellationPreview,
-  SimReissueFullRequest,
-  SimCallHistoryPagination,
-  SimDomesticCallRecord,
-  SimDomesticCallHistoryResponse,
-  SimInternationalCallRecord,
-  SimInternationalCallHistoryResponse,
-  SimSmsRecord,
-  SimSmsHistoryResponse,
-  SimHistoryMonth,
-  SimHistoryAvailableMonths,
-  SimCallHistoryImportResult,
-  SimSftpFiles,
-  SimSftpListResult,
-  // Request types
-  SimTopUpRequest,
-  SimPlanChangeRequest,
-  SimCancelRequest,
-  SimTopUpHistoryRequest,
-  SimFeaturesUpdateRequest,
-  SimReissueRequest,
-  SimConfigureFormData,
-  SimCardType,
-  ActivationType,
-  MnpData,
-  // Enhanced request types
-  SimCancelFullRequest,
-  SimTopUpFullRequest,
-  SimChangePlanFullRequest,
-  SimHistoryQuery,
-  SimSftpListQuery,
-  SimCallHistoryImportQuery,
-  SimReissueEsimRequest,
-  // Activation types
-  SimOrderActivationRequest,
-  SimOrderActivationMnp,
-  SimOrderActivationAddons,
-  // Pricing types
-  SimTopUpPricing,
-  SimTopUpPricingPreviewRequest,
-  SimTopUpPricingPreviewResponse,
-} from "./schema.js";
 export type { SimPlanCode } from "./contract.js";
 export type { SimPlanOption, SimFeatureToggleSnapshot } from "./helpers.js";

packages/domain/subscriptions/index.ts

@@ -12,25 +12,6 @@ export { SUBSCRIPTION_STATUS, SUBSCRIPTION_CYCLE } from "./contract.js";
 // Schemas (includes derived types)
 export * from "./schema.js";
 
-// Re-export types for convenience
-export type {
-  SubscriptionStatus,
-  SubscriptionCycle,
-  Subscription,
-  SubscriptionArray,
-  SubscriptionList,
-  SubscriptionIdParam,
-  SubscriptionQueryParams,
-  SubscriptionQuery,
-  SubscriptionStats,
-  SimActionResponse,
-  SimPlanChangeResult,
-  // Internet cancellation types
-  InternetCancellationMonth,
-  InternetCancellationPreview,
-  InternetCancelRequest,
-} from "./schema.js";
-
 // Re-export schemas for validation
 export {
   internetCancellationMonthSchema,

scripts/check-domain-imports.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Domain Import Boundary Checker
+ *
+ * Validates:
+ * 1. No @customer-portal/domain (root) imports
+ * 2. No deep imports beyond module/providers
+ * 3. Portal has zero provider imports
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const ROOT = process.cwd();
+
+const APPS_DIR = path.join(ROOT, "apps");
+const BFF_SRC_DIR = path.join(APPS_DIR, "bff", "src");
+const PORTAL_SRC_DIR = path.join(APPS_DIR, "portal", "src");
+
+const FILE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx"]);
+const IGNORE_DIRS = new Set(["node_modules", "dist", ".next", ".turbo", ".cache"]);
+
+function toPos(text, idx) {
+  // 1-based line/column
+  let line = 1;
+  let col = 1;
+  for (let i = 0; i < idx; i += 1) {
+    if (text.charCodeAt(i) === 10) {
+      line += 1;
+      col = 1;
+    } else {
+      col += 1;
+    }
+  }
+  return { line, col };
+}
+
+async function* walk(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (IGNORE_DIRS.has(e.name) || e.name.startsWith(".")) continue;
+      yield* walk(p);
+      continue;
+    }
+    if (!e.isFile()) continue;
+    if (!FILE_EXTS.has(path.extname(e.name))) continue;
+    yield p;
+  }
+}
+
+function collectDomainImports(code) {
+  const results = [];
+
+  const patterns = [
+    { kind: "from", re: /\bfrom\s+['"]([^'"]+)['"]/g },
+    { kind: "import", re: /\bimport\s+['"]([^'"]+)['"]/g },
+    { kind: "dynamicImport", re: /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g },
+    { kind: "require", re: /\brequire\(\s*['"]([^'"]+)['"]\s*\)/g },
+  ];
+
+  for (const { kind, re } of patterns) {
+    for (const m of code.matchAll(re)) {
+      const spec = m[1];
+      if (!spec || !spec.startsWith("@customer-portal/domain")) continue;
+      const idx = typeof m.index === "number" ? m.index : 0;
+      results.push({ kind, spec, idx });
+    }
+  }
+
+  return results;
+}
+
+function validateSpecifier({ spec, isPortal }) {
+  if (spec === "@customer-portal/domain") {
+    return "Do not import @customer-portal/domain (root). Use @customer-portal/domain/<module> instead.";
+  }
+
+  if (spec.includes("/src/")) {
+    return "Import from @customer-portal/domain/<module> instead of internals.";
+  }
+
+  if (spec.startsWith("@customer-portal/domain/toolkit/")) {
+    return "Do not deep-import toolkit internals. Import from @customer-portal/domain/toolkit only.";
+  }
+
+  if (/^@customer-portal\/domain\/[^/]+\/providers\/.+/.test(spec)) {
+    return "Do not deep-import provider internals. Import from @customer-portal/domain/<module>/providers only.";
+  }
+
+  if (/^@customer-portal\/domain\/[^/]+\/providers$/.test(spec)) {
+    if (isPortal) {
+      return "Portal must not import provider adapters/types. Import normalized domain models from @customer-portal/domain/<module> instead.";
+    }
+    return null;
+  }
+
+  // Any 2+ segment import like @customer-portal/domain/a/b is illegal everywhere
+  // (except the explicit .../<module>/providers entrypoint handled above).
+  if (/^@customer-portal\/domain\/[^/]+\/[^/]+/.test(spec)) {
+    return "No deep @customer-portal/domain imports. Use @customer-portal/domain/<module> (or BFF-only: .../<module>/providers).";
+  }
+
+  return null;
+}
+
+async function main() {
+  const errors = [];
+
+  // Broad scan: both apps for root/deep imports
+  for (const baseDir of [BFF_SRC_DIR, PORTAL_SRC_DIR]) {
+    for await (const file of walk(baseDir)) {
+      const code = await fs.readFile(file, "utf8");
+      const isPortal = file.startsWith(PORTAL_SRC_DIR + path.sep);
+
+      for (const imp of collectDomainImports(code)) {
+        const message = validateSpecifier({ spec: imp.spec, isPortal });
+        if (!message) continue;
+        const pos = toPos(code, imp.idx);
+        errors.push({
+          file: path.relative(ROOT, file),
+          line: pos.line,
+          col: pos.col,
+          spec: imp.spec,
+          message,
+        });
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    console.error(`[domain] ERROR: illegal domain imports detected (${errors.length})`);
+    for (const e of errors) {
+      console.error(`[domain] ${e.file}:${e.line}:${e.col}  ${e.spec}`);
+      console.error(`         ${e.message}`);
+    }
+    process.exit(1);
+  }
+
+  console.log("[domain] OK: import contract checks passed.");
+}
+
+await main();
+
+