@apitap/core 1.0.0

package/dist/stats/report.js

@@ -0,0 +1,157 @@
+// src/stats/report.ts
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const DEFAULT_SKILLS_DIR = join(homedir(), '.apitap', 'skills');
+/** Default browser token estimate when no measurement available (conservative). */
+const DEFAULT_DOM_BYTES = 400_000; // ~100K tokens
+export async function generateStatsReport(skillsDir = DEFAULT_SKILLS_DIR) {
+    let files;
+    try {
+        files = (await readdir(skillsDir)).filter(f => f.endsWith('.json'));
+    }
+    catch {
+        return emptyReport();
+    }
+    const domains = [];
+    for (const file of files) {
+        const filePath = join(skillsDir, file);
+        try {
+            const content = await readFile(filePath, 'utf-8');
+            const skill = JSON.parse(content);
+            const fileStats = await stat(filePath);
+            const skillFileBytes = fileStats.size;
+            // Browser cost: use measured if available, else default
+            const domBytes = skill.metadata.browserCost?.domBytes ?? DEFAULT_DOM_BYTES;
+            const totalNetworkBytes = skill.metadata.browserCost?.totalNetworkBytes ?? 0;
+            // Replay cost: skill file + response data
+            const totalResponseBytes = skill.endpoints.reduce((sum, ep) => sum + (ep.responseBytes ?? 0), 0);
+            const browserTokens = Math.round(domBytes / 4);
+            const replayTokens = Math.round((skillFileBytes + totalResponseBytes) / 4);
+            const savingsPercent = browserTokens > 0
+                ? Math.round((1 - replayTokens / browserTokens) * 1000) / 10
+                : 0;
+            const replayable = skill.endpoints.filter(ep => {
+                const tier = ep.replayability?.tier;
+                return tier === 'green' || tier === 'yellow';
+            }).length;
+            domains.push({
+                domain: skill.domain,
+                endpoints: skill.endpoints.length,
+                replayable,
+                domBytes,
+                totalNetworkBytes,
+                skillFileBytes,
+                totalResponseBytes,
+                browserTokens,
+                replayTokens,
+                savingsPercent,
+            });
+        }
+        catch {
+            // Skip invalid files
+        }
+    }
+    const totals = {
+        domains: domains.length,
+        endpoints: domains.reduce((s, d) => s + d.endpoints, 0),
+        replayable: domains.reduce((s, d) => s + d.replayable, 0),
+        totalDomBytes: domains.reduce((s, d) => s + d.domBytes, 0),
+        browserTokens: domains.reduce((s, d) => s + d.browserTokens, 0),
+        replayTokens: domains.reduce((s, d) => s + d.replayTokens, 0),
+        savingsPercent: 0,
+    };
+    totals.savingsPercent = totals.browserTokens > 0
+        ? Math.round((1 - totals.replayTokens / totals.browserTokens) * 1000) / 10
+        : 0;
+    return { domains, totals };
+}
+export function formatStatsHuman(report) {
+    if (report.domains.length === 0) {
+        return '  No skill files found. Run `apitap capture <url>` first.';
+    }
+    const lines = [
+        '',
+        '  ApiTap — Usage Report',
+        '  ' + '═'.repeat(22),
+        '',
+        `  Skill files:      ${report.totals.domains} domains`,
+        `  Total endpoints:  ${report.totals.endpoints}`,
+        `  Replayable:       ${report.totals.replayable} (green/yellow tier)`,
+        '',
+        '  Token savings (measured):',
+    ];
+    // Table
+    const domCol = 24;
+    const hdr = [
+        '  ' + pad('Domain', domCol) + pad('DOM size', 10) + pad('Browser', 10) + pad('ApiTap', 10) + 'Saved',
+    ];
+    const sep = '  ' + '─'.repeat(domCol) + '─'.repeat(10) + '─'.repeat(10) + '─'.repeat(10) + '─'.repeat(8);
+    lines.push(sep);
+    lines.push(...hdr);
+    lines.push(sep);
+    for (const d of report.domains) {
+        const domName = d.domain.length > domCol - 2
+            ? d.domain.slice(0, domCol - 3) + '…'
+            : d.domain;
+        const hasMeasured = d.domBytes !== DEFAULT_DOM_BYTES;
+        const browserLabel = hasMeasured
+            ? formatTokens(d.browserTokens)
+            : `~${formatTokens(d.browserTokens)}`;
+        lines.push('  ' +
+            pad(domName, domCol) +
+            pad(formatBytes(d.domBytes), 10) +
+            pad(browserLabel, 10) +
+            pad(formatTokens(d.replayTokens), 10) +
+            `${d.savingsPercent}%`);
+    }
+    lines.push(sep);
+    const hasMeasuredTotals = report.domains.some(d => d.domBytes !== DEFAULT_DOM_BYTES);
+    const totalBrowserLabel = hasMeasuredTotals
+        ? formatTokens(report.totals.browserTokens)
+        : `~${formatTokens(report.totals.browserTokens)}`;
+    lines.push('  ' +
+        pad('Total', domCol) +
+        pad(formatBytes(report.totals.totalDomBytes), 10) +
+        pad(totalBrowserLabel, 10) +
+        pad(formatTokens(report.totals.replayTokens), 10) +
+        `${report.totals.savingsPercent}%`);
+    lines.push(sep);
+    lines.push('');
+    if (hasMeasuredTotals) {
+        lines.push('  Browser: measured DOM size during capture (page.content().length / 4)');
+    }
+    else {
+        lines.push('  Browser: estimated ~100K tokens/site (re-capture for measured values)');
+    }
+    lines.push('  ApiTap:  measured skill file + API response sizes');
+    lines.push('');
+    return lines.join('\n');
+}
+function pad(s, width) {
+    return s.length >= width ? s : s + ' '.repeat(width - s.length);
+}
+function formatBytes(bytes) {
+    if (bytes >= 1_000_000)
+        return `${(bytes / 1_000_000).toFixed(1)} MB`;
+    if (bytes >= 1_000)
+        return `${(bytes / 1_000).toFixed(0)} KB`;
+    return `${bytes} B`;
+}
+function formatTokens(tokens) {
+    if (tokens >= 1_000_000)
+        return `${(tokens / 1_000_000).toFixed(2)}M tk`;
+    if (tokens >= 1_000)
+        return `${(tokens / 1_000).toFixed(1)}K tk`;
+    return `${tokens} tk`;
+}
+function emptyReport() {
+    return {
+        domains: [],
+        totals: {
+            domains: 0, endpoints: 0, replayable: 0,
+            totalDomBytes: 0, browserTokens: 0, replayTokens: 0, savingsPercent: 0,
+        },
+    };
+}
+//# sourceMappingURL=report.js.map

