@nexys/user-management-client 0.1.0 → 0.2.0

package/dist/types.js

@@ -3,5 +3,5 @@
  * Field names are camelCase because the Rust wire.rs renames them
  * with serde — keep this file byte-for-byte aligned with the server.
  */
-export {};
+export const isTwoFactorChallenge = (r) => r.twoFactorRequired === true;
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAsDH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,CAAe,EACU,EAAE,CAC1B,CAAwB,CAAC,iBAAiB,KAAK,IAAI,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexys/user-management-client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pure TypeScript client for the Nexys user-management API (auth, tenants, users, roles, refresh tokens, profile). No React, no DOM.",
   "type": "module",
   "license": "MIT",
@@ -9,10 +9,15 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "bun test",

package/src/endpoint.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, mock, test } from "bun:test";
+
+import { createClient, type Endpoint } from "./endpoint.js";
+import {
+  adminListUsers,
+  adminRevokeUserTokens,
+  me,
+  signIn,
+  signOut,
+} from "./endpoints/index.js";
+import { parseApiError, type ApiError } from "./result.js";
+import { isTwoFactorChallenge } from "./types.js";
+
+const jsonResponse = (body: unknown, status = 200): Response =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+
+const makeClient = (
+  responder: (url: string, init: RequestInit) => Response | Promise<Response>,
+  opts: { onUnauthorized?: () => void; headers?: Record<string, string> } = {}
+) => {
+  const fetchSpy = mock((input: RequestInfo | URL, init?: RequestInit) =>
+    Promise.resolve(responder(input.toString(), init ?? {}))
+  );
+  const client = createClient({
+    baseUrl: "https://auth.example.com/",
+    fetch: fetchSpy as unknown as typeof fetch,
+    ...opts,
+  });
+  return { client, fetchSpy };
+};
+
+describe("createClient + call", () => {
+  test("strips a trailing slash, posts JSON, includes credentials", async () => {
+    const { client, fetchSpy } = makeClient((url, init) => {
+      expect(url).toBe("https://auth.example.com/api/auth/sign-in/email");
+      expect(init.method).toBe("POST");
+      expect(init.credentials).toBe("include");
+      const headers = init.headers as Record<string, string>;
+      expect(headers["content-type"]).toBe("application/json");
+      expect(headers["accept"]).toBe("application/json");
+      expect(JSON.parse(init.body as string)).toEqual({
+        email: "a@b.co",
+        password: "hunter2hunter2",
+      });
+      return jsonResponse({ user: { id: "u1", email: "a@b.co" } });
+    });
+    const res = await client.call(signIn, { email: "a@b.co", password: "hunter2hunter2" });
+    expect(res.ok).toBe(true);
+    if (res.ok && !isTwoFactorChallenge(res.data)) {
+      expect(res.data.user.id).toBe("u1");
+    }
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test("returns ok=false with the parsed http error on a 4xx JSON body", async () => {
+    const { client } = makeClient(() =>
+      jsonResponse(
+        { code: "INVALID_EMAIL_OR_PASSWORD", message: "Invalid email or password." },
+        401
+      )
+    );
+    const res = await client.call(signIn, { email: "x@y.z", password: "whatever" });
+    expect(res.ok).toBe(false);
+    if (!res.ok && res.error.kind === "http") {
+      expect(res.error.status).toBe(401);
+      expect(res.error.code).toBe("INVALID_EMAIL_OR_PASSWORD");
+      expect(res.error.message).toBe("Invalid email or password.");
+    } else {
+      throw new Error("expected http error");
+    }
+  });
+
+  test("returns ok=false with { kind: 'network' } when fetch throws", async () => {
+    const { client } = makeClient(() => {
+      throw new Error("dns failure");
+    });
+    const res = await client.call(me);
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.error.kind).toBe("network");
+      if (res.error.kind === "network") {
+        expect(res.error.message).toBe("dns failure");
+      }
+    }
+  });
+
+  test("fires onUnauthorized once when the server returns 401", async () => {
+    const onUnauthorized = mock(() => {});
+    const { client } = makeClient(() => jsonResponse({ code: "unauth" }, 401), {
+      onUnauthorized,
+    });
+    await client.call(me);
+    expect(onUnauthorized).toHaveBeenCalledTimes(1);
+  });
+
+  test("serialises query params and drops undefined", async () => {
+    const { client } = makeClient((url) => {
+      expect(url).toBe(
+        "https://auth.example.com/api/admin/users?status=active&limit=25"
+      );
+      return jsonResponse({ total: 0, rows: [] });
+    });
+    await client.call(adminListUsers, { status: "active", limit: 25, offset: undefined });
+  });
+
+  test("encodes path parameters", async () => {
+    const { client } = makeClient((url) => {
+      expect(url).toBe(
+        "https://auth.example.com/api/admin/users/u%2F1/revoke-tokens"
+      );
+      return jsonResponse({ ok: true, sessionsRevoked: 0, refreshTokensRevoked: 0 });
+    });
+    await client.call(adminRevokeUserTokens, { userId: "u/1" });
+  });
+
+  test("merges configured extra headers into every request", async () => {
+    const { client, fetchSpy } = makeClient(() => jsonResponse({ success: true }), {
+      headers: { "x-tenant": "acme" },
+    });
+    await client.call(signOut);
+    const init = fetchSpy.mock.calls[0]?.[1] as RequestInit;
+    const headers = init.headers as Record<string, string>;
+    expect(headers["x-tenant"]).toBe("acme");
+    expect(headers["accept"]).toBe("application/json");
+  });
+
+  test("handles 204 No Content by feeding null into parseOutput", async () => {
+    type In = { id: string };
+    const noContentEndpoint: Endpoint<In, { ok: true }, ApiError> = {
+      method: "DELETE",
+      path: ({ id }) => `/api/items/${id}`,
+      parseOutput: (data) => {
+        expect(data).toBeNull();
+        return { ok: true };
+      },
+      parseError: parseApiError,
+    };
+    const { client } = makeClient(() => new Response(null, { status: 204 }));
+    const res = await client.call(noContentEndpoint, { id: "a" });
+    expect(res.ok).toBe(true);
+  });
+
+  test("omits the input argument for endpoints whose Input is void", async () => {
+    const { client } = makeClient(() =>
+      jsonResponse({
+        user: { id: "u1", email: "a@b.co", name: "A", role: "user" },
+        session: { activeOrganizationId: null, tenantRoles: [] },
+        authSource: "cookie",
+      })
+    );
+    // No 2nd arg — typechecks because me: Endpoint<void, …>
+    const res = await client.call(me);
+    expect(res.ok).toBe(true);
+  });
+});

