{"_id":"@atlascrew/synapse-api","name":"@atlascrew/synapse-api","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@atlascrew/synapse-api","version":"0.1.0","description":"TypeScript API client for Synapse - WAF sensor, entity management, and rule evaluation","author":{"name":"Nicholas Crew Ferguson","email":"nick@atlascrew.dev","url":"https://atlascrew.dev"},"homepage":"https://horizon.atlascrew.dev/reference/synapse-api","bugs":{"url":"https://github.com/atlas-crew/horizon-security-platform/issues"},"license":"MIT","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"keywords":["synapse","waf","api-client","security","horizon"],"repository":{"type":"git","url":"git+https://github.com/atlas-crew/horizon-security-platform.git","directory":"packages/synapse-api"},"publishConfig":{"access":"public"},"devDependencies":{"@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^7.18.0","@typescript-eslint/parser":"^7.18.0","eslint":"^8.57.1","tsup":"^8.0.0","typescript":"^5.4.5","vitest":"^2.0.0"},"engines":{"node":">=18.18.0"},"scripts":{"build":"tsup","dev":"tsup --watch","type-check":"tsc --noEmit","lint":"eslint src --ext .ts","test":"vitest run","test:watch":"vitest"},"_id":"@atlascrew/synapse-api@0.1.0","_integrity":"sha512-2KhWhiNONamylhYC3q49PgtOKH+1zxJgnr8XWVCil/zojYM52fleWKNtrm5ZBVJyd8kk+IjCIEC1/aECvXzDJQ==","_resolved":"/tmp/c7cbe0dfa9ca87e984d45c5fb8432cca/atlascrew-synapse-api-0.1.0.tgz","_from":"file:atlascrew-synapse-api-0.1.0.tgz","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-2KhWhiNONamylhYC3q49PgtOKH+1zxJgnr8XWVCil/zojYM52fleWKNtrm5ZBVJyd8kk+IjCIEC1/aECvXzDJQ==","shasum":"128bf9b679cc3ad043036f766370b929a385dac7","tarball":"https://registry.npmjs.org/@atlascrew/synapse-api/-/synapse-api-0.1.0.tgz","fileCount":6,"unpackedSize":83163,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC44xrKluRTbnTf5LpWc+cK710Lx1Oh9R3J4Pbpl/Qh6wIhAMDZah5v5p0Gux/XjGdQE4G4d/bsu9/TlI4M/RZkSkcv"}]},"_npmUser":{"name":"nickcrew","email":"nickf4@icloud.com"},"directories":{},"maintainers":[{"name":"nickcrew","email":"nickf4@icloud.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/synapse-api_0.1.0_1774419127239_0.409054765417856"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-25T06:12:07.162Z","0.1.0":"2026-03-25T06:12:07.382Z","modified":"2026-03-25T06:12:07.565Z"},"maintainers":[{"name":"nickcrew","email":"nickf4@icloud.com"}],"description":"TypeScript API client for Synapse - WAF sensor, entity management, and rule evaluation","homepage":"https://horizon.atlascrew.dev/reference/synapse-api","keywords":["synapse","waf","api-client","security","horizon"],"repository":{"type":"git","url":"git+https://github.com/atlas-crew/horizon-security-platform.git","directory":"packages/synapse-api"},"author":{"name":"Nicholas Crew Ferguson","email":"nick@atlascrew.dev","url":"https://atlascrew.dev"},"bugs":{"url":"https://github.com/atlas-crew/horizon-security-platform/issues"},"license":"MIT","readme":"# synapse-api\n\nTypeScript client for the Synapse (risk-server) API - WAF sensor management, entity tracking, rule evaluation, and actor fingerprinting.\n\n## Features\n\n- **Full TypeScript Support** - Comprehensive type definitions for all API endpoints\n- **Promise-based API** - Modern async/await interface with configurable timeouts\n- **Rich Error Handling** - Custom `SynapseError` class with semantic helper methods\n- **18 API Methods** - Complete coverage of all Synapse endpoints\n- **Debug Mode** - Optional request/response logging for troubleshooting\n- **Zero Dependencies** - Uses native `fetch` API\n\n## Installation\n\n```bash\n# npm\nnpm install synapse-api\n\n# pnpm\npnpm add synapse-api\n\n# yarn\nyarn add synapse-api\n```\n\n## Quick Start\n\n```typescript\nimport { SynapseClient } from 'synapse-api';\n\nconst client = new SynapseClient({\n  baseUrl: 'http://localhost:3000'\n});\n\n// Check health\nconst health = await client.health();\nconsole.log(health.status); // \"ok\"\n\n// Get sensor status\nconst status = await client.getStatus();\nconsole.log(`Blocked: ${status.blockedRequests}`);\n\n// Evaluate a request (dry-run)\nconst result = await client.evaluate({\n  method: 'GET',\n  path: '/api/admin',\n  ip: '192.168.1.100'\n});\nconsole.log(`Would block: ${result.wouldBlock}`);\n```\n\n## Configuration\n\n```typescript\ninterface SynapseClientOptions {\n  /** Base URL of the Synapse server */\n  baseUrl: string;\n\n  /** Request timeout in milliseconds (default: 30000) */\n  timeout?: number;\n\n  /** Enable verbose debug logging (default: false) */\n  debug?: boolean;\n}\n```\n\n## API Reference\n\n### Categories\n\n| Category | Description | Methods |\n|----------|-------------|---------|\n| **Health & Status** | Server health and metrics | 3 methods |\n| **Entity Management** | Tracked entities and blocks | 4 methods |\n| **Configuration** | WAF configuration | 2 methods |\n| **WAF Rules** | Rule management | 6 methods |\n| **Actor Tracking** | Actor fingerprinting | 3 methods |\n\n---\n\n### Health & Status\n\n#### `client.health()`\n\nCheck server health status.\n\n```typescript\nconst health = await client.health();\n// { status: 'ok', service: 'synapse', uptime: 3600 }\n```\n\n#### `client.getStatus()`\n\nGet sensor status and metrics.\n\n```typescript\nconst status = await client.getStatus();\n// {\n//   totalRequests: 10000,\n//   blockedRequests: 150,\n//   entities: 523,\n//   ...\n// }\n```\n\n#### `client.getMetrics()`\n\nGet Prometheus-formatted metrics.\n\n```typescript\nconst metrics = await client.getMetrics();\n// Raw prometheus text format\n```\n\n---\n\n### Entity Management\n\n#### `client.listEntities()`\n\nList all tracked entities.\n\n```typescript\nconst { entities } = await client.listEntities();\nentities.forEach(e => {\n  console.log(`${e.ip}: risk ${e.riskScore}`);\n});\n```\n\n#### `client.listBlocks()`\n\nList all block records.\n\n```typescript\nconst { blocks } = await client.listBlocks();\nblocks.forEach(b => {\n  console.log(`${b.ip}: ${b.reason}`);\n});\n```\n\n#### `client.releaseEntity(entityIdOrIp)`\n\nRelease a blocked entity by ID or IP address.\n\n```typescript\nawait client.releaseEntity('192.168.1.100');\n// or\nawait client.releaseEntity('entity-id-abc123');\n```\n\n#### `client.releaseAll()`\n\nRelease all blocked entities.\n\n```typescript\nconst { count } = await client.releaseAll();\nconsole.log(`Released ${count} entities`);\n```\n\n---\n\n### Configuration\n\n#### `client.getConfig()`\n\nGet full system configuration.\n\n```typescript\nconst config = await client.getConfig();\nconsole.log(config.waf.autoblockThreshold);\n```\n\n#### `client.updateConfig(updates)`\n\nUpdate WAF configuration.\n\n```typescript\nawait client.updateConfig({\n  autoblockThreshold: 80,\n  riskBasedBlockingEnabled: true\n});\n```\n\n---\n\n### WAF Rules\n\n#### `client.listRules()`\n\nList all WAF rules (static + runtime).\n\n```typescript\nconst { rules, stats } = await client.listRules();\nconsole.log(`Total rules: ${stats.total}`);\n```\n\n#### `client.addRule(rule, ttl?)`\n\nAdd a runtime rule with optional TTL.\n\n```typescript\nawait client.addRule({\n  description: 'Block /admin access',\n  blocking: true,\n  matches: [{ type: 'path', match: '/admin' }]\n}, 3600); // TTL in seconds\n```\n\n#### `client.removeRule(ruleId)`\n\nRemove a runtime rule by ID.\n\n```typescript\nawait client.removeRule(123);\n```\n\n#### `client.clearRules()`\n\nClear all runtime rules.\n\n```typescript\nawait client.clearRules();\n```\n\n#### `client.reloadRules()`\n\nReload rules from file.\n\n```typescript\nawait client.reloadRules();\n```\n\n#### `client.evaluate(request)`\n\nEvaluate a request against WAF rules (dry-run).\n\n```typescript\nconst result = await client.evaluate({\n  method: 'POST',\n  path: '/api/login',\n  ip: '192.168.1.100',\n  headers: { 'Content-Type': 'application/json' },\n  body: '{\"username\":\"admin\"}'\n});\n\nif (result.wouldBlock) {\n  console.log(`Would block: ${result.blockReason}`);\n  console.log(`Risk score: ${result.riskScore}`);\n}\n```\n\n---\n\n### Actor Tracking\n\n#### `client.listActors()`\n\nList all tracked actors.\n\n```typescript\nconst { actors } = await client.listActors();\nactors.forEach(a => {\n  console.log(`${a.ip}: fingerprint=${a.fingerprint}`);\n});\n```\n\n#### `client.getActorStats()`\n\nGet actor tracking statistics.\n\n```typescript\nconst stats = await client.getActorStats();\nconsole.log(`Total actors: ${stats.totalActors}`);\n```\n\n#### `client.setActorFingerprint(ip, fingerprint)`\n\nSet fingerprint for an actor.\n\n```typescript\nawait client.setActorFingerprint('192.168.1.100', 'fp-abc123');\n```\n\n---\n\n## Error Handling\n\n```typescript\nimport { SynapseClient, SynapseError } from 'synapse-api';\n\ntry {\n  await client.getStatus();\n} catch (error) {\n  if (error instanceof SynapseError) {\n    console.log(`Status: ${error.statusCode}`);\n\n    if (error.isClientError()) {\n      console.log('Client error (4xx)');\n    } else if (error.isServerError()) {\n      console.log('Server error (5xx)');\n    } else if (error.isNetworkError()) {\n      console.log('Network/timeout error');\n    }\n  }\n}\n```\n\n### SynapseError Methods\n\n| Method | Description |\n|--------|-------------|\n| `isStatus(code)` | Check for specific HTTP status |\n| `isClientError()` | Check if 4xx error |\n| `isServerError()` | Check if 5xx error |\n| `isNetworkError()` | Check if network/timeout error |\n\n---\n\n## Examples\n\n### Health Monitoring\n\n```typescript\nasync function monitorHealth(client: SynapseClient) {\n  const health = await client.health();\n  if (health.status !== 'ok') {\n    console.error('Service unhealthy!');\n    return false;\n  }\n  return true;\n}\n\n// Poll every 10 seconds\nsetInterval(() => monitorHealth(client), 10000);\n```\n\n### Block Management\n\n```typescript\nasync function releaseHighRiskEntities(client: SynapseClient, threshold: number) {\n  const { entities } = await client.listEntities();\n  const highRisk = entities.filter(e => e.riskScore > threshold && e.blocked);\n\n  for (const entity of highRisk) {\n    console.log(`Releasing: ${entity.ip} (risk: ${entity.riskScore})`);\n    await client.releaseEntity(entity.ip);\n  }\n\n  return highRisk.length;\n}\n```\n\n### Rule Testing\n\n```typescript\nasync function testRule(client: SynapseClient, rule: RuleDefinition) {\n  // Add rule temporarily\n  const { rule: added } = await client.addRule(rule, 60); // 1 minute TTL\n\n  // Test against sample requests\n  const testRequests = [\n    { method: 'GET', path: '/api/users', ip: '10.0.0.1' },\n    { method: 'POST', path: '/admin', ip: '10.0.0.1' },\n  ];\n\n  for (const req of testRequests) {\n    const result = await client.evaluate(req);\n    console.log(`${req.method} ${req.path}: ${result.wouldBlock ? 'BLOCKED' : 'ALLOWED'}`);\n  }\n\n  // Rule auto-expires after TTL\n}\n```\n\n---\n\n## TypeScript Types\n\nAll types are exported from the main package:\n\n```typescript\nimport type {\n  SynapseClientOptions,\n  HealthResponse,\n  SensorStatus,\n  Entity,\n  Block,\n  EntitiesResponse,\n  BlocksResponse,\n  ReleaseResponse,\n  ReleaseAllResponse,\n  ConfigResponse,\n  ConfigUpdateResponse,\n  WafConfig,\n  Rule,\n  RuleDefinition,\n  RulesResponse,\n  AddRuleResponse,\n  RemoveRuleResponse,\n  ClearRulesResponse,\n  ReloadRulesResponse,\n  EvaluateRequest,\n  EvaluateResult,\n  Actor,\n  ActorsResponse,\n  ActorStats,\n  SetFingerprintResponse,\n} from 'synapse-api';\n```\n\n---\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build\npnpm build\n\n# Type-check\npnpm type-check\n\n# Run tests\npnpm test\n\n# Watch mode\npnpm test:watch\n```\n\n---\n\n## See Also\n\n- **[synapse-client](../../apps/synapse-client)** - CLI wrapper for Synapse API\n- **[risk-server](../../apps/risk-server)** - Synapse WAF service\n- **[edge-cli](../../apps/edge-cli)** - Unified Edge Labs CLI\n\n---\n\n## License\n\nLicensed under the GNU Affero General Public License v3.0 only.\nSee [LICENSE](../../LICENSE).\n","readmeFilename":"README.md","_rev":"1-820c3e99f5c863655610dd70c6a8cee5"}