@relazio/plugin-sdk 0.1.0 → 0.2.0

package/dist/utils/id-generator.js

@@ -0,0 +1,122 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateEntityId = generateEntityId;
+exports.generateEdgeId = generateEdgeId;
+exports.generateRandomId = generateRandomId;
+exports.normalizeValue = normalizeValue;
+exports.isValidEntityId = isValidEntityId;
+exports.isValidEdgeId = isValidEdgeId;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Genera un ID deterministico per un'entità
+ * Formato: {type}-{hash-short}
+ *
+ * @param type - Tipo di entità
+ * @param value - Valore dell'entità
+ * @returns ID univoco e deterministico
+ *
+ * @example
+ * ```ts
+ * generateEntityId('ip', '8.8.8.8')
+ * // => "ip-c909e98d"
+ *
+ * generateEntityId('location', 'Mountain View, CA')
+ * // => "location-a3f42bc1"
+ * ```
+ */
+function generateEntityId(type, value) {
+    const hash = crypto_1.default
+        .createHash('md5')
+        .update(value.toLowerCase().trim())
+        .digest('hex')
+        .substring(0, 8);
+    return `${type}-${hash}`;
+}
+/**
+ * Genera un ID deterministico per un edge
+ * Formato: edge-{hash-short}
+ *
+ * @param sourceId - ID dell'entità sorgente
+ * @param targetId - ID dell'entità target
+ * @param label - Label dell'edge (opzionale, per maggiore unicità)
+ * @returns ID univoco e deterministico
+ *
+ * @example
+ * ```ts
+ * generateEdgeId('ip-c909e98d', 'location-a3f42bc1')
+ * // => "edge-4f8a2d1c"
+ *
+ * generateEdgeId('ip-c909e98d', 'org-5b3c1a2d', 'assigned by')
+ * // => "edge-7e9b3f4a"
+ * ```
+ */
+function generateEdgeId(sourceId, targetId, label) {
+    const content = label
+        ? `${sourceId}-${targetId}-${label}`
+        : `${sourceId}-${targetId}`;
+    const hash = crypto_1.default
+        .createHash('md5')
+        .update(content.toLowerCase().trim())
+        .digest('hex')
+        .substring(0, 8);
+    return `edge-${hash}`;
+}
+/**
+ * Genera un ID casuale con prefisso
+ * Utile per entità temporanee o quando non serve deterministicità
+ *
+ * @param prefix - Prefisso per l'ID (es: 'note', 'temp')
+ * @returns ID univoco random
+ *
+ * @example
+ * ```ts
+ * generateRandomId('note')
+ * // => "note-1735123456789"
+ * ```
+ */
+function generateRandomId(prefix) {
+    return `${prefix}-${Date.now()}-${crypto_1.default.randomBytes(4).toString('hex')}`;
+}
+/**
+ * Normalizza un valore per la generazione di ID
+ * Rimuove spazi extra, converte a lowercase, rimuove caratteri speciali
+ *
+ * @param value - Valore da normalizzare
+ * @returns Valore normalizzato
+ *
+ * @example
+ * ```ts
+ * normalizeValue('  Mountain View, CA  ')
+ * // => "mountain-view-ca"
+ * ```
+ */
+function normalizeValue(value) {
+    return value
+        .toLowerCase()
+        .trim()
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9-]/g, '')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Valida un ID di entità
+ *
+ * @param id - ID da validare
+ * @returns true se l'ID è valido
+ */
+function isValidEntityId(id) {
+    return id.length > 0 && id.trim() === id;
+}
+/**
+ * Valida un ID di edge
+ *
+ * @param id - ID da validare
+ * @returns true se l'ID è valido
+ */
+function isValidEdgeId(id) {
+    return id.length > 0 && id.trim() === id;
+}

package/dist/utils/result-builder.d.ts

