@relazio/plugin-sdk 0.1.0 → 0.2.0

package/dist/index.js

@@ -4,7 +4,7 @@
  * SDK ufficiale per creare plugin esterni per Relazio
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExpressServer = exports.MemoryStorage = exports.InstallationRegistry = exports.InMemorySecretProvider = exports.JobQueue = exports.JobProgressTracker = exports.verifyWebhookSignature = exports.HMACUtils = exports.ManifestGenerator = exports.OSINTPlugin = exports.RelazioPlugin = void 0;
+exports.multiEntityResult = exports.singleEntityResult = exports.errorResult = exports.emptyResult = exports.ResultBuilder = exports.isValidEdgeId = exports.isValidEntityId = exports.normalizeValue = exports.generateRandomId = exports.generateEdgeId = exports.generateEntityId = exports.validateTransformResult = exports.validateEdges = exports.validateEntities = exports.EdgeBuilder = exports.EntityBuilder = exports.createEdge = exports.createEntity = exports.ExpressServer = exports.MemoryStorage = exports.InstallationRegistry = exports.InMemorySecretProvider = exports.JobQueue = exports.JobProgressTracker = exports.verifyWebhookSignature = exports.HMACUtils = exports.ManifestGenerator = exports.OSINTPlugin = exports.RelazioPlugin = void 0;
 // Core exports
 var plugin_1 = require("./core/plugin");
 Object.defineProperty(exports, "RelazioPlugin", { enumerable: true, get: function () { return plugin_1.RelazioPlugin; } });
