@taodigital/crawler 0.0.0-stage → 1.2.1

package/types/response-cache.d.ts

@@ -0,0 +1,38 @@
+export interface ResponseCacheEntry {
+    url: string;
+    etag?: string;
+    lastModified?: string;
+    cacheControl?: string;
+    body: string;
+    contentType: string;
+    statusCode: number;
+    cachedAt: number;
+    hitCount: number;
+}
+export declare class ResponseCache {
+    private readonly dir;
+    private totalHits;
+    private totalRequests;
+    constructor(cacheDir: string);
+    private key;
+    private path;
+    get(url: string): ResponseCacheEntry | null;
+    private read;
+    isFresh(url: string): boolean;
+    staleIfError(url: string): boolean;
+    set(url: string, entry: Omit<ResponseCacheEntry, 'cachedAt' | 'hitCount'>): void;
+    getValidationHeaders(url: string): {
+        'If-None-Match'?: string;
+        'If-Modified-Since'?: string;
+    };
+    markHit(url: string): void;
+    invalidate(url: string): void;
+    clear(): void;
+    stats(): {
+        entries: number;
+        totalSizeBytes: number;
+        hitRate: number;
+        totalHits: number;
+    };
+    prune(maxAgeMs: number): number;
+}

package/types/responsive-detector.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Responsive design detector — captures page at multiple breakpoints
+ * and detects layout differences between desktop and mobile viewports.
+ *
+ * Breakpoints: mobile(375), tablet(768), desktop(1280), wide(1920)
+ * Detects: viewport-specific content visibility, menu collapse state,
+ * font size changes, hidden/shown elements.
+ */
+import type { Page } from 'playwright';
+export interface ViewportCapture {
+    width: number;
+    height: number;
+    label: 'mobile' | 'tablet' | 'desktop' | 'wide';
+    screenshotBuffer?: Buffer;
+    visibleTextLength: number;
+    hasHamburgerMenu: boolean;
+    hiddenElements: number;
+    scrollHeight: number;
+}
+export interface ResponsiveReport {
+    url: string;
+    captures: ViewportCapture[];
+    isResponsive: boolean;
+    hasMobileMenu: boolean;
+    issues: string[];
+}
+export declare function detectResponsive(page: Page, url: string, opts?: {
+    captureScreenshots?: boolean;
+}): Promise<ResponsiveReport>;

package/types/retry-policy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Retry policy — configurable exponential backoff with jitter.
+ * Covers: 5xx server errors, network timeouts, ECONNREFUSED, ECONNRESET.
+ * NOT retried: 4xx client errors (except 429 — handled separately), redirects.
+ */
+export interface RetryPolicyOpts {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitterMs?: number;
+    retryOn?: number[];
+}
+export interface RetryResult<T> {
+    value: T;
+    attempts: number;
+    totalDelayMs: number;
+}
+export declare function withRetry<T>(fn: (attempt: number) => Promise<T>, opts?: RetryPolicyOpts): Promise<RetryResult<T>>;
+/** Wraps fetch() with retry policy */
+export declare function fetchWithRetry(url: string, init?: RequestInit, retryOpts?: RetryPolicyOpts): Promise<Response>;

package/types/robots-txt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Minimal robots.txt fetcher + parser. No external deps. Caches per origin.
+ * Implements the subset of robots.txt spec used in practice:
+ *   User-agent, Disallow, Allow — longest match wins (RFC 9309).
+ */
+export declare class RobotsCache {
+    private readonly cache;
+    isAllowed(url: string, userAgent?: string): Promise<boolean>;
+}

package/types/screen-reader.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Reads a page as a structured outline (cheap + reliable), the way
+ * Playwright MCP / the accessibility tree works — NOT by sending pixels to a
+ * vision model. Vision is a fallback for image-only pages (added later).
+ *
+ * Returns the interactive elements found, which the Screen Reader Agent then
+ * enriches with MEANING and saves to the Zeta Core.
+ */
+export interface RawElement {
+    role: string;
+    label: string;
+    selectorHint: string;
+    expectedData?: string;
+}
+export declare function readScreen(page: any): Promise<RawElement[]>;

