@mearl/plugin-qoder 0.0.0-stage → 3.0.0-beta.10

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { createQoderPairingInfo, formatQoderPairingOutput } from './pairing.js';
+import { readFileSync } from 'node:fs';
+if (process.argv[2] === '--version' || process.argv[2] === '-v')
+    console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version);
+else if (process.argv[2] === 'pair')
+    console.log(formatQoderPairingOutput(createQoderPairingInfo()));
+else {
+    console.log('Usage: mearl-qoder pair\nInstall the Qoder capability preset on the browser machine before starting its connector.');
+    if (process.argv[2] && !['--help', '-h'].includes(process.argv[2]))
+        process.exitCode = 2;
+}

package/dist/connector.d.ts

@@ -0,0 +1,108 @@
+import type { CloudConnectorStateChange } from '@mearl/cloud-connector/contracts';
+import type { ConnectorIdentity } from '@mearl/cloud-connector/contracts';
+import type { QoderConnectorEndpoint } from './endpoint.js';
+export declare const QODER_TOOL_NAME = "mearl";
+export declare const DEFAULT_QODER_API_BASE_URL = "https://api.qoder.com";
+export type QoderContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: 'image/png' | 'image/jpeg';
+        data: string;
+    };
+};
+export interface QoderPublicEvent {
+    id?: string;
+    type?: string;
+    name?: string;
+    input?: unknown;
+    processed_at?: string;
+    [key: string]: unknown;
+}
+interface QoderSession {
+    id: string;
+    status?: string;
+    updated_at?: string;
+}
+export interface QoderPairingRequest {
+    sessionId: string;
+    event: QoderPublicEvent & {
+        id: string;
+    };
+}
+export interface QoderSseFrame {
+    id?: string;
+    event?: string;
+    data: QoderPublicEvent;
+}
+export declare class QoderApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export interface FormattedQoderResult {
+    content: QoderContentBlock[];
+    fallbackContent: QoderContentBlock[];
+}
+/** Format screenshots as multimodal tool results while retaining a text-only API fallback. */
+export declare function formatQoderToolResult(value: unknown): FormattedQoderResult;
+export declare class QoderApiClient {
+    private readonly token;
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    constructor(token: string, baseUrl?: string, fetchImpl?: typeof fetch);
+    private request;
+    listSessions(createdAfter: string, signal?: AbortSignal): Promise<QoderSession[]>;
+    listCustomToolEvents(sessionId: string, createdAfter: string, signal?: AbortSignal): Promise<QoderPublicEvent[]>;
+    findPairingRequest(pairingCode: string, createdAfter: string, signal?: AbortSignal): Promise<QoderPairingRequest | null>;
+    sendCustomToolResult(sessionId: string, customToolUseId: string, content: QoderContentBlock[], isError?: boolean, signal?: AbortSignal): Promise<string | undefined>;
+    streamEvents(sessionId: string, lastEventId: string | undefined, signal: AbortSignal, onFrame: (frame: QoderSseFrame) => Promise<void>, onOpen?: () => void): Promise<void>;
+}
+export declare function parseQoderSse(body: ReadableStream<Uint8Array>, onFrame: (frame: QoderSseFrame) => Promise<void>): Promise<void>;
+export interface QoderConnectorOptions {
+    endpoint: QoderConnectorEndpoint;
+    identity: ConnectorIdentity;
+    reconnectInterval?: number;
+    maxReconnectAttempts?: number;
+    failFast?: boolean;
+    token?: string;
+    apiBaseUrl?: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+    invokeAction?: (action: string, payload: Record<string, unknown>, options: {
+        browser?: string;
+        timeoutSec: number;
+    }) => Promise<unknown>;
+    onConnected?: () => void;
+    onInitialConnectionFailed?: (message: string) => void;
+    onStateChange?: (change: CloudConnectorStateChange) => void;
+}
+export declare class QoderConnector {
+    private readonly options;
+    private readonly api;
+    private readonly now;
+    private readonly sleep;
+    private readonly invokeAction;
+    private readonly reconnectInterval;
+    private readonly maxReconnectAttempts;
+    private abortController;
+    private reconnectAttempts;
+    private running;
+    private connected;
+    private sessionId;
+    private lastEventId;
+    private readonly cachedResults;
+    constructor(options: QoderConnectorOptions);
+    connect(): void;
+    disconnect(): void;
+    private run;
+    private findPairing;
+    private completePairing;
+    private handleFrame;
+    private executeTool;
+    private rememberResult;
+}
+export {};

