@awsmbiz/inbis-api-client 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,568 @@
+import createClient from "openapi-fetch";
+import { createAuthClient } from "better-auth/client";
+import { adminClient } from "better-auth/client/plugins";
+// src/api-error.ts
+/**
+* One error type for every failed call: app routes (the platform envelope
+* `{ error: { code, message, requestId, details? } }`) and auth routes
+* (Better Auth's `{ code, message, details? }`).
+*/
+/** Codes the platform returns that callers commonly branch on. Any other server code passes through as is. */
+const API_ERROR_CODES = {
+	/** No response: offline, DNS, CORS or the server is unreachable (`status` 0). */
+	NETWORK_ERROR: "NETWORK_ERROR",
+	/** Sign in again with one of `details.allowedMethods` (see {@link ApiError.requirement}). */
+	STEP_UP_REQUIRED: "STEP_UP_REQUIRED",
+	/** Complete two-factor authentication (or enrol an authenticator) to continue. */
+	TWO_FACTOR_REQUIRED: "TWO_FACTOR_REQUIRED",
+	/** The action needs a recent sign-in. */
+	SESSION_NOT_FRESH: "SESSION_NOT_FRESH",
+	/** The session has ended. */
+	SESSION_EXPIRED: "SESSION_EXPIRED",
+	/** A settings change would leave no administrator able to use the admin area. */
+	ADMIN_LOCKOUT: "ADMIN_LOCKOUT",
+	/** The runtime auth settings changed since they were loaded (a stale-version conflict). */
+	SETTINGS_VERSION_CONFLICT: "SETTINGS_VERSION_CONFLICT",
+	VALIDATION_FAILED: "VALIDATION_FAILED",
+	RATE_LIMITED: "RATE_LIMITED",
+	UNAUTHORIZED: "UNAUTHORIZED",
+	FORBIDDEN: "FORBIDDEN",
+	NOT_FOUND: "NOT_FOUND",
+	INTERNAL_ERROR: "INTERNAL_ERROR",
+	/** A failed response without a recognisable code. */
+	REQUEST_FAILED: "REQUEST_FAILED"
+};
+const HTTP_CODES = {
+	400: "BAD_REQUEST",
+	401: "UNAUTHORIZED",
+	403: "FORBIDDEN",
+	404: "NOT_FOUND",
+	405: "METHOD_NOT_ALLOWED",
+	409: "CONFLICT",
+	413: "PAYLOAD_TOO_LARGE",
+	415: "UNSUPPORTED_MEDIA_TYPE",
+	422: "VALIDATION_FAILED",
+	429: "RATE_LIMITED",
+	500: "INTERNAL_ERROR"
+};
+const API_ERROR = Symbol.for("@awsmbiz/inbis-api-client/ApiError");
+/** A failed call. `code` is stable and machine-readable; `message` is safe to show. */
+var ApiError = class ApiError extends Error {
+	/** HTTP status; `0` when no response arrived (`NETWORK_ERROR`). */
+	status;
+	code;
+	/** The server's request ID (app routes), for support and logs. */
+	requestId;
+	/** Extra caller-safe information from the server, e.g. `{ allowedMethods }` or validation issues. */
+	details;
+	[API_ERROR] = true;
+	constructor(options) {
+		super(options.message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "ApiError";
+		this.status = options.status;
+		this.code = options.code;
+		this.requestId = options.requestId ?? null;
+		this.details = options.details;
+	}
+	/** The server could not be reached. */
+	get isNetworkError() {
+		return this.code === API_ERROR_CODES.NETWORK_ERROR;
+	}
+	/**
+	* A stale-version conflict: someone else changed the resource since it was
+	* loaded (`409` with a `…VERSION_CONFLICT` code, e.g. `SETTINGS_VERSION_CONFLICT`).
+	* Reload and let the user reapply their change.
+	*/
+	get isVersionConflict() {
+		return this.status === 409 && this.code.endsWith("VERSION_CONFLICT");
+	}
+	/** What the session needs before retrying (`TWO_FACTOR_REQUIRED` / `STEP_UP_REQUIRED`), else `null`. */
+	get requirement() {
+		if (this.code === API_ERROR_CODES.TWO_FACTOR_REQUIRED) return { kind: "two-factor" };
+		if (this.code !== API_ERROR_CODES.STEP_UP_REQUIRED) return null;
+		const allowed = this.details?.allowedMethods;
+		return {
+			kind: "step-up",
+			allowedMethods: Array.isArray(allowed) ? allowed.filter((m) => typeof m === "string") : []
+		};
+	}
+	/** Reads a failed response's body (either error shape). Consumes the body. */
+	static async fromResponse(response) {
+		const body = await response.json().catch(() => null);
+		return ApiError.fromBody(response.status, body);
+	}
+	/** Builds the error from a status and a parsed body (either error shape, or anything else). */
+	static fromBody(status, body) {
+		const record = asRecord(body);
+		const fields = asRecord(record?.["error"]) ?? record;
+		const code = fields?.["code"];
+		const message = fields?.["message"];
+		const requestId = fields?.["requestId"];
+		return new ApiError({
+			status,
+			code: typeof code === "string" && code !== "" ? code : HTTP_CODES[status] ?? (status >= 500 ? "INTERNAL_ERROR" : "REQUEST_FAILED"),
+			message: typeof message === "string" && message !== "" ? message : "The request failed.",
+			requestId: typeof requestId === "string" ? requestId : null,
+			details: fields?.["details"]
+		});
+	}
+	/** No response arrived. */
+	static network(cause) {
+		return new ApiError({
+			status: 0,
+			code: API_ERROR_CODES.NETWORK_ERROR,
+			message: "Could not reach the server.",
+			cause
+		});
+	}
+};
+function asRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+/** True for any {@link ApiError}, including instances from another copy of this package. */
+function isApiError(value) {
+	return typeof value === "object" && value !== null && API_ERROR in value;
+}
+// src/api-client.ts
+/** Creates the typed client for the app's routes (see the README for generating `Paths`). */
+function createApiClient(options = {}) {
+	const client = createClient({
+		baseUrl: options.baseUrl ?? "",
+		credentials: "include",
+		...options.fetch === void 0 ? {} : { fetch: options.fetch },
+		...options.headers === void 0 ? {} : { headers: options.headers }
+	});
+	client.use({
+		onResponse: async ({ response }) => {
+			if (!response.ok) throw await ApiError.fromResponse(response.clone());
+		},
+		onError: ({ error }) => isApiError(error) ? error : ApiError.network(error)
+	});
+	return client;
+}
+// src/role-admin.ts
+/**
+* `@awsmbiz/inbis-access-control`'s role admin API (`mountRoleAdmin`, under
+* `/api/admin`): the permission catalogue, roles, and users' role
+* assignments. Errors use the `@awsmbiz/inbis-api` envelope; every call rejects with
+* an {@link ApiError}.
+*/
+const reviveRole = (role) => ({
+	...role,
+	createdAt: new Date(role.createdAt),
+	updatedAt: new Date(role.updatedAt)
+});
+const reviveUserRoles = (body) => ({ items: body.items.map((role) => ({
+	...role,
+	assignedAt: new Date(role.assignedAt)
+})) });
+/** The role admin calls under `adminBase` (origin + admin path, e.g. `https://app.test/api/admin`). */
+function createRoleAdminClient(adminBase, doFetch) {
+	const call = async (path, init = {}) => {
+		let response;
+		try {
+			response = await doFetch(`${adminBase}${path}`, {
+				method: init.method ?? "GET",
+				credentials: "include",
+				headers: init.body === void 0 ? { accept: "application/json" } : {
+					accept: "application/json",
+					"content-type": "application/json"
+				},
+				...init.body === void 0 ? {} : { body: JSON.stringify(init.body) },
+				...init.signal === void 0 ? {} : { signal: init.signal }
+			});
+		} catch (cause) {
+			throw ApiError.network(cause);
+		}
+		if (!response.ok) throw await ApiError.fromResponse(response);
+		return response;
+	};
+	const json = async (path, init) => await (await call(path, init)).json();
+	const role = (roleId) => `/roles/${encodeURIComponent(roleId)}`;
+	const userRole = (userId, roleId) => `/users/${encodeURIComponent(userId)}/roles/${encodeURIComponent(roleId)}`;
+	return {
+		permissions: { list: (init = {}) => json("/permissions", { signal: init.signal }) },
+		roles: {
+			list: async (init = {}) => ({ items: (await json("/roles", { signal: init.signal })).items.map(reviveRole) }),
+			get: async (roleId, init = {}) => reviveRole(await json(role(roleId), { signal: init.signal })),
+			create: async (input) => reviveRole(await json("/roles", {
+				method: "POST",
+				body: input
+			})),
+			update: async (roleId, changes) => reviveRole(await json(role(roleId), {
+				method: "PATCH",
+				body: changes
+			})),
+			delete: async (roleId) => {
+				await call(role(roleId), { method: "DELETE" });
+			}
+		},
+		userRoles: {
+			list: async (userId, init = {}) => reviveUserRoles(await json(`/users/${encodeURIComponent(userId)}/roles`, { signal: init.signal })),
+			assign: async (userId, roleId) => reviveUserRoles(await json(userRole(userId, roleId), { method: "PUT" })),
+			unassign: async (userId, roleId) => reviveUserRoles(await json(userRole(userId, roleId), { method: "DELETE" }))
+		}
+	};
+}
+// src/admin-routes.ts
+/**
+* The platform's admin app routes (Hono, under `/api/admin`): the dashboard
+* stats (`mountAuthStats` from `@awsmbiz/inbis-auth/hono`), the audit timeline
+* (`mountAuditTimeline` from `@awsmbiz/inbis-audit/hono`), and roles (`role-admin.ts`). Their errors use the
+* `@awsmbiz/inbis-api` envelope; all reject with an {@link ApiError}.
+*/
+const dateOrNull = (value) => value === null ? null : new Date(value);
+const reviveSummary = (user) => ({
+	...user,
+	banExpires: dateOrNull(user.banExpires),
+	createdAt: new Date(user.createdAt)
+});
+function searchOf(query) {
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) {
+		if (value === void 0) continue;
+		params.set(key, value instanceof Date ? value.toISOString() : String(value));
+	}
+	const search = params.toString();
+	return search === "" ? "" : `?${search}`;
+}
+function createAdminRoutesClient(options) {
+	const request = async (method, path, signal) => {
+		let response;
+		try {
+			response = await options.fetch(`${options.baseURL}${options.adminPath}${path}`, {
+				method,
+				credentials: "include",
+				headers: method === "POST" ? {
+					accept: "application/json",
+					"content-type": "application/json"
+				} : { accept: "application/json" },
+				...method === "POST" ? { body: "{}" } : {},
+				...signal === void 0 ? {} : { signal }
+			});
+		} catch (cause) {
+			throw ApiError.network(cause);
+		}
+		if (!response.ok) throw await ApiError.fromResponse(response);
+		return await response.json();
+	};
+	const get = (path, signal) => request("GET", path, signal);
+	return {
+		...createRoleAdminClient(`${options.baseURL}${options.adminPath}`, options.fetch),
+		stats: async (init = {}) => {
+			const body = await get("/auth-stats", init.signal);
+			return {
+				...body,
+				generatedAt: new Date(body.generatedAt)
+			};
+		},
+		auditEvents: { list: async (query = {}, init = {}) => {
+			const body = await get(`/audit-events${searchOf(query)}`, init.signal);
+			return {
+				items: body.items.map((item) => ({
+					...item,
+					occurredAt: new Date(item.occurredAt)
+				})),
+				nextCursor: body.nextCursor
+			};
+		} },
+		users: {
+			list: async (query = {}, init = {}) => {
+				const body = await get(`/users${searchOf(query)}`, init.signal);
+				return {
+					...body,
+					users: body.users.map(reviveSummary)
+				};
+			},
+			get: async (userId, init = {}) => {
+				const { user } = await get(`/users/${encodeURIComponent(userId)}`, init.signal);
+				return {
+					...reviveSummary(user),
+					signInMethods: user.signInMethods.map((method) => ({
+						...method,
+						createdAt: dateOrNull(method.createdAt)
+					})),
+					updatedAt: new Date(user.updatedAt)
+				};
+			},
+			resetTwoFactor: (userId) => request("POST", `/users/${encodeURIComponent(userId)}/two-factor/reset`)
+		}
+	};
+}
+// src/auth-settings.ts
+/**
+* `@awsmbiz/inbis-auth`'s runtime settings routes (`mountAuthSettings`): the wire
+* shapes and the calls. App routes, so errors use the platform envelope.
+*/
+/** The settings and provider-status calls under `adminBase` (origin + admin path, e.g. `https://app.test/api/admin`). */
+function authSettingsClients(adminBase, doFetch) {
+	const call = async (path, init = {}) => {
+		let response;
+		try {
+			response = await doFetch(`${adminBase}${path}`, {
+				...init,
+				credentials: "include"
+			});
+		} catch (cause) {
+			throw ApiError.network(cause);
+		}
+		if (!response.ok) throw await ApiError.fromResponse(response);
+		return await response.json();
+	};
+	return {
+		settings: {
+			get: () => call("/auth-settings"),
+			update: (input) => call("/auth-settings", {
+				method: "PATCH",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(input)
+			})
+		},
+		providers: { status: () => call("/auth-providers/status") }
+	};
+}
+// src/auth-admin-client.ts
+const DEFAULT_BASE_PATH = "/api/auth";
+function pageOrigin() {
+	return globalThis.location?.origin ?? "";
+}
+function betterAuthClient(options) {
+	const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+	return createAuthClient({
+		baseURL: `${options.baseURL ?? pageOrigin()}${options.basePath ?? DEFAULT_BASE_PATH}`,
+		plugins: [adminClient()],
+		fetchOptions: {
+			throw: true,
+			credentials: "include",
+			customFetchImpl: async (input, init) => {
+				try {
+					return await doFetch(input, init);
+				} catch (cause) {
+					throw ApiError.network(cause);
+				}
+			},
+			onError: ({ response, error }) => {
+				throw ApiError.fromBody(response.status, error);
+			}
+		}
+	});
+}
+/** Creates the client for auth admin endpoints. */
+function createAuthAdminClient(options = {}) {
+	const client = betterAuthClient(options);
+	const call = client.$fetch;
+	return {
+		...createAdminRoutesClient({
+			baseURL: options.baseURL ?? pageOrigin(),
+			adminPath: options.adminPath ?? "/api/admin",
+			fetch: options.fetch ?? ((input, init) => fetch(input, init))
+		}),
+		admin: client.admin,
+		userActions: {
+			create: (input) => call("/admin/create-user", {
+				method: "POST",
+				body: input
+			}),
+			revokeSession: (input) => call("/admin/revoke-user-session-by-id", {
+				method: "POST",
+				body: input
+			})
+		},
+		invitations: {
+			create: (input) => call("/admin/create-invitation", {
+				method: "POST",
+				body: input
+			}),
+			list: (input = {}) => call("/admin/list-invitations", {
+				method: "GET",
+				query: input
+			}),
+			resend: (input) => call("/admin/resend-invitation", {
+				method: "POST",
+				body: input
+			}),
+			revoke: (input) => call("/admin/revoke-invitation", {
+				method: "POST",
+				body: input
+			})
+		},
+		...authSettingsClients(`${options.baseURL ?? pageOrigin()}${options.adminPath ?? "/api/admin"}`, options.fetch ?? ((input, init) => fetch(input, init)))
+	};
+}
+// src/query.ts
+/** Invalidates every query whose key starts with one of `keys`. */
+async function invalidateQueries(queryClient, ...keys) {
+	await Promise.all(keys.map((queryKey) => queryClient.invalidateQueries({ queryKey })));
+}
+function apiQueryKey(path, params) {
+	return params === void 0 ? ["api", path] : [
+		"api",
+		path,
+		params
+	];
+}
+/** Invalidates every query of the given app-route paths (any params), or of all app routes when none is given. */
+function invalidateApi(queryClient, ...paths) {
+	return invalidateQueries(queryClient, ...paths.length === 0 ? [["api"]] : paths.map((path) => apiQueryKey(path)));
+}
+/**
+* Query options for a `GET` app route: keyed by path and `params` (see
+* {@link apiQueryKey}), failing with an `ApiError`:
+* `useQuery(apiQueryOptions(api, "/v1/notes/{id}", { params: { path: { id } } }))`.
+*/
+function apiQueryOptions(client, path, ...[init]) {
+	const params = init?.params;
+	const get = client.GET;
+	return {
+		queryKey: params === void 0 ? apiQueryKey(path) : apiQueryKey(path, params),
+		queryFn: async ({ signal }) => (await get(path, {
+			...init,
+			signal
+		})).data
+	};
+}
+/**
+* Query keys for auth admin data. Invalidate `users()` after any change to a
+* user (it covers lists, details and sessions), `invitations()` after any
+* invitation change, `stats()` after anything the dashboard counts, or `all`
+* for everything.
+*/
+const authAdminKeys = {
+	all: ["auth-admin"],
+	users: () => ["auth-admin", "users"],
+	userList: (query) => [
+		"auth-admin",
+		"users",
+		"list",
+		query
+	],
+	user: (userId) => [
+		"auth-admin",
+		"users",
+		"detail",
+		userId
+	],
+	userSessions: (userId) => [
+		"auth-admin",
+		"users",
+		"detail",
+		userId,
+		"sessions"
+	],
+	/** The admin directory (`users.list`: combined filters). */
+	userDirectory: (query) => [
+		"auth-admin",
+		"users",
+		"directory",
+		query
+	],
+	/** One user's profile, sign-in methods and 2FA status (`users.get`). */
+	userProfile: (userId) => [
+		"auth-admin",
+		"users",
+		"detail",
+		userId,
+		"profile"
+	],
+	invitations: () => ["auth-admin", "invitations"],
+	invitationList: (query) => [
+		"auth-admin",
+		"invitations",
+		"list",
+		query
+	],
+	settings: () => ["auth-admin", "settings"],
+	providerStatus: () => [
+		"auth-admin",
+		"providers",
+		"status"
+	],
+	stats: () => ["auth-admin", "stats"],
+	auditEvents: () => ["auth-admin", "audit-events"],
+	auditEventList: (query) => [
+		"auth-admin",
+		"audit-events",
+		"list",
+		query
+	],
+	/** The declared permission catalogue (`permissions.list`). */
+	permissions: () => ["auth-admin", "permissions"],
+	/** Every role query: invalidate after a role change or an assignment (it changes `userCount`). */
+	roles: () => ["auth-admin", "roles"],
+	roleList: () => [
+		"auth-admin",
+		"roles",
+		"list"
+	],
+	role: (roleId) => [
+		"auth-admin",
+		"roles",
+		"detail",
+		roleId
+	],
+	/** A user's assigned roles (`userRoles.list`); covered by `users()`. */
+	userRoles: (userId) => [
+		"auth-admin",
+		"users",
+		"detail",
+		userId,
+		"roles"
+	]
+};
+/** Query options for auth admin data, keyed by {@link authAdminKeys}. */
+function authAdminQueries(auth) {
+	return {
+		userList: (query) => ({
+			queryKey: authAdminKeys.userList(query),
+			queryFn: ({ signal }) => auth.admin.listUsers({
+				query,
+				fetchOptions: { signal }
+			})
+		}),
+		user: (userId) => ({
+			queryKey: authAdminKeys.user(userId),
+			queryFn: ({ signal }) => auth.admin.getUser({
+				query: { id: userId },
+				fetchOptions: { signal }
+			})
+		}),
+		userSessions: (userId) => ({
+			queryKey: authAdminKeys.userSessions(userId),
+			queryFn: ({ signal }) => auth.admin.listUserSessions({
+				userId,
+				fetchOptions: { signal }
+			})
+		}),
+		userDirectory: (query) => ({
+			queryKey: authAdminKeys.userDirectory(query),
+			queryFn: ({ signal }) => auth.users.list(query, { signal })
+		}),
+		userProfile: (userId) => ({
+			queryKey: authAdminKeys.userProfile(userId),
+			queryFn: ({ signal }) => auth.users.get(userId, { signal })
+		}),
+		invitationList: (query) => ({
+			queryKey: authAdminKeys.invitationList(query),
+			queryFn: () => auth.invitations.list(query)
+		}),
+		settings: () => ({
+			queryKey: authAdminKeys.settings(),
+			queryFn: () => auth.settings.get()
+		}),
+		providerStatus: () => ({
+			queryKey: authAdminKeys.providerStatus(),
+			queryFn: () => auth.providers.status()
+		}),
+		stats: () => ({
+			queryKey: authAdminKeys.stats(),
+			queryFn: ({ signal }) => auth.stats({ signal })
+		}),
+		auditEventList: (query) => ({
+			queryKey: authAdminKeys.auditEventList(query),
+			queryFn: ({ signal }) => auth.auditEvents.list(query, { signal })
+		})
+	};
+}
+export { API_ERROR_CODES, ApiError, apiQueryKey, apiQueryOptions, authAdminKeys, authAdminQueries, createApiClient, createAuthAdminClient, invalidateApi, invalidateQueries, isApiError };
+
+//# sourceMappingURL=index.js.map