package/types/screenshot-masker.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Screenshot masker — blur or black-box PII regions in captured screenshots.
+ *
+ * Strategy: inject a CSS overlay into the page before screenshot capture that
+ * covers detected PII-likely elements (input[type=email], input[type=password],
+ * elements with PII-containing text) with a blur or solid black mask.
+ *
+ * This is a CSS-based approach (no image processing library needed):
+ * 1. Identify likely-PII DOM elements via selectors
+ * 2. Add an overlaid <div> with blur/black filter at each element's bounding box
+ * 3. Take screenshot
+ * 4. Remove overlays
+ *
+ * Falls back gracefully if elements are not found or overlay injection fails.
+ */
+import type { Page } from 'playwright';
+export interface MaskingOpts {
+    /** Additional CSS selectors to mask (in addition to defaults) */
+    extraSelectors?: string[];
+    /** Masking style: 'blur' or 'blackout' */
+    style?: 'blur' | 'blackout';
+    /** Blur strength in px (default 8) */
+    blurPx?: number;
+}
+export declare function maskScreenshot(page: Page, opts?: MaskingOpts): Promise<{
+    maskedCount: number;
+    screenshot: Buffer;
+}>;

package/types/seo-checker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SEO indexability checker — determines if a page is crawlable and indexable.
+ *
+ * Checks:
+ * 1. X-Robots-Tag response header (noindex, nofollow, noarchive)
+ * 2. <meta name="robots"> tag (noindex, nofollow)
+ * 3. Canonical URL (self-canonical vs cross-canonical)
+ * 4. rel="nofollow" on outbound links
+ * 5. hreflang tags (multilingual)
+ * 6. Open Graph completeness (og:title, og:description, og:image)
+ * 7. Structured data presence (JSON-LD)
+ * 8. Meta description
+ * 9. Title tag length (< 60 chars recommended)
+ * 10. URL structure (query params, fragments, excessive depth)
+ */
+import type { Page } from 'playwright';
+export interface SeoIssue {
+    rule: string;
+    severity: 'critical' | 'warning' | 'info';
+    message: string;
+    value?: string;
+}
+export interface SeoCheckResult {
+    url: string;
+    isIndexable: boolean;
+    canonicalUrl?: string;
+    isSelfCanonical?: boolean;
+    hreflang: Record<string, string>;
+    issues: SeoIssue[];
+    score: number;
+    checkedAt: string;
+}
+export declare function checkSeo(page: Page, url: string, responseHeaders?: Record<string, string>): Promise<SeoCheckResult>;

package/types/service-worker-interceptor.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Service Worker detection — inspects SW registrations, cache storage, background
+ * sync queues, and PWA installability for a crawled page.
+ * Surfaces offline-first contracts and push-capable surfaces that HTTP-only
+ * crawlers cannot observe.
+ */
+export interface SwRegistration {
+    scope: string;
+    scriptURL: string | null;
+    state: 'active' | 'installing' | 'waiting' | 'none';
+    updateViaCache: string;
+}
+export interface SwCacheEntry {
+    cacheName: string;
+    entryCount: number;
+    sampleUrls: string[];
+}
+export interface BackgroundSyncInfo {
+    scope: string;
+    pendingTags: string[];
+}
+export interface PwaInfo {
+    isInstallable: boolean;
+    manifestUrl: string | null;
+    hasPushPermission: boolean;
+}
+export interface ServiceWorkerResult {
+    supported: boolean;
+    active: boolean;
+    registrations: SwRegistration[];
+    cacheStorages: SwCacheEntry[];
+    backgroundSync: BackgroundSyncInfo[];
+    pwa: PwaInfo;
+    totalCachedEntries: number;
+}
+export declare function inspectServiceWorker(page: any): Promise<ServiceWorkerResult>;

