app-devtools 0.31.0 → 1.0.1

package/dist/main.d.ts

@@ -1,11 +1,20 @@
+/** opens the devtools panel, does nothing if it is already open */
+declare function openDevTools(): void;
+/** closes the devtools panel, does nothing if it is not open */
+declare function closeDevTools(): void;
+declare function toggleDevTools(): void;
+declare function devToolsIsOpen(): boolean;
+
 type RequestSubTypes = 'delete' | 'update' | 'create' | 'custom' | 'send' | 'receive';
 type RequestTypes = 'ws' | 'fetch' | 'mutation';
+type RequestStatus = 'pending' | 'success' | 'error';
 type ApiRequest = {
     id: string;
     alias?: string;
     payload: unknown;
     response: unknown;
     metadata: unknown;
+    status: RequestStatus;
     isError: boolean;
     path: string;
     searchParams: Record<string, string> | null;
@@ -17,7 +26,36 @@ type ApiRequest = {
     pathParams: Record<string, string | null> | null;
     code: number | undefined;
     tags: string[];
+    /**
+     * request headers, shown in the request details with values replaced by
+     * type descriptions (unless allowed by the `visibleRequestHeaders`
+     * config), full values are only used to generate the copy as cURL command
+     */
+    headers: Record<string, string> | undefined;
+    /**
+     * warnings attached to the request, e.g. deprecated endpoint usage or
+     * slow responses, highlighted in the ui like errors are
+     */
+    warnings: RequestWarning[] | undefined;
+    /**
+     * response fields that were not used by the app, an optimization
+     * opportunity shown in the stats tab
+     */
+    unusedResponseData: string[] | undefined;
+    /**
+     * approximate stored size (json string length of payload/response/metadata
+     * plus a fixed overhead), used by the size-based eviction budget
+     */
+    approxSize: number;
+};
+declare function addMarker(label?: string, time?: number): void;
+declare function clearHistory(): void;
+type RequestWarning = {
+    message: string;
+    /** optional structured data attached to the warning */
+    details?: unknown;
 };
+type RequestWarningInput = string | RequestWarning | null | undefined;
 type Config = {
     callsProcessor: {
         match: ((request: {
@@ -35,6 +73,25 @@ type Config = {
         }) => string;
         payloadAlias?: (payload: any, request: ApiRequest) => string;
     }[];
+    /**
+     * request header values are masked in the ui by default (replaced by type
+     * descriptions) as they may contain sensitive data, headers listed here
+     * (case-insensitive) show their raw values
+     */
+    visibleRequestHeaders: string[];
+    /**
+     * payload fields with these names (at any nesting level) have their values
+     * masked in the ui (replaced by type descriptions), matching is
+     * case-insensitive and ignores `_` and `-` (e.g. `apiKey` also matches
+     * `api_key`)
+     */
+    sensitiveDataFields: string[];
+    /**
+     * approximate max stored size (in MB, based on json string length) for
+     * requests across all call groups, oldest requests are evicted first to
+     * avoid memory issues in long-running sessions
+     */
+    maxRequestsSizeMb: number;
 };
 type RegisterCallResult = (props: {
     isError: boolean;
@@ -42,6 +99,17 @@ type RegisterCallResult = (props: {
     response: unknown;
     metadata?: unknown;
     tags?: (string | null | undefined)[] | undefined;
+    /**
+     * warnings attached to the request, e.g. deprecated endpoint usage or
+     * slow responses, highlighted in the ui like errors are
+     */
+    warnings?: RequestWarningInput[] | undefined;
+    /**
+     * response fields (e.g. object paths like `user.settings`) that were not
+     * used by the app, e.g. fields not declared in the response schema, shown
+     * in the stats tab as an optimization opportunity
+     */
+    unusedResponseData?: (string | null | undefined)[] | undefined;
 }) => void;
 declare function addWebsocketEvent({ type, response, payload, event, startTime, }: {
     type: 'send' | 'receive';
@@ -59,12 +127,136 @@ declare function addCall(request: {
     startTime?: number;
     duration?: number;
     tags?: (string | null | undefined)[];
+    warnings?: RequestWarningInput[];
+    /**
+     * request headers, shown in the request details with values replaced by
+     * type descriptions (unless allowed by the `visibleRequestHeaders`
+     * config), full values are only used to generate the copy as cURL command
+     */
+    headers?: Record<string, string | null | undefined>;
 }): RegisterCallResult;
 
-declare function initializeDevTools({ callsProcessor, shortcut, }: {
+type RequestCallerResult = {
+    response: unknown;
+    status?: number;
+    isError?: boolean;
+};
+type RequestCallerSelectOption = string | {
+    value: string;
+    label: string;
+};
+/**
+ * An input rendered in the caller form. `json` inputs are validated and
+ * parsed, `string` and `select` values are passed as plain strings.
+ */
+type RequestCallerInput = {
+    type: 'json';
+    name: string;
+    label?: string;
+    placeholder?: string;
+} | {
+    type: 'string';
+    name: string;
+    label?: string;
+    placeholder?: string;
+} | {
+    type: 'select';
+    name: string;
+    label?: string;
+    options: RequestCallerSelectOption[];
+};
+/**
+ * A request caller configured by the lib consumer. It should abstract all
+ * app-specific details (auth, base url, headers, etc), receiving only the
+ * request path, method and payload.
+ */
+type RequestCaller = {
+    /** name shown in the caller selector */
+    name: string;
+    /** methods available in the UI, defaults to GET, POST, PUT, PATCH and DELETE */
+    methods?: string[];
+    /**
+     * inputs shown in the form, defaults to a single json input named
+     * `payload`, whose parsed value is passed directly as the call `payload`.
+     * With custom inputs, `payload` is a record with the value of each input
+     * keyed by its name (json input values are parsed, empty ones are omitted).
+     */
+    inputs?: RequestCallerInput[];
+    /**
+     * maps a request opened from the network history into the form input
+     * values, keyed by input name. Defaults to putting the request payload
+     * JSON into the `payload` input, which matches the default inputs config.
+     * Configure it when using custom `inputs` that don't fit that mapping.
+     */
+    mapRequestToInputs?: (request: {
+        path: string;
+        method: string;
+        payload: unknown;
+    }) => Record<string, string>;
+    call: (request: {
+        path: string;
+        method: string;
+        payload: unknown;
+    }) => Promise<RequestCallerResult>;
+};
+
+declare function initializeDevTools({ callsProcessor, shortcut, requestCallers, visibleRequestHeaders, sensitiveDataFields, maxRequestsSizeMb, maxLogsSizeMb, }: {
     callsProcessor?: Config['callsProcessor'];
     /** use $mod for CMD or Ctrl */
     shortcut: string;
+    /**
+     * callers used by the request caller tab to perform requests using the
+     * consumer app data fetching mechanisms
+     */
+    requestCallers?: RequestCaller[];
+    /**
+     * request header values are masked in the ui by default (replaced by type
+     * descriptions) as they may contain sensitive data, headers listed here
+     * (case-insensitive) show their raw values
+     */
+    visibleRequestHeaders?: string[];
+    /**
+     * payload fields with these names (at any nesting level) have their values
+     * masked in the ui (replaced by type descriptions), matching is
+     * case-insensitive and ignores `_` and `-`, overrides the default list
+     * (token, password, secret, apiKey, etc)
+     */
+    sensitiveDataFields?: string[];
+    /**
+     * approximate max stored size (in MB, based on json string length) for
+     * requests across all call groups, oldest requests are evicted first to
+     * avoid memory issues in long-running sessions (default: 30)
+     */
+    maxRequestsSizeMb?: number;
+    /**
+     * approximate max stored size (in MB, based on json string length) for
+     * logs, oldest logs are evicted first to avoid memory issues in
+     * long-running sessions (default: 10)
+     */
+    maxLogsSizeMb?: number;
+}): void;
+
+type LogSeverity = 'error' | 'warning' | 'info';
+type DevtoolsLog = {
+    id: string;
+    severity: LogSeverity;
+    message: string;
+    category: string | undefined;
+    details: unknown;
+    time: number;
+    /**
+     * approximate stored size (json string length of message/details plus a
+     * fixed overhead), used by the size-based eviction budget
+     */
+    approxSize: number;
+};
+declare function addLog(log: {
+    message: string;
+    severity?: LogSeverity;
+    category?: string;
+    details?: unknown;
+    time?: number;
 }): void;
+declare function clearLogs(): void;
 
-export { RegisterCallResult, addCall, addWebsocketEvent, initializeDevTools };
+export { type DevtoolsLog, type LogSeverity, type RegisterCallResult, type RequestCaller, type RequestCallerInput, type RequestCallerSelectOption, type RequestWarning, type RequestWarningInput, addCall, addLog, addMarker, addWebsocketEvent, clearHistory, clearLogs, closeDevTools, devToolsIsOpen, initializeDevTools, openDevTools, toggleDevTools };