@@ -27,3 +27,29 @@ Object.defineProperty(exports, "MemoryStorage", { enumerable: true, get: functio
 // Server
 var express_1 = require("./server/express");
 Object.defineProperty(exports, "ExpressServer", { enumerable: true, get: function () { return express_1.ExpressServer; } });
+// Utils - Entity & Edge Builders
+var builders_1 = require("./utils/builders");
+// Core builders (scalabili e dinamici)
+Object.defineProperty(exports, "createEntity", { enumerable: true, get: function () { return builders_1.createEntity; } });
+Object.defineProperty(exports, "createEdge", { enumerable: true, get: function () { return builders_1.createEdge; } });
+Object.defineProperty(exports, "EntityBuilder", { enumerable: true, get: function () { return builders_1.EntityBuilder; } });
+Object.defineProperty(exports, "EdgeBuilder", { enumerable: true, get: function () { return builders_1.EdgeBuilder; } });
+// Validazione
+Object.defineProperty(exports, "validateEntities", { enumerable: true, get: function () { return builders_1.validateEntities; } });
+Object.defineProperty(exports, "validateEdges", { enumerable: true, get: function () { return builders_1.validateEdges; } });
+Object.defineProperty(exports, "validateTransformResult", { enumerable: true, get: function () { return builders_1.validateTransformResult; } });
+// Utils - ID Generation
+var id_generator_1 = require("./utils/id-generator");
+Object.defineProperty(exports, "generateEntityId", { enumerable: true, get: function () { return id_generator_1.generateEntityId; } });
+Object.defineProperty(exports, "generateEdgeId", { enumerable: true, get: function () { return id_generator_1.generateEdgeId; } });
+Object.defineProperty(exports, "generateRandomId", { enumerable: true, get: function () { return id_generator_1.generateRandomId; } });
+Object.defineProperty(exports, "normalizeValue", { enumerable: true, get: function () { return id_generator_1.normalizeValue; } });
+Object.defineProperty(exports, "isValidEntityId", { enumerable: true, get: function () { return id_generator_1.isValidEntityId; } });
+Object.defineProperty(exports, "isValidEdgeId", { enumerable: true, get: function () { return id_generator_1.isValidEdgeId; } });
+// Utils - Result Builder
+var result_builder_1 = require("./utils/result-builder");
+Object.defineProperty(exports, "ResultBuilder", { enumerable: true, get: function () { return result_builder_1.ResultBuilder; } });
+Object.defineProperty(exports, "emptyResult", { enumerable: true, get: function () { return result_builder_1.emptyResult; } });
+Object.defineProperty(exports, "errorResult", { enumerable: true, get: function () { return result_builder_1.errorResult; } });
+Object.defineProperty(exports, "singleEntityResult", { enumerable: true, get: function () { return result_builder_1.singleEntityResult; } });
+Object.defineProperty(exports, "multiEntityResult", { enumerable: true, get: function () { return result_builder_1.multiEntityResult; } });

package/dist/utils/builders.d.ts

@@ -0,0 +1,147 @@
+import type { OSINTEntity, OSINTEdge, EntityType } from '../core/types';
+/**
+ * Crea un'entità OSINT nel formato corretto
+ * Genera automaticamente un ID deterministico se non specificato
+ *
+ * @param type - Tipo di entità
+ * @param value - Valore dell'entità (obbligatorio)
+ * @param options - Opzioni aggiuntive (label, metadata, id)
+ * @returns Entità nel formato corretto
+ *
+ * @example
+ * ```ts
+ * // Esempio semplice
+ * createEntity('ip', '8.8.8.8')
+ *
+ * // Con label e metadata
+ * createEntity('ip', '8.8.8.8', {
+ *   label: 'Google DNS',
+ *   metadata: { country: 'US', isp: 'Google LLC' }
+ * })
+ *
+ * // Con ID personalizzato
+ * createEntity('location', 'Mountain View, CA', {
+ *   id: 'custom-location-id',
+ *   metadata: { latitude: 37.386, longitude: -122.084 }
+ * })
+ * ```
+ */
+export declare function createEntity(type: EntityType, value: string, options?: {
+    id?: string;
+    label?: string;
+    metadata?: Record<string, any>;
+}): OSINTEntity;
+/**
+ * Crea un edge tra due entità nel formato corretto
+ * Genera automaticamente un ID deterministico se non specificato
+ *
+ * @param sourceId - ID dell'entità sorgente
+ * @param targetId - ID dell'entità target
+ * @param label - Label visibile dell'edge (obbligatorio)
+ * @param options - Opzioni aggiuntive (id, relationship, metadata)
+ * @returns Edge nel formato corretto
+ *
+ * @example
+ * ```ts
+ * // Esempio semplice
+ * createEdge('ip-c909e98d', 'location-a3f42bc1', 'located in')
+ *
+ * // Con relationship e metadata
+ * createEdge('ip-c909e98d', 'org-5b3c1a2d', 'assigned by', {
+ *   relationship: 'isp_assignment',
+ *   metadata: { confidence: 0.98 }
+ * })
+ *
+ * // Con ID personalizzato
+ * createEdge('node-1', 'node-2', 'related to', {
+ *   id: 'custom-edge-id'
+ * })
+ * ```
+ */
+export declare function createEdge(sourceId: string, targetId: string, label: string, options?: {
+    id?: string;
+    relationship?: string;
+    metadata?: Record<string, any>;
+}): OSINTEdge;
+/**
+ * NOTA: Gli helper specifici sono stati rimossi per rendere l'SDK più scalabile.
+ * Usa `createEntity(type, value, options)` per creare qualsiasi tipo di entità.
+ *
+ * Esempio:
+ * ```ts
+ * createEntity('ip', '8.8.8.8', { metadata: { country: 'US' } })
+ * createEntity('domain', 'example.com')
+ * createEntity('custom-type', 'value')  // Funziona anche con tipi futuri!
+ * ```
+ */
+/**
+ * Builder fluente per creare entità complesse
+ *
+ * @example
+ * ```ts
+ * const entity = EntityBuilder
+ *   .create('ip', '8.8.8.8')
+ *   .withLabel('Google DNS')
+ *   .withMetadata({ country: 'US', isp: 'Google LLC' })
+ *   .build();
+ * ```
+ */
+export declare class EntityBuilder {
+    private entity;
+    private constructor();
+    static create(type: EntityType, value: string): EntityBuilder;
+    withId(id: string): this;
+    withLabel(label: string): this;
+    withMetadata(metadata: Record<string, any>): this;
+    addMetadata(key: string, value: any): this;
+    build(): OSINTEntity;
+}
+/**
+ * Builder fluente per creare edge complessi
+ *
+ * @example
+ * ```ts
+ * const edge = EdgeBuilder
+ *   .create('ip-abc', 'location-xyz', 'located in')
+ *   .withRelationship('geolocation')
+ *   .withMetadata({ confidence: 0.98 })
+ *   .build();
+ * ```
+ */
+export declare class EdgeBuilder {
+    private edge;
+    private constructor();
+    static create(sourceId: string, targetId: string, label: string): EdgeBuilder;
+    withId(id: string): this;
+    withRelationship(relationship: string): this;
+    withMetadata(metadata: Record<string, any>): this;
+    addMetadata(key: string, value: any): this;
+    build(): OSINTEdge;
+}
+/**
+ * Helper per validare un array di entità
+ * Controlla ID duplicati e campi obbligatori
+ */
+export declare function validateEntities(entities: OSINTEntity[]): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Helper per validare un array di edge
+ * Controlla ID duplicati, campi obbligatori e riferimenti validi
+ */
+export declare function validateEdges(edges: OSINTEdge[], entities: OSINTEntity[], inputEntityId?: string): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Helper per validare una risposta completa di transform
+ */
+export declare function validateTransformResult(result: {
+    entities: OSINTEntity[];
+    edges: OSINTEdge[];
+}, inputEntityId?: string): {
+    valid: boolean;
+    errors: string[];
+};
+//# sourceMappingURL=builders.d.ts.map

package/dist/utils/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/utils/builders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGxE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IACR,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC,GACA,WAAW,CAYb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IACR,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC,GACA,SAAS,CAmBX;AAED;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAuB;IAErC,OAAO;IAOP,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa;IAI7D,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKxB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK9B,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAKjD,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAQ1C,KAAK,IAAI,WAAW;CAkBrB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAAqB;IAEjC,OAAO;IAQP,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW;IAI7E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKxB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAK5C,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAKjD,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAQ1C,KAAK,IAAI,SAAS;CA0BnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CA6B9F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,EAAE,WAAW,EAAE,EACvB,aAAa,CAAC,EAAE,MAAM,GACrB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CA8CtC;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE;IAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAAC,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,EACvD,aAAa,CAAC,EAAE,MAAM,GACrB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAQtC"}

package/dist/utils/builders.js

@@ -0,0 +1,316 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EdgeBuilder = exports.EntityBuilder = void 0;
+exports.createEntity = createEntity;
+exports.createEdge = createEdge;
+exports.validateEntities = validateEntities;
+exports.validateEdges = validateEdges;
+exports.validateTransformResult = validateTransformResult;
+const id_generator_1 = require("./id-generator");
+/**
+ * Crea un'entità OSINT nel formato corretto
+ * Genera automaticamente un ID deterministico se non specificato
+ *
+ * @param type - Tipo di entità
+ * @param value - Valore dell'entità (obbligatorio)
+ * @param options - Opzioni aggiuntive (label, metadata, id)
+ * @returns Entità nel formato corretto
+ *
+ * @example
+ * ```ts
+ * // Esempio semplice
+ * createEntity('ip', '8.8.8.8')
+ *
+ * // Con label e metadata
+ * createEntity('ip', '8.8.8.8', {
+ *   label: 'Google DNS',
+ *   metadata: { country: 'US', isp: 'Google LLC' }
+ * })
+ *
+ * // Con ID personalizzato
+ * createEntity('location', 'Mountain View, CA', {
+ *   id: 'custom-location-id',
+ *   metadata: { latitude: 37.386, longitude: -122.084 }
+ * })
+ * ```
+ */
+function createEntity(type, value, options) {
+    if (!value || value.trim() === '') {
+        throw new Error('Entity value cannot be empty');
+    }
+    return {
+        id: options?.id || (0, id_generator_1.generateEntityId)(type, value),
+        type,
+        value: value.trim(),
+        ...(options?.label && { label: options.label }),
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+/**
+ * Crea un edge tra due entità nel formato corretto
+ * Genera automaticamente un ID deterministico se non specificato
+ *
+ * @param sourceId - ID dell'entità sorgente
+ * @param targetId - ID dell'entità target
+ * @param label - Label visibile dell'edge (obbligatorio)
+ * @param options - Opzioni aggiuntive (id, relationship, metadata)
+ * @returns Edge nel formato corretto
+ *
+ * @example
+ * ```ts
+ * // Esempio semplice
+ * createEdge('ip-c909e98d', 'location-a3f42bc1', 'located in')
+ *
+ * // Con relationship e metadata
+ * createEdge('ip-c909e98d', 'org-5b3c1a2d', 'assigned by', {
+ *   relationship: 'isp_assignment',
+ *   metadata: { confidence: 0.98 }
+ * })
+ *
+ * // Con ID personalizzato
+ * createEdge('node-1', 'node-2', 'related to', {
+ *   id: 'custom-edge-id'
+ * })
+ * ```
+ */
+function createEdge(sourceId, targetId, label, options) {
+    if (!sourceId || sourceId.trim() === '') {
+        throw new Error('Edge sourceId cannot be empty');
+    }
+    if (!targetId || targetId.trim() === '') {
+        throw new Error('Edge targetId cannot be empty');
+    }
+    if (!label || label.trim() === '') {
+        throw new Error('Edge label cannot be empty');
+    }
+    return {
+        id: options?.id || (0, id_generator_1.generateEdgeId)(sourceId, targetId, label),
+        sourceId: sourceId.trim(),
+        targetId: targetId.trim(),
+        label: label.trim(),
+        ...(options?.relationship && { relationship: options.relationship }),
+        ...(options?.metadata && { metadata: options.metadata }),
+    };
+}
+/**
+ * NOTA: Gli helper specifici sono stati rimossi per rendere l'SDK più scalabile.
+ * Usa `createEntity(type, value, options)` per creare qualsiasi tipo di entità.
+ *
+ * Esempio:
+ * ```ts
+ * createEntity('ip', '8.8.8.8', { metadata: { country: 'US' } })
+ * createEntity('domain', 'example.com')
+ * createEntity('custom-type', 'value')  // Funziona anche con tipi futuri!
+ * ```
+ */
+/**
+ * Builder fluente per creare entità complesse
+ *
+ * @example
+ * ```ts
+ * const entity = EntityBuilder
+ *   .create('ip', '8.8.8.8')
+ *   .withLabel('Google DNS')
+ *   .withMetadata({ country: 'US', isp: 'Google LLC' })
+ *   .build();
+ * ```
+ */
+class EntityBuilder {
+    constructor(type, value) {
+        this.entity = {
+            type,
+            value: value.trim(),
+        };
+    }
+    static create(type, value) {
+        return new EntityBuilder(type, value);
+    }
+    withId(id) {
+        this.entity.id = id;
+        return this;
+    }
+    withLabel(label) {
+        this.entity.label = label;
+        return this;
+    }
+    withMetadata(metadata) {
+        this.entity.metadata = { ...this.entity.metadata, ...metadata };
+        return this;
+    }
+    addMetadata(key, value) {
+        if (!this.entity.metadata) {
+            this.entity.metadata = {};
+        }
+        this.entity.metadata[key] = value;
+        return this;
+    }
+    build() {
+        if (!this.entity.value) {
+            throw new Error('Entity value is required');
+        }
+        if (!this.entity.type) {
+            throw new Error('Entity type is required');
+        }
+        const id = this.entity.id || (0, id_generator_1.generateEntityId)(this.entity.type, this.entity.value);
+        return {
+            id,
+            type: this.entity.type,
+            value: this.entity.value,
+            ...(this.entity.label && { label: this.entity.label }),
+            ...(this.entity.metadata && { metadata: this.entity.metadata }),
+        };
+    }
+}
+exports.EntityBuilder = EntityBuilder;
+/**
+ * Builder fluente per creare edge complessi
+ *
+ * @example
+ * ```ts
+ * const edge = EdgeBuilder
+ *   .create('ip-abc', 'location-xyz', 'located in')
+ *   .withRelationship('geolocation')
+ *   .withMetadata({ confidence: 0.98 })
+ *   .build();
+ * ```
+ */
+class EdgeBuilder {
+    constructor(sourceId, targetId, label) {
+        this.edge = {
+            sourceId: sourceId.trim(),
+            targetId: targetId.trim(),
+            label: label.trim(),
+        };
+    }
+    static create(sourceId, targetId, label) {
+        return new EdgeBuilder(sourceId, targetId, label);
+    }
+    withId(id) {
+        this.edge.id = id;
+        return this;
+    }
+    withRelationship(relationship) {
+        this.edge.relationship = relationship;
+        return this;
+    }
+    withMetadata(metadata) {
+        this.edge.metadata = { ...this.edge.metadata, ...metadata };
+        return this;
+    }
+    addMetadata(key, value) {
+        if (!this.edge.metadata) {
+            this.edge.metadata = {};
+        }
+        this.edge.metadata[key] = value;
+        return this;
+    }
+    build() {
+        if (!this.edge.sourceId) {
+            throw new Error('Edge sourceId is required');
+        }
+        if (!this.edge.targetId) {
+            throw new Error('Edge targetId is required');
+        }
+        if (!this.edge.label) {
+            throw new Error('Edge label is required');
+        }
+        const id = this.edge.id || (0, id_generator_1.generateEdgeId)(this.edge.sourceId, this.edge.targetId, this.edge.label);
+        return {
+            id,
+            sourceId: this.edge.sourceId,
+            targetId: this.edge.targetId,
+            label: this.edge.label,
+            ...(this.edge.relationship && { relationship: this.edge.relationship }),
+            ...(this.edge.metadata && { metadata: this.edge.metadata }),
+        };
+    }
+}
+exports.EdgeBuilder = EdgeBuilder;
+/**
+ * Helper per validare un array di entità
+ * Controlla ID duplicati e campi obbligatori
+ */
+function validateEntities(entities) {
+    const errors = [];
+    const ids = new Set();
+    for (const entity of entities) {
+        // Verifica campi obbligatori
+        if (!entity.id) {
+            errors.push(`Entity missing required field: id`);
+        }
+        if (!entity.type) {
+            errors.push(`Entity missing required field: type`);
+        }
+        if (!entity.value) {
+            errors.push(`Entity missing required field: value`);
+        }
+        // Verifica ID duplicati
+        if (entity.id) {
+            if (ids.has(entity.id)) {
+                errors.push(`Duplicate entity ID: ${entity.id}`);
+            }
+            ids.add(entity.id);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Helper per validare un array di edge
+ * Controlla ID duplicati, campi obbligatori e riferimenti validi
+ */
+function validateEdges(edges, entities, inputEntityId) {
+    const errors = [];
+    const edgeIds = new Set();
+    const entityIds = new Set(entities.map(e => e.id));
+    // Aggiungi l'ID dell'entità di input se fornito
+    if (inputEntityId) {
+        entityIds.add(inputEntityId);
+    }
+    for (const edge of edges) {
+        // Verifica campi obbligatori
+        if (!edge.id) {
+            errors.push(`Edge missing required field: id`);
+        }
+        if (!edge.sourceId) {
+            errors.push(`Edge missing required field: sourceId`);
+        }
+        if (!edge.targetId) {
+            errors.push(`Edge missing required field: targetId`);
+        }
+        if (!edge.label) {
+            errors.push(`Edge missing required field: label`);
+        }
+        // Verifica ID duplicati
+        if (edge.id) {
+            if (edgeIds.has(edge.id)) {
+                errors.push(`Duplicate edge ID: ${edge.id}`);
+            }
+            edgeIds.add(edge.id);
+        }
+        // Verifica riferimenti validi
+        if (edge.targetId && !entityIds.has(edge.targetId)) {
+            errors.push(`Edge references non-existent target entity: ${edge.targetId}`);
+        }
+        if (edge.sourceId && !entityIds.has(edge.sourceId)) {
+            errors.push(`Edge references non-existent source entity: ${edge.sourceId}`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Helper per validare una risposta completa di transform
+ */
+function validateTransformResult(result, inputEntityId) {
+    const entityValidation = validateEntities(result.entities);
+    const edgeValidation = validateEdges(result.edges, result.entities, inputEntityId);
+    return {
+        valid: entityValidation.valid && edgeValidation.valid,
+        errors: [...entityValidation.errors, ...edgeValidation.errors],
+    };
+}

package/dist/utils/id-generator.d.ts

@@ -0,0 +1,81 @@
+import type { EntityType } from '../core/types';
+/**
+ * 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"
+ * ```
+ */
+export declare function generateEntityId(type: EntityType, value: string): string;
+/**
+ * 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"
+ * ```
+ */
+export declare function generateEdgeId(sourceId: string, targetId: string, label?: string): string;
+/**
+ * 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"
+ * ```
+ */
+export declare function generateRandomId(prefix: string): string;
+/**
+ * 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"
+ * ```
+ */
+export declare function normalizeValue(value: string): string;
+/**
+ * Valida un ID di entità
+ *
+ * @param id - ID da validare
+ * @returns true se l'ID è valido
+ */
+export declare function isValidEntityId(id: string): boolean;
+/**
+ * Valida un ID di edge
+ *
+ * @param id - ID da validare
+ * @returns true se l'ID è valido
+ */
+export declare function isValidEdgeId(id: string): boolean;
+//# sourceMappingURL=id-generator.d.ts.map

package/dist/utils/id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQxE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CAYR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQpD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEjD"}