@apifuse/provider-sdk 2.1.0-beta.0 → 2.1.0-beta.10

package/dist/runtime/waterfall.js

@@ -0,0 +1,147 @@
+const ANSI = {
+    green: "\x1b[32m",
+    red: "\x1b[31m",
+    yellow: "\x1b[33m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+    reset: "\x1b[0m",
+};
+export function renderWaterfall(spans, request, options) {
+    if (spans.length === 0) {
+        return "";
+    }
+    const slowThresholdMs = options?.slowThresholdMs ?? 500;
+    const maxBarWidth = options?.maxBarWidth ?? 40;
+    const tree = buildTree(spans);
+    const bottleneckId = findBottleneck(tree);
+    const totalDuration = request.totalMs;
+    const lines = [];
+    const headerRule = "─".repeat(40);
+    lines.push(`  ${ANSI.dim}┌─${ANSI.reset} ${request.method} ${request.path} ${ANSI.dim}${headerRule}${ANSI.reset}`);
+    lines.push(`  ${ANSI.dim}│${ANSI.reset}`);
+    for (const node of tree) {
+        const operationDuration = formatDuration(node.span.duration_ms);
+        const operationBar = renderBar(node.span.duration_ms, totalDuration, maxBarWidth);
+        const operationColor = spanColor(node.span, slowThresholdMs);
+        lines.push(`  ${ANSI.dim}│${ANSI.reset}  ${operationColor}[${node.span.name}] ${operationDuration} ${operationBar}${ANSI.reset}`);
+        renderChildren(lines, node.children, 1, {
+            totalDuration,
+            maxBarWidth,
+            slowThresholdMs,
+            bottleneckId,
+        });
+    }
+    lines.push(`  ${ANSI.dim}│${ANSI.reset}`);
+    const statusColor = request.status >= 400 ? ANSI.red : ANSI.green;
+    const totalFormatted = formatDuration(request.totalMs);
+    lines.push(`  ${ANSI.dim}└─${ANSI.reset} ${statusColor}${request.status} ${statusText(request.status)}${ANSI.reset} (${totalFormatted})`);
+    return lines.join("\n");
+}
+function renderChildren(lines, children, depth, ctx) {
+    const indent = "  ".repeat(depth);
+    for (let i = 0; i < children.length; i++) {
+        const node = children[i];
+        if (!node) {
+            continue;
+        }
+        const isLast = i === children.length - 1;
+        const provider = isLast ? "└─" : "├─";
+        const duration = formatDuration(node.span.duration_ms);
+        const bar = renderBar(node.span.duration_ms, ctx.totalDuration, ctx.maxBarWidth);
+        const color = spanColor(node.span, ctx.slowThresholdMs);
+        const star = node.span.id === ctx.bottleneckId ? `  ${ANSI.yellow}★${ANSI.reset}` : "";
+        const barSuffix = bar ? ` ${bar}` : "";
+        const nameWidth = 20;
+        const paddedName = node.span.name.padEnd(nameWidth);
+        lines.push(`  ${ANSI.dim}│${ANSI.reset}  ${indent}${ANSI.dim}${provider}${ANSI.reset} ${color}${paddedName}${ANSI.reset} ${duration}${barSuffix}${star}`);
+        if (node.children.length > 0) {
+            renderChildren(lines, node.children, depth + 1, ctx);
+        }
+    }
+}
+function buildTree(spans) {
+    const sorted = [...spans].sort((a, b) => a.startedAt - b.startedAt);
+    const nodeMap = new Map();
+    for (const span of sorted) {
+        nodeMap.set(span.id, { span, children: [] });
+    }
+    const roots = [];
+    for (const span of sorted) {
+        const node = nodeMap.get(span.id);
+        if (!node) {
+            continue;
+        }
+        if (span.parentId) {
+            const parent = nodeMap.get(span.parentId);
+            if (parent) {
+                parent.children.push(node);
+                continue;
+            }
+        }
+        roots.push(node);
+    }
+    return roots;
+}
+function findBottleneck(roots) {
+    if (roots.length === 0) {
+        return null;
+    }
+    const allTopLevel = [];
+    for (const root of roots) {
+        for (const child of root.children) {
+            allTopLevel.push(child.span);
+        }
+    }
+    if (allTopLevel.length === 0) {
+        return null;
+    }
+    const first = allTopLevel[0];
+    if (!first) {
+        return null;
+    }
+    let longest = first;
+    for (const span of allTopLevel) {
+        if (span.duration_ms > longest.duration_ms) {
+            longest = span;
+        }
+    }
+    return longest.id;
+}
+function renderBar(durationMs, totalMs, maxWidth) {
+    if (totalMs <= 0 || durationMs <= 0) {
+        return "";
+    }
+    const ratio = durationMs / totalMs;
+    const width = Math.max(1, Math.round(ratio * maxWidth));
+    return "━".repeat(width);
+}
+function spanColor(span, slowThresholdMs) {
+    if (span.status === "error") {
+        return ANSI.red;
+    }
+    if (span.duration_ms >= slowThresholdMs) {
+        return ANSI.yellow;
+    }
+    return ANSI.green;
+}
+function formatDuration(ms) {
+    if (ms >= 1000) {
+        return `${(ms / 1000).toFixed(1)}s`;
+    }
+    if (ms >= 10) {
+        return `${Math.round(ms)}ms`;
+    }
+    return `${ms.toFixed(1)}ms`;
+}
+function statusText(status) {
+    const texts = {
+        200: "OK",
+        201: "Created",
+        400: "Bad Request",
+        401: "Unauthorized",
+        404: "Not Found",
+        500: "Internal Server Error",
+        502: "Bad Gateway",
+    };
+    return texts[status] ?? "";
+}

package/dist/schema.d.ts

@@ -0,0 +1,74 @@
+import { type ZodString, type ZodType, z } from "zod";
+import type { InferSchemaOutput, ProviderLocaleKey, SchemaLike } from "./types";
+export { z };
+export type SchemaValidationResult<TSchema extends SchemaLike> = {
+    success: true;
+    data: InferSchemaOutput<TSchema>;
+} | {
+    success: false;
+    error: unknown;
+};
+export declare function parseSchema<TSchema extends SchemaLike>(schema: TSchema, value: unknown, fieldPath: string): Promise<InferSchemaOutput<TSchema>>;
+export declare function safeParseSchemaSync<TSchema extends SchemaLike>(schema: TSchema, value: unknown, fieldPath: string): SchemaValidationResult<TSchema>;
+export declare const APIFUSE_SENSITIVE_META_KEY = "x-apifuse-sensitive";
+export declare const APIFUSE_SENSITIVE_KIND_META_KEY = "x-apifuse-sensitive-kind";
+export declare const APIFUSE_DESCRIPTION_KEY_META_KEY = "x-apifuse-description-key";
+export declare const APIFUSE_REDACTION_MARKER = "<redacted>";
+export type SensitivePathSegment = string | "*";
+export type SensitivePath = readonly SensitivePathSegment[];
+export type SensitiveFieldKind = "api_key" | "authorization" | "cookie" | "credential" | "otp" | "password" | "payment_url" | "personal_data" | "phone" | "secret" | "token";
+export interface SensitiveFieldOptions {
+    /**
+     * Mark this schema as sensitive. Defaults to true for the helper presets.
+     */
+    sensitive?: boolean;
+    /**
+     * Machine-readable sensitivity category propagated to JSON Schema.
+     */
+    kind?: SensitiveFieldKind;
+    /**
+     * Optional public description applied with Zod's `.describe()`.
+     */
+    description?: string;
+}
+export declare function describeKey<TSchema extends ZodType>(schema: TSchema, key: ProviderLocaleKey | string): TSchema;
+declare module "zod" {
+    interface ZodType {
+        describeKey(key: ProviderLocaleKey | string): this;
+    }
+}
+export declare function field<TSchema extends ZodType>(schema: TSchema, options?: SensitiveFieldOptions): TSchema;
+export declare function sensitive<TSchema extends ZodType>(schema: TSchema, kind?: SensitiveFieldKind): TSchema;
+export declare const fields: {
+    readonly apiKey: (options?: {
+        description?: string;
+    }) => ZodString;
+    readonly authorization: (options?: {
+        description?: string;
+    }) => ZodString;
+    readonly cookie: (options?: {
+        description?: string;
+    }) => ZodString;
+    readonly otp: (options?: {
+        description?: string;
+    }) => ZodString;
+    readonly password: (options?: {
+        description?: string;
+        minLength?: number;
+    }) => ZodString;
+    readonly paymentUrl: (options?: {
+        description?: string;
+    }) => ZodString;
+    readonly phone: (options?: {
+        description?: string;
+    }) => ZodString;
+    readonly secret: (options?: {
+        description?: string;
+    }) => ZodString;
+    readonly token: (options?: {
+        description?: string;
+    }) => ZodString;
+};
+export declare function isSensitiveSchema(schema: unknown): boolean;
+export declare function collectSensitivePaths(schema: unknown): SensitivePath[];
+export declare function redactPayload(value: unknown, paths?: readonly SensitivePath[]): unknown;

package/dist/schema.js

@@ -0,0 +1,243 @@
+import { z } from "zod";
+import { ValidationError } from "./errors";
+import { providerLocaleKey } from "./i18n/keys";
+export { z };
+function isFailureResult(result) {
+    return "issues" in result;
+}
+function isPromiseResult(result) {
+    return result instanceof Promise;
+}
+function formatStandardSchemaIssues(issues) {
+    return issues.map((issue) => issue.message).join("; ");
+}
+export async function parseSchema(schema, value, fieldPath) {
+    if ("parse" in schema && typeof schema.parse === "function")
+        return schema.parse(value);
+    const result = schema["~standard"].validate(value);
+    const resolved = isPromiseResult(result) ? await result : result;
+    if (isFailureResult(resolved))
+        throw new ValidationError(`Schema validation failed for ${fieldPath}: ${formatStandardSchemaIssues(resolved.issues)}`, { zodError: resolved.issues });
+    return resolved.value;
+}
+export function safeParseSchemaSync(schema, value, fieldPath) {
+    if ("safeParse" in schema && typeof schema.safeParse === "function")
+        return schema.safeParse(value);
+    try {
+        const result = schema["~standard"].validate(value);
+        if (isPromiseResult(result))
+            return {
+                success: false,
+                error: new ValidationError(`Schema validation for ${fieldPath} returned a Promise. defineProvider fixture validation requires synchronous Standard Schema validation.`),
+            };
+        if (isFailureResult(result))
+            return { success: false, error: result.issues };
+        return { success: true, data: result.value };
+    }
+    catch (error) {
+        return { success: false, error };
+    }
+}
+export const APIFUSE_SENSITIVE_META_KEY = "x-apifuse-sensitive";
+export const APIFUSE_SENSITIVE_KIND_META_KEY = "x-apifuse-sensitive-kind";
+export const APIFUSE_DESCRIPTION_KEY_META_KEY = "x-apifuse-description-key";
+export const APIFUSE_REDACTION_MARKER = "<redacted>";
+export function describeKey(schema, key) {
+    const descriptionKey = providerLocaleKey(key);
+    const metadata = schema.meta() ?? {};
+    return schema.meta({
+        ...metadata,
+        [APIFUSE_DESCRIPTION_KEY_META_KEY]: descriptionKey,
+    });
+}
+const describeKeyMethod = function (key) {
+    return describeKey(this, key);
+};
+function installDescribeKeyOnPrototype(prototype) {
+    const target = prototype;
+    if (!target || typeof target.describeKey === "function") {
+        return;
+    }
+    Object.defineProperty(target, "describeKey", {
+        configurable: true,
+        value: describeKeyMethod,
+        writable: true,
+    });
+}
+for (const [name, value] of Object.entries(z)) {
+    if (!name.startsWith("Zod") || name.endsWith("Error")) {
+        continue;
+    }
+    if (typeof value !== "function") {
+        continue;
+    }
+    installDescribeKeyOnPrototype(value.prototype);
+}
+const RESERVED_SENSITIVE_KEYS = new Set([
+    "authorization",
+    "cookie",
+    "secret",
+    "secrets",
+    "token",
+    "accesstoken",
+    "refreshtoken",
+    "apikey",
+    "api_key",
+    "password",
+    "passwd",
+    "otp",
+    "otpcode",
+    "phone",
+    "phonenumber",
+    "paymenturl",
+    "payment_url",
+]);
+export function field(schema, options = {}) {
+    const described = options.description && typeof schema.describe === "function"
+        ? schema.describe(options.description)
+        : schema;
+    const metadata = described.meta() ?? {};
+    return described.meta({
+        ...metadata,
+        ...((options.sensitive ?? true)
+            ? { [APIFUSE_SENSITIVE_META_KEY]: true }
+            : {}),
+        ...(options.kind
+            ? { [APIFUSE_SENSITIVE_KIND_META_KEY]: options.kind }
+            : {}),
+    });
+}
+export function sensitive(schema, kind) {
+    return field(schema, { sensitive: true, kind });
+}
+function sensitiveString(kind, description, options = {}) {
+    const schema = options.minLength === undefined
+        ? z.string()
+        : z.string().min(options.minLength);
+    return field(schema, {
+        kind,
+        description: options.description ?? description,
+    });
+}
+export const fields = {
+    apiKey: (options) => sensitiveString("api_key", "Provider API key or credential secret.", options),
+    authorization: (options) => sensitiveString("authorization", "Authorization header value or bearer credential.", options),
+    cookie: (options) => sensitiveString("cookie", "Cookie header or browser session secret.", options),
+    otp: (options) => sensitiveString("otp", "One-time verification code.", options),
+    password: (options) => sensitiveString("password", "Password credential.", options),
+    paymentUrl: (options) => sensitiveString("payment_url", "Sensitive payment or checkout URL.", options),
+    phone: (options) => sensitiveString("phone", "Phone number or phone-based identity.", options),
+    secret: (options) => sensitiveString("secret", "Provider secret material.", options),
+    token: (options) => sensitiveString("token", "Provider access or refresh token.", options),
+};
+export function isSensitiveSchema(schema) {
+    const metadata = readZodMetadata(schema);
+    return (metadata !== undefined &&
+        Reflect.get(metadata, APIFUSE_SENSITIVE_META_KEY) === true);
+}
+export function collectSensitivePaths(schema) {
+    const out = [];
+    collectSensitivePathsInto(schema, [], out, new Set(), new Set());
+    return out;
+}
+export function redactPayload(value, paths = []) {
+    return redactValue(value, [], paths);
+}
+function collectSensitivePathsInto(schema, path, out, activeSchemas, emittedPaths) {
+    if (!schema || typeof schema !== "object" || activeSchemas.has(schema))
+        return;
+    activeSchemas.add(schema);
+    try {
+        if (isSensitiveSchema(schema))
+            pushSensitivePath(out, emittedPaths, path);
+        const def = readZodDef(schema);
+        if (!def)
+            return;
+        switch (Reflect.get(def, "type")) {
+            case "object": {
+                const shape = readObjectShape(def);
+                for (const [key, child] of Object.entries(shape)) {
+                    collectSensitivePathsInto(child, [...path, key], out, activeSchemas, emittedPaths);
+                }
+                break;
+            }
+            case "array":
+                collectSensitivePathsInto(Reflect.get(def, "element"), [...path, "*"], out, activeSchemas, emittedPaths);
+                break;
+            case "optional":
+            case "nullable":
+            case "default":
+            case "catch":
+            case "readonly":
+                collectSensitivePathsInto(Reflect.get(def, "innerType"), path, out, activeSchemas, emittedPaths);
+                break;
+            case "pipe":
+                collectSensitivePathsInto(Reflect.get(def, "in"), path, out, activeSchemas, emittedPaths);
+                collectSensitivePathsInto(Reflect.get(def, "out"), path, out, activeSchemas, emittedPaths);
+                break;
+        }
+    }
+    finally {
+        activeSchemas.delete(schema);
+    }
+}
+function pushSensitivePath(out, emittedPaths, path) {
+    const key = JSON.stringify(path);
+    if (emittedPaths.has(key))
+        return;
+    emittedPaths.add(key);
+    out.push([...path]);
+}
+function redactValue(value, path, paths) {
+    if (pathMatches(path, paths))
+        return APIFUSE_REDACTION_MARKER;
+    if (Array.isArray(value)) {
+        return value.map((item) => redactValue(item, [...path, "*"], paths));
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (isReservedSensitiveKey(key)) {
+                out[key] = APIFUSE_REDACTION_MARKER;
+            }
+            else {
+                out[key] = redactValue(child, [...path, key], paths);
+            }
+        }
+        return out;
+    }
+    return value;
+}
+function pathMatches(path, patterns) {
+    return patterns.some((pattern) => {
+        if (pattern.length !== path.length)
+            return false;
+        return pattern.every((segment, index) => segment === "*" || segment === path[index]);
+    });
+}
+function isReservedSensitiveKey(key) {
+    const normalized = key.toLowerCase().replace(/[-_\s]/g, "");
+    return (RESERVED_SENSITIVE_KEYS.has(normalized) ||
+        RESERVED_SENSITIVE_KEYS.has(key.toLowerCase()));
+}
+function readZodMetadata(schema) {
+    if (!schema || typeof schema !== "object" || !("meta" in schema)) {
+        return undefined;
+    }
+    const maybeMeta = schema.meta;
+    if (typeof maybeMeta !== "function")
+        return undefined;
+    const metadata = maybeMeta.call(schema);
+    return metadata && typeof metadata === "object" ? metadata : undefined;
+}
+function readZodDef(schema) {
+    if (!schema || typeof schema !== "object")
+        return undefined;
+    const def = Reflect.get(schema, "def") ?? Reflect.get(schema, "_def");
+    return def && typeof def === "object" ? def : undefined;
+}
+function readObjectShape(def) {
+    const shape = Reflect.get(def, "shape");
+    const value = typeof shape === "function" ? shape() : shape;
+    return value && typeof value === "object" ? value : {};
+}

