Public

The public module is the read side of the public player: a flat DealView without owner, themes or permissions, and the services that serve single deals, "next deal" picks and the deal payloads behind a shared session or collection link. It also holds the one anonymous write, the public editor's deal creation. The player app, its SSR host and the API routes under the public prefix consume it.

Import from @workspace/training/domain/public and @workspace/training/application/public.

No ServiceContext

None of the methods on this page take a ServiceContext. They serve readers who have no account: the public player opened from a code, a shared session link, the anonymous editor. The credential is the code itself. The visibility gate for shared containers is applied by the owning repository's public read (getByCode for sessions, a publiclyVisible() query for collections), which finds nothing when the link is disabled or outside its window, and the deal payloads never carry userId. This is the deliberate exception to the rule described in Service Context.

Reads that need a viewer (bookmarks, private boards, votes) are on Boards, with a ctx.

Domain

DealView

DealView = EditorDealView | AppDealView, discriminated on source. The two differ only in the comment shape carried by auction and play: editor deals are anonymous and language-unknown, so their per-move comments are plain RichText; app deals come from an account with a known language, so their comments are LocalizedField<RichText>. Narrow on source for typed comments, or keep treating comment as unknown and use the isRichText and isLocalizedField guards.

The module's index.ts exports the three types only. The hand sorting used by the services is internal.

Application

DealService

createDealService(repository: DealReadRepository): DealService

// The player reads take no ServiceContext: a deal code is the whole credential.
export function buildDealService(repository: DealReadRepository): DealService {
  return createDealService(repository);
}

export async function openDeal(
  deals: DealService,
  code: string
): Promise<DealView | null> {
  const deal = await deals.getByCode(code);
  // deal.cards is re-sorted suit by suit, deal.source narrows the comment shape
  if (deal?.source === "app") {
    deal.auction; // Auction<LocalizedField<RichText>> | null
  }
  return deal;
}

export function findDealToImport(
  deals: DealService,
  code: string,
  ctx: ServiceContext
): Promise<SearchByCodeResult | null> {
  // only the deals ctx.userId may read, with its own user themes alone
  return deals.searchByCode(code, ctx);
}

ApiDealService is DealService without searchByCodes. The API types its public deals with it, so a request cannot reach the batch read that spans every account.

export function anotherDealLikeThis(deals: DealService, seen: string[]) {
  // excludeCodes is dropped on a second try when the pool is empty;
  // teachingMode never is.
  return deals.pickNext({
    levels: [2],
    language: "fr",
    excludeCodes: seen,
    teachingMode: "auction",
  });
}

PublicDealsService

createPublicDealsService(deps: { dealRepo: DealReadRepository; sessionsRead: GroupSessionsReadRepository; collectionsRead: DealCollectionsReadRepository }): PublicDealsService

Backs the deal payload of a shared link. The owning container's public read is the visibility gate; the deal repository is the data source. The boundary mapper drops userId and re-sorts each suit, so consumers that do not re-sort at render time, like the PDF diagram, get canonical rank order.

PublicDealView is Omit<DealView, "userId"> & { code: string }.

export function buildPublicDeals(
  dealRepo: DealReadRepository,
  sessionsRead: GroupSessionsReadRepository,
  collectionsRead: DealCollectionsReadRepository
): PublicDealsService {
  return createPublicDealsService({ dealRepo, sessionsRead, collectionsRead });
}

export function dealsOfSharedSession(
  publicDeals: PublicDealsService,
  sessionCode: string
): Promise<PublicDealView[]> {
  // [] when the code is unknown, the link is disabled or outside its window;
  // rows come back in session order, without userId.
  return publicDeals.getForSessionCode(sessionCode);
}

PublicCollectionsService

createPublicCollectionsService(deps: { collectionsRead: DealCollectionsReadRepository; overflow: StockOverflowResolver; publicDeals: Pick<PublicDealsService, "getForBoardCodes"> }): PublicCollectionsService

