@privateaim/telemetry-kit 0.8.16

package/src/domains/event/entity.ts

@@ -0,0 +1,85 @@
+/*
+ * Copyright (c) 2025.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+// todo: add service, trace ?
+
+import type { Realm } from '@authup/core-kit';
+import type { ObjectDiff } from '@privateaim/kit';
+
+export type EventData = {
+    diff?: ObjectDiff,
+    [key: string]: any
+};
+
+export interface Event {
+    id: string;
+
+    /**
+     * domaine
+     *
+     * eg. analysis, node, analysisNode, ....
+     */
+    ref_type: string;
+
+    /**
+     * eg. uuid
+     */
+    ref_id: string | null;
+
+    /**
+     * component, prozess,
+     *
+     * eg. build, push, modelChanges, ...
+     */
+    scope: string;
+
+    /**
+     * eg. started, starting, finished, ...
+     */
+    name: string;
+
+    /**
+     *
+     * { diff: { description: { next: "xxx", previous: "yyy" }, name {}}}
+     */
+    data: Record<string, any>;
+
+    /**
+     * default: false
+     */
+    expiring: boolean;
+
+    // ------------------------------------------------------------------
+
+    request_path: string | null;
+
+    request_method: string | null;
+
+    request_ip_address: string | null;
+
+    request_user_agent: string | null;
+
+    // ------------------------------------------------------------------
+
+    actor_type: string | null;
+
+    actor_id: string | null;
+
+    actor_name: string | null;
+
+    // ------------------------------------------------------------------
+
+    realm_id: Realm['id'] | null;
+
+    // ------------------------------------------------------------------
+
+    expires_at: string | null;
+
+    created_at: string;
+
+    updated_at: string;
+}

package/src/domains/event/index.ts

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) 2025.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+export * from './api';
+export * from './entity';
+export * from './validator';

package/src/domains/event/validator.ts