package/dist/connector.js

@@ -0,0 +1,517 @@
+import { resolveActionTimeoutSec } from '@mearl/client/action-timeouts';
+import { qoderAuthenticationHint, resolveQoderPersonalAccessToken } from './auth.js';
+export const QODER_TOOL_NAME = 'mearl';
+export const DEFAULT_QODER_API_BASE_URL = 'https://api.qoder.com';
+const DEFAULT_DISCOVERY_WINDOW_MS = 60 * 60 * 1000;
+const DEFAULT_RECONNECT_INTERVAL_MS = 5000;
+const MAX_RECENT_SESSIONS = 100;
+const MAX_RECENT_TOOL_EVENTS = 20;
+const MAX_CACHED_RESULTS = 100;
+export class QoderApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'QoderApiError';
+    }
+}
+class QoderPairingExpiredError extends Error {
+    constructor() {
+        super('Qoder pairing is no longer pending. Generate a new pairing URL with `npx @mearl/plugin-qoder pair`, run the new connector command, and immediately invoke the mearl tool with action "pair". Do not reuse this URL.');
+        this.name = 'QoderPairingExpiredError';
+    }
+}
+function isPendingActionNotFound(error) {
+    return (error instanceof QoderApiError &&
+        /^Pending action\b.*\bwas not found\.?$/i.test(error.message.trim()));
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value ?? null);
+    }
+    catch {
+        return JSON.stringify({ error: 'Mearl returned a value that cannot be serialized' });
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asScreenshot(value) {
+    if (!isRecord(value) || typeof value.data !== 'string' || !isRecord(value.meta))
+        return null;
+    const format = value.meta.format;
+    if (format !== 'png' && format !== 'jpeg')
+        return null;
+    return { data: value.data, meta: { ...value.meta, format } };
+}
+function extractBatchScreenshots(value) {
+    if (!isRecord(value) || !Array.isArray(value.results))
+        return null;
+    const screenshots = [];
+    const results = value.results.map(result => {
+        if (!isRecord(result) || result.action !== 'page_screenshot')
+            return result;
+        const screenshot = asScreenshot(result.data);
+        if (!screenshot)
+            return result;
+        const data = { ...result.data };
+        delete data.data;
+        data.meta = screenshot.meta;
+        data.imageContentIndex = screenshots.length + 1;
+        screenshots.push(screenshot);
+        return { ...result, data };
+    });
+    if (screenshots.length === 0)
+        return null;
+    return { metadata: { ...value, results }, screenshots };
+}
+function imageContentBlock(screenshot) {
+    return {
+        type: 'image',
+        source: {
+            type: 'base64',
+            media_type: `image/${screenshot.meta.format}`,
+            data: screenshot.data,
+        },
+    };
+}
+/** Format screenshots as multimodal tool results while retaining a text-only API fallback. */
+export function formatQoderToolResult(value) {
+    const directScreenshot = asScreenshot(value);
+    const nestedScreenshot = !directScreenshot && isRecord(value) ? asScreenshot(value.screenshot) : null;
+    const screenshot = directScreenshot ?? nestedScreenshot;
+    if (!screenshot) {
+        const batch = extractBatchScreenshots(value);
+        if (batch) {
+            return {
+                content: [
+                    { type: 'text', text: safeJson(batch.metadata) },
+                    ...batch.screenshots.map(imageContentBlock),
+                ],
+                fallbackContent: [{ type: 'text', text: safeJson(value) }],
+            };
+        }
+    }
+    if (!screenshot) {
+        const content = [{ type: 'text', text: safeJson(value) }];
+        return { content, fallbackContent: content };
+    }
+    let metadata;
+    if (directScreenshot) {
+        metadata = { meta: screenshot.meta };
+    }
+    else {
+        metadata = { ...value, screenshot: { meta: screenshot.meta } };
+    }
+    return {
+        content: [{ type: 'text', text: safeJson(metadata) }, imageContentBlock(screenshot)],
+        fallbackContent: [{ type: 'text', text: safeJson(value) }],
+    };
+}
+function pairingCodeFromEvent(event) {
+    if (event.type !== 'agent.custom_tool_use' || event.name !== QODER_TOOL_NAME)
+        return null;
+    if (!isRecord(event.input) || event.input.action !== 'pair')
+        return null;
+    const payload = isRecord(event.input.payload)
+        ? event.input.payload
+        : isRecord(event.input.data)
+            ? event.input.data
+            : null;
+    return payload && typeof payload.code === 'string' ? payload.code : null;
+}
+function qoderErrorMessage(status, body) {
+    try {
+        const parsed = JSON.parse(body);
+        const message = parsed.error?.message ?? parsed.message;
+        if (typeof message === 'string' && message.trim())
+            return message.trim();
+    }
+    catch {
+        // A non-JSON proxy response is summarized by status below.
+    }
+    return `Qoder API request failed with HTTP ${status}`;
+}
+export class QoderApiClient {
+    token;
+    fetchImpl;
+    baseUrl;
+    constructor(token, baseUrl = DEFAULT_QODER_API_BASE_URL, fetchImpl = fetch) {
+        this.token = token;
+        this.fetchImpl = fetchImpl;
+        const parsed = new URL(baseUrl);
+        if (parsed.protocol !== 'https:' &&
+            parsed.hostname !== 'localhost' &&
+            parsed.hostname !== '127.0.0.1') {
+            throw new Error('Qoder API base URL must use https:// (localhost may use http:// for tests)');
+        }
+        this.baseUrl = parsed.toString().replace(/\/$/, '');
+    }
+    async request(path, init = {}) {
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                ...init.headers,
+            },
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            const message = qoderErrorMessage(response.status, body);
+            throw new QoderApiError(response.status === 401 ? `${message}\n${qoderAuthenticationHint()}` : message, response.status);
+        }
+        return response;
+    }
+    async listSessions(createdAfter, signal) {
+        const query = new URLSearchParams({
+            limit: String(MAX_RECENT_SESSIONS),
+            order: 'desc',
+            'created_at[gte]': createdAfter,
+        });
+        const response = await this.request(`/api/v1/cloud/sessions?${query}`, { signal });
+        const body = (await response.json());
+        return Array.isArray(body.data)
+            ? body.data.filter(session => typeof session.id === 'string')
+            : [];
+    }
+    async listCustomToolEvents(sessionId, createdAfter, signal) {
+        const query = new URLSearchParams({
+            limit: String(MAX_RECENT_TOOL_EVENTS),
+            order: 'desc',
+            types: 'agent.custom_tool_use',
+            'created_at[gte]': createdAfter,
+        });
+        const response = await this.request(`/api/v1/cloud/sessions/${encodeURIComponent(sessionId)}/events?${query}`, { signal });
+        const body = (await response.json());
+        return Array.isArray(body.data) ? body.data : [];
+    }
+    async findPairingRequest(pairingCode, createdAfter, signal) {
+        const sessions = await this.listSessions(createdAfter, signal);
+        for (const session of sessions) {
+            const events = await this.listCustomToolEvents(session.id, createdAfter, signal);
+            const event = events.find(candidate => pairingCodeFromEvent(candidate) === pairingCode);
+            if (event?.id)
+                return { sessionId: session.id, event: { ...event, id: event.id } };
+        }
+        return null;
+    }
+    async sendCustomToolResult(sessionId, customToolUseId, content, isError = false, signal) {
+        const response = await this.request(`/api/v1/cloud/sessions/${encodeURIComponent(sessionId)}/events`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            signal,
+            body: JSON.stringify({
+                events: [
+                    {
+                        type: 'user.custom_tool_result',
+                        custom_tool_use_id: customToolUseId,
+                        content,
+                        is_error: isError,
+                    },
+                ],
+            }),
+        });
+        const body = (await response.json());
+        return body.data?.[0]?.id;
+    }
+    async streamEvents(sessionId, lastEventId, signal, onFrame, onOpen) {
+        const response = await this.request(`/api/v1/cloud/sessions/${encodeURIComponent(sessionId)}/events/stream`, {
+            headers: {
+                Accept: 'text/event-stream',
+                ...(lastEventId ? { 'Last-Event-ID': lastEventId } : {}),
+            },
+            signal,
+        });
+        if (!response.body)
+            throw new Error('Qoder event stream returned no response body');
+        onOpen?.();
+        await parseQoderSse(response.body, onFrame);
+    }
+}
+export async function parseQoderSse(body, onFrame) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let frameLines = [];
+    const dispatch = async () => {
+        if (frameLines.length === 0)
+            return;
+        let id;
+        let event;
+        const data = [];
+        for (const line of frameLines) {
+            if (!line || line.startsWith(':'))
+                continue;
+            const separator = line.indexOf(':');
+            const field = separator === -1 ? line : line.slice(0, separator);
+            const value = separator === -1 ? '' : line.slice(separator + 1).replace(/^ /, '');
+            if (field === 'id')
+                id = value;
+            else if (field === 'event')
+                event = value;
+            else if (field === 'data')
+                data.push(value);
+        }
+        frameLines = [];
+        if (data.length === 0)
+            return;
+        const parsed = JSON.parse(data.join('\n'));
+        await onFrame({ ...(id ? { id } : {}), ...(event ? { event } : {}), data: parsed });
+    };
+    while (true) {
+        const { done, value } = await reader.read();
+        buffer += decoder.decode(value, { stream: !done });
+        let newlineIndex;
+        while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+            const line = buffer.slice(0, newlineIndex).replace(/\r$/, '');
+            buffer = buffer.slice(newlineIndex + 1);
+            if (line === '')
+                await dispatch();
+            else
+                frameLines.push(line);
+        }
+        if (done)
+            break;
+    }
+    if (buffer)
+        frameLines.push(buffer.replace(/\r$/, ''));
+    await dispatch();
+}
+function defaultSleep(milliseconds, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason ?? new Error('Aborted'));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error('Aborted'));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, milliseconds);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function toolInput(event) {
+    if (!isRecord(event.input) || typeof event.input.action !== 'string') {
+        throw new Error('Qoder mearl tool input requires a string action');
+    }
+    const browser = typeof event.input.browser === 'string' ? event.input.browser : undefined;
+    const timeoutSec = typeof event.input.timeoutSec === 'number' && Number.isFinite(event.input.timeoutSec)
+        ? event.input.timeoutSec
+        : undefined;
+    const payloadValue = event.input.payload ?? event.input.data ?? {};
+    if (!isRecord(payloadValue)) {
+        throw new Error('Qoder mearl tool input payload must be an object');
+    }
+    return {
+        action: event.input.action,
+        payload: payloadValue,
+        ...(browser ? { browser } : {}),
+        ...(timeoutSec === undefined ? {} : { timeoutSec }),
+    };
+}
+export class QoderConnector {
+    options;
+    api;
+    now;
+    sleep;
+    invokeAction;
+    reconnectInterval;
+    maxReconnectAttempts;
+    abortController = null;
+    reconnectAttempts = 0;
+    running = false;
+    connected = false;
+    sessionId = null;
+    lastEventId;
+    cachedResults = new Map();
+    constructor(options) {
+        this.options = options;
+        const token = resolveQoderPersonalAccessToken({ token: options.token });
+        if (!token) {
+            throw new Error(`Qoder authentication is required.\n${qoderAuthenticationHint()}`);
+        }
+        this.api = new QoderApiClient(token, options.apiBaseUrl ?? DEFAULT_QODER_API_BASE_URL, options.fetchImpl);
+        this.now = options.now ?? Date.now;
+        this.sleep = options.sleep ?? defaultSleep;
+        this.invokeAction = options.invokeAction ?? (async () => { throw new Error('Qoder connector requires an invokeAction host'); });
+        this.reconnectInterval = options.reconnectInterval ?? DEFAULT_RECONNECT_INTERVAL_MS;
+        this.maxReconnectAttempts = options.maxReconnectAttempts ?? -1;
+    }
+    connect() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.options.onStateChange?.({ state: 'connecting' });
+        this.abortController = new AbortController();
+        void this.run(this.abortController.signal);
+    }
+    disconnect() {
+        this.running = false;
+        this.abortController?.abort();
+        this.abortController = null;
+    }
+    async run(signal) {
+        while (!signal.aborted) {
+            try {
+                if (!this.sessionId) {
+                    const pairing = await this.findPairing(signal);
+                    await this.completePairing(pairing, signal);
+                }
+                const sessionId = this.sessionId;
+                await this.api.streamEvents(sessionId, this.lastEventId, signal, async (frame) => this.handleFrame(sessionId, frame, signal), () => {
+                    this.reconnectAttempts = 0;
+                    this.options.onStateChange?.({ state: 'connected' });
+                });
+                if (!signal.aborted)
+                    throw new Error('Qoder event stream ended');
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return;
+                const message = error instanceof Error ? error.message : String(error);
+                if (!this.connected && error instanceof QoderPairingExpiredError) {
+                    this.running = false;
+                    this.options.onStateChange?.({ state: 'failed', reason: message });
+                    if (this.options.onInitialConnectionFailed) {
+                        this.options.onInitialConnectionFailed(message);
+                    }
+                    else {
+                        console.error(`[CloudConnector] Qoder connection error: ${message}`);
+                    }
+                    return;
+                }
+                if (!this.connected && this.options.failFast) {
+                    this.options.onStateChange?.({ state: 'failed', reason: message });
+                    this.options.onInitialConnectionFailed?.(message);
+                    this.running = false;
+                    return;
+                }
+                this.reconnectAttempts += 1;
+                if (this.maxReconnectAttempts !== -1 &&
+                    this.reconnectAttempts > this.maxReconnectAttempts) {
+                    console.error(`[CloudConnector] Qoder max reconnect attempts (${this.maxReconnectAttempts}) reached`);
+                    this.options.onStateChange?.({
+                        state: 'failed',
+                        reason: message,
+                        reconnectAttempt: this.reconnectAttempts,
+                    });
+                    this.running = false;
+                    return;
+                }
+                console.error(`[CloudConnector] Qoder connection error: ${message}`);
+                this.options.onStateChange?.({
+                    state: 'reconnecting',
+                    reason: message,
+                    reconnectAttempt: this.reconnectAttempts,
+                    retryInMs: this.reconnectInterval,
+                });
+                try {
+                    await this.sleep(this.reconnectInterval, signal);
+                }
+                catch {
+                    return;
+                }
+            }
+        }
+    }
+    async findPairing(signal) {
+        const createdAt = this.options.endpoint.createdAt ?? this.now();
+        const createdAfter = new Date(createdAt - DEFAULT_DISCOVERY_WINDOW_MS).toISOString();
+        const pairing = await this.api.findPairingRequest(this.options.endpoint.pairingCode, createdAfter, signal);
+        if (!pairing) {
+            throw new Error('Qoder pairing request was not found. Ask the Agent to call the mearl tool with action "pair" and the code from this URL.');
+        }
+        return pairing;
+    }
+    async completePairing(pairing, signal) {
+        if (!this.connected) {
+            let resultEventId;
+            try {
+                resultEventId = await this.api.sendCustomToolResult(pairing.sessionId, pairing.event.id, [
+                    {
+                        type: 'text',
+                        text: safeJson({
+                            connected: true,
+                            connectorId: this.options.identity.connectorId,
+                            name: this.options.identity.name,
+                        }),
+                    },
+                ], false, signal);
+            }
+            catch (error) {
+                if (isPendingActionNotFound(error))
+                    throw new QoderPairingExpiredError();
+                throw error;
+            }
+            this.lastEventId = resultEventId ?? pairing.event.id;
+            this.sessionId = pairing.sessionId;
+            this.connected = true;
+            this.reconnectAttempts = 0;
+            this.options.onStateChange?.({ state: 'connected' });
+            this.options.onConnected?.();
+            console.log(`[CloudConnector] Connected to Qoder session ${pairing.sessionId}`);
+        }
+    }
+    async handleFrame(sessionId, frame, signal) {
+        this.reconnectAttempts = 0;
+        this.options.onStateChange?.({ state: 'connected', heartbeat: true });
+        const event = frame.data;
+        const eventId = event.id ?? frame.id;
+        if (event.type !== 'agent.custom_tool_use' || event.name !== QODER_TOOL_NAME || !eventId) {
+            if (eventId)
+                this.lastEventId = eventId;
+            return;
+        }
+        const cached = this.cachedResults.get(eventId) ?? (await this.executeTool(event));
+        this.rememberResult(eventId, cached);
+        try {
+            this.lastEventId =
+                (await this.api.sendCustomToolResult(sessionId, eventId, cached.content, cached.isError, signal)) ?? eventId;
+        }
+        catch (error) {
+            if (error instanceof QoderApiError &&
+                error.status === 400 &&
+                cached.content !== cached.fallbackContent) {
+                this.lastEventId =
+                    (await this.api.sendCustomToolResult(sessionId, eventId, cached.fallbackContent, cached.isError, signal)) ?? eventId;
+                return;
+            }
+            if (error instanceof QoderApiError && error.status === 404) {
+                this.lastEventId = eventId;
+                return;
+            }
+            throw error;
+        }
+    }
+    async executeTool(event) {
+        try {
+            const input = toolInput(event);
+            if (input.action === 'pair') {
+                throw new Error('This pairing request does not match the active connector');
+            }
+            const result = await this.invokeAction(input.action, input.payload, {
+                browser: input.browser,
+                timeoutSec: input.timeoutSec ?? resolveActionTimeoutSec(input.action, input.payload, 15),
+            });
+            return { ...formatQoderToolResult(result), isError: false };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const content = [{ type: 'text', text: safeJson({ error: message }) }];
+            return { content, fallbackContent: content, isError: true };
+        }
+    }
+    rememberResult(eventId, result) {
+        this.cachedResults.set(eventId, result);
+        while (this.cachedResults.size > MAX_CACHED_RESULTS) {
+            const oldest = this.cachedResults.keys().next().value;
+            if (!oldest)
+                break;
+            this.cachedResults.delete(oldest);
+        }
+    }
+}

