feat(companies): add Transit Agent service linked to transit-agent roster; forwarder/agent onboarding step, assigned-bookings tab, booking assignment + notify, drop agent validity window

apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.ts

@@ -656,4 +656,67 @@ export class BookingLifecycleNotifierService {
       },
     );
   }
+
+  /**
+   * The customer picked a registered transit agent (a freight forwarder on the
+   * platform) to clear this booking. Tell the forwarder company — every one of
+   * its portal users in the bell, plus SMS and email to its contact — so the
+   * job shows up in its Assigned Bookings tab and it can start preparing
+   * documents. The company is found through its transit-agent link; an agent
+   * nobody has registered against gets no message, since there is nobody to
+   * send it to. Never throws: a failed notice must not undo a completed booking.
+   */
+  async transitAgentAssigned(
+    b: Booking,
+    agent: { id: string; name: string },
+  ): Promise<void> {
+    try {
+      const [forwarder]: Array<{ id: string }> = await this.dataSource.query(
+        `SELECT id FROM freight.companies
+          WHERE transit_agent_id = $1 AND deleted_at IS NULL
+          LIMIT 1`,
+        [agent.id],
+      );
+      if (!forwarder) {
+        this.logger.warn(
+          `Transit agent ${agent.name} has no forwarder company — assignment notice for ${this.ref(b)} not sent`,
+        );
+        return;
+      }
+      const title = 'New booking assigned to you';
+      const body = `Booking ${b.reference} has been assigned to ${agent.name} for customs clearance. Open Assigned Bookings in the portal to see it.`;
+      void this.inbox.notify({
+        recipients: { companyId: forwarder.id },
+        audience: NotificationAudience.PORTAL,
+        type: NotificationType.BOOKING_STATUS,
+        title,
+        body,
+        link: '/forwarder/assigned-bookings',
+        data: { bookingId: b.id, reference: b.reference, transitAgentId: agent.id },
+      });
+      const { phone, email } = await resolveCompanyNotifyContact(
+        this.dataSource,
+        forwarder.id,
+      );
+      const message = `EDR Freight: ${body}`;
+      if (phone) {
+        try {
+          await this.notifications.directSend('sms', phone, message);
+        } catch (err) {
+          this.logger.warn(`Forwarder SMS failed for ${this.ref(b)}: ${(err as Error).message}`);
+        }
+      }
+      if (email) {
+        try {
+          await this.notifications.directSend('email', email, message);
+        } catch (err) {
+          this.logger.warn(`Forwarder email failed for ${this.ref(b)}: ${(err as Error).message}`);
+        }
+      }
+    } catch (err) {
+      this.logger.warn(
+        `transitAgentAssigned failed for ${this.ref(b)}: ${(err as Error).message}`,
+      );
+    }
+  }
 }