@docsxai/engine 0.2.0

package/dist/auth/ui-form.d.ts

@@ -0,0 +1,204 @@
+import { z } from "zod";
+import { type AuthPage, type AuthPageLauncher } from "./browser-session.js";
+import { type AuthContext, type AuthResult, type AuthStrategy } from "./types.js";
+/** One pre-login step (cookie banner, locale picker) shared by the browser-driving strategies. */
+export declare const PreStep: z.ZodObject<{
+    action: z.ZodEnum<["click", "fill"]>;
+    selector: z.ZodString;
+    /** Env var *name* holding the fill value (required for `fill`). */
+    value_env: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    selector: string;
+    action: "fill" | "click";
+    value_env?: string | undefined;
+}, {
+    selector: string;
+    action: "fill" | "click";
+    value_env?: string | undefined;
+}>;
+export type PreStep = z.infer<typeof PreStep>;
+/** Read a required env var by *name*; missing/empty → config error that never echoes a value. */
+export declare function requireEnvVar(strategy: string, what: string, varName: string, env: NodeJS.ProcessEnv): string;
+/** Resolve every `fill` pre-step's `value_env` up front, so a missing var fails before any browser launches. */
+export declare function resolvePreStepValues(strategy: string, steps: PreStep[], env: NodeJS.ProcessEnv): string[];
+/** Execute pre-login steps in order (`values` from {@link resolvePreStepValues}, index-aligned). */
+export declare function runPreSteps(page: AuthPage, steps: PreStep[], values: string[]): Promise<void>;
+export declare const UiFormTotpOptions: z.ZodObject<{
+    /** Env var *name* holding the base32 TOTP secret. */
+    secret_env: z.ZodString;
+    otp_selector: z.ZodString;
+    submit_selector: z.ZodOptional<z.ZodString>;
+    digits: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<6>, z.ZodLiteral<8>]>>;
+    period: z.ZodDefault<z.ZodNumber>;
+    algorithm: z.ZodDefault<z.ZodEnum<["sha1", "sha256"]>>;
+}, "strict", z.ZodTypeAny, {
+    digits: 8 | 6;
+    period: number;
+    algorithm: "sha1" | "sha256";
+    secret_env: string;
+    otp_selector: string;
+    submit_selector?: string | undefined;
+}, {
+    secret_env: string;
+    otp_selector: string;
+    digits?: 8 | 6 | undefined;
+    period?: number | undefined;
+    algorithm?: "sha1" | "sha256" | undefined;
+    submit_selector?: string | undefined;
+}>;
+export type UiFormTotpOptions = z.infer<typeof UiFormTotpOptions>;
+export declare const UiFormOptions: z.ZodEffects<z.ZodObject<{
+    /** Login page; resolved against the target's base URL when relative. */
+    login_url: z.ZodString;
+    username_selector: z.ZodString;
+    password_selector: z.ZodString;
+    submit_selector: z.ZodString;
+    /** Logged-in marker: a selector that appears… */
+    success_selector: z.ZodOptional<z.ZodString>;
+    /** …or a regex (source) the post-login URL matches. One of the two is required. */
+    url_matches: z.ZodOptional<z.ZodString>;
+    /** Per-wait timeout. Default 15000. */
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+    ignore_https_errors: z.ZodDefault<z.ZodBoolean>;
+    /** Pre-login chrome (cookie banners, locale pickers): clicked / filled before the form. */
+    pre_steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        action: z.ZodEnum<["click", "fill"]>;
+        selector: z.ZodString;
+        /** Env var *name* holding the fill value (required for `fill`). */
+        value_env: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }, {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }>, "many">>;
+    totp: z.ZodOptional<z.ZodObject<{
+        /** Env var *name* holding the base32 TOTP secret. */
+        secret_env: z.ZodString;
+        otp_selector: z.ZodString;
+        submit_selector: z.ZodOptional<z.ZodString>;
+        digits: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<6>, z.ZodLiteral<8>]>>;
+        period: z.ZodDefault<z.ZodNumber>;
+        algorithm: z.ZodDefault<z.ZodEnum<["sha1", "sha256"]>>;
+    }, "strict", z.ZodTypeAny, {
+        digits: 8 | 6;
+        period: number;
+        algorithm: "sha1" | "sha256";
+        secret_env: string;
+        otp_selector: string;
+        submit_selector?: string | undefined;
+    }, {
+        secret_env: string;
+        otp_selector: string;
+        digits?: 8 | 6 | undefined;
+        period?: number | undefined;
+        algorithm?: "sha1" | "sha256" | undefined;
+        submit_selector?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    timeout_ms: number;
+    login_url: string;
+    ignore_https_errors: boolean;
+    submit_selector: string;
+    username_selector: string;
+    password_selector: string;
+    pre_steps: {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }[];
+    url_matches?: string | undefined;
+    totp?: {
+        digits: 8 | 6;
+        period: number;
+        algorithm: "sha1" | "sha256";
+        secret_env: string;
+        otp_selector: string;
+        submit_selector?: string | undefined;
+    } | undefined;
+    success_selector?: string | undefined;
+}, {
+    login_url: string;
+    submit_selector: string;
+    username_selector: string;
+    password_selector: string;
+    timeout_ms?: number | undefined;
+    url_matches?: string | undefined;
+    totp?: {
+        secret_env: string;
+        otp_selector: string;
+        digits?: 8 | 6 | undefined;
+        period?: number | undefined;
+        algorithm?: "sha1" | "sha256" | undefined;
+        submit_selector?: string | undefined;
+    } | undefined;
+    ignore_https_errors?: boolean | undefined;
+    success_selector?: string | undefined;
+    pre_steps?: {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }[] | undefined;
+}>, {
+    timeout_ms: number;
+    login_url: string;
+    ignore_https_errors: boolean;
+    submit_selector: string;
+    username_selector: string;
+    password_selector: string;
+    pre_steps: {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }[];
+    url_matches?: string | undefined;
+    totp?: {
+        digits: 8 | 6;
+        period: number;
+        algorithm: "sha1" | "sha256";
+        secret_env: string;
+        otp_selector: string;
+        submit_selector?: string | undefined;
+    } | undefined;
+    success_selector?: string | undefined;
+}, {
+    login_url: string;
+    submit_selector: string;
+    username_selector: string;
+    password_selector: string;
+    timeout_ms?: number | undefined;
+    url_matches?: string | undefined;
+    totp?: {
+        secret_env: string;
+        otp_selector: string;
+        digits?: 8 | 6 | undefined;
+        period?: number | undefined;
+        algorithm?: "sha1" | "sha256" | undefined;
+        submit_selector?: string | undefined;
+    } | undefined;
+    ignore_https_errors?: boolean | undefined;
+    success_selector?: string | undefined;
+    pre_steps?: {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }[] | undefined;
+}>;
+export type UiFormOptions = z.infer<typeof UiFormOptions>;
+export declare class UiFormStrategy implements AuthStrategy {
+    private readonly launcher;
+    private readonly env;
+    readonly name: "ui-form";
+    constructor(launcher?: AuthPageLauncher, env?: NodeJS.ProcessEnv);
+    authenticate(ctx: AuthContext): Promise<AuthResult>;
+    private waitStep;
+}
+/** Shared success wait: a selector that appears, or a URL regex match. Timeouts become config errors. */
+export declare function waitForLoginSuccess(page: AuthPage, opts: {
+    success_selector?: string;
+    url_matches?: string;
+    timeout_ms: number;
+}, strategy: string): Promise<void>;

