@nexys/user-management-client 0.1.0 → 0.2.0

package/src/endpoints/auth.ts

@@ -0,0 +1,203 @@
+import type { Endpoint } from "../endpoint.js";
+import type { ApiError } from "../result.js";
+import { parseApiError } from "../result.js";
+import type { AuthSuccess, SignInResult } from "../types.js";
+
+/** Sign-up surfaces a couple of specific codes the UI may want to switch on. */
+export type SignUpError =
+  | ApiError
+  | { kind: "http"; status: 422; code: "USER_ALREADY_EXISTS"; message: string }
+  | { kind: "http"; status: 422; code: "PASSWORD_TOO_SHORT"; message: string };
+
+export const signUp: Endpoint<
+  {
+    name: string;
+    email: string;
+    password: string;
+    /**
+     * Project-scoped sign-up: the target project must exist and have
+     * `allowSignup` enabled (403 `signup_disabled` otherwise).
+     */
+    projectId?: string;
+  },
+  AuthSuccess,
+  SignUpError
+> = {
+  method: "POST",
+  path: () => "/api/auth/sign-up/email",
+  body: (input) => input,
+  parseOutput: (data) => data as AuthSuccess,
+  parseError: parseApiError,
+};
+
+/** Sign-in collapses bad-email / bad-password into one enumeration-safe code. */
+export type SignInError =
+  | ApiError
+  | { kind: "http"; status: 401; code: "INVALID_EMAIL_OR_PASSWORD"; message: string }
+  | { kind: "http"; status: 403; code: "INACTIVE_USER"; message: string };
+
+export const signIn: Endpoint<
+  { email: string; password: string },
+  SignInResult,
+  SignInError
+> = {
+  method: "POST",
+  path: () => "/api/auth/sign-in/email",
+  body: (input) => input,
+  parseOutput: (data) => data as SignInResult,
+  parseError: parseApiError,
+};
+
+/** Full user + session snapshot; `null` body when unauthenticated. */
+export const getSession: Endpoint<void, AuthSuccess | null, ApiError> = {
+  method: "GET",
+  path: () => "/api/auth/get-session",
+  parseOutput: (data) => data as AuthSuccess | null,
+  parseError: parseApiError,
+};
+
+export const signOut: Endpoint<void, { success: boolean }, ApiError> = {
+  method: "POST",
+  path: () => "/api/auth/sign-out",
+  parseOutput: (data) => data as { success: boolean },
+  parseError: parseApiError,
+};
+
+export const requestPasswordReset: Endpoint<{ email: string }, { ok: true }, ApiError> = {
+  method: "POST",
+  path: () => "/api/auth/forget-password",
+  body: (input) => input,
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};
+
+export const resetPassword: Endpoint<
+  { token: string; newPassword: string },
+  { ok: true },
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/auth/reset-password",
+  body: (input) => ({ token: input.token, newPassword: input.newPassword }),
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};
+
+export const requestMagicLink: Endpoint<{ email: string }, { ok: true }, ApiError> = {
+  method: "POST",
+  path: () => "/api/auth/sign-in/magic-link",
+  body: (input) => input,
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};
+
+export const verifyMagicLink: Endpoint<{ token: string }, { ok: true }, ApiError> = {
+  method: "GET",
+  path: () => "/api/auth/magic-link/verify",
+  query: ({ token }) => ({ token }),
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};
+
+/**
+ * Better Auth admin-plugin user create. Superadmin/useradmin only;
+ * the account lands active + email-verified with a password
+ * credential. Returns the full user under `user`.
+ */
+export const adminCreateUser: Endpoint<
+  {
+    email: string;
+    password: string;
+    name?: string;
+    firstName?: string;
+    lastName?: string;
+    role?: string;
+  },
+  { user: { id: string; email: string } },
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/auth/admin/create-user",
+  body: (input) => input,
+  parseOutput: (data) => data as { user: { id: string; email: string } },
+  parseError: parseApiError,
+};
+
+/**
+ * Better Auth admin-plugin user update — edit name and/or email.
+ * Email keeps its verified flag; uniqueness enforced (422).
+ */
+export const adminUpdateUser: Endpoint<
+  {
+    userId: string;
+    name?: string;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+  },
+  { user: { id: string; email: string; name: string } },
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/auth/admin/update-user",
+  body: (input) => input,
+  parseOutput: (data) => data as { user: { id: string; email: string; name: string } },
+  parseError: parseApiError,
+};
+
+/**
+ * Better Auth admin-plugin user delete (soft delete — sets
+ * `deletedAt` and revokes the user's sessions). Idempotent.
+ */
+export const adminRemoveUser: Endpoint<
+  { userId: string },
+  { success: true; sessionsRevoked: number; refreshTokensRevoked: number },
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/auth/admin/remove-user",
+  body: (input) => input,
+  parseOutput: (data) =>
+    data as { success: true; sessionsRevoked: number; refreshTokensRevoked: number },
+  parseError: parseApiError,
+};
+
+export const getProviders: Endpoint<void, { providers: string[] }, ApiError> = {
+  method: "GET",
+  path: () => "/api/providers",
+  parseOutput: (data) => data as { providers: string[] },
+  parseError: parseApiError,
+};
+
+export const socialSignIn: Endpoint<
+  {
+    provider: string;
+    callbackURL?: string;
+    /**
+     * Project-scoped flow. If the callback would create a *new* user,
+     * the project's `allowSignup` setting gates it; existing users
+     * sign in regardless.
+     */
+    projectId?: string;
+  },
+  { url: string; redirect: true },
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/auth/sign-in/social",
+  body: (input) => input,
+  parseOutput: (data) => data as { url: string; redirect: true },
+  parseError: parseApiError,
+};
+
+export const changePassword: Endpoint<
+  { currentPassword: string; newPassword: string },
+  { ok: true },
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/auth/change-password",
+  body: (input) => input,
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};

