@sailfish-ai/sf-veritas 0.1.0

package/dist/types/baseTransmitter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * BaseTransmitter is the base class responsible for transmitting GraphQL requests.
+ * It is used to send requests to a GraphQL endpoint, including default parameters
+ * like API key, service UUID, and session ID. It provides functionality for
+ * setting the operation name, endpoint, and additional variables.
+ */
+export declare class BaseTransmitter {
+    /** The API key used for authentication. */
+    protected apiKey: string;
+    /** The GraphQL endpoint to which requests are sent. */
+    protected endpoint: string;
+    /** The type of GraphQL query (default is 'mutation'). */
+    protected queryType: string;
+    /** The operation name for the GraphQL query. */
+    protected operationName: string;
+    /** The UUID of the service from the configuration. */
+    protected serviceUUID: string;
+    private contextManager;
+    /**
+     * Constructor to initialize the `BaseTransmitter` with the provided API key.
+     * If no API key is provided, the one from the configuration will be used.
+     *
+     * @param apiKey - The API key to authenticate with (optional, defaults to config value).
+     */
+    constructor();
+    /**
+     * Getter for the query name used in GraphQL requests.
+     * The operation name is converted to camel case (first letter lowercased).
+     *
+     * @returns The formatted query name based on the operation name.
+     */
+    protected get queryName(): string;
+    /**
+     * Generates default variables to be included in GraphQL queries.
+     * These variables include the API key, service UUID, session ID, and timestamp.
+     *
+     * @returns An object containing the default variables for the request.
+     */
+    protected getDefaultVariables(): {
+        apiKey: string;
+        serviceUuid: string;
+        sessionId: string;
+        timestampMs: string;
+    };
+    /**
+     * Merges the default variables with any additional variables passed as arguments.
+     * Optionally, a session ID can be provided to override the default one.
+     *
+     * @param additionalVariables - Additional variables to include in the request.
+     * @returns A merged object containing all variables for the GraphQL query.
+     */
+    protected getVariables(additionalVariables?: Record<string, any>): Record<string, any>;
+    /**
+     * Sets the operation name for the GraphQL query.
+     *
+     * @param name - The name of the operation to set.
+     */
+    setOperationName(name: string): void;
+    /**
+     * Sets the GraphQL endpoint to use for the requests.
+     *
+     * @param endpoint - The endpoint URL to set.
+     */
+    setEndpoint(endpoint: string): void;
+    /**
+     * Sets the service UUID to be used in the GraphQL request.
+     *
+     * @param serviceUUID - The service UUID to set.
+     */
+    setServiceUUID(serviceUUID: string): void;
+}

package/dist/types/collectMetadataTransmitter.d.ts

@@ -0,0 +1,35 @@
+import { Traits } from "./utils";
+/**
+ * Main transmitter class for managing metadata collection and user identification.
+ * This class coordinates the metadata transmission and handles user identification.
+ */
+export declare class SailfishTransmitter {
+    private apiKey;
+    private metadataTransmitter;
+    /**
+     * Creates an instance of SailfishTransmitter.
+     *
+     * @param apiKey - The API key to authenticate requests.
+     */
+    constructor(apiKey: string);
+    /**
+     * Identifies a user and either adds or updates metadata for them.
+     * If neither traits nor traitsJson is provided, empty metadata is sent.
+     *
+     * @param userId - Unique identifier for the user, typically a username or email.
+     * @param traits - Optional dictionary of traits to add or update.
+     * @param traitsJson - Optional JSON string of traits to add or update.
+     * @param override - Optional flag to override existing traits.
+     */
+    identify(userId: string, traits?: Traits, traitsJson?: string, override?: boolean): void;
+    /**
+     * Adds or updates metadata for a user.
+     * Sends the provided traits or traitsJson to update user information.
+     *
+     * @param userId - Unique identifier for the user, typically a username or email.
+     * @param traits - Optional dictionary of traits to add or update.
+     * @param traitsJson - Optional JSON string of traits to add or update.
+     * @param override - Optional flag to override existing traits.
+     */
+    addOrUpdateMetadata(userId: string, traits?: Traits, traitsJson?: string, override?: boolean): void;
+}

package/dist/types/contextManager.d.ts