package/dist/serve.d.ts

@@ -0,0 +1 @@
+export { createServerApp, type ServeOptions, serve } from "./server/serve";

package/dist/serve.js

@@ -0,0 +1 @@
+export { createServerApp, serve } from "./server/serve";

package/dist/server/index.d.ts

@@ -0,0 +1,3 @@
+export { createServerApp, type ServeOptions, serve } from "./serve";
+export type { AuthFlowRequest, AuthFlowResponse, AuthFlowSuccessResponse, ConnectionMode, OperationConnection, OperationErrorResponse, OperationRequest, OperationResponse, OperationSuccessResponse, } from "./types";
+export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types";

package/dist/server/index.js

@@ -0,0 +1,2 @@
+export { createServerApp, serve } from "./serve";
+export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types";

package/dist/server/serve.d.ts

@@ -0,0 +1,64 @@
+import { Hono } from "hono";
+import { type ProviderErrorCategory } from "../observability";
+import type { ProviderDefinition, ProviderRuntimeState, SttContext } from "../types";
+import { type OperationRequest } from "./types";
+export declare function resolveProviderProxyAffinityKey(provider: ProviderDefinition, request: OperationRequest, operationId: string): string;
+type ProviderRequestCost = {
+    durationMs: number;
+    cpuUserMicros: number;
+    cpuSystemMicros: number;
+    cpuTotalMicros: number;
+};
+type ProviderServerLogEventBase = ProviderRequestCost & {
+    providerId: string;
+    kind: "operation" | "auth";
+    route: string;
+    requestId?: string;
+    status: number;
+};
+export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
+    level: "info";
+    event: "provider_request_completed";
+}) | (ProviderServerLogEventBase & {
+    level: "warn" | "error";
+    event: "provider_request_failed";
+    code: string;
+    errorClass: string;
+    message: string;
+    upstreamStatus?: number;
+    errorCategory?: ProviderErrorCategory;
+    taxonomyVersion?: string;
+    retryable?: boolean;
+    issues?: Array<{
+        path: string;
+        code: string;
+        message: string;
+    }>;
+}) | {
+    level: "warn";
+    event: "provider_cleanup_failed";
+    providerId: string;
+    kind: "operation";
+    route: string;
+    requestId?: string;
+    resource: "browser" | "stealth";
+    errorClass: string;
+    message: string;
+};
+export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
+export type ProviderServerOptions = {
+    logger?: ProviderServerLogger;
+    /** Optional STT override for tests or custom hosts; local/prod normally resolves from env. */
+    stt?: SttContext;
+    /** Optional runtime state override for tests or custom hosts. Production resolves Redis from env and fails closed when unavailable. */
+    state?: ProviderRuntimeState;
+    /** Allow process-local runtime state only for local development and tests. */
+    allowMemoryStateFallback?: boolean;
+};
+export declare function createServerApp(provider: ProviderDefinition, options?: ProviderServerOptions): Hono;
+export interface ServeOptions extends ProviderServerOptions {
+    host?: string;
+    port?: number;
+}
+export declare function serve(provider: ProviderDefinition, options?: ServeOptions): Promise<void>;
+export {};