@relazio/plugin-sdk 0.1.0 → 0.2.0

package/docs/response-format.md

@@ -0,0 +1,515 @@
+# External Plugin Response Format
+
+This document defines the required response format for external plugins when returning entities and edges.
+
+## Response Modes
+
+External plugins can return results in two modes:
+
+1. **Synchronous (sync)**: Immediate results
+2. **Asynchronous (async)**: Background job with webhook completion
+
+## Response Structure
+
+### Synchronous Response
+
+```typescript
+{
+  "async": false,
+  "result": {
+    "success": true,
+    "entities": [...],  // Array of entities (format below)
+    "edges": [...],     // Array of edges (format below)
+    "message": "Optional success message",
+    "metadata": {}      // Optional additional metadata
+  }
+}
+```
+
+### Asynchronous Response
+
+```typescript
+{
+  "async": true,
+  "jobId": "your-plugin-job-id-123",
+  "estimatedTime": 30  // Estimated time in seconds (optional)
+}
+```
+
+## Entity Format
+
+### Structure
+
+```typescript
+{
+  "id": string,        // REQUIRED - Unique ID generated by plugin
+  "type": string,      // REQUIRED - Entity type (see list below)
+  "value": string,     // REQUIRED - Short entity value
+  "label": string,     // OPTIONAL - Display text (default: value)
+  "metadata": object   // OPTIONAL - Additional metadata
+}
+```
+
+### Required Rules
+
+1. **`id` must be unique** across the entire response
+2. **`type` must be valid** (see list below)
+3. **`value` must be a non-empty string**
+4. **Use `metadata` only** - not `properties`
+5. **IDs should be stable** and deterministic when possible
+
+### Supported Entity Types
+
+```typescript
+type EntityType = 
+  | 'email'           // Email address
+  | 'domain'          // Domain name
+  | 'ip'              // IP address
+  | 'person'          // Person name
+  | 'username'        // Username/handle
+  | 'phone'           // Phone number
+  | 'organization'    // Organization/company
+  | 'hash'            // Hash/checksum
+  | 'credential'      // Credential pair
+  | 'social'          // Social media profile
+  | 'document'        // Document
+  | 'note'            // Text note
+  | 'image'           // Image
+  | 'video'           // Video
+  | 'location'        // Geographic location
+  | 'wallet'          // Crypto wallet
+  | 'transaction'     // Transaction
+  | 'exchange'        // Exchange
+  | 'url'             // URL
+  | 'maps'            // Map view
+  | 'custom';         // Custom entity
+```
+
+### Entity Examples
+
+**IP Address**:
+```json
+{
+  "id": "ip-8.8.8.8",
+  "type": "ip",
+  "value": "8.8.8.8",
+  "label": "Google DNS",
+  "metadata": {
+    "country": "US",
+    "isp": "Google LLC"
+  }
+}
+```
+
+**Location**:
+```json
+{
+  "id": "loc-mountain-view-ca",
+  "type": "location",
+  "value": "Mountain View, CA",
+  "metadata": {
+    "latitude": 37.386,
+    "longitude": -122.084,
+    "country": "United States"
+  }
+}
+```
+
+**Organization**:
+```json
+{
+  "id": "org-google-llc",
+  "type": "organization",
+  "value": "Google LLC",
+  "metadata": {
+    "industry": "Technology",
+    "website": "google.com"
+  }
+}
+```
+
+**Note with Markdown**:
+```json
+{
+  "id": "note-ip-analysis-1",
+  "type": "note",
+  "value": "IP Analysis",
+  "label": "## IP: 8.8.8.8\n\n**Location**: Mountain View, CA\n**ISP**: Google LLC",
+  "metadata": {
+    "tags": ["ip-lookup", "analysis"],
+    "format": "markdown"
+  }
+}
+```
+
+## Edge Format
+
+### Structure
+
+```typescript
+{
+  "id": string,           // REQUIRED - Unique edge ID
+  "sourceId": string,     // REQUIRED - Source entity ID
+  "targetId": string,     // REQUIRED - Target entity ID
+  "label": string,        // REQUIRED - Visible label
+  "relationship": string, // OPTIONAL - Relationship type (default: label)
+  "metadata": object      // OPTIONAL - Additional metadata
+}
+```
+
+### Required Rules
+
+1. **`id` must be unique** across the entire response
+2. **`sourceId` must match an entity ID** (or input entity ID)
+3. **`targetId` must match an entity ID** returned
+4. **Use `sourceId/targetId` only** - not `from/to`
+5. **`label` is required** and visible in the graph
+
+### Edge Examples
+
+**IP to Location**:
+```json
+{
+  "id": "edge-ip-to-location-1",
+  "sourceId": "input-node-id",
+  "targetId": "loc-mountain-view-ca",
+  "label": "located in",
+  "relationship": "geolocation"
+}
+```
+
+**IP to Organization**:
+```json
+{
+  "id": "edge-ip-to-org-1",
+  "sourceId": "input-node-id",
+  "targetId": "org-google-llc",
+  "label": "assigned by",
+  "relationship": "isp_assignment"
+}
+```
+
+## Complete Example
+
+### Input Transform
+
+```json
+{
+  "transformId": "lookup-ip",
+  "input": {
+    "entity": {
+      "id": "node-abc123",
+      "type": "ip",
+      "value": "8.8.8.8"
+    }
+  },
+  "callbackUrl": "https://app.example.com/api/webhooks/transforms/job-xyz?token=..."
+}
+```
+
+### Synchronous Output
+
+```json
+{
+  "async": false,
+  "result": {
+    "success": true,
+    "entities": [
+      {
+        "id": "loc-mountain-view-ca",
+        "type": "location",
+        "value": "Mountain View, CA",
+        "metadata": {
+          "latitude": 37.386,
+          "longitude": -122.084,
+          "country": "United States"
+        }
+      },
+      {
+        "id": "org-google-llc",
+        "type": "organization",
+        "value": "Google LLC",
+        "metadata": {
+          "type": "isp",
+          "asn": "AS15169"
+        }
+      }
+    ],
+    "edges": [
+      {
+        "id": "edge-ip-to-loc",
+        "sourceId": "node-abc123",
+        "targetId": "loc-mountain-view-ca",
+        "label": "located in",
+        "relationship": "geolocation"
+      },
+      {
+        "id": "edge-ip-to-org",
+        "sourceId": "node-abc123",
+        "targetId": "org-google-llc",
+        "label": "assigned by",
+        "relationship": "isp_assignment"
+      }
+    ],
+    "message": "Successfully analyzed IP 8.8.8.8"
+  }
+}
+```
+
+### Asynchronous Output
+
+```json
+{
+  "async": true,
+  "jobId": "scan-job-12345",
+  "estimatedTime": 60
+}
+```
+
+## Webhook for Async Jobs
+
+When an async job completes, the plugin must send a webhook to the provided callback URL.
+
+### Required Headers
+
+```
+Content-Type: application/json
+X-Plugin-Signature: sha256={hmac_signature}
+```
+
+The HMAC signature is calculated on the JSON body using the plugin's webhook secret.
+
+### Webhook Body - Completion
+
+```json
+{
+  "jobId": "scan-job-12345",
+  "status": "completed",
+  "progress": 100,
+  "progressMessage": "Scan complete",
+  "result": {
+    "success": true,
+    "entities": [
+      {
+        "id": "...",
+        "type": "...",
+        "value": "..."
+      }
+    ],
+    "edges": [
+      {
+        "id": "...",
+        "sourceId": "...",
+        "targetId": "...",
+        "label": "..."
+      }
+    ]
+  }
+}
+```
+
+### Webhook Body - Progress Update
+
+```json
+{
+  "jobId": "scan-job-12345",
+  "status": "processing",
+  "progress": 45,
+  "progressMessage": "Scanning ports..."
+}
+```
+
+### Webhook Body - Failure
+
+```json
+{
+  "jobId": "scan-job-12345",
+  "status": "failed",
+  "error": "Connection timeout"
+}
+```
+
+## ID Generation Best Practices
+
+### Deterministic IDs
+
+Use predictable, deterministic formats:
+
+```javascript
+const entityId = `${type}-${hashValue(value)}`;
+// Example: "location-a3f42bc1"
+```
+
+### Unique IDs
+
+Ensure every entity has a unique ID:
+
+```javascript
+const entityId = `${type}-${normalizedValue}-${Date.now()}`;
+const edgeId = `edge-${sourceId}-${targetId}-${Date.now()}`;
+```
+
+### Clear Prefixes
+
+Use prefixes to identify the type:
+
+```javascript
+"ip-8.8.8.8"
+"loc-nyc-us"
+"org-google"
+"note-analysis-1"
+"edge-ip-to-loc-1"
+```
+
+### Input Entity ID
+
+Always use the input entity ID in edges as `sourceId`:
+
+```javascript
+// Input contains:
+{
+  "entity": {
+    "id": "node-abc123",  // Use this as sourceId
+    "type": "ip",
+    "value": "8.8.8.8"
+  }
+}
+
+// Edges must use this ID:
+{
+  "id": "edge-1",
+  "sourceId": "node-abc123",  // Input entity ID
+  "targetId": "loc-nyc",
+  "label": "located in"
+}
+```
+
+## SDK Example
+
+```typescript
+import crypto from 'crypto';
+
+function generateEntityId(type: string, value: string): string {
+  const hash = crypto.createHash('md5')
+    .update(value.toLowerCase().trim())
+    .digest('hex')
+    .substring(0, 8);
+  return `${type}-${hash}`;
+}
+
+function generateEdgeId(sourceId: string, targetId: string): string {
+  const hash = crypto.createHash('md5')
+    .update(`${sourceId}-${targetId}`)
+    .digest('hex')
+    .substring(0, 8);
+  return `edge-${hash}`;
+}
+
+async function executeTransform(input) {
+  const { entity } = input;
+  
+  const lookupResult = await lookupIP(entity.value);
+  
+  const entities = [
+    {
+      id: generateEntityId('location', lookupResult.city),
+      type: 'location',
+      value: lookupResult.city,
+      metadata: {
+        latitude: lookupResult.lat,
+        longitude: lookupResult.lon
+      }
+    },
+    {
+      id: generateEntityId('organization', lookupResult.isp),
+      type: 'organization',
+      value: lookupResult.isp,
+      metadata: {
+        asn: lookupResult.asn
+      }
+    }
+  ];
+  
+  const edges = [
+    {
+      id: generateEdgeId(entity.id, entities[0].id),
+      sourceId: entity.id,
+      targetId: entities[0].id,
+      label: 'located in',
+      relationship: 'geolocation'
+    },
+    {
+      id: generateEdgeId(entity.id, entities[1].id),
+      sourceId: entity.id,
+      targetId: entities[1].id,
+      label: 'assigned by',
+      relationship: 'isp_assignment'
+    }
+  ];
+  
+  return {
+    async: false,
+    result: {
+      success: true,
+      entities,
+      edges,
+      message: `Analyzed IP ${entity.value}`
+    }
+  };
+}
+```
+
+## Validation
+
+The Relazio system validates responses and rejects non-compliant ones.
+
+### Applied Validations
+
+- Each entity must have `id`, `type`, `value`
+- Each edge must have `id`, `sourceId`, `targetId`, `label`
+- `type` must be a valid type
+- All IDs must be unique
+- Edge `targetId` must correspond to a returned entity
+- Edge `sourceId` must be the input entity ID or a returned entity
+
+### Common Errors
+
+```
+"Entity missing required field: id"
+"Edge missing required field: sourceId"
+"Invalid entity type: unknown"
+"Edge references non-existent entity: xyz"
+"Duplicate entity ID: loc-1"
+```
+
+## HMAC Security
+
+For webhooks, calculate the HMAC signature:
+
+```typescript
+import crypto from 'crypto';
+
+function generateHMACSignature(payload: string, secret: string): string {
+  return crypto
+    .createHmac('sha256', secret)
+    .update(payload)
+    .digest('hex');
+}
+
+// Usage:
+const body = JSON.stringify(webhookPayload);
+const signature = generateHMACSignature(body, webhookSecret);
+
+// Send with header:
+headers: {
+  'Content-Type': 'application/json',
+  'X-Plugin-Signature': `sha256=${signature}`
+}
+```
+
+## References
+
+- [Quick Start Guide](./quick-start.md)
+- [Builders Guide](./builders-guide.md)
+- [Examples Documentation](./examples.md)
+- [Main README](../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relazio/plugin-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official SDK for building external plugins for Relazio",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,11 +22,13 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/relazio/plugin-sdk.git"
+    "url": "git+https://github.com/relazio/plugin-sdk.git"
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "publishConfig": {
@@ -43,10 +45,9 @@
     "@typescript-eslint/parser": "^6.17.0",
     "eslint": "^8.56.0",
     "typescript": "^5.3.3",
-    "vitest": "^1.1.0"
+    "vitest": "^4.0.16"
   },
   "engines": {
     "node": ">=18.0.0"
   }
 }
-