package/src/endpoints/health.ts

@@ -0,0 +1,50 @@
+import type { Endpoint } from "../endpoint.js";
+import type { ApiError } from "../result.js";
+import { parseApiError } from "../result.js";
+
+export const health: Endpoint<void, { ok: boolean }, ApiError> = {
+  method: "GET",
+  path: () => "/health",
+  parseOutput: (data) => data as { ok: boolean },
+  parseError: parseApiError,
+};
+
+export interface AuthHealth {
+  ok: boolean;
+  /** Server crate version (Cargo `version`) — baked in at compile time. */
+  version: string;
+  /** UTC ISO-8601 build timestamp seeded by CI via `BUILD_DATE`;
+   *  `"unknown"` outside CI. */
+  date: string;
+  /** Build commit SHA. `null` in dev builds where `GIT_SHA` was unset. */
+  sha: string | null;
+  /** Release tag, set only on tagged builds. */
+  tag: string | null;
+  startedAt: string;
+  uptimeSeconds: number;
+}
+
+export const authHealth: Endpoint<void, AuthHealth, ApiError> = {
+  method: "GET",
+  path: () => "/api/auth/health",
+  parseOutput: (data) => data as AuthHealth,
+  parseError: parseApiError,
+};
+
+export interface JwksKey {
+  kid: string;
+  kty: string;
+  use?: string;
+  alg?: string;
+  crv?: string;
+  x?: string;
+  // additional fields per JWK spec; left open
+  [k: string]: unknown;
+}
+
+export const jwks: Endpoint<void, { keys: JwksKey[] }, ApiError> = {
+  method: "GET",
+  path: () => "/api/auth/jwks",
+  parseOutput: (data) => data as { keys: JwksKey[] },
+  parseError: parseApiError,
+};

package/src/endpoints/index.ts

@@ -0,0 +1,12 @@
+export * from "./api-tokens.js";
+export * from "./auth.js";
+export * from "./me.js";
+export * from "./passkeys.js";
+export * from "./two-factor.js";
+export * from "./refresh-tokens.js";
+export * from "./admin-users.js";
+export * from "./admin-audit.js";
+export * from "./admin-keys.js";
+export * from "./health.js";
+export * from "./tenants.js";
+export * from "./projects.js";

package/src/endpoints/me.ts