@@ -0,0 +1,28 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export declare const context: AsyncLocalStorage<Map<string, any>>;
+type Context = {
+    traceId?: string;
+    handledExceptions: Set<any>;
+    reentrancyGuardLoggingActive: boolean;
+    reentrancyGuardLoggingPreActive: boolean;
+    reentrancyGuardPrintActive: boolean;
+    reentrancyGuardPrintPreActive: boolean;
+    reentrancyGuardExceptionActive: boolean;
+    reentrancyGuardExceptionPreActive: boolean;
+};
+export declare class ContextManager {
+    private static instance;
+    private constructor();
+    static getInstance(): ContextManager;
+    getCurrentContext(): Context;
+    private setCurrentContext;
+    getTraceId(): string | undefined;
+    setTraceId(traceId: string): void;
+    getOrSetSfTraceId(newTraceIdIfNotSet?: string, isAssociatedWithInboundRequest?: boolean): string;
+    getHandledExceptions(): Set<any>;
+    markExceptionHandled(exception: any): void;
+    hasHandledException(exception: any): boolean;
+    resetHandledExceptions(): void;
+}
+export declare function runWithContext(fn: Function): void;
+export {};

package/dist/types/dataTransmitter.d.ts

@@ -0,0 +1,39 @@
+import { BaseTransmitter } from "./baseTransmitter";
+/**
+ * DataTransmitter class extends BaseTransmitter to handle sending data,
+ * including sending app identifiers and specific contents to a designated endpoint.
+ */
+export declare class DataTransmitter extends BaseTransmitter {
+    private serviceIdentifier;
+    /**
+     * Constructor for DataTransmitter.
+     */
+    constructor();
+    /**
+     * Checks if the contents should be ignored. Override this function to define specific logic for ignoring content.
+     * @param contents - The contents to check.
+     * @returns boolean - Whether the contents should be ignored.
+     */
+    protected checkIfContentsShouldBeIgnored(contents: any): boolean;
+    /**
+     * Sends the application identifier by invoking the serviceIdentifier.
+     * This function ensures the app identifier is sent before any other data.
+     */
+    sendAppIdentifier(): Promise<void>;
+    /**
+     * Main method to send data.
+     * This first sends the application identifier and then sends the actual content.
+     * @param args - The arguments to be sent, including contents and level.
+     */
+    doSend(args: any): Promise<void>;
+    /**
+     * Sends the contents to the server endpoint. It checks the contents type and prepares the request.
+     * @param contents - The content to be sent, which can be a string or an array of strings.
+     */
+    send(contents: string | string[]): Promise<void>;
+    /**
+     * Constructs the GraphQL query string based on operation details.
+     * @returns string - The formatted query string with required parameters.
+     */
+    private getQuery;
+}

package/dist/types/domainsToNotPassHeaderToTransmitter.d.ts

@@ -0,0 +1,22 @@
+import { DataTransmitter } from "./dataTransmitter";
+/**
+ * DomainsToNotPassHeaderToTransmitter class extends DataTransmitter to handle sending domains data
+ * that should not pass the header to the server endpoint.
+ */
+export declare class DomainsToNotPassHeaderToTransmitter extends DataTransmitter {
+    /**
+     * Constructor for DomainsToNotPassHeaderToTransmitter.
+     * Sets the operation name to 'DomainsToNotPassHeaderTo' upon instantiation.
+     */
+    constructor();
+    /**
+     * Main method to send data. This method sends the app identifier and then calls the send method to send the domains.
+     * @param args - Arguments passed for sending, typically includes domains.
+     */
+    doSend(args: any): Promise<void>;
+    /**
+     * Sends a list of domains that should not pass the header to the server.
+     * @param domains - An array of domain strings that need to be sent to the server.
+     */
+    send(domains: string[]): Promise<void>;
+}

package/dist/types/exceptionHandler.d.ts

@@ -0,0 +1,2 @@
+import { ExceptionTransmitter } from "./exceptionTransmitter";
+export declare function initializeExceptionInterceptor(transmitter: ExceptionTransmitter): void;

package/dist/types/exceptionTransmitter.d.ts