package/src/endpoint.ts

@@ -0,0 +1,123 @@
+import type { NetworkError, Result } from "./result.js";
+
+export type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/**
+ * An Endpoint is plain data — no execution, no transport. It says
+ * "this is how the URL is shaped, how to encode the body, and how to
+ * parse the response (ok or error)". Run it with `call(endpoint, input)`.
+ */
+export interface Endpoint<Input, Output, Err> {
+  method: Method;
+  path: (input: Input) => string;
+  /** Returns the JSON body. Omit for GET / DELETE. */
+  body?: (input: Input) => unknown;
+  /** Returns query params; undefined / null entries are dropped. */
+  query?: (input: Input) => Record<string, string | number | boolean | undefined | null>;
+  parseOutput: (data: unknown) => Output;
+  parseError: (status: number, data: unknown) => Err;
+}
+
+export interface ClientConfig {
+  /** API base URL — e.g. https://auth.example.com (no trailing slash). */
+  baseUrl: string;
+  /** Override the global fetch (SSR / tests). */
+  fetch?: typeof fetch;
+  /** Headers merged into every request. */
+  headers?: Record<string, string>;
+  /** Fired whenever the server returns 401 — typically triggers a re-login flow. */
+  onUnauthorized?: () => void;
+}
+
+/**
+ * Pull I, O, E out of a concrete endpoint so call() can be typed
+ * without callers spelling the parameters.
+ */
+export type EndpointInput<E> = E extends Endpoint<infer I, unknown, unknown> ? I : never;
+export type EndpointOutput<E> = E extends Endpoint<unknown, infer O, unknown> ? O : never;
+export type EndpointError<E> = E extends Endpoint<unknown, unknown, infer Err> ? Err : never;
+
+/** "If Input is void, omit the input arg" trick. */
+type CallArgs<I> = [I] extends [void] ? [] : [input: I];
+
+export interface UmClient {
+  /** Execute an endpoint. Never throws — returns Result. */
+  call<I, O, E>(
+    endpoint: Endpoint<I, O, E>,
+    ...args: CallArgs<I>
+  ): Promise<Result<O, E | NetworkError>>;
+}
+
+const stripTrailing = (b: string): string => b.replace(/\/+$/, "");
+
+const encodeQuery = (
+  q: Record<string, string | number | boolean | undefined | null> | undefined
+): string => {
+  if (!q) return "";
+  const parts: string[] = [];
+  for (const [k, v] of Object.entries(q)) {
+    if (v === undefined || v === null || v === "") continue;
+    parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+  }
+  return parts.length ? `?${parts.join("&")}` : "";
+};
+
+/**
+ * Build a client. The returned object exposes a single `call` method;
+ * everything else is endpoint data.
+ *
+ *   const um = createClient({ baseUrl: "https://auth.example.com" });
+ *   const res = await um.call(signIn, { email, password });
+ *   if (res.ok) { … } else { … }
+ */
+export const createClient = (config: ClientConfig): UmClient => {
+  const baseUrl = stripTrailing(config.baseUrl);
+  const fetcher = config.fetch ?? (globalThis.fetch?.bind(globalThis) as typeof fetch);
+
+  return {
+    call: async <I, O, E>(
+      endpoint: Endpoint<I, O, E>,
+      ...args: CallArgs<I>
+    ): Promise<Result<O, E | NetworkError>> => {
+      const input = (args[0] as I) ?? (undefined as I);
+      const url = `${baseUrl}${endpoint.path(input)}${encodeQuery(endpoint.query?.(input))}`;
+      const init: RequestInit = {
+        method: endpoint.method,
+        credentials: "include",
+        headers: {
+          accept: "application/json",
+          ...(endpoint.body ? { "content-type": "application/json" } : {}),
+          ...(config.headers ?? {}),
+        },
+        ...(endpoint.body ? { body: JSON.stringify(endpoint.body(input)) } : {}),
+      };
+
+      let res: Response;
+      try {
+        res = await fetcher(url, init);
+      } catch (e) {
+        return {
+          ok: false,
+          error: {
+            kind: "network",
+            message: e instanceof Error ? e.message : String(e),
+          },
+        };
+      }
+
+      // 204 No Content — no body to parse. Endpoints that legitimately
+      // return 204 should set parseOutput to accept null.
+      const data: unknown =
+        res.status === 204
+          ? null
+          : await res.json().catch(() => null);
+
+      if (res.status === 401) config.onUnauthorized?.();
+
+      if (!res.ok) {
+        return { ok: false, error: endpoint.parseError(res.status, data) };
+      }
+      return { ok: true, data: endpoint.parseOutput(data) };
+    },
+  };
+};

