@kya-os/agentshield-shared

Shared types, schemas, and constants for AgentShield - the single source of truth for all TypeScript type definitions.

Installation

npm install @kya-os/agentshield-shared
# or
pnpm add @kya-os/agentshield-shared
# or
yarn add @kya-os/agentshield-shared

Overview

This package provides:

• Type Definitions: Core TypeScript types for detection, agents, and configuration
• Zod Schemas: Runtime validation schemas for all types
• Constants: Known agent patterns, headers, and IP ranges
• API Types: Request/response schemas for API communication
• Event Types: Behavioral and real-time event definitions

Usage

Import Types

import {
  DetectionInput,
  DetectionResult,
  AgentShieldConfig,
  AgentType,
  ConfidenceLevel
} from '@kya-os/agentshield-shared';

Use Zod Schemas for Validation

import { DetectionInputSchema } from '@kya-os/agentshield-shared';

// Validate input
const input = DetectionInputSchema.parse({
  userAgent: 'Mozilla/5.0...',
  ipAddress: '192.168.1.1',
  headers: {
    'User-Agent': 'Mozilla/5.0...'
  }
});

Access Constants

import { 
  KNOWN_AGENT_PATTERNS,
  CLOUD_PROVIDER_RANGES,
  AI_AGENT_HEADERS 
} from '@kya-os/agentshield-shared';

// Use predefined patterns
const openAIPattern = KNOWN_AGENT_PATTERNS.find(p => p.type === 'openai');

Type Categories

Core Types

• DetectionInput - Input data for agent detection
• DetectionResult - Result from detection engine
• AgentInfo - Information about detected agents
• ConfidenceLevel - Confidence levels (low, medium, high, very_high)

Configuration Types

• AgentShieldConfig - Main configuration object
• ExpressMiddlewareOptions - Express.js middleware configuration
• NextMiddlewareOptions - Next.js middleware configuration

Event Types

• BehavioralData - Mouse, keyboard, scroll events
• RealtimeEvent - Real-time detection events
• DetectionEvent - Specific detection event data

API Types

• DetectionRequest - API request format
• DetectionResponse - API response format
• ApiResponse<T> - Generic API response wrapper

Development

# Install dependencies
pnpm install

# Build the package
pnpm build

# Type check
pnpm type-check

# Watch mode
pnpm dev

License

MIT OR Apache-2.0