@ciphyrshq/sdk 2.6.0

package/types.d.ts

@@ -0,0 +1,382 @@
+// @ciphyrshq/sdk — TypeScript declarations
+
+// ── Errors ────────────────────────────────────────────────────────────────────
+
+export declare class CiphyrsError extends Error {
+  status?: number;
+  code?:   string;
+  constructor(message: string, opts?: { status?: number; code?: string });
+}
+export declare class CiphyrsAuthError       extends CiphyrsError {}
+export declare class CiphyrsPermissionError extends CiphyrsError {}
+export declare class CiphyrsNotFoundError   extends CiphyrsError {}
+export declare class CiphyrsRateLimitError  extends CiphyrsError { retryAfter: number | null; }
+export declare class CiphyrsTimeoutError    extends CiphyrsError {}
+export declare class CiphyrsJobTimeoutError extends CiphyrsError { jobId: string; }
+
+// ── Shared types ──────────────────────────────────────────────────────────────
+
+export type Source  = 'PROMPT' | 'PASTE' | 'RAG' | 'TOOL_RESULT' | 'AGENT_MEMORY' | 'FILE_UPLOAD';
+export type Surface = 'vscode' | 'browser' | 'mcp' | 'api' | 'sdk';
+export type JobStatus = 'queued' | 'processing' | 'done' | 'failed';
+export type UserRole  = 'owner' | 'admin' | 'member';
+export type Plan      = 'free' | 'pro' | 'team' | 'enterprise';
+
+export interface EntitySummaryItem {
+  type:  string;
+  count: number;
+}
+
+// ── Scan ─────────────────────────────────────────────────────────────────────
+
+export interface MaskOptions {
+  sessionId?:   string;
+  entities?:    string[];
+  source?:      Source;
+  surface?:     Surface;
+  llmProvider?: string;
+}
+
+export interface MaskResult {
+  maskedText:    string;
+  sessionId:     string;
+  entitiesFound: number;
+  entitySummary: EntitySummaryItem[];
+}
+
+export interface MaskAsyncOptions extends MaskOptions {
+  webhookUrl?: string;
+}
+
+export interface MaskAsyncResult {
+  jobId:     string;
+  sessionId: string;
+  status:    'queued';
+}
+
+export interface JobResult {
+  jobId:         string;
+  status:        JobStatus;
+  sessionId:     string;
+  maskedText?:   string;
+  entitiesFound?: number;
+  entitySummary?: EntitySummaryItem[];
+  latencyMs?:    number;
+  error?:        string;
+}
+
+export interface RestoreOptions {
+  purge?: boolean;
+}
+
+export interface RestoreResult {
+  restoredText:   string;
+  tokensRestored: number;
+  purged:         boolean;
+}
+
+export interface WaitForJobOptions {
+  pollIntervalMs?: number;
+  timeoutMs?:      number;
+}
+
+export interface ProtectOptions extends MaskOptions {
+  /** Default true — purge vault after restore (data minimisation). */
+  purge?: boolean;
+}
+export interface ProtectContext {
+  sessionId: string;
+  entitiesFound: any[];
+}
+export interface ProtectResult {
+  /** Unmasked LLM response — return THIS to your end user. */
+  output: string;
+  /** What was actually sent to the LLM (placeholder version, for audit). */
+  maskedInput: string;
+  /** What the LLM returned, before unmask (audit). */
+  maskedOutput: string;
+  sessionId: string;
+  entitiesFound: any[];
+  tokensRestored: number;
+}
+export type ProtectLLMCall = (masked: string, ctx: ProtectContext) => Promise<string>;
+
+export declare class ScanResource {
+  mask(text: string, opts?: MaskOptions): Promise<MaskResult>;
+  maskAsync(text: string, opts?: MaskAsyncOptions): Promise<MaskAsyncResult>;
+  getJob(jobId: string): Promise<JobResult>;
+  waitForJob(jobId: string, opts?: WaitForJobOptions): Promise<JobResult>;
+  restore(maskedText: string, sessionId: string, opts?: RestoreOptions): Promise<RestoreResult>;
+  /** mask → LLM call → restore round-trip in one call. */
+  protect(userInput: string, llmCall: ProtectLLMCall, opts?: ProtectOptions): Promise<ProtectResult>;
+}
+
+// ── Auth ─────────────────────────────────────────────────────────────────────
+
+export interface RegisterResult {
+  token:  string;
+  apiKey: string;
+  user:   { id: string; email: string; name: string };
+}
+
+export interface LoginResult {
+  token: string;
+  user:  { id: string; email: string; name: string; role: UserRole };
+}
+
+export interface ApiKey {
+  id:          string;
+  name:        string;
+  prefix:      string;
+  scopes:      string[];
+  isActive:    boolean;
+  createdAt:   string;
+  lastUsedAt?: string;
+}
+
+export declare class AuthResource {
+  register(email: string, password: string, name: string): Promise<RegisterResult>;
+  login(email: string, password: string): Promise<LoginResult>;
+  createApiKey(opts?: { name?: string; scopes?: string[] }): Promise<{ apiKey: string; key: ApiKey }>;
+  listApiKeys(): Promise<{ apiKeys: ApiKey[] }>;
+  revokeApiKey(id: string): Promise<void>;
+}
+
+// ── Metrics ───────────────────────────────────────────────────────────────────
+
+export type TimeRange = '7d' | '30d' | '90d';
+
+export interface SummaryResult {
+  totalEvents:    number;
+  totalMasked:    number;
+  uniqueSessions: number;
+  avgLatencyMs:   number;
+}
+
+export interface TimeseriesPoint {
+  date:    string;
+  events:  number;
+  masked:  number;
+}
+
+export interface BreakdownItem {
+  label: string;
+  count: number;
+}
+
+export interface DetectionEvent {
+  id:           string;
+  sessionId:    string;
+  source:       Source;
+  surface:      Surface;
+  totalMasked:  number;
+  scanLatencyMs: number;
+  createdAt:    string;
+}
+
+export interface ComplianceReport {
+  from:         string;
+  to:           string;
+  totalEvents:  number;
+  totalMasked:  number;
+  bySource:     BreakdownItem[];
+  bySurface:    BreakdownItem[];
+}
+
+export interface ApiKeyBreakdown {
+  keyName:      string;
+  keyPrefix:    string;
+  events:       number;
+  piiMasked:    number;
+  avgLatencyMs: number;
+  lastUsed:     string;
+}
+
+export interface LatencyPercentilePoint {
+  day:    string;
+  p50:    number;
+  p95:    number;
+  p99:    number;
+  events: number;
+}
+
+export interface PeakHourPoint {
+  dow:    number;
+  hour:   number;
+  events: number;
+}
+
+export declare class MetricsResource {
+  summary(): Promise<SummaryResult>;
+  timeseries(opts?: { range?: TimeRange }): Promise<{ data: TimeseriesPoint[] }>;
+  byEntity(): Promise<{ data: BreakdownItem[] }>;
+  bySurface(): Promise<{ data: BreakdownItem[] }>;
+  bySource(): Promise<{ data: BreakdownItem[] }>;
+  byDeveloper(): Promise<{ data: BreakdownItem[] }>;
+  recentEvents(opts?: { limit?: number; offset?: number }): Promise<{ events: DetectionEvent[]; total: number }>;
+  eventDetail(eventId: string): Promise<{ event: DetectionEvent }>;
+  byApiKey(): Promise<{ by_api_key: ApiKeyBreakdown[] }>;
+  latencyPercentiles(): Promise<{ latency_percentiles: LatencyPercentilePoint[] }>;
+  peakHours(): Promise<{ peak_hours: PeakHourPoint[] }>;
+  complianceReport(opts?: { from?: string; to?: string }): Promise<ComplianceReport>;
+}
+
+// ── Tenant ────────────────────────────────────────────────────────────────────
+
+export interface TenantProfile {
+  id:       string;
+  name:     string;
+  plan:     Plan;
+  status:   'active' | 'suspended';
+  seats:    number;
+  settings: Record<string, unknown>;
+}
+
+export interface TeamMember {
+  id:        string;
+  email:     string;
+  name:      string;
+  role:      UserRole;
+  joinedAt:  string;
+}
+
+export declare class TenantResource {
+  profile(): Promise<TenantProfile>;
+  members(): Promise<{ members: TeamMember[] }>;
+  invite(email: string, role?: UserRole): Promise<void>;
+  updateSettings(settings: Record<string, unknown>): Promise<TenantProfile>;
+}
+
+// ── CiphyrsClient ─────────────────────────────────────────────────────────────
+
+export interface CiphyrsClientOptions {
+  /** API key (cyp_live_...) — for server-side integrations */
+  apiKey?:  string;
+  /** JWT token — for dashboard / management endpoints */
+  token?:   string;
+  /** Override gateway URL for VPC or on-prem deployments */
+  baseUrl?: string;
+  /** Override dashboard API URL */
+  dashUrl?: string;
+  /** Request timeout in milliseconds (default: 10000) */
+  timeout?: number;
+}
+
+// ── V58 Guard ────────────────────────────────────────────────────────────
+export type GuardDecision = 'allow' | 'block' | 'review';
+export type GuardPolicyMode = 'block_attacks' | 'block_critical' | 'review' | 'observe';
+export interface GuardCheckParams {
+  input?: string;
+  output?: string;
+  agentName?: string;
+  traceId?: string;
+  spanId?: string;
+  sessionId?: string;
+  userId?: string;
+  operationName?: string;
+  policyOverride?: GuardPolicyMode;
+}
+export interface GuardCheckResult {
+  decision_id: string;
+  decision: GuardDecision;
+  reason: string | null;
+  policy_mode: GuardPolicyMode;
+  detections: Array<{
+    attack_type: string;
+    severity: string;
+    confidence: number;
+    pattern_id: string;
+    pattern_name: string;
+    source_kind: string;
+  }>;
+  highest_severity: string | null;
+  highest_attack_type: string | null;
+  detections_count: number;
+  classifier_ms: number;
+  total_ms: number;
+}
+export interface GuardWrapResult {
+  blocked: boolean;
+  output: string | null;
+  reason?: string;
+  decision: GuardDecision;
+  detections?: GuardCheckResult['detections'];
+  decision_id: string;
+}
+export type GuardLLMCall = (input: string) => Promise<string>;
+
+export declare class GuardResource {
+  check(params: GuardCheckParams): Promise<GuardCheckResult>;
+  wrap(userInput: string, llmCall: GuardLLMCall, opts?: GuardCheckParams): Promise<GuardWrapResult>;
+  getPolicy(): Promise<{ policy_mode: GuardPolicyMode; modes: any[] }>;
+  setPolicy(mode: GuardPolicyMode): Promise<{ policy_mode: GuardPolicyMode }>;
+  decisions(opts?: { limit?: number; decision?: GuardDecision }): Promise<{ decisions: any[]; total: number }>;
+  stats(opts?: { days?: number }): Promise<any>;
+}
+
+// ── V55-V59 Security ─────────────────────────────────────────────────────
+export declare class SecurityResource {
+  // Detections
+  listDetections(params?: { days?: number; limit?: number; severity?: string; attack_type?: string; status?: string; agent_name?: string }): Promise<{ detections: any[]; total: number }>;
+  detectionSummary(opts?: { days?: number }): Promise<any>;
+  detectionTimeseries(opts?: { days?: number }): Promise<any>;
+  detectionsByTrace(traceId: string): Promise<{ trace_id: string; detections: any[]; total: number }>;
+  detectionContext(detectionId: string): Promise<any>;
+  setDetectionStatus(id: string, status: string, note?: string): Promise<any>;
+  // Custom rules
+  listRules(): Promise<{ rules: any[]; total: number }>;
+  createRule(rule: any): Promise<{ rule: any }>;
+  updateRule(id: string, rule: any): Promise<{ rule: any }>;
+  deleteRule(id: string): Promise<void>;
+  // Canaries
+  listCanaries(): Promise<{ canaries: any[]; total: number }>;
+  createCanary(canary: { name: string; token?: string; scope?: string; severity?: string; attack_type?: string; environment?: string }): Promise<{ canary: any; token: string; notice: string }>;
+  deleteCanary(id: string): Promise<void>;
+  // Threat intel
+  listIntelFeeds(): Promise<{ feeds: any[]; total: number }>;
+  refreshIntelFeed(id: string): Promise<{ result: any }>;
+  // Marketplace
+  marketplaceList(params?: { q?: string; category?: string; attack_type?: string }): Promise<{ rules: any[]; total: number }>;
+  marketplaceInstall(id: string): Promise<{ rule_id: string; notice: string }>;
+  // Benchmark
+  runBenchmark(target?: string): Promise<{ run: any }>;
+  benchmarkRuns(): Promise<{ runs: any[]; total: number }>;
+  // SIEM
+  listSiemTargets(): Promise<{ targets: any[]; total: number }>;
+  createSiemTarget(target: any): Promise<{ target: any }>;
+  testSiemTarget(id: string): Promise<{ result: any }>;
+  // Replay
+  listReplayJobs(): Promise<{ jobs: any[]; total: number }>;
+  createReplayJob(body: { pattern_id?: string; rule_id?: string; range_start: string; range_end: string }): Promise<{ job: any }>;
+}
+
+// ── V54 Reports ──────────────────────────────────────────────────────────
+export declare class ReportsResource {
+  generateProd(opts: { title?: string; rangeStart: string | Date; rangeEnd: string | Date; sections?: string[]; format?: 'pdf' | 'csv' | 'json' }): Promise<{ report: any }>;
+  listProd(): Promise<{ reports: any[]; total: number }>;
+  downloadProdPdf(reportId: string): Promise<Blob | Buffer>;
+  downloadTestRunPdf(runId: string): Promise<Blob | Buffer>;
+  share(reportId: string, ttlDays?: number): Promise<{ share_token: string; share_expires_at: string; share_url_path: string }>;
+  archive(reportId: string): Promise<void>;
+}
+
+export declare class CiphyrsClient {
+  readonly scan:     ScanResource;
+  readonly auth:     AuthResource;
+  readonly metrics:  MetricsResource;
+  readonly tenant:   TenantResource;
+  // V54-V59 — security platform
+  readonly guard:    GuardResource;
+  readonly security: SecurityResource;
+  readonly reports:  ReportsResource;
+
+  constructor(opts: CiphyrsClientOptions);
+
+  // Top-level shortcuts
+  mask(text: string, opts?: MaskOptions): Promise<MaskResult>;
+  restore(maskedText: string, sessionId: string, opts?: RestoreOptions): Promise<RestoreResult>;
+  protect(userInput: string, llmCall: ProtectLLMCall, opts?: ProtectOptions): Promise<ProtectResult>;
+  maskAsync(text: string, opts?: MaskAsyncOptions): Promise<MaskAsyncResult>;
+  waitForJob(jobId: string, opts?: WaitForJobOptions): Promise<JobResult>;
+  createKey(opts?: { name?: string; scopes?: string[] }): Promise<{ apiKey: string; key: ApiKey }>;
+}