package/src/endpoints/admin-audit.ts

@@ -0,0 +1,60 @@
+import type { Endpoint } from "../endpoint.js";
+import type { ApiError } from "../result.js";
+import { parseApiError } from "../result.js";
+
+export interface AuditLogRow {
+  id: string;
+  action: string;
+  actorId: string | null;
+  actorEmail: string | null;
+  actorType: string | null;
+  resourceType: string | null;
+  resourceId: string | null;
+  organizationId: string | null;
+  ipAddress: string | null;
+  userAgent: string | null;
+  metadata: unknown;
+  success: boolean;
+  createdAt: string;
+}
+
+export interface AuditLogListResponse {
+  total: number;
+  rows: AuditLogRow[];
+}
+
+/**
+ * Query filters supported by `/api/admin/audit-logs`.
+ * Mirrors `apps/server/crates/um-server/src/routes/admin_audit.rs` — keep
+ * field names + semantics aligned with the server's `ListQuery`. Note:
+ * `actionPrefix` is a prefix match; there's no exact-action filter.
+ */
+export interface AdminListAuditLogsInput {
+  actorId?: string;
+  actionPrefix?: string;
+  organizationId?: string;
+  since?: string;
+  until?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export const adminListAuditLogs: Endpoint<
+  AdminListAuditLogsInput,
+  AuditLogListResponse,
+  ApiError
+> = {
+  method: "GET",
+  path: () => "/api/admin/audit-logs",
+  query: (input) => ({
+    actorId: input.actorId,
+    actionPrefix: input.actionPrefix,
+    organizationId: input.organizationId,
+    since: input.since,
+    until: input.until,
+    limit: input.limit,
+    offset: input.offset,
+  }),
+  parseOutput: (data) => data as AuditLogListResponse,
+  parseError: parseApiError,
+};

package/src/endpoints/admin-keys.ts

@@ -0,0 +1,37 @@
+import type { Endpoint } from "../endpoint.js";
+import type { ApiError } from "../result.js";
+import { parseApiError } from "../result.js";
+
+export interface AdminKeyRow {
+  kid: string;
+  alg: string;
+  status: "active" | "retired" | "revoked" | (string & {});
+  createdAt: string;
+  retiredAt: string | null;
+  revokedAt: string | null;
+}
+
+export const adminListKeys: Endpoint<void, { keys: AdminKeyRow[] }, ApiError> = {
+  method: "GET",
+  path: () => "/api/admin/keys",
+  parseOutput: (data) => data as { keys: AdminKeyRow[] },
+  parseError: parseApiError,
+};
+
+export const adminRotateKey: Endpoint<
+  void,
+  { kid: string; createdAt: string },
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/admin/keys/rotate",
+  parseOutput: (data) => data as { kid: string; createdAt: string },
+  parseError: parseApiError,
+};
+
+export const adminRevokeKey: Endpoint<{ kid: string }, { ok: true }, ApiError> = {
+  method: "POST",
+  path: ({ kid }) => `/api/admin/keys/${encodeURIComponent(kid)}/revoke`,
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};

