{"_id":"@ascend-ai/sdk","_rev":"5-2f3260513b8510d5596a1073d7231144","name":"@ascend-ai/sdk","dist-tags":{"latest":"2.4.0"},"versions":{"2.1.0":{"name":"@ascend-ai/sdk","version":"2.1.0","keywords":["ai","authorization","governance","enterprise","security","compliance","soc2","hipaa","pci-dss","typescript","mcp","circuit-breaker","fail-mode"],"author":{"name":"ASCEND by OW-AI","email":"support@ascendowkai.com"},"license":"MIT","_id":"@ascend-ai/sdk@2.1.0","maintainers":[{"name":"ascend_security","email":"info@ow-kai.com"}],"homepage":"https://ascendowkai.com","bugs":{"url":"https://github.com/anthropics/ascend-sdk-nodejs/issues"},"dist":{"shasum":"989286717cff4576b1644372e35eefd2a8ed760e","tarball":"https://registry.npmjs.org/@ascend-ai/sdk/-/sdk-2.1.0.tgz","fileCount":8,"integrity":"sha512-rnckybZuoNFjPfXWdRB4irmMvS3S7kaZ0Ke9M4i807pklykLpL7chJcV0pX5K8XWDsfHtCgq3+AFXk2oIe8NFA==","signatures":[{"sig":"MEUCIHARCREVFZpHkBYaAV//GH9gxTPQ2t8Rm77zFzB8bqXfAiEAnSekd81kLLgJn+aRcg64EC1r0Cpk3htpshj1jGxk3Ls=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":676162},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"af9b6fa8b8ca7de32af939b50977a28988024b26","scripts":{"dev":"tsup --watch","lint":"eslint src/","test":"vitest","build":"tsup","typecheck":"tsc --noEmit","test:coverage":"vitest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"ascend_security","email":"info@ow-kai.com"},"repository":{"url":"git+https://github.com/anthropics/ascend-sdk-nodejs.git","type":"git"},"_npmVersion":"10.9.2","description":"ASCEND SDK - Enterprise AI Governance with fail mode, circuit breaker, and MCP integration","directories":{},"_nodeVersion":"22.14.0","dependencies":{"axios":"^1.6.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.0.0","tsup":"^8.0.0","eslint":"^8.0.0","vitest":"^1.0.0","ts-jest":"^29.0.0","typescript":"^5.0.0","@types/jest":"^29.0.0","@types/node":"^20.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"peerDependencies":{"dotenv":">=16.0.0"},"peerDependenciesMeta":{"dotenv":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_2.1.0_1774749380253_0.015355010834139593","host":"s3://npm-registry-packages-npm-production"}},"2.1.1":{"name":"@ascend-ai/sdk","version":"2.1.1","keywords":["ai","authorization","governance","enterprise","security","compliance","soc2","hipaa","pci-dss","typescript","mcp","circuit-breaker","fail-mode"],"author":{"name":"ASCEND by OW-AI","email":"support@ascendowkai.com"},"license":"MIT","_id":"@ascend-ai/sdk@2.1.1","maintainers":[{"name":"ascend_security","email":"info@ow-kai.com"}],"homepage":"https://ascendowkai.com","bugs":{"url":"https://github.com/anthropics/ascend-sdk-nodejs/issues"},"dist":{"shasum":"863487fe8a09fd6bc528fc68b6b24628f54376fc","tarball":"https://registry.npmjs.org/@ascend-ai/sdk/-/sdk-2.1.1.tgz","fileCount":6,"integrity":"sha512-wy9lVpb2JgLmjnptFwbUXX0LTVH6MC6Ufe7KjvvNgZpNFjsO+tI/Av7hoFS/g6L1G96SEV3fUbYH+5gqTYdAsA==","signatures":[{"sig":"MEUCIEF66Qx6jJ9TZyNql+P4ObHp0ZFOJAqjUTJzMO7dFy9YAiEA1uS0NgiJTknAmOE/wFITRoD/zXbOjCNvkDzVJ4ubRe4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":252825},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"7248e2971d114479b31c9944472cb4fed11da3dd","scripts":{"dev":"tsup --watch","lint":"eslint src/","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:coverage":"vitest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"ascend_security","email":"info@ow-kai.com"},"repository":{"url":"git+https://github.com/anthropics/ascend-sdk-nodejs.git","type":"git"},"_npmVersion":"10.9.2","description":"ASCEND SDK - Enterprise AI Governance with fail mode, circuit breaker, and MCP integration","directories":{},"_nodeVersion":"22.14.0","dependencies":{"axios":"^1.6.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.0.0","tsup":"^8.0.0","eslint":"^8.0.0","vitest":"^1.0.0","ts-jest":"^29.0.0","typescript":"^5.0.0","@types/jest":"^29.0.0","@types/node":"^20.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"peerDependencies":{"dotenv":">=16.0.0"},"peerDependenciesMeta":{"dotenv":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_2.1.1_1776016581265_0.13627674264390155","host":"s3://npm-registry-packages-npm-production"}},"2.2.0":{"name":"@ascend-ai/sdk","version":"2.2.0","keywords":["ai","authorization","governance","enterprise","security","compliance","soc2","hipaa","pci-dss","typescript","mcp","circuit-breaker","fail-mode"],"author":{"name":"ASCEND by OW-AI","email":"support@ascendowkai.com"},"license":"MIT","_id":"@ascend-ai/sdk@2.2.0","maintainers":[{"name":"ascend_security","email":"info@ow-kai.com"}],"homepage":"https://ascendowkai.com","bugs":{"url":"https://github.com/anthropics/ascend-sdk-nodejs/issues"},"dist":{"shasum":"ca65ad209aaf346879deab8d14c1e408e87976ea","tarball":"https://registry.npmjs.org/@ascend-ai/sdk/-/sdk-2.2.0.tgz","fileCount":8,"integrity":"sha512-aIa4TPkwnVjK/Wb3kcJ8CP0ITBh57k3laqPV/AFkjxf1QauvGbzU80JOxzoG+HmVIKKlz6L8cXQnkOHUThPbXw==","signatures":[{"sig":"MEUCIQDkRJS+dsA/1/nV4QorX3FwcqiUh9fQAXOww8vkl8Vu7AIgBOKz5MWvzeZjuq2CcS4fAIpbD50RidtSztYK1BrA+4A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":607505},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"b3ab1ab9e627955ab1dfb8287c769661ed4e73c1","scripts":{"dev":"tsup --watch","lint":"eslint src/","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:coverage":"vitest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"ascend_security","email":"info@ow-kai.com"},"repository":{"url":"git+https://github.com/anthropics/ascend-sdk-nodejs.git","type":"git"},"_npmVersion":"10.9.2","description":"ASCEND SDK - Enterprise AI Governance with fail mode, circuit breaker, and MCP integration","directories":{},"_nodeVersion":"22.14.0","dependencies":{"axios":"^1.6.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.0.0","tsup":"^8.0.0","eslint":"^8.0.0","vitest":"^1.0.0","ts-jest":"^29.0.0","typescript":"^5.0.0","@types/jest":"^29.0.0","@types/node":"^20.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"peerDependencies":{"dotenv":">=16.0.0"},"peerDependenciesMeta":{"dotenv":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_2.2.0_1778027902130_0.034727264056484186","host":"s3://npm-registry-packages-npm-production"}},"2.3.0":{"name":"@ascend-ai/sdk","version":"2.3.0","keywords":["ai","authorization","governance","enterprise","security","compliance","soc2","hipaa","pci-dss","typescript","mcp","circuit-breaker","fail-mode"],"author":{"name":"ASCEND by OW-AI","email":"support@ascendowkai.com"},"license":"MIT","_id":"@ascend-ai/sdk@2.3.0","maintainers":[{"name":"ascend_security","email":"info@ow-kai.com"}],"homepage":"https://ascendowkai.com","bugs":{"url":"https://github.com/Amplify-Cost/owkai-pilot-backend/issues"},"dist":{"shasum":"7bad5a4feffe7ad86477521fc964272efd90e809","tarball":"https://registry.npmjs.org/@ascend-ai/sdk/-/sdk-2.3.0.tgz","fileCount":8,"integrity":"sha512-W/hQkAALGlYmVHP0P2n9JtxDbhnuall7Y6NAqBPjToEwnwJDxNABy8rt8+o1jbn57+w6FL36xQWFxHMDikWgyA==","signatures":[{"sig":"MEUCIFlKVV1/p5CxFQjAALaLQg0vV12fKU08rMvVMaL1sQu0AiEAn5zyrLo0dEhudu+yS0l/H6h0fZoBEgACHN2bdpJ2oJA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":633985},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"f66ca01d6d2edc25e75de064fe3f1bcaf34dcd15","scripts":{"dev":"tsup --watch","lint":"eslint src/","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:coverage":"vitest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"ascend_security","email":"info@ow-kai.com"},"repository":{"url":"git+https://github.com/Amplify-Cost/owkai-pilot-backend.git","type":"git"},"_npmVersion":"10.9.2","description":"ASCEND SDK - Enterprise AI Governance with fail mode, circuit breaker, and MCP integration","directories":{},"_nodeVersion":"22.14.0","dependencies":{"axios":"^1.6.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.0.0","tsup":"^8.0.0","eslint":"^8.0.0","vitest":"^1.0.0","ts-jest":"^29.0.0","typescript":"^5.0.0","@types/jest":"^29.0.0","@types/node":"^20.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"peerDependencies":{"dotenv":">=16.0.0"},"peerDependenciesMeta":{"dotenv":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/sdk_2.3.0_1778028872107_0.9580042740784789","host":"s3://npm-registry-packages-npm-production"}},"2.4.0":{"name":"@ascend-ai/sdk","version":"2.4.0","description":"ASCEND SDK - Enterprise AI Governance with fail mode, circuit breaker, and MCP integration","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"require":"./dist/index.js","import":"./dist/index.mjs","types":"./dist/index.d.ts"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:coverage":"vitest --coverage","lint":"eslint src/","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["ai","authorization","governance","enterprise","security","compliance","soc2","hipaa","pci-dss","typescript","mcp","circuit-breaker","fail-mode"],"author":{"name":"ASCEND by OW-AI","email":"support@ascendowkai.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Amplify-Cost/owkai-pilot-backend.git"},"homepage":"https://ascendowkai.com","bugs":{"url":"https://github.com/Amplify-Cost/owkai-pilot-backend/issues"},"engines":{"node":">=16.0.0"},"dependencies":{"axios":"^1.6.0"},"devDependencies":{"@types/node":"^20.0.0","@types/jest":"^29.0.0","tsup":"^8.0.0","typescript":"^5.0.0","jest":"^29.0.0","ts-jest":"^29.0.0","vitest":"^1.0.0","eslint":"^8.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0"},"peerDependencies":{"dotenv":">=16.0.0"},"peerDependenciesMeta":{"dotenv":{"optional":true}},"_id":"@ascend-ai/sdk@2.4.0","gitHead":"2df94072129a7cd7b6d2871f471aae7406672670","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-BijryA5Ou6PlOkIB0AXObXO3+45EgGFUed+3O35PMW4TmbiqwgV/uroE2Zc6MFwc5uVjd/HCP/4OL319zhXjkw==","shasum":"691b47d90f851497e4ea8053881ad0eb3c2e940c","tarball":"https://registry.npmjs.org/@ascend-ai/sdk/-/sdk-2.4.0.tgz","fileCount":8,"unpackedSize":670450,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFQ7wXachw9B5Xgt4HdiCtskQCTbf4Xfxq21VvS70AiiAiEAz8+pzznQGvORBya1xysVUDkdH2PKIwWUYzRigwlaL1M="}]},"_npmUser":{"name":"ascend_security","email":"info@ow-kai.com"},"directories":{},"maintainers":[{"name":"ascend_security","email":"info@ow-kai.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_2.4.0_1779996153387_0.9725349634341851"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-29T01:56:20.071Z","modified":"2026-05-28T19:22:33.736Z","2.1.0":"2026-03-29T01:56:20.485Z","2.1.1":"2026-04-12T17:56:21.411Z","2.2.0":"2026-05-06T00:38:22.265Z","2.3.0":"2026-05-06T00:54:32.360Z","2.4.0":"2026-05-28T19:22:33.598Z"},"bugs":{"url":"https://github.com/Amplify-Cost/owkai-pilot-backend/issues"},"author":{"name":"ASCEND by OW-AI","email":"support@ascendowkai.com"},"license":"MIT","homepage":"https://ascendowkai.com","keywords":["ai","authorization","governance","enterprise","security","compliance","soc2","hipaa","pci-dss","typescript","mcp","circuit-breaker","fail-mode"],"repository":{"type":"git","url":"git+https://github.com/Amplify-Cost/owkai-pilot-backend.git"},"description":"ASCEND SDK - Enterprise AI Governance with fail mode, circuit breaker, and MCP integration","maintainers":[{"name":"ascend_security","email":"info@ow-kai.com"}],"readme":"# ASCEND Node.js/TypeScript SDK\n\nEnterprise-grade AI governance SDK for Node.js and TypeScript applications.\n\n## Features\n\n- **Fail Mode Configuration** - Choose between fail-closed (secure) or fail-open (available) when ASCEND is unreachable\n- **Circuit Breaker Pattern** - Automatic failure detection with graceful recovery\n- **Agent Registration** - Register agents with capabilities and permissions\n- **Action Evaluation** - Real-time authorization decisions with risk scoring\n- **Completion Logging** - Track action success/failure for audit trails\n- **Approval Workflows** - Human-in-the-loop approval for high-risk actions\n- **MCP Integration** - Higher-order functions for MCP server tools\n- **HMAC-SHA256 Signing** - Request integrity verification\n- **Structured Logging** - JSON logs with automatic API key masking\n- **Full TypeScript Support** - Complete type definitions included\n\n## Installation\n\n```bash\nnpm install @ascend-ai/sdk\n# or\nyarn add @ascend-ai/sdk\n```\n\n## Quick Start\n\n```typescript\nimport { AscendClient, FailMode, Decision } from '@ascend-ai/sdk';\n\nasync function main() {\n  // Initialize client\n  const client = new AscendClient({\n    apiKey: 'owkai_your_api_key',\n    agentId: 'agent-001',\n    agentName: 'My AI Agent',\n    failMode: FailMode.CLOSED,  // Block on ASCEND unreachable\n  });\n\n  // Register agent (call once on startup)\n  await client.register({\n    agentType: 'automation',\n    capabilities: ['data_access', 'file_operations'],\n    allowedResources: ['production_db', '/var/log/*'],\n  });\n\n  // Evaluate action before execution\n  const decision = await client.evaluateAction({\n    actionType: 'database.query',\n    resource: 'production_db',\n    parameters: { query: 'SELECT * FROM users WHERE active = true' },\n  });\n\n  if (decision.decision === Decision.ALLOWED) {\n    // Execute your action\n    const result = await executeDatabaseQuery();\n\n    // Log completion\n    await client.logActionCompleted(\n      decision.actionId,\n      { rowsReturned: result.length },\n      150  // duration in ms\n    );\n  } else if (decision.decision === Decision.DENIED) {\n    console.log(`Action denied: ${decision.reason}`);\n    console.log(`Policy violations: ${decision.policyViolations}`);\n  } else if (decision.decision === Decision.PENDING) {\n    console.log(`Awaiting approval from: ${decision.requiredApprovers}`);\n  }\n\n  // Governance verdict attribution (npm 2.4.0)\n  // Inspect WHY the decision was reached:\n  console.log(decision.enforcementDecision);\n  // 'auto_approved' | 'pending_approval' | 'denied' | 'escalated'\n\n  console.log(decision.enforcementDecisionSource);\n  // 'threshold' | 'policy' | 'smart_rule' |\n  // 'code_analysis' | 'prompt_security'\n\n  console.log(decision.riskScoreSource);\n  // 'cvss' | 'policy' | 'code_analysis' |\n  // 'prompt_security' | 'pipeline'\n\n  // Shadow scoring — undefined when org has no shadow config\n  console.log(decision.shadowEnforcementDecision);\n}\n\nmain();\n```\n\n## Fail Mode Configuration\n\nASCEND supports two fail modes for handling service unavailability:\n\n### Fail-Closed (Recommended for Production)\n\n```typescript\nconst client = new AscendClient({\n  apiKey: '...',\n  agentId: '...',\n  agentName: '...',\n  failMode: FailMode.CLOSED,  // Default\n});\n```\n\nWhen ASCEND is unreachable:\n- All actions are **blocked**\n- `ConnectionError` or `CircuitBreakerOpenError` thrown\n- Ensures no unauthorized actions occur\n\n### Fail-Open (Use with Caution)\n\n```typescript\nconst client = new AscendClient({\n  apiKey: '...',\n  agentId: '...',\n  agentName: '...',\n  failMode: FailMode.OPEN,\n});\n```\n\nWhen ASCEND is unreachable:\n- Actions are **allowed** to proceed\n- Returns synthetic `ALLOWED` decision with `fail_open_mode` condition\n- Use only when availability is critical\n\n## Circuit Breaker\n\nThe SDK includes an automatic circuit breaker to prevent cascading failures:\n\n```typescript\nconst client = new AscendClient({\n  apiKey: '...',\n  agentId: '...',\n  agentName: '...',\n  circuitBreakerOptions: {\n    failureThreshold: 5,     // Open after 5 failures\n    recoveryTimeout: 30,     // Try recovery after 30s\n    halfOpenMaxCalls: 3,     // Allow 3 test calls in half-open\n  },\n});\n\n// Check circuit state\nconst state = client.getCircuitBreakerState();\nconsole.log(`State: ${state.state}, Failures: ${state.failures}`);\n\n// Reset circuit breaker\nclient.resetCircuitBreaker();\n```\n\nCircuit states:\n- **CLOSED**: Normal operation, requests flow through\n- **OPEN**: After threshold failures, requests fail immediately\n- **HALF_OPEN**: After recovery timeout, limited test requests allowed\n\n## MCP Server Integration\n\nIntegrate ASCEND governance with MCP (Model Context Protocol) servers:\n\n```typescript\nimport { AscendClient } from '@ascend-ai/sdk';\nimport { mcpGovernance, highRiskAction } from '@ascend-ai/sdk/mcp';\n\nconst client = new AscendClient({ ... });\n\n// Basic governance wrapper\nconst queryDatabase = mcpGovernance(client, {\n  actionType: 'database.query',\n  resource: 'production_db',\n})(async (sql: string) => {\n  return await db.execute(sql);\n});\n\n// High-risk action requiring human approval\nconst deleteRecords = highRiskAction(client, 'database.delete', 'production_db')(\n  async (table: string, whereClause: string) => {\n    return await db.execute(`DELETE FROM ${table} WHERE ${whereClause}`);\n  }\n);\n\n// Use the governed functions\nconst result = await queryDatabase('SELECT * FROM users');\n```\n\n### MCP Governance Configuration\n\n```typescript\nimport { mcpGovernance, MCPGovernanceConfig } from '@ascend-ai/sdk/mcp';\n\nconst config: MCPGovernanceConfig = {\n  waitForApproval: true,           // Wait for pending approvals\n  approvalTimeoutMs: 300000,       // 5 minute timeout\n  approvalPollIntervalMs: 5000,    // Check every 5 seconds\n  raiseOnDenial: true,             // Throw error on denial\n  logAllDecisions: true,           // Log all authorization decisions\n  onApprovalRequired: (decision, toolName) => {\n    notifyAdmin(`Approval needed for ${toolName}`);\n  },\n};\n\nconst writeConfig = mcpGovernance(client, {\n  actionType: 'file.write',\n  resource: '/etc/config',\n  config,\n})(writeToFile);\n```\n\n### Middleware Pattern\n\n```typescript\nimport { MCPGovernanceMiddleware } from '@ascend-ai/sdk/mcp';\n\nconst middleware = new MCPGovernanceMiddleware(client);\n\n// Wrap multiple tools\nconst tools = {\n  query: middleware.wrap('database.query', 'prod_db', queryFn),\n  write: middleware.wrap('file.write', '/var/log', writeFn),\n  delete: middleware.wrapHighRisk('database.delete', 'prod_db', deleteFn),\n};\n\n// Check governed tools\nconsole.log(`Governed tools: ${middleware.governedTools}`);\n```\n\n## Security Guarantees\n\nThe SDK enforces several security invariants at the library boundary, before any network call:\n\n- **TLS enforced** — `http://` URLs are rejected for non-local hosts. The constructor throws `ConfigurationError` if `apiUrl` is `http://` and the host is not `localhost`, `127.0.0.1`, `0.0.0.0`, `::1` / `[::1]`, or `*.local`. Plain HTTP would expose the API key on the wire; this is a fail-secure default.\n- **API key masking** — API keys are never written to log output. The logger redacts any string matching the `owkai_*` pattern (in both the message and the `extra` dict) before serialization.\n- **Error header stripping** — credentials are stripped from `axios` error objects automatically. The SDK installs a response error interceptor that deletes `error.config.headers`, `error.response.config.headers`, `error.request._headers`, and `error.request._header` before the error propagates. This prevents accidental credential leakage through error logs, Sentry traces, or rethrows.\n- **Input validation** — `ValidationError` is thrown synchronously before any network call when required fields are missing. `evaluateAction()` rejects empty/whitespace `actionType` or `resource` with a populated `fieldErrors` map, so callers can branch on the specific missing field instead of debugging a downstream null-deref.\n\n## Approval Workflows\n\nHandle human-in-the-loop approvals for high-risk actions:\n\n```typescript\n// Request with automatic approval waiting\nconst decision = await client.evaluateAction({\n  actionType: 'financial.transfer',\n  resource: 'payment_gateway',\n  parameters: { amount: 50000, currency: 'USD' },\n  waitForApproval: true,        // Block until approved/denied\n  approvalTimeout: 300000,      // 5 minute timeout\n  requireHumanApproval: true,   // Force human review\n});\n\n// Manual approval polling\nconst decision = await client.evaluateAction({\n  actionType: 'financial.transfer',\n  resource: 'payment_gateway',\n  parameters: { amount: 50000 },\n});\n\nif (decision.decision === Decision.PENDING) {\n  const approvalId = decision.approvalRequestId!;\n\n  // Poll for approval\n  while (true) {\n    const status = await client.checkApproval(approvalId);\n    if (status.status === 'approved') {\n      // Execute action\n      break;\n    } else if (status.status === 'rejected') {\n      // Handle rejection\n      break;\n    }\n    await sleep(5000);\n  }\n}\n```\n\n## Webhook Configuration\n\nReceive real-time notifications for authorization events:\n\n```typescript\nawait client.configureWebhook({\n  url: 'https://your-app.com/webhooks/ascend',\n  events: [\n    'action.evaluated',\n    'action.approved',\n    'action.denied',\n    'action.completed',\n    'action.failed',\n  ],\n  secret: 'your_webhook_secret',  // For signature verification\n});\n```\n\n## Structured Logging\n\nThe SDK includes structured JSON logging with automatic API key masking:\n\n```typescript\nconst client = new AscendClient({\n  apiKey: '...',\n  agentId: '...',\n  agentName: '...',\n  logLevel: 'DEBUG',  // DEBUG, INFO, WARNING, ERROR\n  jsonLogs: true,     // Enable JSON format\n});\n\n// Logs automatically mask API keys:\n// {\"timestamp\":\"2026-01-15T10:30:00Z\",\"level\":\"INFO\",\"message\":\"Evaluating action\",\"api_key\":\"owkai_****\"}\n```\n\n## Error Handling\n\n```typescript\nimport {\n  AscendClient,\n  AuthenticationError,\n  AuthorizationError,\n  CircuitBreakerOpenError,\n  ConnectionError,\n  TimeoutError,\n  RateLimitError,\n} from '@ascend-ai/sdk';\n\ntry {\n  const decision = await client.evaluateAction({ ... });\n} catch (error) {\n  if (error instanceof AuthenticationError) {\n    console.log(`Invalid API key: ${error.message}`);\n  } else if (error instanceof AuthorizationError) {\n    console.log(`Authorization denied: ${error.message}`);\n    console.log(`Policy violations: ${error.policyViolations}`);\n    console.log(`Risk score: ${error.riskScore}`);\n  } else if (error instanceof CircuitBreakerOpenError) {\n    console.log(`Service unavailable: ${error.message}`);\n    console.log(`Recovery in: ${error.recoveryTimeSeconds}s`);\n  } else if (error instanceof ConnectionError) {\n    console.log(`Connection failed: ${error.message}`);\n  } else if (error instanceof TimeoutError) {\n    console.log(`Request timed out after ${error.timeoutMs}ms`);\n  } else if (error instanceof RateLimitError) {\n    console.log(`Rate limited, retry after ${error.retryAfter}s`);\n  }\n}\n```\n\n## API Reference\n\n### AscendClient\n\n```typescript\ninterface AscendClientOptions {\n  apiKey: string;                    // Required: Organization API key\n  agentId: string;                   // Required: Unique agent identifier\n  agentName: string;                 // Required: Human-readable name\n  apiUrl?: string;                   // Default: 'https://pilot.owkai.app'\n  environment?: string;              // Default: 'production'\n  failMode?: FailMode;               // Default: FailMode.CLOSED\n  timeout?: number;                  // Request timeout in ms (default: 30000)\n  maxRetries?: number;               // Default: 3\n  debug?: boolean;                   // Enable debug logging\n  logLevel?: LogLevel;               // 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR'\n  jsonLogs?: boolean;                // Use JSON format (default: true)\n  enableMetrics?: boolean;           // Enable metrics collection\n  signingSecret?: string;            // For HMAC signing\n  circuitBreakerOptions?: {\n    failureThreshold?: number;       // Default: 5\n    recoveryTimeout?: number;        // Default: 30\n    halfOpenMaxCalls?: number;       // Default: 3\n  };\n}\n```\n\n### Methods\n\n| Method | Description |\n|--------|-------------|\n| `register(options)` | Register agent with ASCEND |\n| `evaluateAction(options)` | Evaluate action for authorization |\n| `logActionCompleted(actionId, result?, durationMs?)` | Log successful completion |\n| `logActionFailed(actionId, error, durationMs?)` | Log action failure |\n| `checkApproval(approvalRequestId)` | Check approval status |\n| `configureWebhook(options)` | Configure webhook notifications |\n| `testConnection()` | Test API connectivity |\n| `getCircuitBreakerState()` | Get circuit breaker state |\n| `resetCircuitBreaker()` | Reset circuit breaker |\n| `getMetrics()` | Get metrics snapshot |\n\n### Types\n\n```typescript\n// Decision enum — used in EvaluateActionResult.decision below.\n// AscendClient.evaluateAction() maps the backend wire vocabulary\n// ('approved' | 'auto_approved' | 'executed' → ALLOWED;\n//  'denied' → DENIED;\n//  'pending' | 'pending_approval' | 'escalated' → PENDING)\n// onto this enum.\nenum Decision {\n  ALLOWED = 'allowed',\n  DENIED = 'denied',\n  PENDING = 'pending',\n}\n\n// EvaluateActionResult — the return type of AscendClient.evaluateAction().\n// (Defined in src/client.ts; this is the authoritative shape callers\n// receive.) For the OWKAIClient v1 path, see AuthorizationDecision in\n// src/models.ts which has a different field set.\ninterface EvaluateActionResult {\n  /** Decision class (see enum above) */\n  decision: Decision;\n  /** Action ID assigned by the backend */\n  actionId: string;\n  /** Human-readable reason — populated on denial or pending */\n  reason?: string;\n  /** Calculated risk score (0-100) */\n  riskScore?: number;\n  /** Policy IDs/names the action violated, if any */\n  policyViolations: string[];\n  /** Conditions attached to an ALLOWED decision (e.g. fail_open_mode) */\n  conditions: string[];\n  /** Approval request ID — set when decision is PENDING */\n  approvalRequestId?: string;\n  /** Required approver IDs/emails for a PENDING decision */\n  requiredApprovers: string[];\n  /** ISO timestamp when the approval window expires */\n  expiresAt?: string;\n  /** Catch-all metadata dict — also mirrors every typed field below\n   *  (so callers reading metadata['enforcement_decision_source']\n   *  continue to work in addition to the typed accessors) */\n  metadata: Record<string, unknown>;\n\n  // Governance verdict attribution (npm 2.4.0 / SDK-ALIGN-001 Phase 2)\n  /** Authoritative governance verdict\n   *  (auto_approved | pending_approval | escalated | denied) */\n  enforcementDecision?: string;\n  /** Signal that produced the verdict\n   *  (threshold | policy | smart_rule | code_analysis | prompt_security) */\n  enforcementDecisionSource?: string;\n  /** Risk-score signal attribution\n   *  (code_analysis | prompt_security | cvss | policy | pipeline) */\n  riskScoreSource?: string;\n  /** Shadow-scoring verdict — observational only.\n   *  undefined when org has no active shadow threshold config. */\n  shadowEnforcementDecision?: string;\n  /** Shadow-scoring source. undefined when no shadow config. */\n  shadowEnforcementDecisionSource?: string;\n}\n\n// Registration response\ninterface RegisterResponse {\n  agentId: string;\n  status: string;\n  registeredAt: string;\n  capabilities: string[];\n  metadata?: Record<string, unknown>;\n}\n```\n\n## Legacy Client (v1.0)\n\nFor backward compatibility, the legacy `OWKAIClient` is still available:\n\n```typescript\nimport { OWKAIClient } from '@ascend-ai/sdk';\n\nconst client = new OWKAIClient({\n  apiKey: 'your-api-key',\n});\n\nconst decision = await client.submitAction({\n  agentId: 'agent-001',\n  agentName: 'My Agent',\n  actionType: ActionType.DATA_ACCESS,\n  resource: 'customer_data',\n});\n```\n\n## Compliance\n\nThis SDK supports the following compliance frameworks:\n\n- **SOC 2 Type II** (CC6.1) - Access control and audit trails\n- **HIPAA** (164.312(e)) - Transmission security\n- **PCI-DSS** (8.2, 8.3) - API key management, MFA\n- **NIST AI RMF** - Govern, Map, Measure, Manage\n- **NIST 800-63B** - Authentication standards\n\n## Support\n\n- Documentation: https://docs.ascendowkai.com\n- Issues: https://github.com/Amplify-Cost/owkai-pilot-backend/issues\n- Email: info@ow-kai.com\n","readmeFilename":"README.md"}