package/dist/auth/ui-form.js

@@ -0,0 +1,153 @@
+// `ui-form` — drive the app's own login form in a headless Chromium: fill username/password,
+// submit, wait for the logged-in marker, snapshot storageState. `pre_steps` dismiss cookie
+// banners and similar pre-login chrome; `options.totp` hooks an RFC-6238 one-time code in after
+// the password submit (the `totp` catalogue entry composes this strategy).
+import { z } from "zod";
+import { launchAuthPage } from "./browser-session.js";
+import { jarAuthExpiry } from "./cookie-jar.js";
+import { generateTotp } from "./totp.js";
+import { AuthStrategyConfigError, maskSecret, parseStrategyOptions, } from "./types.js";
+/** One pre-login step (cookie banner, locale picker) shared by the browser-driving strategies. */
+export const PreStep = z
+    .object({
+    action: z.enum(["click", "fill"]),
+    selector: z.string().min(1),
+    /** Env var *name* holding the fill value (required for `fill`). */
+    value_env: z.string().min(1).optional(),
+})
+    .strict();
+/** Read a required env var by *name*; missing/empty → config error that never echoes a value. */
+export function requireEnvVar(strategy, what, varName, env) {
+    const value = env[varName];
+    if (!value) {
+        throw new AuthStrategyConfigError(`${strategy}: ${what} $${varName} is ${maskSecret(value)}`);
+    }
+    return value;
+}
+/** Resolve every `fill` pre-step's `value_env` up front, so a missing var fails before any browser launches. */
+export function resolvePreStepValues(strategy, steps, env) {
+    return steps.map((step) => {
+        if (step.action !== "fill")
+            return "";
+        if (!step.value_env) {
+            throw new AuthStrategyConfigError(`${strategy}: pre_steps fill on "${step.selector}" needs value_env (the env var name to fill from)`);
+        }
+        return requireEnvVar(strategy, "pre_steps value_env", step.value_env, env);
+    });
+}
+/** Execute pre-login steps in order (`values` from {@link resolvePreStepValues}, index-aligned). */
+export async function runPreSteps(page, steps, values) {
+    for (const [i, step] of steps.entries()) {
+        if (step.action === "click")
+            await page.click(step.selector);
+        else
+            await page.fill(step.selector, values[i]);
+    }
+}
+export const UiFormTotpOptions = z
+    .object({
+    /** Env var *name* holding the base32 TOTP secret. */
+    secret_env: z.string().min(1),
+    otp_selector: z.string().min(1),
+    submit_selector: z.string().min(1).optional(),
+    digits: z.union([z.literal(6), z.literal(8)]).default(6),
+    period: z.number().int().positive().default(30),
+    algorithm: z.enum(["sha1", "sha256"]).default("sha1"),
+})
+    .strict();
+export const UiFormOptions = z
+    .object({
+    /** Login page; resolved against the target's base URL when relative. */
+    login_url: z.string().min(1),
+    username_selector: z.string().min(1),
+    password_selector: z.string().min(1),
+    submit_selector: z.string().min(1),
+    /** Logged-in marker: a selector that appears… */
+    success_selector: z.string().min(1).optional(),
+    /** …or a regex (source) the post-login URL matches. One of the two is required. */
+    url_matches: z.string().min(1).optional(),
+    /** Per-wait timeout. Default 15000. */
+    timeout_ms: z.number().int().positive().default(15_000),
+    ignore_https_errors: z.boolean().default(false),
+    /** Pre-login chrome (cookie banners, locale pickers): clicked / filled before the form. */
+    pre_steps: z.array(PreStep).default([]),
+    totp: UiFormTotpOptions.optional(),
+})
+    .strict()
+    .refine((o) => o.success_selector !== undefined || o.url_matches !== undefined, {
+    message: "one of success_selector or url_matches is required",
+});
+export class UiFormStrategy {
+    launcher;
+    env;
+    name = "ui-form";
+    constructor(launcher = launchAuthPage, env = process.env) {
+        this.launcher = launcher;
+        this.env = env;
+    }
+    async authenticate(ctx) {
+        const opts = parseStrategyOptions(this.name, UiFormOptions, ctx.options);
+        const { username, password } = ctx.creds;
+        if (!username || !password) {
+            throw new AuthStrategyConfigError(`ui-form: creds_env must map "username" (${maskSecret(username)}) and "password" (${maskSecret(password)})`);
+        }
+        // Read env-var-name options up front so a missing var fails before a browser launches.
+        const totpSecret = opts.totp
+            ? requireEnvVar(this.name, "totp.secret_env", opts.totp.secret_env, this.env)
+            : "";
+        const preStepValues = resolvePreStepValues(this.name, opts.pre_steps, this.env);
+        const page = await this.launcher({
+            baseURL: ctx.baseURL,
+            ...(opts.ignore_https_errors ? { ignoreHTTPSErrors: true } : {}),
+        });
+        try {
+            await page.goto(new URL(opts.login_url, ctx.baseURL).href);
+            await runPreSteps(page, opts.pre_steps, preStepValues);
+            await page.fill(opts.username_selector, username);
+            await page.fill(opts.password_selector, password);
+            await page.click(opts.submit_selector);
+            if (opts.totp) {
+                await this.waitStep(page, opts.totp.otp_selector, opts.timeout_ms, "the TOTP prompt");
+                await page.fill(opts.totp.otp_selector, generateTotp(totpSecret, {
+                    digits: opts.totp.digits,
+                    period: opts.totp.period,
+                    algorithm: opts.totp.algorithm,
+                }));
+                if (opts.totp.submit_selector)
+                    await page.click(opts.totp.submit_selector);
+            }
+            await waitForLoginSuccess(page, opts, "ui-form");
+            const storageState = await page.storageState();
+            const expiresAt = jarAuthExpiry(storageState);
+            return { storageState, ...(expiresAt !== undefined ? { expiresAt } : {}) };
+        }
+        finally {
+            await page.close();
+        }
+    }
+    async waitStep(page, selector, timeoutMs, what) {
+        try {
+            await page.waitForSelector(selector, { timeoutMs });
+        }
+        catch {
+            throw new AuthStrategyConfigError(`ui-form: ${what} ("${selector}") did not appear within ${timeoutMs}ms`);
+        }
+    }
+}
+/** Shared success wait: a selector that appears, or a URL regex match. Timeouts become config errors. */
+export async function waitForLoginSuccess(page, opts, strategy) {
+    try {
+        if (opts.success_selector !== undefined) {
+            await page.waitForSelector(opts.success_selector, { timeoutMs: opts.timeout_ms });
+        }
+        else {
+            await page.waitForUrl(new RegExp(opts.url_matches), { timeoutMs: opts.timeout_ms });
+        }
+    }
+    catch {
+        const expected = opts.success_selector !== undefined
+            ? `success_selector "${opts.success_selector}"`
+            : `url matching /${opts.url_matches}/`;
+        throw new AuthStrategyConfigError(`${strategy}: login did not reach ${expected} within ${opts.timeout_ms}ms — check the credential env vars (values not shown) and the selectors`);
+    }
+}