@@ -0,0 +1,79 @@
+import type { Endpoint } from "../endpoint.js";
+import type { ApiError } from "../result.js";
+import { parseApiError } from "../result.js";
+import type {
+  MeResponse,
+  TokenMintResponse,
+  TokenRefreshResponse,
+  UserMembership,
+} from "../types.js";
+
+export const me: Endpoint<void, MeResponse, ApiError> = {
+  method: "GET",
+  path: () => "/api/me",
+  parseOutput: (data) => data as MeResponse,
+  parseError: parseApiError,
+};
+
+/**
+ * The caller's own tenant memberships — self-service counterpart of
+ * the admin-only `adminListUserTenants`, for org discovery before
+ * `setActiveTenant`.
+ */
+export const myTenants: Endpoint<
+  void,
+  { memberships: UserMembership[] },
+  ApiError
+> = {
+  method: "GET",
+  path: () => "/api/me/tenants",
+  parseOutput: (data) => data as { memberships: UserMembership[] },
+  parseError: parseApiError,
+};
+
+export const updateProfile: Endpoint<
+  { name?: string; image?: string | null },
+  { ok: true },
+  ApiError
+> = {
+  method: "PATCH",
+  path: () => "/api/me",
+  body: (input) => input,
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};
+
+export const mintToken: Endpoint<void, TokenMintResponse, ApiError> = {
+  method: "GET",
+  path: () => "/api/auth/token",
+  parseOutput: (data) => data as TokenMintResponse,
+  parseError: parseApiError,
+};
+
+export const refreshToken: Endpoint<
+  {
+    refreshToken: string;
+    /**
+     * The expiring access token — lets the rotation carry its active
+     * organization forward (membership re-validated server-side).
+     */
+    accessToken?: string;
+  },
+  TokenRefreshResponse,
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/auth/refresh",
+  body: (input) => input,
+  parseOutput: (data) => data as TokenRefreshResponse,
+  parseError: parseApiError,
+};
+
+/** Cookie-based refresh — no body needed, the httpOnly cookie carries the token. */
+export const refreshViaCookie: Endpoint<void, TokenRefreshResponse, ApiError> =
+  {
+    method: "POST",
+    path: () => "/api/auth/refresh",
+    parseOutput: (data) => data as TokenRefreshResponse,
+    parseError: parseApiError,
+  };

package/src/endpoints/passkeys.ts

@@ -0,0 +1,77 @@
+import type { Endpoint } from "../endpoint.js";
+import type { ApiError } from "../result.js";
+import { parseApiError } from "../result.js";
+import type {
+  AuthSuccess,
+  PasskeyItem,
+  WebAuthnCeremonyStart,
+} from "../types.js";
+
+/**
+ * WebAuthn ceremonies are two round-trips: `start` returns the options
+ * JSON for `navigator.credentials.create()/get()` plus an opaque
+ * `challenge` handle; `finish` echoes the handle with the credential
+ * the browser produced (serialised with base64url fields — see the
+ * webauthn helpers in `@nexys/user-management-web`).
+ */
+export const passkeyRegisterStart: Endpoint<void, WebAuthnCeremonyStart, ApiError> = {
+  method: "POST",
+  path: () => "/api/auth/passkey/register/start",
+  parseOutput: (data) => data as WebAuthnCeremonyStart,
+  parseError: parseApiError,
+};
+
+export const passkeyRegisterFinish: Endpoint<
+  { challenge: string; response: Record<string, unknown>; name?: string },
+  { id: string },
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/auth/passkey/register/finish",
+  body: (input) => input,
+  parseOutput: (data) => data as { id: string },
+  parseError: parseApiError,
+};
+
+/**
+ * Anonymous. With `email`, `allowCredentials` is scoped to that user's
+ * authenticators; without it the browser offers discoverable
+ * credentials.
+ */
+export const passkeySignInStart: Endpoint<
+  { email?: string },
+  WebAuthnCeremonyStart,
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/auth/passkey/sign-in/start",
+  body: (input) => input,
+  parseOutput: (data) => data as WebAuthnCeremonyStart,
+  parseError: parseApiError,
+};
+
+export const passkeySignInFinish: Endpoint<
+  { challenge: string; response: Record<string, unknown> },
+  AuthSuccess,
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/auth/passkey/sign-in/finish",
+  body: (input) => input,
+  parseOutput: (data) => data as AuthSuccess,
+  parseError: parseApiError,
+};
+
+export const listPasskeys: Endpoint<void, { passkeys: PasskeyItem[] }, ApiError> = {
+  method: "GET",
+  path: () => "/api/auth/passkey/list",
+  parseOutput: (data) => data as { passkeys: PasskeyItem[] },
+  parseError: parseApiError,
+};
+
+export const deleteOwnPasskey: Endpoint<{ id: string }, { ok: true }, ApiError> = {
+  method: "DELETE",
+  path: (input) => `/api/auth/passkey/${input.id}`,
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};

package/src/endpoints/projects.ts