package/types/session-capture.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Opens a headed (visible) browser at appUrl and returns a captureId.
+ * The user logs in manually, then calls completeSessionCapture() to harvest storageState.
+ * Sessions expire after 10 minutes if not completed.
+ *
+ * Throws 'HEADLESS_ENV' if running in Docker/Linux without a display server.
+ * The API route surfaces this as a 503 so the frontend can switch to manual JSON paste.
+ */
+export declare function startSessionCapture(appUrl: string): Promise<string>;
+/** Captures storageState from the open browser, closes it, and returns the JSON string. */
+export declare function completeSessionCapture(captureId: string): Promise<string>;
+/** Closes the browser without capturing — called on Cancel. */
+export declare function cancelSessionCapture(captureId: string): Promise<void>;
+/**
+ * Headless login + session capture — works on Docker/cloud (no display needed).
+ * Tries DOM-based login first (fast, free). If it fails and llmConfig is provided,
+ * falls back to Stagehand AI-guided login (handles modals, multi-step, marketing pages).
+ *
+ * Returns { storageState, cookies, localStorage } on success.
+ * Throws a human-readable error on failure.
+ */
+export declare function validateAndCaptureSession(appUrl: string, creds: {
+    username: string;
+    password: string;
+    totpSecret?: string;
+    httpBasicUsername?: string;
+    httpBasicPassword?: string;
+}, llmConfig?: {
+    modelName: string;
+    apiKey: string;
+}, captchaOpts?: {
+    apiKey?: string;
+    provider?: '2captcha' | 'capsolver';
+}, loginInstructions?: string): Promise<{
+    storageState: string;
+    cookies: number;
+    localStorage: number;
+    finalUrl?: string;
+}>;