@@ -0,0 +1,109 @@
+import type { OSINTEntity, OSINTEdge, TransformResult, TransformInput } from '../core/types';
+/**
+ * Builder per costruire facilmente un TransformResult
+ * Gestisce automaticamente gli edge dall'entità di input alle nuove entità
+ *
+ * @example
+ * ```ts
+ * const result = new ResultBuilder(input)
+ *   .addEntity(createIP('8.8.8.8'), 'resolves to')
+ *   .addEntity(createLocation('Mountain View, CA'), 'located in')
+ *   .setMessage('Found IP information')
+ *   .build();
+ * ```
+ */
+export declare class ResultBuilder {
+    private entities;
+    private edges;
+    private message?;
+    private metadata?;
+    private inputEntityId;
+    constructor(input: TransformInput);
+    /**
+     * Aggiungi un'entità con edge automatico dall'input
+     *
+     * @param entity - Entità da aggiungere
+     * @param edgeLabel - Label dell'edge (opzionale)
+     * @param edgeOptions - Opzioni per l'edge
+     */
+    addEntity(entity: OSINTEntity, edgeLabel?: string, edgeOptions?: {
+        relationship?: string;
+        metadata?: Record<string, any>;
+    }): this;
+    /**
+     * Aggiungi multiple entità con lo stesso tipo di edge
+     *
+     * @param entities - Array di entità da aggiungere
+     * @param edgeLabel - Label dell'edge (opzionale)
+     * @param edgeOptions - Opzioni per l'edge
+     */
+    addEntities(entities: OSINTEntity[], edgeLabel?: string, edgeOptions?: {
+        relationship?: string;
+        metadata?: Record<string, any>;
+    }): this;
+    /**
+     * Aggiungi un'entità senza edge automatico
+     */
+    addEntityOnly(entity: OSINTEntity): this;
+    /**
+     * Aggiungi un edge manualmente
+     */
+    addEdge(edge: OSINTEdge): this;
+    /**
+     * Aggiungi multiple edges
+     */
+    addEdges(edges: OSINTEdge[]): this;
+    /**
+     * Imposta il messaggio di successo
+     */
+    setMessage(message: string): this;
+    /**
+     * Imposta metadata addizionali
+     */
+    setMetadata(metadata: Record<string, any>): this;
+    /**
+     * Aggiungi metadata
+     */
+    addMetadata(key: string, value: any): this;
+    /**
+     * Costruisci il risultato finale
+     */
+    build(): TransformResult;
+    /**
+     * Ottieni il numero di entità aggiunte
+     */
+    getEntityCount(): number;
+    /**
+     * Ottieni il numero di edge aggiunti
+     */
+    getEdgeCount(): number;
+    /**
+     * Verifica se ci sono risultati
+     */
+    hasResults(): boolean;
+}
+/**
+ * Helper veloce per creare un risultato vuoto (no results)
+ */
+export declare function emptyResult(message?: string): TransformResult;
+/**
+ * Helper veloce per creare un risultato di errore
+ */
+export declare function errorResult(error: string | Error): TransformResult;
+/**
+ * Helper per creare un risultato con una singola entità
+ */
+export declare function singleEntityResult(inputEntityId: string, entity: OSINTEntity, edgeLabel: string, options?: {
+    relationship?: string;
+    message?: string;
+    metadata?: Record<string, any>;
+}): TransformResult;
+/**
+ * Helper per creare un risultato con multiple entità dello stesso tipo
+ */
+export declare function multiEntityResult(inputEntityId: string, entities: OSINTEntity[], edgeLabel: string, options?: {
+    relationship?: string;
+    message?: string;
+    metadata?: Record<string, any>;
+}): TransformResult;
+//# sourceMappingURL=result-builder.d.ts.map

package/dist/utils/result-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-builder.d.ts","sourceRoot":"","sources":["../../src/utils/result-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG7F;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,CAAsB;IACvC,OAAO,CAAC,aAAa,CAAS;gBAElB,KAAK,EAAE,cAAc;IAIjC;;;;;;OAMG;IACH,SAAS,CACP,MAAM,EAAE,WAAW,EACnB,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE;QACZ,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAChC,GACA,IAAI;IAiBP;;;;;;OAMG;IACH,WAAW,CACT,QAAQ,EAAE,WAAW,EAAE,EACvB,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE;QACZ,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAChC,GACA,IAAI;IAOP;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAKxC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAK9B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI;IAKlC;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKjC;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAKhD;;OAEG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAQ1C;;OAEG;IACH,KAAK,IAAI,eAAe;IAUxB;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,UAAU,IAAI,OAAO;CAGtB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAO7D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,eAAe,CAOlE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IACR,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC,GACA,eAAe,CAYjB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,WAAW,EAAE,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;IACR,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC,GACA,eAAe,CAcjB"}