@@ -0,0 +1,117 @@
+import type { Endpoint } from "../endpoint.js";
+import type { ApiError } from "../result.js";
+import { parseApiError } from "../result.js";
+import type { ProjectRow, TenancyMode, TenantRow } from "../types.js";
+
+/**
+ * Projects — isolated user-management spaces. One account can run
+ * several independent products, each as its own project with its own
+ * tenancy configuration:
+ *
+ * - `tenancyMode` — `"multi"` (any number of tenants) or `"single"`
+ *   (exactly one; a second create returns `409 single_tenant_limit`).
+ * - `allowTenantCreation` — when true, any authenticated user may
+ *   create a tenant inside the project (self-serve).
+ * - `allowSignup` — when true, project-scoped sign-up
+ *   (`signUp` with a `projectId`) is open.
+ */
+export const createProject: Endpoint<
+  {
+    name: string;
+    slug?: string;
+    tenancyMode?: TenancyMode;
+    allowTenantCreation?: boolean;
+    allowSignup?: boolean;
+    metadata?: Record<string, unknown> | null;
+  },
+  ProjectRow,
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/projects",
+  body: (input) => input,
+  parseOutput: (data) => data as ProjectRow,
+  parseError: parseApiError,
+};
+
+/** The caller's projects, tenant counts included (superadmin sees all). */
+export const listProjects: Endpoint<void, { projects: ProjectRow[] }, ApiError> = {
+  method: "GET",
+  path: () => "/api/projects",
+  parseOutput: (data) => data as { projects: ProjectRow[] },
+  parseError: parseApiError,
+};
+
+export const getProject: Endpoint<{ projectId: string }, ProjectRow, ApiError> = {
+  method: "GET",
+  path: (input) => `/api/projects/${encodeURIComponent(input.projectId)}`,
+  parseOutput: (data) => data as ProjectRow,
+  parseError: parseApiError,
+};
+
+/**
+ * Update project settings. Omitted fields keep their current value;
+ * `metadata: null` clears the blob. Narrowing `tenancyMode` to
+ * `"single"` is refused (`409 project_has_multiple_tenants`) while the
+ * project holds more than one tenant. Owner or superadmin only.
+ */
+export const updateProject: Endpoint<
+  {
+    projectId: string;
+    name?: string;
+    slug?: string;
+    tenancyMode?: TenancyMode;
+    allowTenantCreation?: boolean;
+    allowSignup?: boolean;
+    metadata?: Record<string, unknown> | null;
+  },
+  ProjectRow,
+  ApiError
+> = {
+  method: "PATCH",
+  path: (input) => `/api/projects/${encodeURIComponent(input.projectId)}`,
+  body: ({ projectId: _projectId, ...rest }) => rest,
+  parseOutput: (data) => data as ProjectRow,
+  parseError: parseApiError,
+};
+
+/** Delete a project and every tenant inside it (cascade). */
+export const deleteProject: Endpoint<
+  { projectId: string },
+  { ok: true; id: string },
+  ApiError
+> = {
+  method: "DELETE",
+  path: (input) => `/api/projects/${encodeURIComponent(input.projectId)}`,
+  parseOutput: (data) => data as { ok: true; id: string },
+  parseError: parseApiError,
+};
+
+/** Tenants inside a project, member counts included. Owner or superadmin. */
+export const listProjectTenants: Endpoint<
+  { projectId: string },
+  { tenants: TenantRow[] },
+  ApiError
+> = {
+  method: "GET",
+  path: (input) => `/api/projects/${encodeURIComponent(input.projectId)}/tenants`,
+  parseOutput: (data) => data as { tenants: TenantRow[] },
+  parseError: parseApiError,
+};
+
+/**
+ * Create a tenant inside a project; the caller becomes its owner. The
+ * project owner (or a superadmin) always may; other authenticated users
+ * need the project's `allowTenantCreation` setting.
+ */
+export const createProjectTenant: Endpoint<
+  { projectId: string; name: string; slug?: string },
+  TenantRow,
+  ApiError
+> = {
+  method: "POST",
+  path: (input) => `/api/projects/${encodeURIComponent(input.projectId)}/tenants`,
+  body: ({ projectId: _projectId, ...rest }) => rest,
+  parseOutput: (data) => data as TenantRow,
+  parseError: parseApiError,
+};

package/src/endpoints/refresh-tokens.ts

@@ -0,0 +1,25 @@
+import type { Endpoint } from "../endpoint.js";
+import type { ApiError } from "../result.js";
+import { parseApiError } from "../result.js";
+import type { RefreshToken } from "../types.js";
+
+export const listRefreshTokens: Endpoint<void, RefreshToken[], ApiError> = {
+  method: "GET",
+  path: () => "/api/me/refresh-tokens",
+  parseOutput: (data) => (data ?? []) as RefreshToken[],
+  parseError: parseApiError,
+};
+
+export const revokeRefreshToken: Endpoint<{ id: string }, { ok: true }, ApiError> = {
+  method: "DELETE",
+  path: ({ id }) => `/api/me/refresh-tokens/${encodeURIComponent(id)}`,
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};
+
+export const revokeAllRefreshTokens: Endpoint<void, { revoked: number }, ApiError> = {
+  method: "DELETE",
+  path: () => "/api/me/refresh-tokens",
+  parseOutput: (data) => (data ?? { revoked: 0 }) as { revoked: number },
+  parseError: parseApiError,
+};