// ---------------------------------------------------------------------------
// Admin Users HTTP API — the public, tenant-wide operator surface.
//
// The product plane (`/api/*`) answers "what can I, this member, reach". This
// one answers the OWNER's question: "who are my users, and what have they
// connected". It reads the SDK's platform view (`executor.admin`, opt-in via
// `platformView: true`), which is read-only by construction — the owner policy
// rejects writes at `reach: "tenant"` — so every endpoint here is a GET.
//
// VOCABULARY: this is the translation seam. Internal code says subject / tenant
// / reach; everything public-facing says users / owners. `AdminSubject
// .externalId` becomes `externalId` on a `users` collection, and nothing below
// leaks the word "subject".
//
// FIELD DISCIPLINE: the response shapes are 1:1 with the SDK's hand-picked
// admin allowlist (`AdminSubject` / `AdminConnection`), NOT a projection of the
// underlying rows. No credential material of any kind may appear — no item ids,
// no refresh ids, no oauth client secrets, no tokens. `oauthScope` is a summary
// of ACCESS (which scopes were granted), never a token. Adding a field here is
// a deliberate act that has to be argued against `platform-view.test.ts`'s
// forbidden-field list.
//
// Auth is applied by each host's own admin middleware (cloud: an org-scoped API
// key or an admin session member; self-host: a Better Auth owner/admin member),
// so this contract carries no provider-specific auth scheme — the same shape
// the Account API uses.
// ---------------------------------------------------------------------------

import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
import { Schema } from "effect";

import { ConnectionName, HealthCheckResult, IntegrationSlug, Owner } from "@executor-js/sdk/shared";

// ---------------------------------------------------------------------------
// Errors
// ---------------------------------------------------------------------------

export class AdminUsersError extends Schema.TaggedErrorClass<AdminUsersError>()(
  "AdminUsersError",
  { message: Schema.String },
  { httpApiStatus: 500 },
) {}

export class AdminUsersUnauthorized extends Schema.TaggedErrorClass<AdminUsersUnauthorized>()(
  "AdminUsersUnauthorized",
  {},
  { httpApiStatus: 401 },
) {}

export class AdminUsersForbidden extends Schema.TaggedErrorClass<AdminUsersForbidden>()(
  "AdminUsersForbidden",
  {},
  { httpApiStatus: 403 },
) {}

// ---------------------------------------------------------------------------
// Response schemas — the public projection of the SDK's admin shapes.
// ---------------------------------------------------------------------------

/**
 * One user of the tenant. Mirrors `AdminSubject` with the public vocabulary.
 *
 * `lastSeenAt` is epoch ms of the last sighting on the request path, and is
 * deliberately COARSE: the writer (`touchSubject`) only rewrites it past a
 * throttle interval (1 hour by default), so treat it as "active around then",
 * never as a precise last-activity timestamp. `null` means never seen on a
 * request — a user can earn a row at connection-create before any sighting.
 */
export const AdminUser = Schema.Struct({
  /** The host-auth principal id (cloud: the WorkOS user id). Opaque — it also
   *  carries host sentinels like "local", so nothing may parse it. */
  externalId: Schema.String,
  /** Epoch ms the user was first recorded under this tenant. */
  createdAt: Schema.Number,
  lastSeenAt: Schema.NullOr(Schema.Number),
  /** User lifecycle. Unconstrained until the lifecycle values are defined;
   *  `null` means no state recorded (which is every row today). */
  status: Schema.NullOr(Schema.String),
});

/**
 * A connection as the platform view sees it: enough to answer "what has this
 * user connected, and is it healthy", and nothing that could resolve a
 * credential. Mirrors `AdminConnection`.
 */
export const AdminUserConnection = Schema.Struct({
  owner: Owner,
  integration: IntegrationSlug,
  name: ConnectionName,
  /** The scope set the provider actually granted, space-delimited as recorded
   *  at connect/refresh. Null for static credentials. A summary of ACCESS —
   *  never a token. */
  oauthScope: Schema.NullOr(Schema.String),
  lastHealth: Schema.NullOr(HealthCheckResult),
});

/** A user joined with every connection they own in the tenant. */
export const AdminUserWithConnections = Schema.Struct({
  ...AdminUser.fields,
  connections: Schema.Array(AdminUserConnection),
});

export const AdminUsersResponse = Schema.Struct({
  users: Schema.Array(AdminUser),
});

export const AdminUserConnectionsResponse = Schema.Struct({
  connections: Schema.Array(AdminUserConnection),
});

export const AdminUsersWithConnectionsResponse = Schema.Struct({
  users: Schema.Array(AdminUserWithConnections),
});

// ---------------------------------------------------------------------------
// Params / query
// ---------------------------------------------------------------------------

const AdminUserParams = { externalId: Schema.String };

// Paging, mirroring `AdminListSubjectsOptions`. Query params arrive as strings,
// so decode them here rather than making every handler interpret raw strings —
// an out-of-range or non-numeric value is a 400 from the contract, not a
// silently-ignored filter. The joined endpoint reads per-user connections, so
// its page size is bounded harder than the flat list's.
const AdminListQuery = Schema.Struct({
  limit: Schema.optional(
    Schema.FiniteFromString.check(Schema.isBetween({ minimum: 1, maximum: 500 })),
  ),
  offset: Schema.optional(
    Schema.FiniteFromString.check(
      Schema.isBetween({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
    ),
  ),
});

// ---------------------------------------------------------------------------
// Group
// ---------------------------------------------------------------------------

/**
 * The admin users group, mounted at `/admin/*` by each host.
 *
 * The joined view is its OWN path (`/admin/users/with-connections`) rather than
 * an `?include=connections` flag on `/admin/users`, because the two return
 * different row shapes. A query flag that changes the response schema can't be
 * expressed as one typed endpoint — the repo's list endpoints use query params
 * only to FILTER a fixed shape (`/tools`, `/connections`), never to switch it.
 * It sorts before `/admin/users/:externalId/...` in the router either way, and
 * "with-connections" is not a valid opaque principal id.
 */
export const AdminUsersApi = HttpApiGroup.make("adminUsers")
  .add(
    HttpApiEndpoint.get("listUsers", "/admin/users", {
      query: AdminListQuery,
      success: AdminUsersResponse,
      error: [AdminUsersError, AdminUsersUnauthorized, AdminUsersForbidden],
    }),
  )
  .add(
    HttpApiEndpoint.get("listUsersWithConnections", "/admin/users/with-connections", {
      query: AdminListQuery,
      success: AdminUsersWithConnectionsResponse,
      error: [AdminUsersError, AdminUsersUnauthorized, AdminUsersForbidden],
    }),
  )
  .add(
    HttpApiEndpoint.get("listUserConnections", "/admin/users/:externalId/connections", {
      params: AdminUserParams,
      success: AdminUserConnectionsResponse,
      error: [AdminUsersError, AdminUsersUnauthorized, AdminUsersForbidden],
    }),
  );

/**
 * Standalone HttpApi wrapping just the admin users group. Hosts mount THIS as
 * an extension route (like the account API) rather than adding the group to
 * `CoreExecutorApi`: the core API is served behind the execution-stack
 * middleware, which binds a product-view executor to one acting subject. The
 * admin plane needs the opposite (no subject, tenant reach), so it gets its own
 * mount and its own per-host auth.
 */
export const AdminUsersHttpApi = HttpApi.make("executor-admin-users").add(AdminUsersApi);