Ports

Import from @workspace/training/application/ports. These are the interfaces the application layer depends on for infrastructure that is not a module's own repository: queueing, events, email, the auth provider, object storage, session tokens and webhook verification. Every export here is a type except DEFAULT_SESSION_TOKEN_TTL_MS. Implementations live in capability-named adapter packages and are injected at the composition root of each app, see Adapter packages. A module's own repository ports live under that module's ports/ folder and are documented on its page.

Queue

Durable message queueing for background work such as webhook delivery. The EventIngestionService of Events is its consumer inside the core: it publishes { id } jobs on its process topic. The API worker registers the handlers and the sweep cron.

QueueMessage

QueueRetryOptions

Topic names must satisfy the driver: pg-boss accepts alphanumerics, _, -, . and /, never a colon. The events module publishes its defaults as DEFAULT_INGESTION_TOPICS.

type ProcessJob = { id: string };

const PROCESS_TOPIC = "webhook.process";

const RETRY: QueueRetryOptions = {
  maxAttempts: 8,
  initialDelayMs: 60_000,
  backoff: "exponential",
};

export function enqueueProcessing(queue: Queue, eventId: string): Promise<void> {
  return queue.send<ProcessJob>(PROCESS_TOPIC, { id: eventId });
}

export function startProcessing(
  queue: Queue,
  process: (eventId: string) => Promise<void>
): Promise<void> {
  return queue.work<ProcessJob>(
    PROCESS_TOPIC,
    async (msg: QueueMessage<ProcessJob>) => {
      // msg.id is the queue's job id; msg.retryCount is 0 on the first delivery
      await process(msg.data.id);
    },
    RETRY
  );
}

export async function scheduleSweep(queue: Queue): Promise<void> {
  await queue.schedule("webhook.sweep-pending", "*/2 * * * *"); // UTC cron
  await queue.work("webhook.sweep-pending", async () => {
    // consumed like any other topic
  });
}

DomainEventBus

Emits domain events; subscribers react asynchronously. createAccountsService takes one and emits account:created when ensureAccount creates a row, see Accounts. The API builds its bus with createEventBus from @workspace/shared/event-bus over a ServerEvents map whose entries match DomainEvent.

DomainEvent is the closed union of the events the core emits:

export function announceAccount(
  eventBus: DomainEventBus,
  userId: string,
  email: string
): void {
  eventBus.emit({ type: "account:created", payload: { userId, email } });
}

EmailSender

Renders an email message and hands it to the provider (Resend today). Its only consumer is the EmailsService of Emails, on the worker side; nothing else sends an email. The adapter is null when no API key is configured, and the service then marks every email skipped.

SendEmailInput

SendEmailResult

AdBannersStorage

The object store holding sponsor banner assets, consumed by the ad banners service of Ads. The Supabase Storage implementation lives in @workspace/ads.

BrandAssetsStorage

The object store holding a deal owner's visuals, consumed by the brand assets service of Ads. The API mints a signed upload URL, the browser writes the object, and on confirm the API reads the stored bytes back through this port.

BrandAssetUploadTicket

SessionTokenService

Minting and verification of signed anonymous client session tokens, used by the API's telemetry session guard and its session token handlers. Verification failures throw SessionTokenVerificationError from @workspace/training, see Errors.

MintedSessionToken

VerifiedSessionToken

WebhookVerifier

Webhook signature verification, the first step of EventIngestionService.ingest in Events. WebhookVerifier<TProvider extends string = string> lets an adapter narrow the provider tag to its own literal ("clerk", "stripe") so the composition root can require an exact match at the wiring site. The admin app, which only publishes replays, wires a verifier whose verify throws.

IngestedEvent

A verified webhook event, before persistence. The domain treats provider as opaque; the default string suits readers of a persisted event, whose column has no CHECK, so an unknown value stays lookup-safe. The persisted shape, PersistedIngestedEvent, belongs to the events module. The makeIngestedEvent factory builds one with neutral provider and event type defaults, see Factories.