Alerts

import { Chaos } from '@chaoslabs/ai-sdk';
 
const chaos = new Chaos({ apiKey: process.env.CHAOS_API_KEY! });
 
// Sub-resources
chaos.alerts.subscriptions  // Manage alert subscriptions
chaos.alerts.inbox          // Triggered alert events
chaos.alerts.templates      // Predefined alert templates
chaos.alerts.settings       // Notification preferences
 
// Top-level methods
chaos.alerts.connect()                   // Real-time WebSocket stream
chaos.alerts.fromQuery({ ... })          // Create alert from natural language
chaos.alerts.getOnboarding()             // Get onboarding state
chaos.alerts.completeOnboarding({ ... }) // Complete onboarding

// Create a subscription
const sub = await chaos.alerts.subscriptions.create({
  alert: { alert_type: 'price_change', asset: 'ETH', target_price: 4000, condition: 'above' },
});
 
// List all subscriptions
const subs = await chaos.alerts.subscriptions.list();
 
// Get a specific subscription
const sub = await chaos.alerts.subscriptions.get('ua-abc123');
 
// Get detailed view with resolved parameters
const detail = await chaos.alerts.subscriptions.getDetail('ua-abc123');
 
// Get trigger history
const { events, total } = await chaos.alerts.subscriptions.getEvents('ua-abc123');
 
// Update
const updated = await chaos.alerts.subscriptions.update('ua-abc123', {
  channels: { inApp: true, push: true, telegram: false, email: false },
});
 
// Snooze for 1 hour, 1 day, or 1 week
await chaos.alerts.subscriptions.snooze('ua-abc123', '1d');
 
// Mute until manually resumed
await chaos.alerts.subscriptions.mute('ua-abc123');
 
// Mark all events as read
const { markedCount } = await chaos.alerts.subscriptions.markRead('ua-abc123');
 
// Delete
await chaos.alerts.subscriptions.delete('ua-abc123');

// List triggered alerts with filters
const { events, hasMore } = await chaos.alerts.inbox.list({
  readState: 'unread',
  severity: ['warning', 'critical'],
  limit: 20,
});
 
// Get unread count
const { unreadCount } = await chaos.alerts.inbox.unreadCount();
 
// Mark an event as read
await chaos.alerts.inbox.markRead('ta-abc123');
 
// Archive an event
await chaos.alerts.inbox.archive('ta-abc123');

// List all templates
const { templates, supportedChains } = await chaos.alerts.templates.list();
 
// Filter by category
const whaleTemplates = await chaos.alerts.templates.list('whales');
 
// Search by keyword
const results = await chaos.alerts.templates.list(undefined, 'price');

// Get current settings
const settings = await chaos.alerts.settings.get();
 
// Update notification channels
const updated = await chaos.alerts.settings.update({
  channels: { inApp: true, push: true, telegram: false, email: true },
  dnd: { enabled: true, startTime: '22:00', endTime: '08:00', timezone: 'UTC' },
});

const stream = chaos.alerts.connect();
 
stream.on('alert', (event) => {
  console.log(`${event.severity}: ${event.title}`);
});
 
stream.on('connected', () => console.log('Listening for alerts'));
stream.on('error', (err) => console.error(err));
 
// Later: disconnect
stream.close();

const result = await chaos.alerts.fromQuery({
  query: 'Alert me when ETH drops below $3000',
  userId: 'user-123',
});
 
if (result.mode === 'created') {
  console.log('Alert created:', result.alert?.name);
} else if (result.mode === 'interactive') {
  // Needs user confirmation — result.blocks contains the UI
} else if (result.mode === 'form') {
  // Needs additional parameters
}

// Price threshold
const priceAlert = {
  alert_type: 'price_change' as const,
  asset: 'ETH',
  target_price: 4000,
  condition: 'above' as const,
};
 
// Price percentage change
const percentAlert = {
  alert_type: 'price_change' as const,
  asset: 'BTC',
  change_percent: 10,
  direction: 'down' as const,
};
 
// Volume spike
const volumeAlert = {
  alert_type: 'volume' as const,
  asset: 'SOL',
  threshold_percent: 200,
  time_window: '1h',
};
 
// Whale watch
const whaleAlert = {
  alert_type: 'whale_watch' as const,
  chain: 'ethereum',
  min_balance: 1000000,
  profit_type: 'realized' as const,
};
 
// Dormant wallet
const dormantAlert = {
  alert_type: 'dormant_wallet' as const,
  wallet: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  dormant_days: 90,
};
 
// Token transfer
const transferAlert = {
  alert_type: 'token_transfer' as const,
  symbol: 'USDC',
  min_amount: 1000000,
  chain: 'ethereum',
};

