{"_id":"@agent-action-firewall/sdk","_rev":"2-1b8d8787f840583cbef09f24379fa843","name":"@agent-action-firewall/sdk","dist-tags":{"latest":"1.0.0"},"versions":{"0.1.0":{"name":"@agent-action-firewall/sdk","version":"0.1.0","keywords":["ai","agent","firewall","security","policy","governance","compliance","audit","human-in-the-loop","approval-workflow","ai-safety","llm","openai","anthropic","langchain"],"author":{"name":"Agent Action Firewall","email":"info@agentactionfirewall.com"},"license":"MIT","_id":"@agent-action-firewall/sdk@0.1.0","maintainers":[{"name":"bshannon","email":"bshannon@gmail.com"}],"homepage":"https://agentactionfirewall.com","bugs":{"url":"https://github.com/fubak/agent-action-firewall/issues"},"dist":{"shasum":"8931fc9be5f2d2e0a414dfe35b8b603a59b35cd2","tarball":"https://registry.npmjs.org/@agent-action-firewall/sdk/-/sdk-0.1.0.tgz","fileCount":6,"integrity":"sha512-8DbKFRpt0rJtKp/J2TDjsMZ2qJ75rtDavX9mwo/IHdYkIauXHMTL/8ZPaSfxFBzDKA24W/Haq44cn0vmCxOgQg==","signatures":[{"sig":"MEUCIQCdkO8Hg5hEwohndAkqXqJSr2akQcR9h0J9UBpJ6Alw2QIgevr/J8nixkQ41AfpuQvY3sAZOLkRpUF6qyYaSDSzQIo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37485},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"f89ed33990c9ab810be2fdb6230c5989084bb49b","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","lint":"eslint src --ext .ts","test":"vitest run","build":"tsup src/index.ts --format cjs,esm --dts","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build && npm run test"},"_npmUser":{"name":"bshannon","email":"bshannon@gmail.com"},"repository":{"url":"git+https://github.com/fubak/agent-action-firewall.git","type":"git","directory":"packages/sdk-typescript"},"_npmVersion":"11.7.0","description":"Official TypeScript SDK for Agent Action Firewall - AI agent security platform","directories":{},"_nodeVersion":"20.19.6","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^4.0.16","typescript":"^5.3.0","@types/node":"^20.10.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1767117446155_0.5469411170910354","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@agent-action-firewall/sdk","version":"1.0.0","description":"Official TypeScript SDK for Agent Action Firewall - AI agent security platform","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup src/index.ts --format cjs,esm --dts","dev":"tsup src/index.ts --format cjs,esm --dts --watch","typecheck":"tsc --noEmit","lint":"eslint src --ext .ts","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build && npm run test"},"dependencies":{},"devDependencies":{"@types/node":"^20.10.0","tsup":"^8.0.0","typescript":"^5.3.0","vitest":"^4.0.16"},"keywords":["ai","agent","firewall","security","policy","governance","compliance","audit","human-in-the-loop","approval-workflow","ai-safety","llm","openai","anthropic","langchain"],"license":"MIT","author":{"name":"Agent Action Firewall","email":"info@agentactionfirewall.com"},"homepage":"https://agentactionfirewall.com","bugs":{"url":"https://github.com/fubak/agent-action-firewall/issues"},"repository":{"type":"git","url":"git+https://github.com/fubak/agent-action-firewall.git","directory":"packages/sdk-typescript"},"engines":{"node":">=18"},"publishConfig":{"access":"public"},"gitHead":"8c8574e96ce766d00f29e444b8e2940632734bbb","_id":"@agent-action-firewall/sdk@1.0.0","_nodeVersion":"24.12.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-pX0QhU9nxXRJDl8CdBHnWfRFwBkb1lkAfbRwKYEAVxwQrZXrdF/FkKw4BPjsL7qLcg13YUSMfnNseCZRinIR8A==","shasum":"43875c5c7294d4539b092e3107f2d1a343a8fec6","tarball":"https://registry.npmjs.org/@agent-action-firewall/sdk/-/sdk-1.0.0.tgz","fileCount":6,"unpackedSize":64496,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIF/1RpcR+ryoNvvzKwVd8ggvIEABdY4o9OFjYvTBlG8ZAiEAvcvLwsaE6TRrXSggULLN2XwKNhqoC7lMm8CtvUZ0Eco="}]},"_npmUser":{"name":"bshannon","email":"bshannon@gmail.com"},"directories":{},"maintainers":[{"name":"bshannon","email":"bshannon@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.0.0_1768772743793_0.02205770928793349"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-30T17:57:26.051Z","modified":"2026-01-18T21:45:44.098Z","0.1.0":"2025-12-30T17:57:26.290Z","1.0.0":"2026-01-18T21:45:43.953Z"},"bugs":{"url":"https://github.com/fubak/agent-action-firewall/issues"},"author":{"name":"Agent Action Firewall","email":"info@agentactionfirewall.com"},"license":"MIT","homepage":"https://agentactionfirewall.com","keywords":["ai","agent","firewall","security","policy","governance","compliance","audit","human-in-the-loop","approval-workflow","ai-safety","llm","openai","anthropic","langchain"],"repository":{"type":"git","url":"git+https://github.com/fubak/agent-action-firewall.git","directory":"packages/sdk-typescript"},"description":"Official TypeScript SDK for Agent Action Firewall - AI agent security platform","maintainers":[{"name":"bshannon","email":"bshannon@gmail.com"}],"readme":"# Agent Action Firewall TypeScript SDK\n\nOfficial TypeScript SDK for the Agent Action Firewall - a security layer for AI agents.\n\n## Installation\n\n```bash\nnpm install @agent-action-firewall/sdk\n# or\npnpm add @agent-action-firewall/sdk\n# or\nyarn add @agent-action-firewall/sdk\n```\n\n## Quick Start\n\n```typescript\nimport { AgentFirewallClient } from '@agent-action-firewall/sdk';\n\nconst client = new AgentFirewallClient({\n  baseUrl: 'https://api.agentactionfirewall.com',\n  apiKey: process.env.AGENT_FIREWALL_API_KEY!,\n  agentId: 'my-agent',\n});\n\n// Submit an action for policy evaluation\nconst response = await client.submitAction({\n  tool: 'http_proxy',\n  operation: 'POST',\n  params: {\n    url: 'https://api.example.com/data',\n    body: { key: 'value' },\n  },\n});\n\nconsole.log('Action status:', response.status);\n```\n\n## Usage\n\n### Submit an Action\n\n```typescript\nconst response = await client.submitAction({\n  tool: 'http_proxy',\n  operation: 'POST',\n  params: {\n    url: 'https://api.example.com/data',\n    body: { key: 'value' },\n  },\n  // Optional: prevent duplicate submissions\n  idempotencyKey: 'unique-request-id',\n});\n\nswitch (response.status) {\n  case 'allowed':\n    // Action is allowed, execute it\n    console.log('Action allowed');\n    break;\n  case 'denied':\n    // Action was denied by policy\n    console.log('Denied:', response.decision?.reason);\n    break;\n  case 'pending_approval':\n    // Requires human approval\n    console.log('Waiting for approval:', response.approvalId);\n    break;\n}\n```\n\n### Get Action Status\n\n```typescript\nconst detail = await client.getAction(actionId);\nconsole.log('Status:', detail.status);\nconsole.log('Decision:', detail.decision);\nconsole.log('Approval:', detail.approval);\n```\n\n### Wait for Approval\n\n```typescript\n// Wait up to 5 minutes for approval\nconst finalStatus = await client.waitForApproval(actionId, {\n  timeout: 300000,\n  interval: 2000, // Poll every 2 seconds\n  onStatusChange: (status) => {\n    console.log('Status update:', status.status);\n  },\n});\n\nconsole.log('Final status:', finalStatus.status);\n```\n\n### Submit and Wait\n\nConvenience method that submits an action and waits for completion:\n\n```typescript\nconst result = await client.submitAndWait({\n  tool: 'jira',\n  operation: 'create_ticket',\n  params: {\n    project: 'PROJ',\n    summary: 'New ticket',\n    description: 'Created by AI agent',\n  },\n});\n\nif (result.status === 'succeeded') {\n  console.log('Ticket created:', result.execution?.result);\n}\n```\n\n## Configuration Options\n\n```typescript\nconst client = new AgentFirewallClient({\n  // Required\n  baseUrl: 'https://api.agentactionfirewall.com',\n  apiKey: 'your-api-key',\n  agentId: 'your-agent-id',\n\n  // Optional\n  timeout: 30000, // Request timeout in ms (default: 30000)\n  debug: false, // Enable debug logging\n});\n```\n\n## Error Handling\n\n```typescript\nimport { AgentFirewallError } from '@agent-action-firewall/sdk';\n\ntry {\n  await client.submitAction({ ... });\n} catch (error) {\n  if (error instanceof AgentFirewallError) {\n    console.error('Code:', error.code);\n    console.error('Message:', error.message);\n    console.error('Status:', error.statusCode);\n    console.error('Details:', error.details);\n  }\n}\n```\n\n### Error Codes\n\n- `CONFIG_ERROR` - Invalid configuration\n- `NETWORK_ERROR` - Network connectivity issue\n- `TIMEOUT_ERROR` - Request or polling timeout\n- `API_ERROR` - API returned an error response\n\n## Types\n\nThe SDK exports TypeScript types for all request and response objects:\n\n```typescript\nimport type {\n  AgentFirewallConfig,\n  ActionRequest,\n  ActionResponse,\n  ActionDetail,\n  ActionDecision,\n  ApprovalSummary,\n  ExecutionSummary,\n  PollOptions,\n} from '@agent-action-firewall/sdk';\n```\n\n## Integration Examples\n\n### OpenAI Function Calling\n\nWrap OpenAI function calls with firewall governance:\n\n```typescript\nimport OpenAI from 'openai';\nimport { AgentFirewallClient } from '@agent-action-firewall/sdk';\n\nconst openai = new OpenAI();\nconst firewall = new AgentFirewallClient({\n  baseUrl: 'https://api.agentactionfirewall.com',\n  apiKey: process.env.AGENT_FIREWALL_API_KEY!,\n  agentId: 'openai-assistant',\n});\n\n// Define a governed function\nasync function executeFunction(name: string, args: Record<string, unknown>) {\n  // Check with firewall before executing\n  const response = await firewall.submitAndWait({\n    tool: name,\n    operation: 'execute',\n    params: args,\n  });\n\n  if (response.status === 'denied') {\n    throw new Error(`Action denied: ${response.decision?.reason}`);\n  }\n\n  // Execute the actual function\n  return await actualFunctionExecution(name, args);\n}\n\n// Use with OpenAI\nconst completion = await openai.chat.completions.create({\n  model: 'gpt-4',\n  messages: [{ role: 'user', content: 'Create a Jira ticket for the bug' }],\n  tools: [\n    {\n      type: 'function',\n      function: {\n        name: 'create_jira_ticket',\n        parameters: { /* ... */ },\n      },\n    },\n  ],\n});\n\n// When OpenAI wants to call a function\nfor (const call of completion.choices[0].message.tool_calls || []) {\n  const result = await executeFunction(\n    call.function.name,\n    JSON.parse(call.function.arguments)\n  );\n}\n```\n\n### Anthropic Claude Tool Use\n\nIntegrate with Claude's tool use capabilities:\n\n```typescript\nimport Anthropic from '@anthropic-ai/sdk';\nimport { AgentFirewallClient } from '@agent-action-firewall/sdk';\n\nconst anthropic = new Anthropic();\nconst firewall = new AgentFirewallClient({\n  baseUrl: 'https://api.agentactionfirewall.com',\n  apiKey: process.env.AGENT_FIREWALL_API_KEY!,\n  agentId: 'claude-assistant',\n});\n\nasync function handleToolUse(toolName: string, toolInput: Record<string, unknown>) {\n  // Submit to firewall\n  const response = await firewall.submitAndWait({\n    tool: toolName,\n    operation: 'execute',\n    params: toolInput,\n    metadata: {\n      source: 'claude',\n      model: 'claude-3-opus',\n    },\n  });\n\n  if (response.status !== 'succeeded') {\n    return { error: `Action ${response.status}: ${response.decision?.reason}` };\n  }\n\n  return response.execution?.result;\n}\n\nconst message = await anthropic.messages.create({\n  model: 'claude-3-opus-20240229',\n  max_tokens: 1024,\n  tools: [\n    {\n      name: 'send_email',\n      description: 'Send an email to a recipient',\n      input_schema: {\n        type: 'object',\n        properties: {\n          to: { type: 'string' },\n          subject: { type: 'string' },\n          body: { type: 'string' },\n        },\n        required: ['to', 'subject', 'body'],\n      },\n    },\n  ],\n  messages: [{ role: 'user', content: 'Send an email to team@example.com' }],\n});\n\n// Process tool use blocks\nfor (const block of message.content) {\n  if (block.type === 'tool_use') {\n    const result = await handleToolUse(block.name, block.input);\n    // Continue conversation with result...\n  }\n}\n```\n\n### Vercel AI SDK\n\nUse with the Vercel AI SDK for streaming responses:\n\n```typescript\nimport { openai } from '@ai-sdk/openai';\nimport { streamText, tool } from 'ai';\nimport { z } from 'zod';\nimport { AgentFirewallClient } from '@agent-action-firewall/sdk';\n\nconst firewall = new AgentFirewallClient({\n  baseUrl: 'https://api.agentactionfirewall.com',\n  apiKey: process.env.AGENT_FIREWALL_API_KEY!,\n  agentId: 'vercel-ai-agent',\n});\n\nconst result = await streamText({\n  model: openai('gpt-4-turbo'),\n  tools: {\n    createTicket: tool({\n      description: 'Create a support ticket',\n      parameters: z.object({\n        title: z.string(),\n        description: z.string(),\n        priority: z.enum(['low', 'medium', 'high']),\n      }),\n      execute: async ({ title, description, priority }) => {\n        // Firewall check\n        const response = await firewall.submitAndWait({\n          tool: 'ticketing',\n          operation: 'create',\n          params: { title, description, priority },\n        });\n\n        if (response.status === 'denied') {\n          return { error: response.decision?.reason };\n        }\n\n        return { ticketId: response.execution?.result?.id };\n      },\n    }),\n  },\n  messages: [{ role: 'user', content: 'Create a high priority ticket for the outage' }],\n});\n```\n\n### LangChain.js Integration\n\nWrap LangChain tools with firewall governance:\n\n```typescript\nimport { ChatOpenAI } from '@langchain/openai';\nimport { DynamicStructuredTool } from '@langchain/core/tools';\nimport { AgentExecutor, createOpenAIToolsAgent } from 'langchain/agents';\nimport { AgentFirewallClient } from '@agent-action-firewall/sdk';\nimport { z } from 'zod';\n\nconst firewall = new AgentFirewallClient({\n  baseUrl: 'https://api.agentactionfirewall.com',\n  apiKey: process.env.AGENT_FIREWALL_API_KEY!,\n  agentId: 'langchain-agent',\n});\n\n// Create a governed tool\nconst governedSearchTool = new DynamicStructuredTool({\n  name: 'web_search',\n  description: 'Search the web for information',\n  schema: z.object({\n    query: z.string().describe('The search query'),\n  }),\n  func: async ({ query }) => {\n    // Check with firewall first\n    const response = await firewall.submitAndWait({\n      tool: 'web_search',\n      operation: 'search',\n      params: { query },\n    });\n\n    if (response.status === 'denied') {\n      throw new Error(`Search denied: ${response.decision?.reason}`);\n    }\n\n    // Execute actual search\n    return await performWebSearch(query);\n  },\n});\n\nconst llm = new ChatOpenAI({ model: 'gpt-4' });\nconst agent = await createOpenAIToolsAgent({\n  llm,\n  tools: [governedSearchTool],\n  prompt: /* your prompt */,\n});\n```\n\n### Express.js Middleware\n\nCreate middleware for API routes that require firewall approval:\n\n```typescript\nimport express from 'express';\nimport { AgentFirewallClient } from '@agent-action-firewall/sdk';\n\nconst app = express();\nconst firewall = new AgentFirewallClient({\n  baseUrl: 'https://api.agentactionfirewall.com',\n  apiKey: process.env.AGENT_FIREWALL_API_KEY!,\n  agentId: 'api-gateway',\n});\n\n// Middleware to check firewall for all agent actions\nconst firewallMiddleware = (toolName: string) => {\n  return async (req: express.Request, res: express.Response, next: express.NextFunction) => {\n    try {\n      const response = await firewall.submitAction({\n        tool: toolName,\n        operation: req.method,\n        params: {\n          path: req.path,\n          body: req.body,\n          query: req.query,\n        },\n        metadata: {\n          ip: req.ip,\n          userAgent: req.get('user-agent'),\n        },\n      });\n\n      if (response.status === 'denied') {\n        return res.status(403).json({\n          error: 'Action denied by policy',\n          reason: response.decision?.reason,\n          riskLevel: response.decision?.riskLevel,\n        });\n      }\n\n      if (response.status === 'pending_approval') {\n        return res.status(202).json({\n          message: 'Action requires approval',\n          approvalId: response.approvalId,\n          actionId: response.id,\n        });\n      }\n\n      // Attach action info to request for logging\n      req.firewallAction = response;\n      next();\n    } catch (error) {\n      next(error);\n    }\n  };\n};\n\n// Use on routes\napp.post('/api/agents/:agentId/execute',\n  firewallMiddleware('agent_execution'),\n  async (req, res) => {\n    // Action was approved, proceed with execution\n    const result = await executeAgentAction(req.body);\n    res.json(result);\n  }\n);\n```\n\n### Next.js API Route\n\nProtect Next.js API routes with firewall checks:\n\n```typescript\n// app/api/agent/action/route.ts\nimport { NextRequest, NextResponse } from 'next/server';\nimport { AgentFirewallClient } from '@agent-action-firewall/sdk';\n\nconst firewall = new AgentFirewallClient({\n  baseUrl: 'https://api.agentactionfirewall.com',\n  apiKey: process.env.AGENT_FIREWALL_API_KEY!,\n  agentId: 'nextjs-agent',\n});\n\nexport async function POST(request: NextRequest) {\n  const body = await request.json();\n\n  // Submit to firewall\n  const response = await firewall.submitAndWait({\n    tool: body.tool,\n    operation: body.operation,\n    params: body.params,\n  });\n\n  if (response.status === 'denied') {\n    return NextResponse.json(\n      { error: 'Denied', reason: response.decision?.reason },\n      { status: 403 }\n    );\n  }\n\n  if (response.status === 'succeeded') {\n    return NextResponse.json({\n      success: true,\n      result: response.execution?.result,\n    });\n  }\n\n  return NextResponse.json(\n    { error: 'Action failed', status: response.status },\n    { status: 400 }\n  );\n}\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}