// ---------------------------------------------------------------------------// The READ half of the admin users surface, shared by every host.//// A host's `AdminUsersProvider` owns AUTHORIZATION (who may look) and delegates// the actual reads here, so the projection from the SDK's platform view onto// the wire shapes exists exactly ONCE. That matters because the projection IS// the field-discipline boundary: if each host mapped rows itself, a credential// field could leak into one host's responses and not the other's.//// Every mapping below is explicit rather than a spread. A spread would silently// forward any field a future SDK change adds to `AdminSubject`/`AdminConnection`// — the opposite of an allowlist.// --------------------------------------------------------------------------- import { Effect } from "effect"; import type {  AdminConnection,  AdminSubject,  AdminSubjectWithConnections,  Executor,  ExecutorAdmin,} from "@executor-js/sdk"; import {  AdminUserNotFound,  AdminUsersError,  type AdminUserConnectionsResponse,  type AdminUserResponse,  type AdminUsersResponse,  type AdminUsersWithConnectionsResponse,} from "./api";import type { AdminUsersListOptions } from "./service"; /** * Narrow an executor to its platform view. `admin` is present only when the * executor was built with `platformView: true`; a host that reaches these reads * with a product-view executor is a wiring bug, so it fails loudly as a 500 * rather than silently returning an empty tenant (which would read as "this * owner has no users"). */export const platformViewOf = (executor: Executor): Effect.Effect<ExecutorAdmin, AdminUsersError> =>  executor.admin    ? Effect.succeed(executor.admin)    : Effect.fail(        new AdminUsersError({          message: "Admin reads require an executor built with the platform view enabled",        }),      ); // Storage faults are the only failure these reads can raise. They surface as a// 500 with a flat message — the cause carries the detail into the host's error// capture, and is deliberately not echoed to an API consumer.const readFailed = (what: string) => () =>  new AdminUsersError({ message: `Failed to list ${what}` }); // ---------------------------------------------------------------------------// Host identity join// --------------------------------------------------------------------------- /** What a host's member directory can say about one principal. Both halves are *  independently nullable: a directory can hold an email with no name. */export interface AdminUserIdentity {  readonly email: string | null;  readonly displayName: string | null;} /** * The ONE email normalization rule: shared by the `?email=` filter, the * single-user path parameter, and every host's own resolver (which must apply * it to the DIRECTORY value before comparing). * * Case-insensitive because the two hosts disagree about what they store: * Better Auth lower-cases every email it writes, while WorkOS preserves the * casing it was given. Lower-casing BOTH sides is the only rule that answers * the same way on both. The local part of an address is technically * case-sensitive per RFC 5321, but no directory this reads treats it that way, * and an operator typing "Alice@..." means the same person. */export const normalizeEmail = (email: string): string => email.trim().toLowerCase(); /** * A host's member directory, keyed by the SAME id space the subject table * records in `external_id`. * * That id is the host-auth principal id — cloud binds the WorkOS `user_...`, * self-host binds the Better Auth `user.id` — so the join key on both hosts is * the member list's `userId`, NEVER its `id` (a membership-row id: `om_...` on * cloud, the `member` row on self-host, both of which join to nothing). * * Called ONCE per request with the whole page of ids, so a host implements it * as one directory read joined in memory rather than a lookup per user. A host * that cannot resolve identities at all simply passes no directory, and every * row reports absent identity. */export type AdminIdentityDirectory = (  externalIds: readonly string[],) => Effect.Effect<ReadonlyMap<string, AdminUserIdentity>, unknown>; /** * The REVERSE of the join above: email → the host-auth principal id, so an * operator can name a user by the identifier they actually have. * * The email arrives already trimmed and lower-cased by the contract, and an * implementation must compare against a lower-cased directory value — neither * host guarantees the casing it stores, so case-insensitivity is the seam's * rule and not a per-host accident. * * `null` means the directory knows no such member. That is NOT the same as * "not a user of this tenant": a resolved id may still have no subject row, * which the reads below treat as absent (see `getUser`). Failures are the * caller's to interpret — unlike the decorative identity join, a lookup that * cannot run must not silently become "no such user". */export type AdminEmailResolver = (email: string) => Effect.Effect<string | null, unknown>; /** Both directions of a host's member directory. Optional as a whole (a host *  with no directory reports unnamed rows and cannot resolve emails), and *  optional per direction. */export interface AdminUserDirectory {  readonly identities?: AdminIdentityDirectory;  readonly resolveEmail?: AdminEmailResolver;} /** Identity is decoration on an operator view, not part of the answer: a *  directory outage must degrade to unnamed rows, never fail the read the *  operator actually asked for. Logged once per failed page — the cause carries *  the detail, and the caller learns nothing from it. */const resolveIdentities = (  directory: AdminIdentityDirectory | undefined,  externalIds: readonly string[],): Effect.Effect<ReadonlyMap<string, AdminUserIdentity>> => {  if (!directory || externalIds.length === 0) return Effect.succeed(new Map());  return directory(externalIds).pipe(    Effect.catchCause((cause) =>      Effect.as(        Effect.logWarning("admin users: host identity lookup failed; reporting users unnamed", {          cause,        }),        new Map<string, AdminUserIdentity>(),      ),    ),  );}; const ABSENT_IDENTITY: AdminUserIdentity = { email: null, displayName: null }; /** * `AdminSubject` → the public `AdminUser` shape. * * `createdAt` crosses the wire as epoch ms (the SDK hands back a `Date`), which * matches how every other "when did this happen" field on the API is carried * and keeps the whole response JSON-native. * * `email`/`displayName` come from the host directory rather than storage, so an * id the directory doesn't know — a member who left the org while their * connections remain, or a host sentinel like "local" that names no member — * reports absent identity beside otherwise complete row data. */const toUser = (subject: AdminSubject, identities: ReadonlyMap<string, AdminUserIdentity>) => {  const identity = identities.get(subject.externalId) ?? ABSENT_IDENTITY;  return {    externalId: subject.externalId,    createdAt: subject.createdAt.getTime(),    lastSeenAt: subject.lastSeenAt,    status: subject.status,    email: identity.email,    displayName: identity.displayName,  };}; /** * The stored health verdict → the admin plane's `AdminConnectionHealth`. * * NESTED OBJECTS GET THE SAME TREATMENT AS COLUMNS. `HealthCheckResult` is the * owner's view of their own probe and carries content taken from the UPSTREAM * provider's response: `identity` (the value at the configured `identityField` * — usually the account's email at the provider), `detail` (a raw diagnostic * that can quote an upstream error body), and `responseSample` (a bounded * sample of the real response body's scalar leaves). This plane reports on * OTHER people's connections, so none of that may travel; forwarding * `connection.lastHealth` whole is exactly the leak this function exists to * prevent — the column allowlist below would still have "passed" while every * upstream field rode along inside it. * * Two fields survive, both of them verdicts ABOUT the connection rather than * content FROM it: `status` and `checkedAt`. Written as an explicit * construction, never a spread, for the same reason the row mappings are. */const toHealth = (health: AdminConnection["lastHealth"]) =>  health === null ? null : { status: health.status, checkedAt: health.checkedAt }; /** * `AdminConnection` → the public `AdminUserConnection` shape. * * `subject` is dropped: on `/admin/users/:externalId/connections` it is the * path parameter, and on the joined view it is the enclosing user's own id, so * carrying it would be redundant on both. Everything kept here is either an * identifier or a health/access summary — never credential material, and never * upstream account content (see `toHealth`). */const toConnection = (connection: AdminConnection) => ({  owner: connection.owner,  integration: connection.integration,  name: connection.name,  oauthScope: connection.oauthScope,  lastHealth: toHealth(connection.lastHealth),}); const toUserWithConnections = (  subject: AdminSubjectWithConnections,  identities: ReadonlyMap<string, AdminUserIdentity>,) => ({  ...toUser(subject, identities),  connections: subject.connections.map(toConnection),}); /** * Accept the legacy one-way directory or the two-way one, so a host that only * joins identities keeps working unchanged. */const asDirectory = (  directory: AdminIdentityDirectory | AdminUserDirectory | undefined,): AdminUserDirectory =>  directory === undefined    ? {}    : typeof directory === "function"      ? { identities: directory }      : directory; /** * Turn an `?email=` filter into the id to keep, or `null` for "nothing can * match" (unknown email, or a host with no resolver — an email filter no host * can answer must return nothing, never an unfiltered page). * * A resolver FAILURE is a 500, not an empty page: silently reporting "no such * user" because a directory was unreachable is the kind of wrong answer an * operator would act on. */const resolveEmailFilter = (  directory: AdminUserDirectory,  email: string,): Effect.Effect<string | null, AdminUsersError> => {  const resolve = directory.resolveEmail;  if (!resolve) return Effect.succeed(null);  return resolve(email).pipe(    Effect.mapError(() => new AdminUsersError({ message: "Failed to resolve the email address" })),  );}; /** Keep only the subject naming `externalId`. The filter is applied AFTER the *  page read, so it narrows the requested page rather than scanning past it — *  see the contract's note on paging a filtered result. */const filterToId = <T extends { readonly externalId: string }>(  subjects: readonly T[],  externalId: string | null,): readonly T[] =>  externalId === null ? [] : subjects.filter((subject) => subject.externalId === externalId); export const listUsers = (  admin: ExecutorAdmin,  options: AdminUsersListOptions,  directory?: AdminIdentityDirectory | AdminUserDirectory,): Effect.Effect<typeof AdminUsersResponse.Type, AdminUsersError> =>  Effect.gen(function* () {    const dir = asDirectory(directory);    const wanted =      options.email === undefined ? undefined : yield* resolveEmailFilter(dir, options.email);    const all = yield* admin.listSubjects(options).pipe(Effect.mapError(readFailed("users")));    const subjects = wanted === undefined ? all : filterToId(all, wanted);    // One directory read for the page that was actually returned, joined in    // memory — never a lookup per user.    const identities = yield* resolveIdentities(      dir.identities,      subjects.map((subject) => subject.externalId),    );    return { users: subjects.map((subject) => toUser(subject, identities)) };  }); export const listUsersWithConnections = (  admin: ExecutorAdmin,  options: AdminUsersListOptions,  directory?: AdminIdentityDirectory | AdminUserDirectory,): Effect.Effect<typeof AdminUsersWithConnectionsResponse.Type, AdminUsersError> =>  Effect.gen(function* () {    const dir = asDirectory(directory);    const wanted =      options.email === undefined ? undefined : yield* resolveEmailFilter(dir, options.email);    const all = yield* admin      .listSubjectsWithConnections(options)      .pipe(Effect.mapError(readFailed("users")));    const subjects = wanted === undefined ? all : filterToId(all, wanted);    const identities = yield* resolveIdentities(      dir.identities,      subjects.map((subject) => subject.externalId),    );    return { users: subjects.map((subject) => toUserWithConnections(subject, identities)) };  }); /** * One user by `externalId` OR email, with connections. * * RESOLUTION ORDER. An identifier containing "@" is tried as an email first; * if the directory knows no such member, or the id it resolves to has no * subject row, the identifier is then tried as a literal `externalId`. That * fallback is what keeps `externalId` opaque: no host mints an id containing * "@" today, but the contract promises nothing may parse the id, so the "@" * test is only ever a routing hint that costs one extra keyed read in a case * that does not currently arise. * * A directory hit with no subject row is `AdminUserNotFound`, the same as an * unknown identifier — the plane reports footprint, not org membership. See * the `getUser` contract docs for why. */export const getUser = (  admin: ExecutorAdmin,  identifier: string,  directory?: AdminIdentityDirectory | AdminUserDirectory,): Effect.Effect<typeof AdminUserResponse.Type, AdminUsersError | AdminUserNotFound> =>  Effect.gen(function* () {    const dir = asDirectory(directory);    const read = (externalId: string) =>      admin.getSubjectWithConnections(externalId).pipe(Effect.mapError(readFailed("user")));     const subject = yield* identifier.includes("@")      ? Effect.gen(function* () {          const resolved = yield* resolveEmailFilter(dir, normalizeEmail(identifier));          const byEmail = resolved === null ? null : yield* read(resolved);          return byEmail ?? (yield* read(identifier));        })      : read(identifier);     if (subject === null) return yield* new AdminUserNotFound();     // Identity is joined through the SAME batched seam the list uses, so the    // single read reports exactly the fields the list would for this row.    const identities = yield* resolveIdentities(dir.identities, [subject.externalId]);    return { user: toUserWithConnections(subject, identities) };  }); export const listUserConnections = (  admin: ExecutorAdmin,  externalId: string,): Effect.Effect<typeof AdminUserConnectionsResponse.Type, AdminUsersError> =>  admin.listSubjectConnections(externalId).pipe(    Effect.map((connections) => ({ connections: connections.map(toConnection) })),    Effect.mapError(readFailed("connections")),  );