package/dist/endpoint.d.ts

@@ -0,0 +1,9 @@
+export interface QoderConnectorEndpoint {
+    /** User-facing URL retained for daemon identity and lifecycle commands. */
+    serverUrl: string;
+    scheme: 'qoder';
+    pairingCode: string;
+    createdAt?: number;
+}
+export declare function parseQoderEndpoint(serverUrl: string, parsed: URL): QoderConnectorEndpoint | null;
+export declare function requireQoderEndpoint(serverUrl: string): QoderConnectorEndpoint;

package/dist/endpoint.js

@@ -0,0 +1,38 @@
+const PAIRING_CODE_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+export function parseQoderEndpoint(serverUrl, parsed) {
+    if (parsed.hostname !== 'pair' ||
+        parsed.port ||
+        parsed.username ||
+        parsed.password ||
+        parsed.hash) {
+        return null;
+    }
+    const pathSegments = parsed.pathname.split('/').filter(Boolean);
+    if (pathSegments.length !== 1 || !PAIRING_CODE_PATTERN.test(pathSegments[0]))
+        return null;
+    const allowedParams = new Set(['created']);
+    if ([...parsed.searchParams.keys()].some(key => !allowedParams.has(key)))
+        return null;
+    const createdValues = parsed.searchParams.getAll('created');
+    if (createdValues.length > 1)
+        return null;
+    const createdValue = createdValues[0] ?? null;
+    if (createdValue !== null && !/^\d{13}$/.test(createdValue))
+        return null;
+    const createdAt = createdValue === null ? undefined : Number(createdValue);
+    if (createdAt !== undefined && (!Number.isSafeInteger(createdAt) || createdAt <= 0))
+        return null;
+    return {
+        serverUrl,
+        scheme: 'qoder',
+        pairingCode: pathSegments[0],
+        ...(createdAt === undefined ? {} : { createdAt }),
+    };
+}
+export function requireQoderEndpoint(serverUrl) {
+    const parsed = new URL(serverUrl);
+    const endpoint = parsed.protocol === 'qoder:' ? parseQoderEndpoint(serverUrl, parsed) : null;
+    if (!endpoint)
+        throw new Error('Invalid qoder://pair/<code> endpoint');
+    return endpoint;
+}