package/types/session-export.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Converts a Playwright storageState (the format ZeTa already captures via
+ * session-capture.ts/live-view.ts and stores per-project) into snippets for
+ * other automation frameworks. Playwright's storageState is the de-facto
+ * standard for browser session export — see docs/UNIVERSAL-SESSION-CAPTURE-
+ * STRATEGY.md — so every other framework's import mechanism is a small,
+ * mechanical conversion away, not a new capture flow.
+ *
+ * Pure, dependency-free functions — no I/O, no network, fully unit-testable.
+ */
+export interface StorageStateCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+export interface StorageStateOrigin {
+    origin: string;
+    localStorage: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+export interface StorageState {
+    cookies: StorageStateCookie[];
+    origins: StorageStateOrigin[];
+}
+export type SessionExportFormat = 'cypress' | 'selenium-python' | 'webdriverio';
+/** cy.setCookie() + localStorage.setItem() inside a reusable custom command,
+ *  following Cypress's documented cy.session() pattern (see references in
+ *  docs/UNIVERSAL-SESSION-CAPTURE-STRATEGY.md). */
+export declare function toCypressSnippet(state: StorageState): string;
+/** driver.add_cookie() (Selenium requires the browser already be on the
+ *  cookie's domain before adding it) + execute_script() for localStorage,
+ *  per Selenium's documented Cookie API. */
+export declare function toSeleniumPythonDict(state: StorageState): string;
+/** browser.setCookies() accepts an array shape very close to Playwright's own
+ *  cookie objects (per WebdriverIO's documented API) — closest 1:1 mapping
+ *  of the three target formats. */
+export declare function toWebdriverIOSnippet(state: StorageState): string;
+export declare function exportSessionAs(format: SessionExportFormat, state: StorageState): {
+    content: string;
+    filename: string;
+    mimeType: string;
+};

package/types/shadow-dom-crawler.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shadow DOM crawler — enumerate shadow hosts and detect web component libraries.
+ *
+ * Walks the live DOM recursively (up to depth 8) to find all open shadow roots
+ * and custom elements with closed shadow roots, then classifies the component
+ * framework in use. Results feed ZeTa's test generator so it can account for
+ * elements that are invisible to standard Playwright locators.
+ */
+export interface ShadowInteractiveEl {
+    role: string;
+    label: string;
+    type: string;
+    tagName: string;
+}
+export interface ShadowHostInfo {
+    tagName: string;
+    hostId: string;
+    shadowMode: 'open' | 'closed';
+    depth: number;
+    interactiveCount: number;
+    interactiveElements: ShadowInteractiveEl[];
+    slotNames: string[];
+    childShadowHosts: number;
+}
+export interface ShadowDomCrawlResult {
+    shadowHostCount: number;
+    openShadowCount: number;
+    closedShadowCount: number;
+    maxNestingDepth: number;
+    hosts: ShadowHostInfo[];
+    totalInteractiveInShadow: number;
+    detectedLibraries: string[];
+    blindSpots: string[];
+}
+export declare function crawlShadowDom(page: any): Promise<ShadowDomCrawlResult>;

package/types/sitemap-writer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sitemap writer — generate XML sitemap from crawled screens.
+ *
+ * Compliant with sitemaps.org protocol (sitemap index + individual sitemap files).
+ * Splits into 50k-URL files per the spec when needed.
+ * Used for: SEO audit export, future crawl seed, and crawler/robots.txt comparison.
+ */
+export interface SitemapUrl {
+    loc: string;
+    lastmod?: string;
+    changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    priority?: number;
+}
+export declare function writeSitemap(urls: SitemapUrl[], outputPath: string): Promise<void>;
+/** Convert crawled screen records to SitemapUrl objects */
+export declare function screensToSitemapUrls(screens: Array<{
+    url: string;
+    updatedAt?: Date;
+    depth?: number;
+}>): SitemapUrl[];
+export declare function buildSitemapString(urls: SitemapUrl[]): string;

package/types/sitemap.d.ts

@@ -0,0 +1,51 @@
+import { ProxyAgent } from 'undici';
+/**
+ * Same-site check that tolerates www/non-www and http/https differences — a sitemap on
+ * `vercel.com` is valid for a project pointed at `www.vercel.com` (and vice versa).
+ */
+export declare function sameSite(candidateUrl: string, siteOrigin: string): boolean;
+/**
+ * Pulls page URLs and sub-sitemap URLs out of an already-XML-parsed sitemap
+ * document (either a <urlset> or a <sitemapindex>), filtered to same-origin
+ * and deduped. Pure function — no I/O — for direct unit testing without a
+ * real HTTP fetch.
+ */
+export declare function extractUrlsFromParsedSitemap(parsed: any, origin: string, maxUrls?: number): {
+    pageUrls: string[];
+    subSitemapUrls: string[];
+};
+/**
+ * Fetches and parses a sitemap (or sitemap index, recursed up to a small
+ * depth) into a flat, deduped list of same-origin URLs.
+ */
+export declare function fetchSitemapUrls(sitemapUrl: string, origin: string, depth?: number, dispatcher?: any, maxUrls?: number): Promise<string[]>;
+/**
+ * Discovers a project's sitemap (default `${origin}/sitemap.xml`, or an
+ * explicit override) and returns the URLs it lists. Never throws.
+ */
+export declare function discoverSitemapUrls(appUrl: string, sitemapUrl?: string): Promise<string[]>;
+/**
+ * Build an undici ProxyAgent from a proxy URL. Parses credentials manually because
+ * DataImpulse-style usernames contain commas (country codes) that break new URL().
+ * Returns undefined for no/auto proxy — the caller then fetches directly.
+ */
+export declare function buildProxyDispatcher(proxyUrl?: string): ProxyAgent | undefined;
+/** Extract same-origin `Sitemap:` directives from a robots.txt body. */
+export declare function parseRobotsSitemaps(robotsTxt: string, origin: string): string[];
+export interface UrlCandidate {
+    url: string;
+    source: 'sitemap' | 'robots' | 'link';
+}
+/**
+ * Pre-crawl URL discovery for the review-before-crawl flow: reads robots.txt Sitemap
+ * directives and sitemap.xml (recursed, same-origin), proxy-aware. Returns a deduped
+ * candidate list the user can review and seed before launching the Playwright crawl.
+ * Never throws — bot-protected sites (Akamai/Cloudflare) simply yield an empty list.
+ */
+export declare function discoverProjectUrls(appUrl: string, opts?: {
+    sitemapUrl?: string;
+    proxyUrl?: string;
+}): Promise<{
+    candidates: UrlCandidate[];
+    sitemapFound: boolean;
+}>;

package/types/skyvern.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Skyvern Vision Fallback
+ *
+ * Skyvern combines computer vision + LLM reasoning to navigate sites that
+ * defeat DOM-based approaches: CAPTCHAs, legacy apps, visual-only login flows,
+ * government portals. It's the "break glass" option when Stagehand fails.
+ *
+ * Production setup (Phase 4+):
+ *   1. Self-host: https://github.com/Skyvern-AI/skyvern
+ *   2. Or use cloud: https://app.skyvern.com
+ *   3. Set SKYVERN_API_URL + SKYVERN_API_KEY in .env
+ *
+ * Pricing note: vision tasks cost more per step than DOM-based Stagehand.
+ * Use only when the fast path fails.
+ */
+export interface SkyvernTask {
+    taskDescription: string;
+    url: string;
+    credentials?: {
+        username: string;
+        password: string;
+        oneTimeCode?: string;
+    };
+}
+export interface SkyvernConfig {
+    apiUrl: string;
+    apiKey: string;
+    llmKey?: string;
+    llmApiKey?: string;
+}
+export interface SkyvernStep {
+    order: number;
+    action_type: string;
+    element_description?: string;
+    reasoning?: string;
+    success: boolean;
+    screenshot_url?: string;
+    duration_ms?: number;
+    error?: string;
+}
+export interface SkyvernNavigateResult {
+    screenshotUrls: string[];
+    visitedUrls: string[];
+    status: 'success' | 'failed' | 'partial';
+    steps?: SkyvernStep[];
+    taskId?: string;
+    durationMs?: number;
+    triggerReason?: string;
+}
+/**
+ * Gap 5: Post-login navigation via Skyvern vision for apps where DOM analysis
+ * cannot discover screens (canvas, WebGL, legacy Flash-replacement stacks).
+ * Skyvern drives the browser via screenshot + LLM, returning visited page list.
+ */
+export declare function skyvernNavigate(startUrl: string, navigationGoals: string[], tenantConfig?: SkyvernConfig, triggerReason?: string): Promise<SkyvernNavigateResult>;
+export declare function skyvernFallback(task: SkyvernTask, tenantConfig?: SkyvernConfig): Promise<'success' | 'failed'>;

package/types/sqs-queue.d.ts

@@ -0,0 +1,13 @@
+export declare function sendJobToSqs(jobId: string): Promise<void>;
+/** Returns the approximate number of messages in the SQS DLQ. */
+export declare function getDlqStats(): Promise<{
+    approximateMessageCount: number;
+    dlqUrl: string | null;
+}>;
+/**
+ * Redrive up to `maxMessages` messages from the SQS DLQ back to the main queue.
+ * Each message is received from the DLQ, re-sent to the main queue, then deleted
+ * from the DLQ. Returns the number of messages successfully redriven.
+ */
+export declare function redriveFromDlq(maxMessages?: number): Promise<number>;
+export declare function startSqsWorker(): Promise<void>;

package/types/sso-token.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SSO token retrieval for Okta and Azure AD.
+ * Uses OAuth2 ROPC (Resource Owner Password Credentials) flow to get access tokens
+ * without browser-based login.
+ *
+ * Note: ROPC is deprecated in OAuth 2.1 but still supported by Okta and Azure AD
+ * for service accounts and automated testing scenarios.
+ */
+export type SsoProvider = 'okta' | 'azure_ad' | 'generic_oidc';
+export interface SsoConfig {
+    provider: SsoProvider;
+    /** Okta domain (e.g. 'mycompany.okta.com') or Azure tenant ID */
+    domain: string;
+    /** OAuth2 client ID */
+    clientId: string;
+    /** OAuth2 client secret (for client_credentials or confidential ROPC) */
+    clientSecret?: string;
+    /** Scopes to request (space-separated). Default: 'openid profile' */
+    scope?: string;
+}
+/**
+ * Get an access token using ROPC flow (username + password → token).
+ * Returns the access token string.
+ */
+export declare function getSsoToken(config: SsoConfig, username: string, password: string): Promise<string>;
+/**
+ * Get a client credentials token (no user — for service accounts).
+ */
+export declare function getSsoClientCredentialsToken(config: SsoConfig): Promise<string>;

package/types/state-graph.d.ts

@@ -0,0 +1,59 @@
+import type { Page } from 'playwright';
+export declare function simHash32(text: string): number;
+export declare function hammingDistance32(a: number, b: number): number;
+export declare function normalizeUrl(raw: string): string;
+export declare function computeStateId(normalizedUrl: string, hash: number): string;
+export interface UIStateNode {
+    id: string;
+    url: string;
+    normalizedUrl: string;
+    title: string;
+    interactiveElementCount: number;
+    domFingerprint: string;
+    simHashValue: number;
+    visitedAt: string;
+}
+export interface StateTransition {
+    fromId: string;
+    toId: string;
+    action: string;
+    label: string;
+    triggeredAt: string;
+}
+export interface CoverageReport {
+    totalStates: number;
+    totalTransitions: number;
+    uniqueUrls: number;
+    interactiveElementsTotal: number;
+    estimatedCoveragePercent: number;
+}
+export declare function fingerprintPage(page: Page, visitedAt: string): Promise<{
+    fingerprint: string;
+    visibleText: string;
+    interactiveCount: number;
+    simHashValue: number;
+}>;
+export declare class ScreenTransitionGraph {
+    private states;
+    private transitions;
+    /** Maps simHash value → array of state ids with that hash (for near-dup lookup) */
+    private hashIndex;
+    addState(node: UIStateNode): {
+        added: boolean;
+        duplicateOf?: string;
+    };
+    addTransition(fromId: string, toId: string, action: string, label: string, triggeredAt: string): void;
+    isDuplicate(url: string, visibleText: string, threshold?: number): boolean;
+    getCoverageReport(): CoverageReport;
+    toJSON(): {
+        states: UIStateNode[];
+        transitions: StateTransition[];
+    };
+    static fromJSON(data: {
+        states: UIStateNode[];
+        transitions: StateTransition[];
+    }): ScreenTransitionGraph;
+    getState(id: string): UIStateNode | undefined;
+    getAllStates(): UIStateNode[];
+    getTransitionsFrom(id: string): StateTransition[];
+}

package/types/stealth/human-behavior.d.ts

@@ -0,0 +1,20 @@
+import type { Page } from 'playwright';
+export declare function humanDelay(min?: number, max?: number): Promise<void>;
+export declare function simulateMouseMovement(page: Page, targetX: number, targetY: number): Promise<void>;
+export declare function simulateMouseHover(page: Page, selector: string): Promise<void>;
+export declare function simulateClick(page: Page, selector: string): Promise<void>;
+export declare function injectFingerprintOverrides(page: Page): Promise<void>;
+export declare function infiniteScrollToBottom(page: Page, opts?: {
+    maxScrolls?: number;
+    scrollDelay?: number;
+    stabilizeMs?: number;
+}, rawPage?: any): Promise<{
+    scrollCount: number;
+    heightReached: number;
+}>;
+export declare function extractIframeContent(page: Page): Promise<Array<{
+    src: string;
+    content: string;
+    markdown: string;
+}>>;
+export declare function pierceShadowDom(page: Page): Promise<string>;

package/types/telemetry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Lightweight OTel-compatible tracing for Zeta crawler.
+ *
+ * Emits spans as structured JSON logs compatible with OpenTelemetry format.
+ * Drop-in upgrade path: replace this module with @opentelemetry/sdk-node when needed.
+ *
+ * Usage:
+ *   const span = startSpan('crawl.url', { url, engine });
+ *   // ... do work ...
+ *   endSpan(span, { screensFound: 3 });
+ */
+export interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTimeMs: number;
+    attributes: Record<string, string | number | boolean>;
+}
+export interface FinishedSpan extends Span {
+    endTimeMs: number;
+    durationMs: number;
+    status: 'ok' | 'error';
+    error?: string;
+}
+/** Start a new span. If a trace is already active, the new span is a child. */
+export declare function startSpan(name: string, attributes?: Record<string, string | number | boolean>): Span;
+/** End a span and emit it as a structured log line. */
+export declare function endSpan(span: Span, extraAttributes?: Record<string, string | number | boolean>, error?: Error): FinishedSpan;
+/** Convenience: wrap an async function in a span. */
+export declare function withSpan<T>(name: string, attributes: Record<string, string | number | boolean>, fn: (span: Span) => Promise<T>): Promise<T>;
+export declare function increment(metric: string, value?: number, tags?: Record<string, string>): void;
+/** Flush counters as a structured log — call periodically (e.g. at job end). */
+export declare function flushMetrics(): Record<string, number>;