@juice-js/audit 0.0.0-stage → 1.0.0-alpha.2

package/types/juice-js-audit.d.ts

@@ -0,0 +1,216 @@
+import * as i0 from "@angular/core";
+import { EnvironmentProviders, InjectionToken, PipeTransform } from "@angular/core";
+import { Observable } from "rxjs";
+import { Params, Routes } from "@angular/router";
+import { Menus } from "@juice-js/core";
+/** How the host app mounts Juice Audit. */
+export interface AuditOptions {
+  /** The origin of the API that maps MapJuiceAudit(); empty when it serves the app (same origin). */
+  apiBase: string;
+  /** Where MapJuiceAudit() mapped the API on that origin (its `prefix`). */
+  apiPath: string;
+  /** Where the host mounts {@link AUDIT_ROUTES}: `/` for the whole app, or a path such as `/audit`. */
+  basePath: string;
+  /**
+   * A link to a trace in a tracing UI, shown beside the trace id of each record: for the Juice Observability pages
+   * mounted at `/observability`, `id => ['/observability/traces', id]`. A string is an external URL. Without it, no link.
+   */
+  traceLink?: ((traceId: string) => unknown[] | string | null) | null;
+}
+export declare const AUDIT_OPTIONS: InjectionToken<AuditOptions>;
+/** Configures the pages: where the API is, where the host mounted the routes, and where a trace opens. */
+export declare function provideJuiceAudit(options?: Partial<AuditOptions>): EnvironmentProviders;
+/** `/audit/` → `/audit`; `` and `/` → `/`. */
+export declare function normalizeBasePath(basePath: string): string;
+/** Router links to the pages, under the host's mount path. */
+export declare class AuditLinks {
+  private readonly options;
+  readonly base: string;
+  /** `to('access-logs', id)` → `['/audit', 'access-logs', id]`. */
+  to(...segments: unknown[]): unknown[];
+  /** The host's link to a trace in its tracing UI, if it gave one. */
+  externalTrace(traceId: string | null | undefined): {
+    route: unknown[];
+  } | {
+    href: string;
+  } | null;
+  static ɵfac: i0.ɵɵFactoryDeclaration<AuditLinks, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/** `['access-logs', id] | jaLink`: the same as {@link AuditLinks.to} in a template. */
+export declare class AuditLinkPipe implements PipeTransform {
+  private readonly links;
+  transform(segments: unknown[]): unknown[];
+  static ɵfac: i0.ɵɵFactoryDeclaration<AuditLinkPipe, never>;
+  static ɵpipe: i0.ɵɵPipeDeclaration<AuditLinkPipe, "jaLink", true>;
+}
+/** The audit API's shapes (Juice.Audit.Api, MapJuiceAudit()). Times are ISO 8601. */
+export interface AuditPage<T> {
+  items: T[];
+  nextCursor?: string | null;
+}
+/** One audited HTTP request, message, mediator request or notification. */
+export interface AccessLogSummary {
+  id: string;
+  dateTime: string;
+  user: string | null;
+  tenantId: string | null;
+  action: string;
+  /** The HTTP method, or MESSAGE, REQUEST or NOTIFICATION for work outside a request. */
+  method: string | null;
+  path: string | null;
+  status: number | null;
+  elapsedMs: number | null;
+  app: string | null;
+  traceId: string | null;
+  isRestricted: boolean;
+}
+export interface AccessLogDetail {
+  id: string;
+  dateTime: string;
+  user: string | null;
+  tenantId: string | null;
+  action: string;
+  traceId: string | null;
+  isRestricted: boolean;
+  metadata: Record<string, string | null>;
+  request: {
+    method: string | null;
+    scheme: string | null;
+    host: string | null;
+    path: string | null;
+    query: string | null;
+    headers: string | null;
+    data: string | null;
+    remoteIp: string | null;
+    zone: string | null;
+  } | null;
+  response: {
+    status: number | null;
+    elapsedMs: number | null;
+    message: string | null;
+    error: string | null;
+    headers: string | null;
+    data: string | null;
+  } | null;
+  server: {
+    app: string | null;
+    appVersion: string | null;
+    machine: string | null;
+    os: string | null;
+  } | null;
+  /** Data changes recorded under the same trace id. */
+  dataChanges: number;
+}
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/** A row change: inserted, modified or deleted, with its keys. */
+export interface DataChangeSummary {
+  id: string;
+  dateTime: string;
+  user: string | null;
+  tenantId: string | null;
+  action: string;
+  database: string | null;
+  schema: string | null;
+  table: string;
+  keys: JsonValue;
+  traceId: string | null;
+}
+export interface DataChangeDetail extends DataChangeSummary {
+  /** `{ OriginalValues: {…}, CurrentValues: {…} }`, as the audited app reported them. */
+  changes: JsonValue;
+}
+export interface AuditTrace {
+  traceId: string;
+  accessLogs: AccessLogDetail[];
+  dataChanges: DataChangeDetail[];
+  /** More records share the trace than the API returns. */
+  truncated: boolean;
+}
+export interface AuditCount {
+  name: string;
+  count: number;
+  errors: number;
+}
+export interface AuditOverview {
+  from: string;
+  to: string;
+  requests: number;
+  clientErrors: number;
+  serverErrors: number;
+  restricted: number;
+  dataChanges: number;
+  statuses: AuditCount[];
+  apps: AuditCount[];
+  users: AuditCount[];
+  tables: AuditCount[];
+  changeActions: AuditCount[];
+  recentErrors: AccessLogSummary[];
+  slowest: AccessLogSummary[];
+}
+/** An access record's list row, from its detail (the trace endpoint returns details). */
+export declare function accessLogSummary(d: AccessLogDetail): AccessLogSummary;
+export type AuditQuery = Record<string, string | number | boolean | null | undefined>;
+/**
+ * The audit API that Juice.Audit.Api maps with MapJuiceAudit(). It is scoped to the caller's tenant on the server, and
+ * the host's bearer-token interceptor authenticates the calls.
+ */
+export declare class AuditApiService {
+  private readonly http;
+  private readonly base;
+  private get;
+  /** Access records, newest first; pass the previous page's `nextCursor` as `cursor` for the next. */
+  accessLogs(query: AuditQuery): Observable<AuditPage<AccessLogSummary>>;
+  accessLog(id: string): Observable<AccessLogDetail>;
+  /** Data changes, newest first, paged like {@link accessLogs}. */
+  dataChanges(query: AuditQuery): Observable<AuditPage<DataChangeSummary>>;
+  dataChange(id: string): Observable<DataChangeDetail>;
+  trace(traceId: string): Observable<AuditTrace>;
+  overview(query: AuditQuery): Observable<AuditOverview>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<AuditApiService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+export declare const AUDIT_RANGES: Record<string, number>;
+/**
+ * The time window that follows the user between the audit pages. It lives in the URL (`range`, or `from` and `to`), so
+ * every page is a deep link and the back button restores it.
+ */
+export declare class AuditContextService {
+  private readonly router;
+  private readonly params;
+  readonly range: import("@angular/core").Signal<string>;
+  readonly absolute: import("@angular/core").Signal<{
+    from: string;
+    to: string;
+  } | null>;
+  /** The window as ISO strings, evaluated now for a relative range. */
+  window(): {
+    from: string;
+    to: string;
+  };
+  /** Query parameters for a link: the window plus the target page's own. */
+  keep(extra?: Params): Params;
+  /** Changes the window on the current page, keeping its other parameters. */
+  set(change: {
+    range?: string | null;
+    from?: string | null;
+    to?: string | null;
+  }): void;
+  /** Sets the current page's own query parameters (its filters), keeping the window. */
+  filter(change: Params): void;
+  private leaf;
+  static ɵfac: i0.ɵɵFactoryDeclaration<AuditContextService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * The audit pages. Detail pages are deep links and carry the time window in their query parameters. The host mounts
+ * them at its `basePath` (see {@link provideJuiceAudit}) and adds its own guards.
+ */
+export declare const AUDIT_ROUTES: Routes;
+/**
+ * The side menu entries (juice-layout), linking under `basePath`. Their ids start with `audit-`, so they sit beside
+ * another package's menus (such as @juice-js/observability's) in one MenuModule.
+ */
+export declare function auditMenus(basePath?: string, order?: number): Menus;