package/dist/utils/result-builder.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResultBuilder = void 0;
+exports.emptyResult = emptyResult;
+exports.errorResult = errorResult;
+exports.singleEntityResult = singleEntityResult;
+exports.multiEntityResult = multiEntityResult;
+const builders_1 = require("./builders");
+/**
+ * Builder per costruire facilmente un TransformResult
+ * Gestisce automaticamente gli edge dall'entità di input alle nuove entità
+ *
+ * @example
+ * ```ts
+ * const result = new ResultBuilder(input)
+ *   .addEntity(createIP('8.8.8.8'), 'resolves to')
+ *   .addEntity(createLocation('Mountain View, CA'), 'located in')
+ *   .setMessage('Found IP information')
+ *   .build();
+ * ```
+ */
+class ResultBuilder {
+    constructor(input) {
+        this.entities = [];
+        this.edges = [];
+        this.inputEntityId = input.entity.id;
+    }
+    /**
+     * Aggiungi un'entità con edge automatico dall'input
+     *
+     * @param entity - Entità da aggiungere
+     * @param edgeLabel - Label dell'edge (opzionale)
+     * @param edgeOptions - Opzioni per l'edge
+     */
+    addEntity(entity, edgeLabel, edgeOptions) {
+        this.entities.push(entity);
+        // Se viene specificata una label, crea automaticamente l'edge
+        if (edgeLabel) {
+            const edge = (0, builders_1.createEdge)(this.inputEntityId, entity.id, edgeLabel, edgeOptions);
+            this.edges.push(edge);
+        }
+        return this;
+    }
+    /**
+     * Aggiungi multiple entità con lo stesso tipo di edge
+     *
+     * @param entities - Array di entità da aggiungere
+     * @param edgeLabel - Label dell'edge (opzionale)
+     * @param edgeOptions - Opzioni per l'edge
+     */
+    addEntities(entities, edgeLabel, edgeOptions) {
+        for (const entity of entities) {
+            this.addEntity(entity, edgeLabel, edgeOptions);
+        }
+        return this;
+    }
+    /**
+     * Aggiungi un'entità senza edge automatico
+     */
+    addEntityOnly(entity) {
+        this.entities.push(entity);
+        return this;
+    }
+    /**
+     * Aggiungi un edge manualmente
+     */
+    addEdge(edge) {
+        this.edges.push(edge);
+        return this;
+    }
+    /**
+     * Aggiungi multiple edges
+     */
+    addEdges(edges) {
+        this.edges.push(...edges);
+        return this;
+    }
+    /**
+     * Imposta il messaggio di successo
+     */
+    setMessage(message) {
+        this.message = message;
+        return this;
+    }
+    /**
+     * Imposta metadata addizionali
+     */
+    setMetadata(metadata) {
+        this.metadata = metadata;
+        return this;
+    }
+    /**
+     * Aggiungi metadata
+     */
+    addMetadata(key, value) {
+        if (!this.metadata) {
+            this.metadata = {};
+        }
+        this.metadata[key] = value;
+        return this;
+    }
+    /**
+     * Costruisci il risultato finale
+     */
+    build() {
+        return {
+            success: true,
+            entities: this.entities,
+            edges: this.edges,
+            ...(this.message && { message: this.message }),
+            ...(this.metadata && { metadata: this.metadata }),
+        };
+    }
+    /**
+     * Ottieni il numero di entità aggiunte
+     */
+    getEntityCount() {
+        return this.entities.length;
+    }
+    /**
+     * Ottieni il numero di edge aggiunti
+     */
+    getEdgeCount() {
+        return this.edges.length;
+    }
+    /**
+     * Verifica se ci sono risultati
+     */
+    hasResults() {
+        return this.entities.length > 0;
+    }
+}
+exports.ResultBuilder = ResultBuilder;
+/**
+ * Helper veloce per creare un risultato vuoto (no results)
+ */
+function emptyResult(message) {
+    return {
+        success: true,
+        entities: [],
+        edges: [],
+        ...(message && { message }),
+    };
+}
+/**
+ * Helper veloce per creare un risultato di errore
+ */
+function errorResult(error) {
+    return {
+        success: false,
+        entities: [],
+        edges: [],
+        message: error instanceof Error ? error.message : error,
+    };
+}
+/**
+ * Helper per creare un risultato con una singola entità
+ */
+function singleEntityResult(inputEntityId, entity, edgeLabel, options) {
+    const edge = (0, builders_1.createEdge)(inputEntityId, entity.id, edgeLabel, {
+        relationship: options?.relationship,
+    });
+    return {
+        success: true,
+        entities: [entity],
+        edges: [edge],
+        ...(options?.message && { message: options.message }),
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+/**
+ * Helper per creare un risultato con multiple entità dello stesso tipo
+ */
+function multiEntityResult(inputEntityId, entities, edgeLabel, options) {
+    const edges = entities.map(entity => (0, builders_1.createEdge)(inputEntityId, entity.id, edgeLabel, {
+        relationship: options?.relationship,
+    }));
+    return {
+        success: true,
+        entities,
+        edges,
+        ...(options?.message && { message: options.message }),
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}