@@ -0,0 +1,148 @@
+/*
+ * Copyright (c) 2025.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+import { createValidator } from '@validup/adapter-zod';
+import { Container } from 'validup';
+import zod from 'zod';
+import type { Event } from './entity';
+
+export class EventValidator extends Container<Event> {
+    protected initialize() {
+        super.initialize();
+
+        this.mount(
+            'ref_type',
+            createValidator(
+                zod
+                    .string()
+                    .min(3)
+                    .max(128),
+            ),
+        );
+
+        this.mount(
+            'ref_id',
+            { optional: true },
+            createValidator(
+                zod
+                    .uuidv4()
+                    .nullable(),
+            ),
+        );
+
+        // ----------------------------------------------
+
+        this.mount(
+            'scope',
+            createValidator(
+                zod
+                    .string()
+                    .min(3)
+                    .max(128),
+            ),
+        );
+
+        this.mount(
+            'name',
+            createValidator(
+                zod
+                    .string()
+                    .min(3)
+                    .max(128),
+            ),
+        );
+
+        // ----------------------------------------------
+
+        this.mount(
+            'data',
+            { optional: true },
+            createValidator(
+                zod
+                    .record(zod.string(), zod.any())
+                    .nullable(),
+            ),
+        );
+
+        // ----------------------------------------------
+
+        this.mount(
+            'expiring',
+            { optional: true },
+            createValidator(
+                zod
+                    .boolean()
+                    .nullable(),
+            ),
+        );
+
+        // ----------------------------------------------
+
+        this.mount(
+            'request_path',
+            { optional: true },
+            createValidator(zod.string().min(3).max(256).nullable()),
+        );
+
+        this.mount(
+            'request_method',
+            { optional: true },
+            createValidator(zod.string().min(3).max(10).nullable()),
+        );
+
+        this.mount(
+            'request_ip_address',
+            { optional: true },
+            createValidator(zod.ipv4().nullable()),
+        );
+
+        this.mount(
+            'request_user_agent',
+            { optional: true },
+            createValidator(zod.string().min(3).max(512).nullable()),
+        );
+
+        // ----------------------------------------------
+
+        this.mount(
+            'actor_type',
+            { optional: true },
+            createValidator(zod.string().min(3).max(64).nullable()),
+        );
+
+        this.mount(
+            'actor_id',
+            { optional: true },
+            createValidator(zod.uuidv4().nullable()),
+        );
+
+        this.mount(
+            'actor_name',
+            { optional: true },
+            createValidator(zod.string().min(3).max(64).nullable()),
+        );
+
+        // ----------------------------------------------
+
+        this.mount(
+            'realm_id',
+            { optional: true },
+            createValidator(zod.uuidv4().nullable()),
+        );
+
+        // ----------------------------------------------
+
+        this.mount(
+            'expires_at',
+            { optional: true },
+            createValidator(
+                zod.iso.datetime()
+                    .nullable(),
+            ),
+        );
+    }
+}

package/src/domains/index.ts

@@ -0,0 +1,12 @@
+/*
+ * Copyright (c) 2024.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+export * from './event';
+export * from './log';
+
+export * from './constants';
+export * from './types';

package/src/domains/log/api.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2021-2024.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+import type { BuildInput } from 'rapiq';
+import { buildQuery } from 'rapiq';
+import type { Log, LogInput } from './entity';
+import type { CollectionResourceResponse, SingleResourceResponse } from '../types-base';
+import { BaseAPI } from '../base';
+
+export class LogAPI extends BaseAPI {
+    async getMany(options?: BuildInput<Log>): Promise<CollectionResourceResponse<Log>> {
+        const { data: response } = await this.client.get(`logs${buildQuery(options)}`);
+        return response;
+    }
+
+    async deleteMany(options?: BuildInput<Log>): Promise<void> {
+        await this.client.delete(`logs${buildQuery(options)}`);
+    }
+
+    async create(data: Partial<LogInput>): Promise<SingleResourceResponse<Log>> {
+        const { data: response } = await this.client.post('logs', data);
+
+        return response;
+    }
+}

package/src/domains/log/constants.ts

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2025.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+export enum LogLevel {
+    /**
+     *  indicates that the system is unusable
+     *  and requires immediate attention
+     */
+    EMERGENCE = 'emerg',
+
+    /**
+     * indicates that immediate action is necessary
+     * to resolve a critical issue.
+     */
+    ALERT = 'alert',
+
+    /**
+     * signifies critical conditions in the program that demand
+     * intervention to prevent system failure.
+     */
+    CRITICAL = 'crit',
+
+    /**
+     * indicates error conditions that impair
+     * some operation but are less severe than critical situations.
+     */
+    ERROR = 'error',
+
+    /**
+     * signifies potential issues that may lead to errors
+     * or unexpected behavior in the future if not addressed.
+     */
+    WARNING = 'warn',
+
+    /**
+     *  applies to normal but significant
+     *  conditions that may require monitoring
+     */
+    NOTICE = 'notice',
+
+    /**
+     * includes messages that provide a record
+     * of the normal operation of the system.
+     */
+    INFORMATIONAL = 'info',
+
+    /**
+     * intended for logging detailed information about the system
+     * for debugging purposes.
+     */
+    DEBUG = 'debug',
+}
+
+export enum LogLevelColor {
+    EMERGENCE = '#8B0000',
+    ALERT = '#FF0000',
+    CRITICAL = '#FF4500',
+    ERROR = '#FF6347',
+    WARNING = '#FFD700',
+    NOTICE = '#1E90FF',
+    INFORMATIONAL = '#228B22',
+    DEBUG = '#A9A9A9',
+}
+
+export enum LogFlag {
+    CHANNEL = 'channel',
+
+    COMPONENT = 'component',
+
+    SERVICE = 'service',
+
+    LEVEL = 'level',
+}
+
+export enum LogChannel {
+    HTTP = 'http',
+    WEBSOCKET = 'websocket',
+    BACKGROUND = 'background',
+    SYSTEM = 'system',
+}

package/src/domains/log/entity.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2025.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+import type { LogChannel, LogLevel } from './constants';
+
+export interface Log {
+    /**
+     * Time in micro seconds
+     */
+    time: string | bigint,
+
+    /**
+     *  message
+     */
+    message: string,
+
+    /**
+     * level
+     */
+    level: `${LogLevel}`,
+
+    /**
+     * service
+     */
+    service: string,
+
+    /**
+     * channel
+     */
+    channel: `${LogChannel}`,
+
+    /**
+     * additional labels
+     */
+    labels: Record<string, string>
+}
+
+type RequiredTypes = ('message' | 'level' | 'service' | 'channel');
+
+export type LogInput = Pick<Log, RequiredTypes & keyof Log> & Partial<Omit<Log, RequiredTypes & keyof Log>>;