The unauthenticated read of a collection by code with the owner's stock ceiling applied. A collection above the ceiling keeps its public page during a grace period, with a notice, then closes. The closed page is an explicit unavailability, not an unknown code, so the viewer can say so. See Entitlements for the rule.

export function buildPublicCollections(
  collectionsRead: DealCollectionsReadRepository,
  overflow: StockOverflowResolver,
  publicDeals: PublicDealsService
): PublicCollectionsService {
  return createPublicCollectionsService({
    collectionsRead,
    overflow,
    publicDeals,
  });
}

export async function sharedCollectionPage(
  publicCollections: PublicCollectionsService,
  code: string
) {
  const view = await publicCollections.getByCode(code);
  if (!view) {
    return null; // unknown code, disabled link or outside the window
  }
  view.availability.status; // "active" | "grace" | "degraded"
  view.availability.publicUntil; // ISO instant while in grace
  view.boards; // [] once degraded, publicContent null too
  const deals = await publicCollections.getDeals(code); // [] once degraded
  return { view, deals };
}

PublicSessionsService

createPublicSessionsService(deps: { sessionsRead: GroupSessionsReadRepository; publicDeals: Pick<PublicDealsService, "getForSessionCode"> }): PublicSessionsService

The unauthenticated read of a group session by code, the session counterpart of PublicCollectionsService. Sessions have no stock ceiling, so the visibility filter is the whole gate: a GroupSessionQuery.withCode(code).publiclyVisible() read with the publicPage() projection.

export async function sharedSessionPage(
  sessionsRead: GroupSessionsReadRepository,
  publicDeals: PublicDealsService,
  code: string
) {
  const publicSessions: PublicSessionsService = createPublicSessionsService({
    sessionsRead,
    publicDeals,
  });
  const session = await publicSessions.getByCode(code);
  if (!session) {
    return null; // unknown code, disabled link or outside the window
  }
  const deals = await publicSessions.getDeals(code); // session order, without userId
  return { session, deals };
}

Input shapes

PickNextPublicDealCriteria is { levels: readonly ClassifiedLevel[]; language: string; excludeCodes: readonly string[]; teachingMode: TeachingMode | null }. levels and language rank, they never filter; empty means no preference. excludeCodes and teachingMode are hard constraints, and only excludeCodes is dropped on the fallback retry: the caller asked for another deal of this kind, and a foreign mode is a wrong answer. null means no teaching-mode constraint.

Query objects

Generics are on Queries. The unified deals view is keyed by code and has no id of its own: editor rows carry none, app rows carry their board's.

DealQuery: DealQueryParams = QueryParams<DealWhere, DealSort>.

DealWhere: { code?: Equality<string> & { notIn? }; source?: Equality<"app" \| "editor">; deletedAt?: Nullability; orphanedAt?: Nullability; teachingMode?: Equality<TeachingMode>; publiclyVisible?: true; visibleTo?: string }.

DealSort: { rank: "nextPick"; levels; language }. Closest level first, unclassified deals last; then the requested language over language-agnostic deals over other languages; then deals with a review over bare ones; ties break at random, so a one-row window is a draw. A sorted query must be scoped by pickable(): the ranking reads the board index, which holds app deals only.

DealProjections

Ports

DealReadRepository is ReadRepository<DealQuery>: getById(code, projection), findMany, findManyPaginated, aggregate. Public, no user context. getById takes the code and throws NotFoundError(DEAL_NOT_FOUND); aggregate supports no kind yet. There is no write side: deals are written through Boards and Editor boards.

A query sorted by a DealSort runs in two steps: the ranking reads scalar columns of the board index alone, then the chosen codes are hydrated from the deals view in rank order. Sorting the view directly would build its whole jsonb projection for every candidate before keeping one.

Testing

createFakeDealReadRepository(seed?: FakeDealRow[]) from @workspace/training/testing is an in-memory DealReadRepository. See Testing.

Errors

The public services never throw NotFoundError: an unknown or closed code is a null or an empty array, so the player can render the right page without an exception path.

Test data: makeDealView (app source) and makeEditorDealView in Factories.