@@ -0,0 +1,44 @@
+import { BaseTransmitter } from "./baseTransmitter";
+import { FrameInfo } from "./types";
+/**
+ * The ExceptionTransmitter class handles the process of sending exception data
+ * (message and stack trace) to a designated endpoint, specifically for collecting
+ * exceptions. It inherits from the BaseTransmitter class and is responsible for
+ * encoding the exception trace, constructing the request, and sending it to the
+ * server.
+ */
+export declare class ExceptionTransmitter extends BaseTransmitter {
+    private serviceIdentifier;
+    /**
+     * Constructor for ExceptionTransmitter. It initializes the operation name
+     * and inherits from BaseTransmitter.
+     */
+    constructor();
+    /**
+     * Sends the application identifier to the server to associate the exception
+     * data with the application.
+     */
+    sendAppIdentifier(): Promise<void>;
+    /**
+     * Primary method to send exception data. It triggers the process of sending
+     * the application identifier and exception details (message and stack trace).
+     *
+     * @param contents The exception message.
+     * @param trace An array of FrameInfo objects representing the stack trace.
+     */
+    doSend(contents: string, trace: FrameInfo[]): Promise<void>;
+    /**
+     * Sends the exception data (message, trace, session ID) to the server using
+     * a non-blocking post request. The exception trace is first encoded as a JSON string.
+     *
+     * @param exceptionMessage The exception message to report.
+     * @param trace An array of FrameInfo objects that describe the stack trace.
+     */
+    send(exceptionMessage: string, trace: FrameInfo[]): Promise<void>;
+    /**
+     * Generates the GraphQL mutation query for reporting the exception.
+     *
+     * @returns The GraphQL mutation query string.
+     */
+    protected getQuery(): string;
+}

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export { addOrUpdateMetadata, identify, setupInterceptors, } from "./unifiedInterceptor";

package/dist/types/logHandler.d.ts

@@ -0,0 +1,2 @@
+import { DataTransmitter } from "./dataTransmitter";
+export declare function initializeLogInterceptor(transmitter: DataTransmitter): void;

package/dist/types/requestTransmitter.d.ts

@@ -0,0 +1,13 @@
+export declare class RequestInterceptor {
+    private headerNameTracing;
+    private domainsToNotPropagateHeadersTo;
+    private contextManager;
+    private domainCache;
+    constructor();
+    private extractDomain;
+    private domainMatchesExclusionList;
+    addHeaders(headers: Record<string, string>, url: string): void;
+    getDomainsToNotPropagateHeadersTo(customDomains?: string[]): void;
+}
+export declare function patchHttp(domainsToNotPropagateHeadersTo?: string[]): void;
+export declare function patchRequests(domainsToNotPropagateHeadersTo?: string[]): void;

package/dist/types/requestUtils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Sends a non-blocking POST request to a GraphQL endpoint.
+ * The request is sent asynchronously, and any response errors or issues are logged.
+ *
+ * @param {string} url - The URL of the GraphQL endpoint.
+ * @param {string} operationName - The name of the GraphQL operation being invoked.
+ * @param {string} query - The GraphQL query string.
+ * @param {Record<string, any>} variables - The variables to be sent with the GraphQL query.
+ * @returns {Promise<void>} Resolves when the request has been handled.
+ */
+export declare function nonBlockingPost(url: string, operationName: string, query: string, variables: Record<string, any>): Promise<void>;

package/dist/types/serviceIdentifier.d.ts

@@ -0,0 +1,27 @@
+import { BaseTransmitter } from "./baseTransmitter";
+/**
+ * ServiceIdentifier is responsible for identifying the service details.
+ * It sends a request to a GraphQL endpoint to identify the service and logs the response.
+ */
+export declare class ServiceIdentifier extends BaseTransmitter {
+    /**
+     * Constructor for the ServiceIdentifier class.
+     * Initializes the operation name and calls the parent constructor.
+     */
+    constructor();
+    /**
+     * Main method for sending the identification request.
+     * It checks if the service identification has already been received and attempts to send it.
+     *
+     * @param {any} args - Arguments for the request (not used in this method).
+     * @returns {Promise<void>} - Resolves when the identification process is complete.
+     */
+    doSend(args: any): Promise<void>;
+    /**
+     * Constructs and sends the GraphQL query to identify the service.
+     * This function sends the request asynchronously and processes the response.
+     *
+     * @returns {Promise<void>} - Resolves when the send operation is complete.
+     */
+    private send;
+}