package/dist/stats/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/stats/report.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,214 @@
+/** A captured HTTP request/response pair from the browser */
+export interface CapturedExchange {
+    request: {
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        postData?: string;
+    };
+    response: {
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+        contentType: string;
+    };
+    timestamp: string;
+}
+/** Stored auth credentials for a domain */
+export interface StoredAuth {
+    type: 'bearer' | 'api-key' | 'cookie' | 'custom';
+    header: string;
+    value: string;
+    tokens?: Record<string, StoredToken>;
+    session?: StoredSession;
+    refreshToken?: string;
+    clientSecret?: string;
+}
+/**
+ * Extended auth storage for v0.8 token refresh.
+ */
+/** Stored token with refresh metadata */
+export interface StoredToken {
+    value: string;
+    refreshedAt: string;
+    expiresAt?: string;
+}
+/** Cached browser session for warm restarts */
+export interface StoredSession {
+    cookies: PlaywrightCookie[];
+    localStorage?: Record<string, string>;
+    savedAt: string;
+    maxAgeMs?: number;
+}
+/** Playwright cookie shape (subset of full type) */
+export interface PlaywrightCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/** OAuth configuration (non-secret, lives in shareable skill file) */
+export interface OAuthConfig {
+    tokenEndpoint: string;
+    clientId: string;
+    grantType: 'refresh_token' | 'client_credentials';
+    scope?: string;
+}
+/** Top-level auth config on SkillFile */
+export interface SkillAuth {
+    refreshUrl?: string;
+    browserMode: 'headless' | 'visible';
+    captchaRisk: boolean;
+    ttlHint?: number;
+    oauthConfig?: OAuthConfig;
+}
+/** Replay difficulty classification for an endpoint */
+export interface Replayability {
+    tier: 'green' | 'yellow' | 'orange' | 'red' | 'unknown';
+    verified: boolean;
+    signals: string[];
+}
+/** Detected pagination pattern */
+export interface PaginationInfo {
+    type: 'offset' | 'cursor' | 'page';
+    paramName: string;
+    limitParam?: string;
+}
+/** Request body template for POST/PUT/PATCH endpoints */
+export interface RequestBody {
+    contentType: string;
+    template: string | Record<string, unknown>;
+    variables?: string[];
+    refreshableTokens?: string[];
+}
+/** A single API endpoint in a skill file */
+export interface SkillEndpoint {
+    id: string;
+    method: string;
+    path: string;
+    queryParams: Record<string, {
+        type: string;
+        example: string;
+    }>;
+    headers: Record<string, string>;
+    responseShape: {
+        type: string;
+        fields?: string[];
+    };
+    examples: {
+        request: {
+            url: string;
+            headers: Record<string, string>;
+        };
+        responsePreview: unknown;
+    };
+    replayability?: Replayability;
+    pagination?: PaginationInfo;
+    requestBody?: RequestBody;
+    responseBytes?: number;
+}
+/** The full skill file written to disk */
+export interface SkillFile {
+    version: string;
+    domain: string;
+    capturedAt: string;
+    baseUrl: string;
+    endpoints: SkillEndpoint[];
+    metadata: {
+        captureCount: number;
+        filteredCount: number;
+        toolVersion: string;
+        browserCost?: {
+            domBytes: number;
+            totalNetworkBytes: number;
+            totalRequests: number;
+        };
+    };
+    provenance: 'self' | 'imported' | 'unsigned';
+    signature?: string;
+    auth?: SkillAuth;
+}
+/** Interactive element on a page, for agent targeting */
+export interface PageElement {
+    ref: string;
+    tag: string;
+    role?: string;
+    text: string;
+    name?: string;
+    placeholder?: string;
+    href?: string;
+    type?: string;
+    disabled?: boolean;
+}
+/** Structured page snapshot returned after every interaction */
+export interface PageSnapshot {
+    url: string;
+    title: string;
+    elements: PageElement[];
+    endpointsCaptured: number;
+    totalRequests: number;
+    filteredRequests: number;
+    recentEndpoints: string[];
+}
+/** Result from a capture session interaction */
+export interface InteractionResult {
+    success: boolean;
+    error?: string;
+    snapshot: PageSnapshot;
+}
+/** Result from finishing a capture session */
+export interface FinishResult {
+    aborted: boolean;
+    domains: {
+        domain: string;
+        endpointCount: number;
+        tiers: Record<string, number>;
+        skillFile: string;
+    }[];
+}
+/** Summary returned by `apitap list` */
+export interface SkillSummary {
+    domain: string;
+    skillFile: string;
+    endpointCount: number;
+    capturedAt: string;
+    provenance: 'self' | 'imported' | 'unsigned';
+}
+/** Detected web framework with predicted API patterns */
+export interface DetectedFramework {
+    name: string;
+    confidence: 'high' | 'medium' | 'low';
+    apiPatterns: string[];
+}
+/** Discovered API spec */
+export interface DiscoveredSpec {
+    type: 'openapi' | 'swagger' | 'graphql-introspection';
+    url: string;
+    version?: string;
+    endpointCount?: number;
+}
+/** Result from probing a common API path */
+export interface ProbeResult {
+    method: string;
+    path: string;
+    status: number;
+    contentType: string;
+    isApi: boolean;
+}
+/** Result from the discovery pipeline */
+export interface DiscoveryResult {
+    confidence: 'high' | 'medium' | 'low' | 'none';
+    skillFile?: SkillFile;
+    hints?: string[];
+    frameworks?: DetectedFramework[];
+    specs?: DiscoveredSpec[];
+    probes?: ProbeResult[];
+    duration: number;
+    authRequired?: boolean;
+    authSignals?: string[];
+    loginUrl?: string;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// src/types.ts
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,eAAe"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@apitap/core",
+  "version": "1.0.0",
+  "description": "Intercept web API traffic during browsing. Generate portable skill files so AI agents can call APIs directly instead of scraping.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "apitap": "dist/cli.js",
+    "apitap-mcp": "dist/mcp.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "node --import tsx --test 'test/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  },
+  "license": "BSL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/n1byn1kt/apitap.git"
+  },
+  "homepage": "https://github.com/n1byn1kt/apitap#readme",
+  "bugs": {
+    "url": "https://github.com/n1byn1kt/apitap/issues"
+  },
+  "author": "ApiTap Contributors",
+  "keywords": [
+    "api",
+    "interception",
+    "ai-agent",
+    "mcp",
+    "browser-automation",
+    "web-scraping",
+    "playwright",
+    "skill-file",
+    "api-discovery"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "LICENSE",
+    "README.md",
+    "SKILL.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "playwright": "^1.58.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/auth/crypto.ts

@@ -0,0 +1,92 @@
+// src/auth/crypto.ts
+import {
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+  pbkdf2Sync,
+  createHmac,
+  timingSafeEqual,
+} from 'node:crypto';
+
+const ALGORITHM = 'aes-256-gcm';
+const KEY_LENGTH = 32; // 256 bits
+const IV_LENGTH = 16;
+const PBKDF2_ITERATIONS = 100_000;
+const PBKDF2_SALT = 'apitap-v0.2-key-derivation';
+
+export interface EncryptedData {
+  salt: string;
+  iv: string;
+  ciphertext: string;
+  tag: string;
+}
+
+/**
+ * Derive a 256-bit key from a machine identifier using PBKDF2.
+ * Uses a fixed application salt — the entropy comes from the machine ID
+ * being stretched through 100K iterations.
+ */
+export function deriveKey(machineId: string): Buffer {
+  return pbkdf2Sync(machineId, PBKDF2_SALT, PBKDF2_ITERATIONS, KEY_LENGTH, 'sha512');
+}
+
+/**
+ * Encrypt plaintext using AES-256-GCM.
+ * Each call generates a random IV for semantic security.
+ */
+export function encrypt(plaintext: string, key: Buffer): EncryptedData {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+
+  let ciphertext = cipher.update(plaintext, 'utf8', 'hex');
+  ciphertext += cipher.final('hex');
+  const tag = cipher.getAuthTag();
+
+  return {
+    salt: PBKDF2_SALT,
+    iv: iv.toString('hex'),
+    ciphertext,
+    tag: tag.toString('hex'),
+  };
+}
+
+/**
+ * Decrypt ciphertext using AES-256-GCM.
+ * Throws if key is wrong or data was tampered with.
+ */
+export function decrypt(data: EncryptedData, key: Buffer): string {
+  const decipher = createDecipheriv(
+    ALGORITHM,
+    key,
+    Buffer.from(data.iv, 'hex'),
+  );
+  decipher.setAuthTag(Buffer.from(data.tag, 'hex'));
+
+  let plaintext = decipher.update(data.ciphertext, 'hex', 'utf8');
+  plaintext += decipher.final('utf8');
+  return plaintext;
+}
+
+/**
+ * Create an HMAC-SHA256 signature.
+ * Returns a prefixed string: "hmac-sha256:<hex>"
+ */
+export function hmacSign(data: string, key: Buffer): string {
+  const hmac = createHmac('sha256', key);
+  hmac.update(data);
+  return `hmac-sha256:${hmac.digest('hex')}`;
+}
+
+/**
+ * Verify an HMAC-SHA256 signature using timing-safe comparison.
+ */
+export function hmacVerify(data: string, signature: string, key: Buffer): boolean {
+  if (!signature.startsWith('hmac-sha256:')) return false;
+
+  const expected = hmacSign(data, key);
+  const sigBuf = Buffer.from(signature);
+  const expBuf = Buffer.from(expected);
+
+  if (sigBuf.length !== expBuf.length) return false;
+  return timingSafeEqual(sigBuf, expBuf);
+}