package/src/domains/log/helpers.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2025.
+ *  Author Peter Placzek (tada5hi)
+ *  For the full copyright and license information,
+ *  view the LICENSE file that was distributed with this source code.
+ */
+
+import { nanoSeconds } from '@privateaim/kit';
+import type { Log, LogInput } from './entity';
+
+export function normalizeLogInput(input: LogInput) : Log {
+    return {
+        ...input,
+        time: input.time || nanoSeconds(),
+        labels: input.labels || {},
+    };
+}

package/src/domains/log/index.ts

@@ -0,0 +1,12 @@
+/*
+ * Copyright (c) 2025.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+export * from './api';
+export * from './constants';
+export * from './entity';
+export * from './helpers';
+export * from './validator';

package/src/domains/log/validator.ts

@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) 2025.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+import { createValidator } from '@validup/adapter-zod';
+import { Container } from 'validup';
+import zod from 'zod';
+import { LogChannel, LogLevel } from './constants';
+import type { LogInput } from './entity';
+
+export class LogValidator extends Container<LogInput> {
+    protected initialize() {
+        super.initialize();
+
+        this.mount(
+            'time',
+            { optional: true },
+            createValidator(
+                zod
+                    .string()
+                    .min(0)
+                    .max(20)
+                    .or(zod.bigint())
+                    .optional(),
+            ),
+        );
+
+        this.mount(
+            'message',
+            createValidator(
+                zod
+                    .string()
+                    .min(3)
+                    .max(512),
+            ),
+        );
+
+        this.mount(
+            'service',
+            createValidator(
+                zod
+                    .string()
+                    .min(3)
+                    .max(64),
+            ),
+        );
+
+        // ----------------------------------------------
+
+        this.mount(
+            'level',
+            createValidator(
+                zod
+                    .enum(Object.values(LogLevel)),
+            ),
+        );
+
+        this.mount(
+            'channel',
+            createValidator(
+                zod
+                    .enum(Object.values(LogChannel)),
+            ),
+        );
+
+        this.mount(
+            'labels',
+            { optional: true },
+            createValidator(
+                zod
+                    .record(zod.string(), zod.string())
+                    .nullable(),
+            ),
+        );
+    }
+}

package/src/domains/types-base.ts

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2024.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+import type { Client, RequestBaseOptions } from 'hapic';
+
+export type SingleResourceResponse<R> = R;
+export type CollectionResourceResponse<R> = {
+    data: R[],
+    meta: {
+        limit: number,
+        offset: number,
+        total: number
+    }
+};
+
+export type BaseAPIContext = {
+    client?: Client | RequestBaseOptions
+};

package/src/domains/types.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) 2023-2024.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+import type { DomainType } from './constants';
+import type { Event } from './event';
+import type { Log } from './log';
+
+type DomainTypeMapRaw = {
+    [DomainType.EVENT]: Event,
+    [DomainType.LOG]: Log,
+};
+
+export type DomainTypeMap = {
+    [K in keyof DomainTypeMapRaw as `${K}`]: DomainTypeMapRaw[K]
+};

package/src/http/api-client/index.ts

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2022-2024.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+export * from './module';

package/src/http/api-client/module.ts

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2022-2024.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+import type { RequestBaseOptions } from 'hapic';
+import { Client, HookName, isClientError } from 'hapic';
+import {
+    EventAPI,
+    LogAPI,
+} from '../../domains';
+
+export class APIClient extends Client {
+    public readonly event : EventAPI;
+
+    public readonly log : LogAPI;
+
+    constructor(config: RequestBaseOptions) {
+        super(config);
+
+        this.event = new EventAPI({ client: this });
+        this.log = new LogAPI({ client: this });
+
+        this.on(HookName.RESPONSE_ERROR, ((error) => {
+            if (
+                isClientError(error) &&
+                error.response &&
+                error.response.data &&
+                typeof error.response.data.message === 'string'
+            ) {
+                error.message = error.response.data.message;
+            }
+
+            throw error;
+        }));
+    }
+}

package/src/http/index.ts

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2024.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+export * from './api-client';

package/src/index.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2024.
+ * Author Peter Placzek (tada5hi)
+ * For the full copyright and license information,
+ * view the LICENSE file that was distributed with this source code.
+ */
+
+export * from './http';
+export * from './domains';

package/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+    "extends": "../../tsconfig.build.json",
+
+    "compilerOptions": {
+        "outDir": "./dist"
+    },
+
+    "include": [
+        "src/**/*.ts"
+    ]
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "paths": {
+            "@privateaim/kit": ["./packages/kit/src"]
+        }
+    }
+}