@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/dist/pairing.js

@@ -0,0 +1,235 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { z } from 'zod';
+import { apiOrigin } from './api.js';
+import { fail, SupportPagesError } from './errors.js';
+import { connectionFailure } from './development-tls.js';
+import { CLI_NAME } from './brand.js';
+const hex = z.string().regex(/^[a-f0-9]{64}$/);
+const startSchema = z.object({ pairing_id: hex, pairing_secret: hex, verification_uri: z.string(),
+    user_code: z.string().regex(/^[A-Z0-9]{4}-[A-Z0-9]{4}$/), expires_at: z.iso.datetime(), interval: z.number().int().min(3).max(60) });
+const deliverySchema = z.object({ status: z.literal('authorized'), api_origin: z.string(),
+    account: z.object({ id: z.string().regex(/^[1-9][0-9]*$/), email: z.string().max(320) }),
+    token: z.string().regex(/^sp_local_[a-f0-9]{64}$/),
+    scopes: z.array(z.enum(['read', 'import', 'projects:create', 'publish', 'manage', 'generate'])).min(3).max(6), token_expires_at: z.iso.datetime() });
+const runtime = { fetcher: (...args) => fetch(...args), now: Date.now, sleep: ms => sleep(ms, undefined, { ref: false }) };
+export const REQUIRED_SCOPES = ['read', 'import', 'projects:create'];
+/** Offered alongside the required ones at every sign-in. The approval page is
+ * where the user decides what to grant; sending them back to the browser
+ * mid-task for one more box is worse than one informed decision up front. */
+export const OPTIONAL_SCOPES = ['publish', 'manage', 'generate'];
+/** Device sign-in. Bootstrap secrets and delivery responses never leave this native process. */
+export class Pairing {
+    origin;
+    dev;
+    rt;
+    secret = '';
+    id = '';
+    deadline = 0;
+    interval = 3000;
+    stopped = false;
+    done;
+    failure;
+    status = 'authentication_required';
+    approval;
+    approvalOrigin;
+    requestedScopes = [];
+    constructor(origin, dev, rt = runtime) {
+        this.origin = origin;
+        this.dev = dev;
+        this.rt = rt;
+        this.origin = apiOrigin(origin, dev);
+        this.approvalOrigin = this.origin;
+    }
+    /** `label` is the device name shown on the approval page (never a filesystem path). */
+    async start(label, options) {
+        const device = [...label.replace(/[\p{Cc}\p{Cf}]/gu, '').trim()].slice(0, 100).join('') || 'This device';
+        this.requestedScopes = [...REQUIRED_SCOPES, ...OPTIONAL_SCOPES];
+        let raw;
+        try {
+            raw = await this.request('', { client_name: options.client, workspace_name: device,
+                requested_scopes: this.requestedScopes });
+        }
+        catch (error) {
+            if (error instanceof SupportPagesError && ['invalid_request', 'not_found'].includes(error.code))
+                fail('setup_unsupported', 'This SupportPages.io server does not support device sign-in yet. Ask its administrator to update it.');
+            throw error;
+        }
+        const parsed = startSchema.safeParse(raw);
+        if (!parsed.success)
+            fail('invalid_response', 'The authorization service returned an invalid request.');
+        const value = parsed.data;
+        let approvalUrl;
+        try {
+            approvalUrl = new URL(value.verification_uri);
+        }
+        catch {
+            fail('invalid_response', 'The authorization service returned an invalid approval URL.');
+        }
+        const transportUrl = new URL(this.origin);
+        // Docker exposes native HTTP and canonical browser HTTPS on separate ports.
+        // Only explicit dev mode permits this upgrade on the same local hostname.
+        // All private requests continue to use the configured native API origin.
+        const devUpgrade = this.dev && transportUrl.protocol === 'http:' &&
+            approvalUrl.protocol === 'https:' && approvalUrl.hostname === transportUrl.hostname;
+        if ((approvalUrl.origin !== this.origin && !devUpgrade) ||
+            value.verification_uri !== `${approvalUrl.origin}/settings/mcp/connect/${value.pairing_id}` || value.pairing_secret === value.pairing_id) {
+            fail('invalid_response', 'The authorization service returned an invalid approval URL.');
+        }
+        this.approvalOrigin = approvalUrl.origin;
+        this.deadline = Date.parse(value.expires_at);
+        if (this.deadline <= this.rt.now() || this.deadline > this.rt.now() + 11 * 60_000)
+            fail('invalid_response', 'The authorization deadline is invalid.');
+        this.id = value.pairing_id;
+        this.secret = value.pairing_secret;
+        this.interval = value.interval * 1000;
+        this.approval = { url: value.verification_uri, code: value.user_code, id: value.pairing_id };
+        return this.approval;
+    }
+    cancel() { this.stopped = true; this.secret = ''; this.status = 'authorization_cancelled'; }
+    get finished() { return this.status !== 'authentication_required'; }
+    result() {
+        if (this.failure)
+            throw this.failure;
+        return { status: this.status, verification_uri: this.approval?.url, user_code: this.approval?.code,
+            expires_at: new Date(this.deadline).toISOString(),
+            instructions: this.status === 'authentication_required'
+                ? 'Open the approval link in the user’s browser, compare the code, and approve sign-in for this device. The sign-in finishes automatically while this MCP stays running. Call supportpages_status to check progress. Never ask for a token or approve on the user’s behalf.'
+                : 'Call supportpages_init again to continue.' };
+    }
+    run(save, completed) {
+        if (this.done)
+            return;
+        this.done = this.deliver(save).then(async () => {
+            if (this.stopped)
+                return;
+            this.status = 'ready';
+            try {
+                await completed?.();
+            }
+            catch { /* The credential is already saved; notification is advisory. */ }
+        }).catch(error => { this.failure = error; this.status = 'authorization_failed'; }).finally(() => { this.secret = ''; });
+    }
+    async wait(ms = 20_000) {
+        let timer;
+        try {
+            await Promise.race([this.done, new Promise(resolve => { timer = setTimeout(resolve, ms); timer.unref(); })]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async deliver(save) {
+        let saved = false;
+        while (!this.stopped && this.rt.now() < this.deadline) {
+            await this.rt.sleep(Math.min(this.interval, this.deadline - this.rt.now()));
+            if (this.stopped)
+                return;
+            if (this.rt.now() >= this.deadline)
+                break;
+            try {
+                if (!saved) {
+                    const poll = z.object({ status: z.enum(['pending', 'approved', 'denied', 'expired', 'exchanged', 'completed']) }).safeParse(await this.request('/poll'));
+                    if (!poll.success)
+                        fail('invalid_response', 'Invalid authorization status.');
+                    if (poll.data.status === 'pending')
+                        continue;
+                    if (poll.data.status === 'denied')
+                        fail('authorization_denied', `Sign-in was declined in the browser. Run ${CLI_NAME} login or call supportpages_init to start again.`);
+                    if (poll.data.status === 'expired')
+                        break;
+                    if (poll.data.status === 'completed')
+                        fail('pairing_completed', 'This sign-in request was already completed. Start again to sign in.');
+                    const parsed = deliverySchema.safeParse(await this.request('/exchange'));
+                    if (!parsed.success)
+                        fail('invalid_response', 'The authorization service returned invalid credentials.');
+                    const value = parsed.data;
+                    if (value.api_origin !== this.approvalOrigin || REQUIRED_SCOPES.some(scope => !value.scopes.includes(scope)) ||
+                        value.scopes.some(scope => !this.requestedScopes.includes(scope)) ||
+                        new Set(value.scopes).size !== value.scopes.length || Date.parse(value.token_expires_at) <= this.rt.now()) {
+                        fail('invalid_response', 'The authorization service returned invalid permissions or origin.');
+                    }
+                    if (this.stopped)
+                        return;
+                    await save(value);
+                    saved = true;
+                }
+                if (this.stopped)
+                    return;
+                const ack = await this.request('/acknowledge');
+                if (!z.object({ status: z.literal('completed') }).safeParse(ack).success)
+                    fail('invalid_response', 'Invalid authorization acknowledgment.');
+                return;
+            }
+            catch (error) {
+                if (error instanceof SupportPagesError && ['network_error', 'rate_limited', 'service_unavailable', 'authorization_pending'].includes(error.code))
+                    continue;
+                // An expired delivery window cannot invalidate a credential already saved.
+                if (saved && error instanceof SupportPagesError && error.code === 'pairing_expired')
+                    return;
+                throw error;
+            }
+        }
+        if (!this.stopped && !saved)
+            fail('pairing_expired', `The sign-in request expired. Run ${CLI_NAME} login or call supportpages_init to start again.`);
+    }
+    async request(action, body, method = 'POST') {
+        let response;
+        try {
+            response = await this.rt.fetcher(`${this.origin}/api/v1/mcp/pairings${action ? `/${this.id}${action}` : ''}`, {
+                method, redirect: 'error', signal: AbortSignal.timeout(15_000),
+                headers: { Accept: 'application/json', ...(action ? { Authorization: `Bearer ${this.secret}` } : {}), ...(body ? { 'Content-Type': 'application/json' } : {}) },
+                ...(body ? { body: JSON.stringify(body) } : {})
+            });
+        }
+        catch (error) {
+            connectionFailure(error, this.dev, 'SupportPages.io authorization could not be reached. Retry sign-in.');
+        }
+        if (!response.ok) {
+            const retry = response.headers.get('retry-after');
+            const seconds = retry && /^\d+$/.test(retry) ? Number(retry) : retry ? (Date.parse(retry) - this.rt.now()) / 1000 : 0;
+            if (Number.isFinite(seconds))
+                this.interval = Math.max(this.interval, Math.min(660_000, seconds * 1000));
+            await response.body?.cancel();
+            const code = { 401: 'invalid_pairing', 403: 'permission_denied', 404: 'not_found', 422: 'invalid_request', 409: 'authorization_pending', 410: 'pairing_expired', 429: 'rate_limited', 503: 'service_unavailable' }[response.status] ?? 'remote_error';
+            fail(code, code === 'permission_denied' ? 'Sign-in was refused by SupportPages.io.' : `SupportPages.io authorization returned HTTP ${response.status}. Retry sign-in.`);
+        }
+        if (!response.headers.get('content-type')?.includes('application/json')) {
+            await response.body?.cancel();
+            fail('invalid_response', 'Invalid authorization response.');
+        }
+        const reader = response.body?.getReader();
+        if (!reader)
+            fail('invalid_response', 'Empty authorization response.');
+        const chunks = [];
+        let size = 0;
+        try {
+            while (true) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                size += chunk.value.byteLength;
+                if (size > 16_384) {
+                    await reader.cancel();
+                    fail('invalid_response', 'Authorization response exceeded its size limit.');
+                }
+                chunks.push(chunk.value);
+            }
+        }
+        catch (error) {
+            if (error instanceof SupportPagesError)
+                throw error;
+            fail('network_error', 'The authorization response was interrupted.');
+        }
+        finally {
+            reader.releaseLock();
+        }
+        try {
+            return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            fail('invalid_response', 'Invalid authorization response.');
+        }
+    }
+}
+//# sourceMappingURL=pairing.js.map

package/dist/pairing.js.map

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

package/dist/preferences.d.ts

@@ -0,0 +1,18 @@
+/** Device-wide preferences that need no account, kept beside the credentials. */
+export type DevicePreferences = {
+    version?: 1;
+    default_destination?: 'local';
+    install_id?: string;
+    telemetry?: boolean;
+    telemetry_notice_shown?: boolean;
+    [key: string]: unknown;
+};
+export declare function devicePreferences(configDir: string): Promise<DevicePreferences>;
+/** Atomic private write, like the credentials beside it. */
+export declare function saveDevicePreferences(configDir: string, changes: Partial<DevicePreferences>): Promise<{
+    version: 1;
+    default_destination?: "local";
+    install_id?: string;
+    telemetry?: boolean;
+    telemetry_notice_shown?: boolean;
+}>;

package/dist/preferences.js

@@ -0,0 +1,44 @@
+import { lstat, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+const devicePreferencesFile = (configDir) => path.join(configDir, 'preferences.json');
+export async function devicePreferences(configDir) {
+    try {
+        const value = JSON.parse(await readFile(devicePreferencesFile(configDir), 'utf8'));
+        return value && typeof value === 'object' && value.version === 1 ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Atomic private write, like the credentials beside it. */
+export async function saveDevicePreferences(configDir, changes) {
+    const file = devicePreferencesFile(configDir);
+    const value = { ...await devicePreferences(configDir), ...changes, version: 1 };
+    await mkdir(configDir, { recursive: true, mode: 0o700 });
+    try {
+        if ((await lstat(file)).isSymbolicLink())
+            throw new Error(`Refusing to write through a symlink: ${file}`);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        const handle = await open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(value, null, 2) + '\n');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return value;
+}
+//# sourceMappingURL=preferences.js.map

package/dist/preferences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preferences.js","sourceRoot":"","sources":["../src/preferences.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAY7B,MAAM,qBAAqB,GAAG,CAAC,SAAiB,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;AAE9F,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,SAAiB;IACvD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACnF,OAAO,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC;IAAC,CAAC;AACxB,CAAC;AAED,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,SAAiB,EAAE,OAAmC;IAChG,MAAM,IAAI,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,EAAE,GAAG,MAAM,iBAAiB,CAAC,SAAS,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,CAAU,EAAE,CAAC;IACzF,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACzD,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,IAAI,EAAE,CAAC,CAAC;IAC5G,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAAC,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,KAAK,CAAC;IAAC,CAAC;IACxF,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,UAAU,EAAE,MAAM,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAClD,IAAI,CAAC;YAAC,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;YAAC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QAAC,CAAC;gBACnF,CAAC;YAAC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QAAC,CAAC;QACjC,MAAM,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;YAAS,CAAC;QAAC,MAAM,EAAE,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAAC,CAAC;IACnD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/progress.d.ts

@@ -0,0 +1,205 @@
+import { z } from 'zod';
+import type { Bridge } from './bridge.js';
+export declare const progressResponse: z.ZodObject<{
+    run_id: z.ZodUUID;
+    attempt: z.ZodUUID;
+    state: z.ZodEnum<{
+        running: "running";
+        failed: "failed";
+        cancelled: "cancelled";
+        interrupted: "interrupted";
+        complete: "complete";
+        kept: "kept";
+        discarded: "discarded";
+    }>;
+    sequence: z.ZodNumber;
+    article: z.ZodObject<{
+        repository_connection: z.ZodOptional<z.ZodObject<{
+            writer: z.ZodOptional<z.ZodObject<{
+                version: z.ZodLiteral<1>;
+                actions: z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodTransform<Partial<Record<"read_articles" | "create_article" | "update_article" | "edit_article" | "publish_article" | "unpublish_article" | "delete_article" | "find_article_gaps" | "suggest_sections" | "recommend_articles" | "review_sections" | "review_recommendations" | "create_video_walkthrough" | "get_operation" | "generate_help_centre", {
+                    action: "read_articles" | "create_article" | "update_article" | "edit_article" | "publish_article" | "unpublish_article" | "delete_article" | "find_article_gaps" | "suggest_sections" | "recommend_articles" | "review_sections" | "review_recommendations" | "create_video_walkthrough" | "get_operation" | "generate_help_centre";
+                    allowed: boolean;
+                    execution: "local" | "remote" | "hosted";
+                    required_scopes: string[];
+                    next_step: {
+                        code: string;
+                        message: string;
+                        requested_action: "read_articles" | "create_article" | "update_article" | "edit_article" | "publish_article" | "unpublish_article" | "delete_article" | "find_article_gaps" | "suggest_sections" | "recommend_articles" | "review_sections" | "review_recommendations" | "create_video_walkthrough" | "get_operation" | "generate_help_centre";
+                        missing_scopes?: ("read" | "import" | "publish" | "manage" | "generate")[] | undefined;
+                        url?: string | undefined;
+                    } | null;
+                }>>, Record<string, unknown>>>;
+            }, z.core.$strip>>;
+            state: z.ZodEnum<{
+                not_connected: "not_connected";
+                connected: "connected";
+                disconnected: "disconnected";
+                suspended: "suspended";
+            }>;
+            connect_url: z.ZodURL;
+            capabilities: z.ZodObject<{
+                sections: z.ZodBoolean;
+                suggestions: z.ZodBoolean;
+                code_analysis: z.ZodBoolean;
+                maintenance: z.ZodBoolean;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+        id: z.ZodString;
+        revision: z.ZodString;
+        status: z.ZodEnum<{
+            draft: "draft";
+            published: "published";
+        }>;
+        editor_url: z.ZodURL;
+        public_url: z.ZodNullable<z.ZodURL>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare function openPreview(url: string): Promise<boolean>;
+/** Session-owned relay. The host writer only writes artifacts, never credentials. */
+export declare class ProgressRelay {
+    private bridge;
+    private open;
+    private timer?;
+    private running;
+    private failures;
+    private generation;
+    constructor(bridge: Bridge, open?: typeof openPreview);
+    stop(): void;
+    start(id: string): void;
+    private schedule;
+    ensureStartedUnlocked(id: string): Promise<{
+        id: string;
+        local_article_id: string;
+        artifact_dir: string;
+        started_at: string;
+        section_id: string | null;
+        status: "failed" | "prepared" | "finalized" | "cancelled" | "interrupted";
+        skills_version: string;
+        article_type?: string | undefined;
+        progress?: {
+            attempt: string;
+            sequence: number;
+            next_attempt?: string | undefined;
+            article?: {
+                id: string;
+                revision: string;
+                status: "draft" | "published";
+                editor_url: string;
+                public_url: string | null;
+                repository_connection?: {
+                    state: "not_connected" | "connected" | "disconnected" | "suspended";
+                    connect_url: string;
+                    capabilities: {
+                        sections: boolean;
+                        suggestions: boolean;
+                        code_analysis: boolean;
+                        maintenance: boolean;
+                    };
+                    writer?: {
+                        version: 1;
+                        actions: Partial<Record<"read_articles" | "create_article" | "update_article" | "edit_article" | "publish_article" | "unpublish_article" | "delete_article" | "find_article_gaps" | "suggest_sections" | "recommend_articles" | "review_sections" | "review_recommendations" | "create_video_walkthrough" | "get_operation" | "generate_help_centre", {
+                            action: "read_articles" | "create_article" | "update_article" | "edit_article" | "publish_article" | "unpublish_article" | "delete_article" | "find_article_gaps" | "suggest_sections" | "recommend_articles" | "review_sections" | "review_recommendations" | "create_video_walkthrough" | "get_operation" | "generate_help_centre";
+                            allowed: boolean;
+                            execution: "local" | "remote" | "hosted";
+                            required_scopes: string[];
+                            next_step: {
+                                code: string;
+                                message: string;
+                                requested_action: "read_articles" | "create_article" | "update_article" | "edit_article" | "publish_article" | "unpublish_article" | "delete_article" | "find_article_gaps" | "suggest_sections" | "recommend_articles" | "review_sections" | "review_recommendations" | "create_video_walkthrough" | "get_operation" | "generate_help_centre";
+                                missing_scopes?: ("read" | "import" | "publish" | "manage" | "generate")[] | undefined;
+                                url?: string | undefined;
+                            } | null;
+                        }>>;
+                    } | undefined;
+                } | undefined;
+            } | undefined;
+            article_hash?: string | undefined;
+            image_hashes?: Record<string, string> | undefined;
+            last_heartbeat?: number | undefined;
+            open_attempted?: boolean | undefined;
+            browser_opened?: boolean | undefined;
+            sync_error?: string | undefined;
+            sync_failures?: number | undefined;
+            pending?: {
+                sequence: number;
+                directory: string;
+            } | undefined;
+        } | undefined;
+        title?: string | undefined;
+        api_origin?: string | undefined;
+        project_id?: string | undefined;
+        codebase_dir?: string | undefined;
+        prefer_background?: boolean | undefined;
+        open_when_ready?: boolean | undefined;
+        execution_mode?: "background" | "foreground" | undefined;
+        host_task_id?: string | undefined;
+        writer_token?: string | undefined;
+        writer_started_at?: string | undefined;
+        writer_completed_at?: string | undefined;
+        first_writer_started_at?: string | undefined;
+        ready_for_review_at?: string | undefined;
+        repository_invitation?: {
+            id: string;
+            message: string;
+            connect_url: string;
+        } | undefined;
+        repository_reminder_checked?: boolean | undefined;
+        hosting_invitation?: {
+            id: string;
+            message: string;
+        } | undefined;
+        hosting_reminder_checked?: boolean | undefined;
+        session_id?: string | undefined;
+        updated_at?: string | undefined;
+        phase?: "published" | "failed" | "prepared" | "cancelled" | "interrupted" | "writing" | "finalizing" | "uploading" | "upload_failed" | "ready_for_review" | "saved" | undefined;
+        bundle_dir?: string | undefined;
+        bundle_hash?: string | undefined;
+        local_export?: {
+            directory: string;
+            markdown_path?: string | undefined;
+            sync_error?: string | undefined;
+        } | undefined;
+        export_path?: string | undefined;
+        remote?: {
+            id: string;
+            revision: string;
+            status: "draft" | "published";
+            editor_url: string;
+            public_url: string | null;
+            repository_connection?: {
+                state: "not_connected" | "connected" | "disconnected" | "suspended";
+                connect_url: string;
+                capabilities: {
+                    sections: boolean;
+                    suggestions: boolean;
+                    code_analysis: boolean;
+                    maintenance: boolean;
+                };
+                writer?: {
+                    version: 1;
+                    actions: Partial<Record<"read_articles" | "create_article" | "update_article" | "edit_article" | "publish_article" | "unpublish_article" | "delete_article" | "find_article_gaps" | "suggest_sections" | "recommend_articles" | "review_sections" | "review_recommendations" | "create_video_walkthrough" | "get_operation" | "generate_help_centre", {
+                        action: "read_articles" | "create_article" | "update_article" | "edit_article" | "publish_article" | "unpublish_article" | "delete_article" | "find_article_gaps" | "suggest_sections" | "recommend_articles" | "review_sections" | "review_recommendations" | "create_video_walkthrough" | "get_operation" | "generate_help_centre";
+                        allowed: boolean;
+                        execution: "local" | "remote" | "hosted";
+                        required_scopes: string[];
+                        next_step: {
+                            code: string;
+                            message: string;
+                            requested_action: "read_articles" | "create_article" | "update_article" | "edit_article" | "publish_article" | "unpublish_article" | "delete_article" | "find_article_gaps" | "suggest_sections" | "recommend_articles" | "review_sections" | "review_recommendations" | "create_video_walkthrough" | "get_operation" | "generate_help_centre";
+                            missing_scopes?: ("read" | "import" | "publish" | "manage" | "generate")[] | undefined;
+                            url?: string | undefined;
+                        } | null;
+                    }>>;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+        error?: {
+            code: string;
+            message: string;
+        } | undefined;
+    }>;
+    tick(id: string, scheduled?: boolean, generation?: number): Promise<void>;
+    private exportLocalUnlocked;
+    sendPendingUnlocked(id: string): Promise<void>;
+}