kloakd-sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,526 @@
+/**
+ * KLOAKD SDK — Shared HTTP transport layer (TypeScript).
+ *
+ * Uses the native `fetch` API (Node 18+, all modern browsers).
+ * Retry policy:
+ *   - Retryable: 429, 500, 502, 503, 504
+ *   - Non-retryable: 400, 401, 403, 404
+ *   - Strategy: exponential backoff (1s * 2^attempt), cap 60s
+ *   - 429 respects Retry-After header
+ *   - Max attempts: configurable, default 3
+ */
+interface TransportOptions {
+    apiKey: string;
+    organizationId: string;
+    baseUrl: string;
+    timeout: number;
+    maxRetries: number;
+    /** Injected fetch implementation — used in tests to mock responses. */
+    fetchImpl?: typeof fetch;
+}
+declare class HttpTransport {
+    readonly _apiKey: string;
+    readonly _organizationId: string;
+    readonly _baseUrl: string;
+    readonly _timeout: number;
+    readonly _maxRetries: number;
+    private readonly _fetch;
+    constructor(opts: TransportOptions);
+    authHeaders(): Record<string, string>;
+    orgPrefix(): string;
+    url(path: string): string;
+    request<T = Record<string, unknown>>(method: string, path: string, body?: Record<string, unknown>, params?: Record<string, string>): Promise<T>;
+    get<T = Record<string, unknown>>(path: string, params?: Record<string, string>): Promise<T>;
+    post<T = Record<string, unknown>>(path: string, body: Record<string, unknown>): Promise<T>;
+    delete(path: string): Promise<void>;
+    /**
+     * Open an SSE stream and return an AsyncIterable over raw `data:` payloads.
+     * Caller is responsible for parsing each chunk.
+     */
+    stream(path: string, body: Record<string, unknown>): AsyncIterable<Record<string, unknown>>;
+    /**
+     * SSE stream that also surfaces `event:` field alongside `data:`.
+     * Used by Parlyr.chatStream().
+     */
+    streamWithEvents(path: string, body: Record<string, unknown>): AsyncIterable<{
+        event: string;
+        data: Record<string, unknown>;
+    }>;
+}
+
+/**
+ * KLOAKD SDK — TypeScript interfaces for all result models.
+ *
+ * All field names use camelCase per §4 of the API design doc.
+ * Nullable fields use `T | null` (not undefined) for JSON compatibility.
+ */
+/** Pagination envelope included in all list-returning responses. */
+interface Paginated {
+    hasMore: boolean;
+    total: number;
+}
+interface FetchResult {
+    success: boolean;
+    url: string;
+    statusCode: number;
+    tierUsed: number;
+    html: string | null;
+    vendorDetected: string | null;
+    antiBotBypassed: boolean;
+    artifactId: string | null;
+    error: string | null;
+    /** True if success is true and error is null. */
+    readonly ok: boolean;
+}
+interface FetchEvent {
+    type: string;
+    tier: number | null;
+    vendor: string | null;
+    metadata: Record<string, unknown>;
+}
+interface AnalyzeResult {
+    blocked: boolean;
+    vendor: string | null;
+    confidence: number;
+    recommendedActions: string[];
+}
+interface PageNode {
+    url: string;
+    depth: number;
+    title: string | null;
+    statusCode: number | null;
+    children: string[];
+}
+interface CrawlResult extends Paginated {
+    success: boolean;
+    crawlId: string;
+    url: string;
+    totalPages: number;
+    maxDepthReached: number;
+    pages: PageNode[];
+    artifactId: string | null;
+    error: string | null;
+    readonly ok: boolean;
+}
+interface CrawlEvent {
+    type: string;
+    url: string | null;
+    depth: number | null;
+    pagesFound: number | null;
+    metadata: Record<string, unknown>;
+}
+interface ApiEndpoint {
+    url: string;
+    method: string;
+    apiType: string;
+    confidence: number;
+    parameters: Record<string, unknown>;
+}
+interface DiscoverResult extends Paginated {
+    success: boolean;
+    discoveryId: string;
+    url: string;
+    totalEndpoints: number;
+    endpoints: ApiEndpoint[];
+    artifactId: string | null;
+    error: string | null;
+    readonly ok: boolean;
+}
+interface DiscoverEvent {
+    type: string;
+    endpointUrl: string | null;
+    apiType: string | null;
+    metadata: Record<string, unknown>;
+}
+interface NexusAnalyzeResult {
+    perceptionId: string;
+    strategy: Record<string, unknown>;
+    pageType: string;
+    complexityLevel: string;
+    artifactId: string | null;
+    durationMs: number;
+    error: string | null;
+    readonly ok: boolean;
+}
+interface NexusSynthesisResult {
+    strategyId: string;
+    strategyName: string;
+    generatedCode: string;
+    artifactId: string | null;
+    synthesisTimeMs: number;
+    error: string | null;
+    readonly ok: boolean;
+}
+interface NexusVerifyResult {
+    verificationResultId: string;
+    isSafe: boolean;
+    riskScore: number;
+    safetyScore: number;
+    violations: string[];
+    durationMs: number;
+    error: string | null;
+    readonly ok: boolean;
+}
+interface NexusExecuteResult {
+    executionResultId: string;
+    success: boolean;
+    records: Record<string, unknown>[];
+    artifactId: string | null;
+    durationMs: number;
+    error: string | null;
+    readonly ok: boolean;
+}
+interface NexusKnowledgeResult extends Paginated {
+    learnedConcepts: Record<string, unknown>[];
+    learnedPatterns: Record<string, unknown>[];
+    durationMs: number;
+    error: string | null;
+    readonly ok: boolean;
+}
+interface ParseResult {
+    intent: string;
+    confidence: number;
+    tier: number;
+    source: string;
+    entities: Record<string, unknown>;
+    requiresAction: boolean;
+    clarificationNeeded: string | null;
+    reasoning: string | null;
+    detectedUrl: string | null;
+    readonly ok: boolean;
+}
+interface ChatTurn {
+    sessionId: string;
+    intent: string;
+    confidence: number;
+    tier: number;
+    response: string;
+    entities: Record<string, unknown>;
+    requiresAction: boolean;
+    clarificationNeeded: string | null;
+}
+interface ChatEvent {
+    event: string;
+    data: Record<string, unknown>;
+}
+interface SessionResult {
+    success: boolean;
+    sessionId: string;
+    url: string;
+    artifactId: string | null;
+    screenshotUrl: string | null;
+    error: string | null;
+    readonly ok: boolean;
+}
+interface FetchyrResult {
+    success: boolean;
+    url: string;
+    statusCode: number;
+    html: string | null;
+    artifactId: string | null;
+    sessionArtifactId: string;
+    error: string | null;
+    readonly ok: boolean;
+}
+interface WorkflowResult {
+    workflowId: string;
+    name: string;
+    steps: Record<string, unknown>[];
+    url: string | null;
+    createdAt: string;
+    error: string | null;
+    readonly ok: boolean;
+}
+interface WorkflowExecutionResult {
+    executionId: string;
+    workflowId: string;
+    status: string;
+    startedAt: string | null;
+    completedAt: string | null;
+    records: Record<string, unknown>[];
+    error: string | null;
+    readonly ok: boolean;
+}
+interface FormDetectionResult {
+    forms: Record<string, unknown>[];
+    totalForms: number;
+    error: string | null;
+}
+interface MfaDetectionResult {
+    mfaDetected: boolean;
+    challengeId: string | null;
+    mfaType: string | null;
+    error: string | null;
+}
+interface MfaResult {
+    success: boolean;
+    sessionArtifactId: string | null;
+    error: string | null;
+}
+interface DeduplicationResult {
+    uniqueRecords: Record<string, unknown>[];
+    duplicateCount: number;
+    totalInput: number;
+    error: string | null;
+    readonly ok: boolean;
+}
+interface ExtractionResult extends Paginated {
+    success: boolean;
+    url: string;
+    method: string;
+    records: Record<string, unknown>[];
+    totalRecords: number;
+    pagesScraped: number;
+    artifactId: string | null;
+    jobId: string | null;
+    error: string | null;
+    readonly ok: boolean;
+}
+
+interface FetchOptions {
+    forceBrowser?: boolean;
+    useProxy?: boolean;
+    sessionArtifactId?: string;
+}
+interface FetchAsyncOptions extends FetchOptions {
+    webhookUrl?: string;
+}
+declare class EvadrNamespace {
+    private readonly _t;
+    constructor(_t: HttpTransport);
+    fetch(url: string, opts?: FetchOptions): Promise<FetchResult>;
+    fetchAsync(url: string, opts?: FetchAsyncOptions): Promise<string>;
+    fetchStream(url: string, opts?: {
+        forceBrowser?: boolean;
+    }): AsyncIterable<FetchEvent>;
+    analyze(url: string, opts?: {
+        statusCode?: number;
+        headers?: Record<string, string>;
+        bodySnippet?: string;
+    }): Promise<AnalyzeResult>;
+    storeProxy(name: string, proxyUrl: string): Promise<void>;
+}
+
+interface LoginOptions {
+    submitSelector?: string;
+    successUrlContains?: string;
+}
+interface FetchyrFetchOptions {
+    waitForSelector?: string;
+    extractHtml?: boolean;
+}
+declare class FetchyrNamespace {
+    private readonly _t;
+    constructor(_t: HttpTransport);
+    login(url: string, usernameSelector: string, passwordSelector: string, username: string, password: string, opts?: LoginOptions): Promise<SessionResult>;
+    fetch(url: string, sessionArtifactId: string, opts?: FetchyrFetchOptions): Promise<FetchyrResult>;
+    getSession(artifactId: string): Promise<Record<string, unknown>>;
+    invalidateSession(artifactId: string): Promise<void>;
+    createWorkflow(name: string, steps: Record<string, unknown>[], url?: string): Promise<WorkflowResult>;
+    executeWorkflow(workflowId: string): Promise<WorkflowExecutionResult>;
+    getExecution(workflowId: string, executionId: string): Promise<WorkflowExecutionResult>;
+    detectForms(url: string, opts?: {
+        sessionArtifactId?: string;
+    }): Promise<FormDetectionResult>;
+    detectMfa(url: string, opts?: {
+        sessionArtifactId?: string;
+    }): Promise<MfaDetectionResult>;
+    submitMfa(challengeId: string, code: string): Promise<MfaResult>;
+    checkDuplicates(records: Record<string, unknown>[], opts?: {
+        domain?: string;
+    }): Promise<DeduplicationResult>;
+}
+
+interface PageOptions {
+    schema?: Record<string, string>;
+    fetchArtifactId?: string;
+    sessionArtifactId?: string;
+    apiMapArtifactId?: string;
+    options?: Record<string, unknown>;
+    limit?: number;
+    offset?: number;
+}
+declare class KolektrNamespace {
+    private readonly _t;
+    constructor(_t: HttpTransport);
+    page(url: string, opts?: PageOptions): Promise<ExtractionResult>;
+    pageAll(url: string, opts?: Omit<PageOptions, 'limit' | 'offset'>): Promise<Record<string, unknown>[]>;
+    extractHtml(html: string, url: string, opts?: {
+        schema?: Record<string, string>;
+    }): Promise<ExtractionResult>;
+}
+
+declare class NexusNamespace {
+    private readonly _t;
+    constructor(_t: HttpTransport);
+    analyze(url: string, opts?: {
+        html?: string;
+        constraints?: Record<string, unknown>;
+    }): Promise<NexusAnalyzeResult>;
+    synthesize(perceptionId: string, opts?: {
+        strategy?: Record<string, unknown>;
+        timeout?: number;
+    }): Promise<NexusSynthesisResult>;
+    verify(strategyId: string): Promise<NexusVerifyResult>;
+    execute(strategyId: string, url: string): Promise<NexusExecuteResult>;
+    knowledge(executionResultId: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<NexusKnowledgeResult>;
+}
+
+declare class ParlyrNamespace {
+    private readonly _t;
+    constructor(_t: HttpTransport);
+    parse(message: string, opts?: {
+        sessionId?: string;
+    }): Promise<ParseResult>;
+    /**
+     * Send one chat turn and collect all SSE events into a ChatTurn.
+     * Blocks until the `done` event is received.
+     */
+    chat(sessionId: string, message: string): Promise<ChatTurn>;
+    /**
+     * Async iterable SSE stream for one chat turn.
+     *
+     * @example
+     * ```typescript
+     * for await (const event of client.parlyr.chatStream('sess-1', 'Scrape linkedin.com')) {
+     *   console.log(event.event, event.data);
+     * }
+     * ```
+     */
+    chatStream(sessionId: string, message: string): AsyncIterable<ChatEvent>;
+    deleteSession(sessionId: string): Promise<void>;
+}
+
+interface DiscoverOptions {
+    siteHierarchyArtifactId?: string;
+    maxRequests?: number;
+    sessionArtifactId?: string;
+    limit?: number;
+    offset?: number;
+}
+declare class SkanyrNamespace {
+    private readonly _t;
+    constructor(_t: HttpTransport);
+    discover(url: string, opts?: DiscoverOptions): Promise<DiscoverResult>;
+    discoverAll(url: string, opts?: Omit<DiscoverOptions, 'limit' | 'offset'>): Promise<ApiEndpoint[]>;
+    discoverStream(url: string, opts?: {
+        siteHierarchyArtifactId?: string;
+        maxRequests?: number;
+    }): AsyncIterable<DiscoverEvent>;
+    getApiMap(artifactId: string): Promise<Record<string, unknown>>;
+    getJob(jobId: string): Promise<Record<string, unknown>>;
+}
+
+interface CrawlOptions {
+    maxDepth?: number;
+    maxPages?: number;
+    includeExternalLinks?: boolean;
+    sessionArtifactId?: string;
+    limit?: number;
+    offset?: number;
+}
+declare class WebgrphNamespace {
+    private readonly _t;
+    constructor(_t: HttpTransport);
+    crawl(url: string, opts?: CrawlOptions): Promise<CrawlResult>;
+    crawlAll(url: string, opts?: Omit<CrawlOptions, 'limit' | 'offset'>): Promise<PageNode[]>;
+    crawlStream(url: string, opts?: {
+        maxDepth?: number;
+        maxPages?: number;
+    }): AsyncIterable<CrawlEvent>;
+    getHierarchy(artifactId: string): Promise<Record<string, unknown>>;
+    getJob(jobId: string): Promise<Record<string, unknown>>;
+}
+
+/**
+ * KLOAKD TypeScript SDK — Main client class.
+ *
+ * @example
+ * ```typescript
+ * import { Kloakd } from 'kloakd-sdk';
+ *
+ * const client = new Kloakd({
+ *   apiKey: 'sk-live-abc123',
+ *   organizationId: 'your-org-id',
+ * });
+ *
+ * const fetch = await client.evadr.fetch('https://books.toscrape.com');
+ * const data  = await client.kolektr.page('https://books.toscrape.com', {
+ *   schema: { title: 'css:h3 a', price: 'css:p.price_color' },
+ *   fetchArtifactId: fetch.artifactId ?? undefined,
+ * });
+ * console.log(data.records.slice(0, 3));
+ * ```
+ */
+
+interface KloakdOptions {
+    apiKey: string;
+    organizationId: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+    /** Injected fetch — for testing only. */
+    fetchImpl?: typeof fetch;
+}
+declare class Kloakd {
+    readonly evadr: EvadrNamespace;
+    readonly webgrph: WebgrphNamespace;
+    readonly skanyr: SkanyrNamespace;
+    readonly nexus: NexusNamespace;
+    readonly parlyr: ParlyrNamespace;
+    readonly fetchyr: FetchyrNamespace;
+    readonly kolektr: KolektrNamespace;
+    private readonly _transport;
+    constructor(opts: KloakdOptions);
+    toString(): string;
+}
+
+/**
+ * KLOAKD SDK — Error hierarchy.
+ *
+ * All errors extend KloakdError, which extends the native Error class.
+ * Every error carries statusCode and message.
+ *
+ * @example
+ * ```typescript
+ * import { RateLimitError, KloakdError } from 'kloakd-sdk';
+ *
+ * try {
+ *   const result = await client.evadr.fetch('https://example.com');
+ * } catch (e) {
+ *   if (e instanceof RateLimitError) {
+ *     await sleep(e.retryAfter * 1000);
+ *   } else if (e instanceof KloakdError) {
+ *     console.error(e.statusCode, e.message);
+ *   }
+ * }
+ * ```
+ */
+declare class KloakdError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+declare class AuthenticationError extends KloakdError {
+    constructor(message: string);
+}
+declare class NotEntitledError extends KloakdError {
+    readonly module: string;
+    readonly upgradeUrl: string;
+    constructor(message: string, module: string, upgradeUrl?: string);
+}
+declare class RateLimitError extends KloakdError {
+    readonly retryAfter: number;
+    readonly resetAt: string;
+    constructor(message: string, retryAfter: number, resetAt?: string);
+}
+declare class UpstreamError extends KloakdError {
+    constructor(message: string);
+}
+declare class ApiError extends KloakdError {
+    constructor(message: string, statusCode: number);
+}
+
+export { type AnalyzeResult, type ApiEndpoint, ApiError, AuthenticationError, type ChatEvent, type ChatTurn, type CrawlEvent, type CrawlResult, type DeduplicationResult, type DiscoverEvent, type DiscoverResult, type ExtractionResult, type FetchEvent, type FetchResult, type FetchyrResult, type FormDetectionResult, Kloakd, KloakdError, type KloakdOptions, type MfaDetectionResult, type MfaResult, type NexusAnalyzeResult, type NexusExecuteResult, type NexusKnowledgeResult, type NexusSynthesisResult, type NexusVerifyResult, NotEntitledError, type PageNode, type ParseResult, RateLimitError, type SessionResult, UpstreamError, type WorkflowExecutionResult, type WorkflowResult };