package/src/endpoints/admin-users.ts

@@ -0,0 +1,172 @@
+import type { Endpoint } from "../endpoint.js";
+import type { ApiError } from "../result.js";
+import { parseApiError } from "../result.js";
+import type {
+  AdminUserListResponse,
+  AdminUserRow,
+  AuthMethodsResponse,
+  UserMembership,
+  UserRole,
+  UserStatus,
+} from "../types.js";
+
+export interface AdminListUsersInput {
+  status?: UserStatus;
+  includeDeleted?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export const adminListUsers: Endpoint<
+  AdminListUsersInput,
+  AdminUserListResponse,
+  ApiError
+> = {
+  method: "GET",
+  path: () => "/api/admin/users",
+  query: (input) => ({
+    status: input.status,
+    includeDeleted: input.includeDeleted ? "true" : undefined,
+    limit: input.limit,
+    offset: input.offset,
+  }),
+  parseOutput: (data) => data as AdminUserListResponse,
+  parseError: parseApiError,
+};
+
+/** Single user with linked auth providers — powers the detail page. */
+export const adminGetUser: Endpoint<{ userId: string }, AdminUserRow, ApiError> = {
+  method: "GET",
+  path: ({ userId }) => `/api/admin/users/${encodeURIComponent(userId)}`,
+  parseOutput: (data) => data as AdminUserRow,
+  parseError: parseApiError,
+};
+
+/** Auth-method inventory: accounts, passkeys, 2FA flag. */
+export const adminAuthMethods: Endpoint<
+  { userId: string },
+  AuthMethodsResponse,
+  ApiError
+> = {
+  method: "GET",
+  path: ({ userId }) =>
+    `/api/admin/users/${encodeURIComponent(userId)}/auth-methods`,
+  parseOutput: (data) => data as AuthMethodsResponse,
+  parseError: parseApiError,
+};
+
+/**
+ * Add a sign-in method as `{authType, value}`. authType "credential"
+ * sets a password (value = the password); a social authType (google,
+ * microsoft, …) pre-links the provider account (value = provider-side
+ * account id or email) so the user's first social sign-in lands here.
+ */
+export const adminAddAccount: Endpoint<
+  { userId: string; authType: string; value: string },
+  { id: string; providerId: string },
+  ApiError
+> = {
+  method: "POST",
+  path: ({ userId }) => `/api/admin/users/${encodeURIComponent(userId)}/accounts`,
+  body: ({ authType, value }) => ({ authType, value }),
+  parseOutput: (data) => data as { id: string; providerId: string },
+  parseError: parseApiError,
+};
+
+/** Unlink an account row (social link or password credential). 409 if it's the last sign-in method. */
+export const adminUnlinkAccount: Endpoint<
+  { userId: string; accountId: string },
+  { ok: true },
+  ApiError
+> = {
+  method: "DELETE",
+  path: ({ userId, accountId }) =>
+    `/api/admin/users/${encodeURIComponent(userId)}/accounts/${encodeURIComponent(accountId)}`,
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};
+
+/** Remove a passkey. 409 if it's the last sign-in method. */
+export const adminDeletePasskey: Endpoint<
+  { userId: string; passkeyId: string },
+  { ok: true },
+  ApiError
+> = {
+  method: "DELETE",
+  path: ({ userId, passkeyId }) =>
+    `/api/admin/users/${encodeURIComponent(userId)}/passkeys/${encodeURIComponent(passkeyId)}`,
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};
+
+/** Admin kill-switch for a user's TOTP (lost authenticator). */
+export const adminDisableTwoFactor: Endpoint<
+  { userId: string },
+  { ok: true },
+  ApiError
+> = {
+  method: "POST",
+  path: ({ userId }) =>
+    `/api/admin/users/${encodeURIComponent(userId)}/two-factor/disable`,
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};
+
+/** Tenants the user belongs to — powers the "manage tenants" panel. */
+export const adminListUserTenants: Endpoint<
+  { userId: string },
+  { memberships: UserMembership[] },
+  ApiError
+> = {
+  method: "GET",
+  path: ({ userId }) => `/api/admin/users/${encodeURIComponent(userId)}/tenants`,
+  parseOutput: (data) => data as { memberships: UserMembership[] },
+  parseError: parseApiError,
+};
+
+export interface SetUserStatusResponse {
+  ok: true;
+  status: UserStatus;
+  sessionsRevoked: number;
+  refreshTokensRevoked: number;
+}
+
+export const adminSetUserStatus: Endpoint<
+  { userId: string; status: UserStatus },
+  SetUserStatusResponse,
+  ApiError
+> = {
+  method: "POST",
+  path: ({ userId }) => `/api/admin/users/${encodeURIComponent(userId)}/status`,
+  body: ({ status }) => ({ status }),
+  parseOutput: (data) => data as SetUserStatusResponse,
+  parseError: parseApiError,
+};
+
+/**
+ * Role change rides the Better Auth admin-plugin route — the server
+ * guards demoting the last active superadmin (409).
+ */
+export const adminSetUserRole: Endpoint<
+  { userId: string; role: UserRole },
+  { ok: true },
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/auth/admin/set-role",
+  body: (input) => input,
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};
+
+export const adminRevokeUserTokens: Endpoint<
+  { userId: string },
+  { ok: true; sessionsRevoked: number; refreshTokensRevoked: number },
+  ApiError
+> = {
+  method: "POST",
+  path: ({ userId }) => `/api/admin/users/${encodeURIComponent(userId)}/revoke-tokens`,
+  parseOutput: (data) =>
+    data as { ok: true; sessionsRevoked: number; refreshTokensRevoked: number },
+  parseError: parseApiError,
+};