package/dist/types/setupConfig.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Interface for setting up options for the service configuration.
+ */
+export interface SetupOptions {
+    apiKey?: string;
+    /**
+     * Optional identifier for api key
+     */
+    apiGraphqlEndpoint?: string;
+    /**
+     * Optional identifier for debug
+     */
+    debug?: boolean;
+    /**
+     * Optional identifier for the service.
+     */
+    serviceIdentifier?: string;
+    /**
+     * Optional version of the service.
+     */
+    serviceVersion?: string;
+    /**
+     * Optional the depth of exception locals.
+     */
+    stackDepthLocals?: string;
+    /**
+     * Optional additional metadata for the service. It can contain key-value pairs
+     * where values can be strings, numbers, null, or undefined.
+     * Defaults to `undefined`.
+     */
+    serviceAdditionalMetadata?: Record<string, string | number | null | undefined>;
+    /**
+     * Profiling mode argument to enable or disable profiling.
+     * Defaults to `false`.
+     */
+    profilingModeEnabled?: boolean;
+    /**
+     * Maximum depth for profiling.
+     * Defaults to `5`.
+     */
+    profilingMaxDepth?: number;
+    /**
+     * Maximum variable size in KB for profiling.
+     * Defaults to `25`.
+     */
+    profilingMaxVariableSizeKb?: number;
+    /**
+     * Optional list of domains for which headers should not be propagated.
+     */
+    domainsToNotPropagateHeadersTo?: string[];
+    /**
+     * Optional list of site and distribution packages for which local variables should be collected.
+     */
+    siteAndDistPackagesToCollectLocalVariablesOn?: string[];
+}
+declare class AppConfig {
+    apiKey: string;
+    apiGraphqlEndpoint: string;
+    sfDebug: boolean;
+    serviceIdentifier: string;
+    serviceVersion: string;
+    serviceUUID: string;
+    serviceAdditionalMetadata: Record<string, string | number | null | undefined>;
+    profilingModeEnabled: boolean;
+    profilingMaxDepth: number;
+    profilingMaxVariableSizeKb: number;
+    domainsToNotPropagateHeadersTo: string[];
+    siteAndDistPackagesToCollectLocalVariablesOn: string[];
+    printConfigurationStatuses: string;
+    logLevel: string;
+    stackDepthLocals: number;
+    stackDepthCodeTraceDepth: number;
+    packageLibraryType: string;
+    version: string;
+    private _serviceIdentificationReceived;
+    constructor(options: SetupOptions);
+    private getPackageVersion;
+    get serviceIdentificationReceived(): boolean;
+    setServiceIdentificationReceived(value: boolean): void;
+}
+/**
+ * Initializes the global configuration with the provided SetupOptions.
+ * This should be called once at the start of the application.
+ */
+export declare function initializeConfig(options: SetupOptions): void;
+/**
+ * Retrieves the global configuration instance.
+ * Ensures the configuration is initialized before accessing.
+ */
+export declare function getConfig(): AppConfig;
+export {};

package/dist/types/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Interface representing frame information data used to initialize a `FrameInfo` instance.
+ */
+export interface FrameInfoData {
+    file: string;
+    line: number;
+    function: string;
+    code: string;
+    locals?: {
+        [key: string]: any;
+    };
+    offender?: boolean;
+}
+/**
+ * Class representing detailed information about a specific frame in a code trace.
+ */
+export declare class FrameInfo {
+    file: string;
+    line: number;
+    function: string;
+    code: string;
+    locals: {
+        [key: string]: any;
+    };
+    offender: boolean;
+    /**
+     * Initializes a new instance of the `FrameInfo` class with provided frame data.
+     *
+     * @param file - The file where the frame is located.
+     * @param line - The line number of the frame.
+     * @param function - The function name associated with the frame.
+     * @param code - The code snippet for this frame.
+     * @param locals - The local variables within the frame scope (optional).
+     * @param offender - Indicates if this frame is considered an "offender" (optional).
+     */
+    constructor({ file, line, function: func, code, locals, offender, }: FrameInfoData);
+    /**
+     * Converts the `FrameInfo` instance to a dictionary format, serializing local variables as strings.
+     *
+     * @returns An object representing the frame, with locals as serialized strings.
+     */
+    toDict(): {
+        [key: string]: any;
+    };
+    /**
+     * Converts the `FrameInfo` instance to a JSON string representation.
+     *
+     * @returns A JSON string representing the frame information.
+     */
+    toJson(): string;
+}
+/**
+ * A custom encoder for serializing `FrameInfo` objects to JSON, handling nested structures.
+ */
+export declare class CustomJSONEncoderForFrameInfo {
+    /**
+     * Encodes an object or array, recursively handling `FrameInfo` objects and nested structures.
+     *
+     * @param obj - The object to encode.
+     * @returns The encoded object with `FrameInfo` instances converted to dictionaries.
+     */
+    static encode(obj: any): any;
+    /**
+     * Converts an object to a JSON string, using a custom encoding process for `FrameInfo` instances.
+     *
+     * @param obj - The object to stringify.
+     * @returns A JSON string representation of the object.
+     */
+    static stringify(obj: any): string;
+}