package/dist/auth/webauthn.d.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { type AuthPageLauncher } from "./browser-session.js";
+import { type AuthContext, type AuthResult, type AuthStrategy } from "./types.js";
+export declare const WebauthnOptions: z.ZodEffects<z.ZodObject<{
+    /** Login page; resolved against the target's base URL when relative. */
+    login_url: z.ZodString;
+    /** The "Sign in with a passkey" control that starts the WebAuthn ceremony. */
+    trigger_selector: z.ZodString;
+    /** Username-first flows: filled with the `username` credential before the trigger. */
+    username_selector: z.ZodOptional<z.ZodString>;
+    success_selector: z.ZodOptional<z.ZodString>;
+    url_matches: z.ZodOptional<z.ZodString>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+    ignore_https_errors: z.ZodDefault<z.ZodBoolean>;
+    pre_steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        action: z.ZodEnum<["click", "fill"]>;
+        selector: z.ZodString;
+        value_env: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }, {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    timeout_ms: number;
+    login_url: string;
+    ignore_https_errors: boolean;
+    pre_steps: {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }[];
+    trigger_selector: string;
+    url_matches?: string | undefined;
+    username_selector?: string | undefined;
+    success_selector?: string | undefined;
+}, {
+    login_url: string;
+    trigger_selector: string;
+    timeout_ms?: number | undefined;
+    url_matches?: string | undefined;
+    ignore_https_errors?: boolean | undefined;
+    username_selector?: string | undefined;
+    success_selector?: string | undefined;
+    pre_steps?: {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }[] | undefined;
+}>, {
+    timeout_ms: number;
+    login_url: string;
+    ignore_https_errors: boolean;
+    pre_steps: {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }[];
+    trigger_selector: string;
+    url_matches?: string | undefined;
+    username_selector?: string | undefined;
+    success_selector?: string | undefined;
+}, {
+    login_url: string;
+    trigger_selector: string;
+    timeout_ms?: number | undefined;
+    url_matches?: string | undefined;
+    ignore_https_errors?: boolean | undefined;
+    username_selector?: string | undefined;
+    success_selector?: string | undefined;
+    pre_steps?: {
+        selector: string;
+        action: "fill" | "click";
+        value_env?: string | undefined;
+    }[] | undefined;
+}>;
+export type WebauthnOptions = z.infer<typeof WebauthnOptions>;
+export declare class WebauthnStrategy implements AuthStrategy {
+    private readonly launcher;
+    private readonly env;
+    readonly name: "webauthn";
+    constructor(launcher?: AuthPageLauncher, env?: NodeJS.ProcessEnv);
+    authenticate(ctx: AuthContext): Promise<AuthResult>;
+}