package/src/endpoints/api-tokens.ts

@@ -0,0 +1,37 @@
+import type { Endpoint } from "../endpoint.js";
+import type { ApiError } from "../result.js";
+import { parseApiError } from "../result.js";
+import type { ApiTokenCreated, ApiTokenRow } from "../types.js";
+
+/**
+ * Personal API tokens ("CLI" credentials). They authenticate as
+ * `Authorization: Bearer um_…` or `x-api-key`. Creating/revoking
+ * requires a session credential — a token cannot mint more tokens.
+ * Revoked tokens keep their row (status flips); the server's retention
+ * policy deletes dead rows after TOKEN_RETENTION_DAYS.
+ */
+export const createApiToken: Endpoint<
+  { name: string; expiresInDays?: number },
+  ApiTokenCreated,
+  ApiError
+> = {
+  method: "POST",
+  path: () => "/api/me/tokens",
+  body: (input) => input,
+  parseOutput: (data) => data as ApiTokenCreated,
+  parseError: parseApiError,
+};
+
+export const listApiTokens: Endpoint<void, { tokens: ApiTokenRow[] }, ApiError> = {
+  method: "GET",
+  path: () => "/api/me/tokens",
+  parseOutput: (data) => data as { tokens: ApiTokenRow[] },
+  parseError: parseApiError,
+};
+
+export const revokeApiToken: Endpoint<{ id: string }, { ok: true }, ApiError> = {
+  method: "DELETE",
+  path: (input) => `/api/me/tokens/${input.id}`,
+  parseOutput: () => ({ ok: true }),
+  parseError: parseApiError,
+};