package/dist/types/unifiedInterceptor.d.ts

@@ -0,0 +1,35 @@
+import { SetupOptions } from "./setupConfig";
+import { Traits } from "./utils";
+/**
+ * Main function to initialize all interceptors and configure data transmission.
+ *
+ * Initializes configuration settings for the application, checks for required
+ * configuration variables, and sets up log, exception, and metadata interceptors.
+ */
+export declare function setupInterceptors(options?: SetupOptions): void;
+/**
+ * Identifies a user and optionally updates their metadata.
+ *
+ * Uses `SailfishTransmitter` to either add or update the user's metadata in the
+ * configured service endpoint.
+ *
+ * @param {string} userId - Unique identifier for the user, typically a username or email.
+ * @param {Traits} [traits] - Optional dictionary of user traits to add or update.
+ * @param {string} [traitsJson] - Optional JSON string containing user traits.
+ * @param {boolean} [override=false] - Whether to override existing traits. Defaults to false.
+ */
+export declare function identify(userId: string, traits?: Traits, traitsJson?: string, override?: boolean): void;
+/**
+ * Adds or updates metadata for a user.
+ *
+ * Uses `SailfishTransmitter` to add or update a user's metadata at the configured
+ * service endpoint. If both `traits` and `traitsJson` are provided, the function
+ * will prioritize `traits`.
+ *
+ * @param {string} userId - Unique identifier for the user, typically a username or email.
+ * @param {Traits} [traits={}] - Optional dictionary of user traits to add or update.
+ *                                Defaults to an empty object.
+ * @param {string} [traitsJson] - Optional JSON string of user traits to add or update.
+ * @param {boolean} [override=false] - Whether to override existing traits. Defaults to false.
+ */
+export declare function addOrUpdateMetadata(userId: string, traits?: Traits, traitsJson?: string, override?: boolean): void;

package/dist/types/updateServiceIdentifierTransmitter.d.ts

@@ -0,0 +1,6 @@
+import { DataTransmitter } from "./dataTransmitter";
+export declare class UpdateServiceIdentifierTransmitter extends DataTransmitter {
+    constructor();
+    doSend(): Promise<void>;
+    send(): Promise<void>;
+}

package/dist/types/utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Interface representing a set of key-value pairs where keys are strings
+ * and values can be of any type.
+ */
+export interface Traits {
+    [key: string]: any;
+}
+/**
+ * Serializes an object to a JSON string, excluding non-serializable fields.
+ *
+ * @param inputObj - The input object to be serialized.
+ * @returns An object containing:
+ *          - `traitsJson`: A JSON string of the serializable fields.
+ *          - `excludedFields`: An array of keys for fields that were not serializable.
+ */
+export declare function serializeJsonWithExclusions(inputObj: Record<string, any> | null): {
+    traitsJson: string;
+    excludedFields: string[];
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@sailfish-ai/sf-veritas",
+  "version": "0.1.0",
+  "publishPublicly": true,
+  "main": "dist/sf-veritas.cjs",
+  "types": "dist/types/index.d.ts",
+  "scripts": {
+    "dev": "vite-node src/index.ts",
+    "build": "vite build && tsc --emitDeclarationOnly && npm run copy-worker",
+    "test": "vite-node --config vite.config.ts",
+    "check-types": "tsc --noEmit",
+    "prepublish": "npm run check-types && npm run build",
+    "copy-worker": "cp src/debuggerWorker.js dist/debuggerWorker.js",
+    "artifactregistry-login": "npx google-artifactregistry-auth",
+    "publish-local": "npm publish --registry http://localhost:4873 --//localhost:4873/:_authToken=none"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/sf-veritas.mjs",
+      "require": "./dist/sf-veritas.cjs",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "cross-fetch": "^4.0.0",
+    "run": "^1.5.0",
+    "tldts": "^6.1.61",
+    "url": "^0.11.4",
+    "util": "^0.12.5",
+    "uuid": "^10.0.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^28.0.1",
+    "@rollup/plugin-node-resolve": "^15.3.0",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@types/uuid": "^10.0.0",
+    "@urql/core": "^5.0.8",
+    "rollup-plugin-dts": "^6.1.1",
+    "rollup-plugin-polyfill-node": "^0.13.0",
+    "rollup-plugin-visualizer": "^5.12.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.11",
+    "vite-node": "^0.28.0",
+    "vite-plugin-compression": "^0.5.1",
+    "vite-tsconfig-paths": "^5.1.2",
+    "vitest": "^2.1.5"
+  }
+}