interface UserAlert {
  id: string;                    // "ua-d7309261..."
  userId: string;
  templateId: string | null;
  name: string;
  alertType: AlertType;
  alertConfig: AlertConfig;
  scope: AlertScope;
  severityPolicy: SeverityPolicy;
  channels: ChannelRouting;
  status: AlertStatus;           // 'active' | 'paused' | 'snoozed'
  cooldownSeconds: number;
  debounceConfig: DebounceConfig;
  createdFrom: AlertCreatedFrom; // 'chat' | 'library'
  createdAt: string;             // ISO 8601
  updatedAt: string;
  lastFiredAt: string | null;
  fireCount7d: number;
  webhook?: WebhookConfig;
}

interface TriggeredAlert {
  id: string;                    // "ta-60a5a3feae3b"
  userId: string;
  subscriptionId: string;        // matches UserAlert.id
  alert: AlertConfig;
  chain: string;
  severity: AlertSeverity;       // 'watch' | 'warning' | 'critical'
  title: string;
  summary: string;
  evidence: EvidencePayload;
  transactionContext: TransactionContext | null;
  readState: ReadState;          // 'unread' | 'read'
  archived: boolean;
  triggeredAt: string;           // ISO 8601
  createdAt: string;
}

interface AlertScope {
  assets: string[];
  chains: string[];
  wallets: string[];
  positions?: string[] | null;
}
 
interface SeverityPolicy {
  watch?: SeverityCondition;
  warning?: SeverityCondition;
  critical?: SeverityCondition;
}
 
interface SeverityCondition {
  condition: string;
  description: string;
}
 
interface ChannelRouting {
  inApp: boolean;
  push: boolean;
  telegram: boolean;
  email: boolean;
}
 
interface DebounceConfig {
  cooldownSeconds: number;
  recurring: boolean;
}
 
interface WebhookConfig {
  url: string;
  secret?: string;  // for HMAC-SHA256 signing
}
 
interface EvidencePayload {
  dataPoints: EvidenceDataPoint[];
  chartData: ChartData | null;
  sourceLinks: SourceLink[] | null;
}
 
interface EvidenceDataPoint {
  label: string;
  value: string;
  unit: string | null;
}
 
interface ChartData {
  timestamps: string[];
  values: number[];
  threshold_line?: number;
}
 
interface SourceLink {
  label: string;
  url: string;
}
 
interface TransactionContext {
  transactionHash: string;
  blockNumber: number;
  blockTimestamp: string;
  fromAddress: string;
  toAddress: string;
}

interface AlertSettings {
  channels: ChannelRouting;
  severityRouting?: SeverityRoutingMatrix;
  chatPings?: ChatPingConfig;
  dnd?: DndConfig;
}
 
interface SeverityRoutingMatrix {
  watch: ChannelRouting;
  warning: ChannelRouting;
  critical: ChannelRouting;
}
 
interface ChatPingConfig {
  enabled: boolean;
  warningAndCriticalOnly: boolean;
}
 
interface DndConfig {
  enabled: boolean;
  startTime?: string;
  endTime?: string;
  timezone?: string;
}

interface AlertTemplate {
  id: string;
  name: string;
  category: AlertCategory;
  description: string;
  bestFor?: string;
  requiredParams: ParamSchema[];
  defaultParams?: Record<string, unknown>;
  severityPolicy: SeverityPolicy;
  allowedScopes?: string[];
  defaultChannels?: ChannelRouting;
  rateCost?: number;
}
 
interface ParamSchema {
  key: string;
  label: string;
  type: 'string' | 'number' | 'currency' | 'select';
  required: boolean;
  options?: string[];
  default?: string | number;
}

interface OnboardingState {
  userId: string;
  completed: boolean;
  goal?: string;
  riskProfile?: string;
}

interface CreateSubscriptionParams {
  alert: AlertConfig;
  webhook?: WebhookConfig;
}
 
interface UpdateSubscriptionParams {
  alertConfig?: AlertConfig;
  channels?: Partial<ChannelRouting>;
  severityPolicy?: Partial<SeverityPolicy>;
  status?: AlertStatus;
  cooldownSeconds?: number;
  webhook?: WebhookConfig | null;  // null to remove
}
 
interface InboxFilters {
  readState?: 'all' | 'unread';
  severity?: AlertSeverity[];
  category?: AlertCategory[];
  includeArchived?: boolean;
  limit?: number;
  offset?: number;
}
 
interface InboxResponse {
  events: TriggeredAlert[];
  hasMore: boolean;
  cursor?: string;
}
 
interface UnreadCountResponse {
  unreadCount: number;
}
 
interface TemplatesResponse {
  templates: AlertTemplate[];
  supportedChains: string[];
}
 
interface SubscriptionDetailResponse {
  subscription: UserAlert;
  params: Record<string, unknown>;
}
 
interface SubscriptionEventsResponse {
  events: TriggeredAlert[];
  total: number;
}
 
interface AlertFromQueryParams {
  query: string;
  userId: string;
  sessionId?: string;
  walletAddress?: string;
  chain?: string;
}
 
interface AlertFromQueryResponse {
  mode: 'created' | 'interactive' | 'form' | 'error';
  alert?: UserAlert;
  blocks?: unknown[];
  error?: string;
}
 
interface SuccessResponse {
  success: boolean;
}
 
interface MarkReadResponse {
  markedCount: number;
}