package/dist/auth/webauthn.js

@@ -0,0 +1,67 @@
+// `webauthn` — passkey login through a CDP virtual authenticator. The authenticator is attached
+// *before* navigation (so the login page's `navigator.credentials` sees a platform authenticator
+// from its first feature probe), then the strategy walks the page's own passkey flow: optional
+// username-first fill, click the trigger, wait for the logged-in marker, snapshot storageState.
+//
+// The virtual device is ctap2 / internal / user-verifying with automatic presence simulation —
+// the standard headless-CI stand-in for Touch ID-style platform authenticators.
+import { z } from "zod";
+import { launchAuthPage } from "./browser-session.js";
+import { jarAuthExpiry } from "./cookie-jar.js";
+import { PreStep, resolvePreStepValues, runPreSteps, waitForLoginSuccess } from "./ui-form.js";
+import { AuthStrategyConfigError, maskSecret, parseStrategyOptions, } from "./types.js";
+export const WebauthnOptions = z
+    .object({
+    /** Login page; resolved against the target's base URL when relative. */
+    login_url: z.string().min(1),
+    /** The "Sign in with a passkey" control that starts the WebAuthn ceremony. */
+    trigger_selector: z.string().min(1),
+    /** Username-first flows: filled with the `username` credential before the trigger. */
+    username_selector: z.string().min(1).optional(),
+    success_selector: z.string().min(1).optional(),
+    url_matches: z.string().min(1).optional(),
+    timeout_ms: z.number().int().positive().default(15_000),
+    ignore_https_errors: z.boolean().default(false),
+    pre_steps: z.array(PreStep).default([]),
+})
+    .strict()
+    .refine((o) => o.success_selector !== undefined || o.url_matches !== undefined, {
+    message: "one of success_selector or url_matches is required",
+});
+export class WebauthnStrategy {
+    launcher;
+    env;
+    name = "webauthn";
+    constructor(launcher = launchAuthPage, env = process.env) {
+        this.launcher = launcher;
+        this.env = env;
+    }
+    async authenticate(ctx) {
+        const opts = parseStrategyOptions(this.name, WebauthnOptions, ctx.options);
+        const { username } = ctx.creds;
+        if (opts.username_selector && !username) {
+            throw new AuthStrategyConfigError(`webauthn: username_selector is set, so creds_env must map "username" (${maskSecret(username)})`);
+        }
+        const preStepValues = resolvePreStepValues(this.name, opts.pre_steps, this.env);
+        const page = await this.launcher({
+            baseURL: ctx.baseURL,
+            ...(opts.ignore_https_errors ? { ignoreHTTPSErrors: true } : {}),
+        });
+        try {
+            // Must precede goto: the page feature-detects authenticators at load.
+            await page.enableVirtualAuthenticator();
+            await page.goto(new URL(opts.login_url, ctx.baseURL).href);
+            await runPreSteps(page, opts.pre_steps, preStepValues);
+            if (opts.username_selector)
+                await page.fill(opts.username_selector, username);
+            await page.click(opts.trigger_selector);
+            await waitForLoginSuccess(page, opts, this.name);
+            const storageState = await page.storageState();
+            const expiresAt = jarAuthExpiry(storageState);
+            return { storageState, ...(expiresAt !== undefined ? { expiresAt } : {}) };
+        }
+        finally {
+            await page.close();
+        }
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1 @@
+export * from "./auth/index.js";

package/dist/auth.js

@@ -0,0 +1,3 @@
+// Target-site auth layer — re-export shim. The implementation lives under `auth/`
+// (one module per strategy); existing imports of `./auth.js` keep working unchanged.
+export * from "./auth/index.js";

package/dist/backend-client-contracts.d.ts

@@ -0,0 +1,88 @@
+import { type RevisionKind } from "./doc-pack.js";
+export declare const API_VERSION: "1";
+export declare const API_VERSION_HEADER = "docsxai-api-version";
+export type RevisionArtifact = "flows" | "annotations" | "screenshots" | "style" | "locators";
+export interface Workspace {
+    id: string;
+    name: string;
+    created_at: string;
+}
+export interface Project {
+    id: string;
+    workspace_id: string;
+    name: string;
+    created_at: string;
+    head_revision_id: string | null;
+}
+export interface Revision {
+    id: string;
+    project_id: string;
+    parent_revision_id: string | null;
+    kind: RevisionKind;
+    author: string;
+    created_at: string;
+    artifacts: RevisionArtifact[];
+    /** True once finalized — artifact PUTs are rejected with 409 from then on. */
+    finalized: boolean;
+}
+export interface RunRecord {
+    id: string;
+    project_id: string;
+    revision_id: string;
+    ok: boolean;
+    duration_ms: number;
+    summary: string;
+    created_at: string;
+}
+/** Reference to a content-addressed blob stored on the backend. */
+export interface BlobRef {
+    sha256: string;
+    bytes: number;
+}
+export declare class BackendClientError extends Error {
+    readonly status?: number | undefined;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, body?: unknown | undefined);
+}
+export interface BackendClientOptions {
+    baseUrl: string;
+    /** Bearer token. Reads from `DOCSX_TOKEN` env if omitted. */
+    token?: string;
+    /** Override the HTTP fetch (for tests). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface FlowsPayload {
+    schema: "docsxai/flows@1";
+    files: Record<string, string>;
+}
+export interface AnnotationsPayload {
+    schema: "docsxai/annotations-bundle@1";
+    files: Record<string, unknown>;
+}
+export interface ScreenshotsPayload {
+    schema: "docsxai/screenshots@2";
+    files: Record<string, BlobRef>;
+}
+export interface StylePayload {
+    schema: "docsxai/style-bundle@1";
+    yaml: string | null;
+    json: unknown;
+}
+export interface LocatorsPayload {
+    schema: "docsxai/locators@1";
+    yaml: string | null;
+}
+export interface BackendTokenFile {
+    access_token: string;
+    refresh_token: string;
+    /** Epoch ms the access token expires. */
+    expires_at: number;
+}
+export interface OAuthLoginOptions {
+    backendUrl: string;
+    /** Receives the authorization URL the operator must open in a browser (the CLI prints it). */
+    onAuthorizeUrl: (url: string) => void;
+    fetch?: typeof globalThis.fetch;
+    /** How long to wait for the browser redirect before giving up. Default 5 minutes. */
+    timeoutMs?: number;
+}

package/dist/backend-client-contracts.js

@@ -0,0 +1,19 @@
+// Wire contracts for `@docsxai/backend` — the leaf shared by the transport, token, OAuth-login and
+// state-cache siblings (`backend-client-*.ts`), re-exported in full from `./backend-client.js`.
+//
+// The contract types are *redeclared* here (not imported from the backend package) so the engine
+// stays decoupled at the package level — there's no runtime nor build-time dep on the backend.
+// Drift is caught by the round-trip integration test that spins up a real stub. The shapes mirror
+// the backend's `api.ts` exactly; if you change one, update the other and the test will tell you.
+export const API_VERSION = "1";
+export const API_VERSION_HEADER = "docsxai-api-version";
+export class BackendClientError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "BackendClientError";
+    }
+}

package/dist/backend-client-oauth-login.d.ts

@@ -0,0 +1,7 @@
+import { type BackendTokenFile, type OAuthLoginOptions } from "./backend-client-contracts.js";
+/**
+ * Drive the authorization-code + PKCE handshake against the backend's minimal authorization
+ * server: start a loopback listener for the redirect, hand the authorize URL to the caller,
+ * await the code, exchange it (S256 verifier) for tokens.
+ */
+export declare function oauthLogin(opts: OAuthLoginOptions): Promise<BackendTokenFile>;