@relayfile/client 0.10.17

package/dist/client.d.ts

@@ -0,0 +1,91 @@
+import type { components } from './generated/control-plane.js';
+/**
+ * Typed client for the relayfile control-plane: HTTP/JSON over a local unix
+ * domain socket (`relayfile control-plane serve`). It replaces shelling out to
+ * the `relayfile` CLI and parsing stdout — the contract is now the socket's
+ * request/response shapes, version-negotiated via `/v1/hello`.
+ *
+ * Transport is Node's built-in `http.request({ socketPath })` — no dependency,
+ * unix-socket support is native. Request/response types are generated from the
+ * authoritative `openapi/relayfile-control-plane-v1.openapi.yaml`, so a field
+ * rename in the contract is a compile error here.
+ */
+/** Control-plane API version this client speaks. Bump on a breaking wire change. */
+export declare const RELAYFILE_API_VERSION = 1;
+/**
+ * Minimum `relayfile` daemon version this client requires. The control-plane
+ * first shipped in 0.10.17, so anything that answers `/v1/hello` is already >=
+ * this — the check is belt-and-suspenders and the bump point for future
+ * contract changes.
+ */
+export declare const MIN_RELAYFILE_VERSION = "0.10.17";
+/** First semver-looking token in a string (tolerates a leading `v` and surrounding words). */
+export declare function firstSemver(value: string): string;
+/** Compare two semvers by numeric core; -1 / 0 / 1. Pre-release/build metadata is ignored. */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * Pure version gate: throws an actionable error unless `version` (a daemon
+ * version string) is a semver >= MIN_RELAYFILE_VERSION. Exported so the contract
+ * it guards is unit-tested without a running daemon.
+ */
+export declare function assertRelayfileVersion(version: string): void;
+/** Resolve the control-plane socket path, mirroring relayfile's Go default. */
+export declare function defaultRelayfileSocketPath(): string;
+/** Structured control-plane error carrying the daemon's typed code + HTTP status. */
+export declare class RelayfileControlPlaneError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(code: string, message: string, status?: number | undefined);
+}
+type Schemas = components['schemas'];
+export type HelloResponse = Schemas['HelloResponse'];
+export type RelayfileBindingRecord = Schemas['Binding'];
+export type ResolvePathResult = Schemas['ResolveResourcePathResponse'];
+export type BindResult = Schemas['BindResponse'];
+export type BindRequestBody = Schemas['BindRequest'];
+export type ConnectRequestBody = Schemas['ConnectProviderRequest'];
+export type ConnectResult = Schemas['ConnectProviderResponse'];
+export type ProviderStatusResult = Schemas['ProviderStatus'];
+export type WritebackSecretResult = Schemas['WritebackSecret'];
+export interface RelayfileClientOptions {
+    /** Socket to connect to. Defaults to defaultRelayfileSocketPath(). */
+    socketPath?: string;
+    /** Binary used to auto-start the daemon. Defaults to RELAYFILE_BIN or `relayfile`. */
+    binary?: string;
+    /**
+     * Auto-start `relayfile control-plane serve` when the socket is absent.
+     * Defaults to true unless RELAYFILE_REQUIRE_DAEMON=1 (strict, never-spawn mode).
+     */
+    autoStart?: boolean;
+    /** How long to wait for an auto-started daemon to answer /v1/hello. */
+    startTimeoutMs?: number;
+    /** Per-request timeout. A hung socket rejects instead of blocking forever. */
+    requestTimeoutMs?: number;
+}
+export declare class RelayfileControlPlaneClient {
+    private readonly socketPath;
+    private readonly binary;
+    private readonly autoStart;
+    private readonly startTimeoutMs;
+    private readonly requestTimeoutMs;
+    private ready;
+    constructor(options?: RelayfileClientOptions);
+    /** Low-level request over the unix socket. Throws RelayfileControlPlaneError. */
+    private rawRequest;
+    /** Connect (auto-starting the daemon if configured), version-negotiating once. */
+    ensureReady(): Promise<void>;
+    private connectAndNegotiate;
+    private startDaemonAndConnect;
+    hello(): Promise<HelloResponse>;
+    resolvePath(provider: string, resource: string): Promise<ResolvePathResult>;
+    bind(input: BindRequestBody): Promise<BindResult>;
+    listBindings(): Promise<RelayfileBindingRecord[]>;
+    unbind(provider: string, resource: string): Promise<unknown>;
+    /** Returns the connection status, or null when the provider is not connected. */
+    providerStatus(provider: string): Promise<ProviderStatusResult | null>;
+    connect(input: ConnectRequestBody): Promise<ConnectResult>;
+    writebackSecret(channel: string, workspace?: string): Promise<WritebackSecretResult>;
+    /** Endpoint request that ensures the daemon is up + version-compatible first. */
+    private request;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,294 @@
+import { spawn } from 'node:child_process';
+import { request } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Typed client for the relayfile control-plane: HTTP/JSON over a local unix
+ * domain socket (`relayfile control-plane serve`). It replaces shelling out to
+ * the `relayfile` CLI and parsing stdout — the contract is now the socket's
+ * request/response shapes, version-negotiated via `/v1/hello`.
+ *
+ * Transport is Node's built-in `http.request({ socketPath })` — no dependency,
+ * unix-socket support is native. Request/response types are generated from the
+ * authoritative `openapi/relayfile-control-plane-v1.openapi.yaml`, so a field
+ * rename in the contract is a compile error here.
+ */
+/** Control-plane API version this client speaks. Bump on a breaking wire change. */
+export const RELAYFILE_API_VERSION = 1;
+/**
+ * Minimum `relayfile` daemon version this client requires. The control-plane
+ * first shipped in 0.10.17, so anything that answers `/v1/hello` is already >=
+ * this — the check is belt-and-suspenders and the bump point for future
+ * contract changes.
+ */
+export const MIN_RELAYFILE_VERSION = '0.10.17';
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+/** First semver-looking token in a string (tolerates a leading `v` and surrounding words). */
+export function firstSemver(value) {
+    for (const raw of value.split(/\s+/)) {
+        const token = raw.replace(/^v/, '');
+        if (SEMVER_RE.test(token))
+            return token;
+    }
+    return '';
+}
+/** Compare two semvers by numeric core; -1 / 0 / 1. Pre-release/build metadata is ignored. */
+export function compareSemver(a, b) {
+    const core = (v) => v.split(/[-+]/)[0].split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const [a0 = 0, a1 = 0, a2 = 0] = core(a);
+    const [b0 = 0, b1 = 0, b2 = 0] = core(b);
+    return a0 - b0 || a1 - b1 || a2 - b2;
+}
+/**
+ * Pure version gate: throws an actionable error unless `version` (a daemon
+ * version string) is a semver >= MIN_RELAYFILE_VERSION. Exported so the contract
+ * it guards is unit-tested without a running daemon.
+ */
+export function assertRelayfileVersion(version) {
+    const parsed = firstSemver(version);
+    if (!parsed || compareSemver(parsed, MIN_RELAYFILE_VERSION) < 0) {
+        // Typed (not a bare Error) so callers that re-throw daemon/version failures
+        // by code don't silently swallow it.
+        throw new RelayfileControlPlaneError('VERSION_INCOMPATIBLE', `relayfile >= ${MIN_RELAYFILE_VERSION} is required; found ${parsed ? `"${parsed}"` : `unparseable version "${version.trim()}"`}. Update relayfile (npm install -g relayfile@latest) or set RELAYFILE_BIN.`);
+    }
+}
+/** Resolve the control-plane socket path, mirroring relayfile's Go default. */
+export function defaultRelayfileSocketPath() {
+    const explicit = process.env.RELAYFILE_SOCK?.trim();
+    if (explicit)
+        return explicit;
+    const xdg = process.env.XDG_RUNTIME_DIR?.trim();
+    if (xdg)
+        return join(xdg, 'relayfile.sock');
+    return join(tmpdir(), 'relayfile.sock');
+}
+function relayfileBinary() {
+    return process.env.RELAYFILE_BIN?.trim() || 'relayfile';
+}
+/** Structured control-plane error carrying the daemon's typed code + HTTP status. */
+export class RelayfileControlPlaneError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'RelayfileControlPlaneError';
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class RelayfileControlPlaneClient {
+    socketPath;
+    binary;
+    autoStart;
+    startTimeoutMs;
+    requestTimeoutMs;
+    ready;
+    constructor(options = {}) {
+        this.socketPath = options.socketPath ?? defaultRelayfileSocketPath();
+        this.binary = options.binary ?? relayfileBinary();
+        this.autoStart = options.autoStart ?? process.env.RELAYFILE_REQUIRE_DAEMON !== '1';
+        this.startTimeoutMs = options.startTimeoutMs ?? 5000;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 10000;
+    }
+    /** Low-level request over the unix socket. Throws RelayfileControlPlaneError. */
+    rawRequest(opts) {
+        const query = opts.query
+            ? Object.entries(opts.query)
+                .filter(([, v]) => v != null && v !== '')
+                .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+                .join('&')
+            : '';
+        const path = query ? `${opts.path}?${query}` : opts.path;
+        const payload = opts.body == null ? undefined : JSON.stringify(opts.body);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const fail = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(err);
+            };
+            const ok = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+            };
+            const req = request({
+                socketPath: this.socketPath,
+                method: opts.method,
+                path,
+                timeout: this.requestTimeoutMs,
+                headers: {
+                    'X-Relayfile-API-Version': String(RELAYFILE_API_VERSION),
+                    Accept: 'application/json',
+                    ...(payload
+                        ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) }
+                        : {}),
+                },
+            }, (res) => {
+                // The response stream can emit 'error' (e.g. socket reset mid-body);
+                // without a listener that's an unhandled error -> crash.
+                res.on('error', (err) => fail(new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', err.message)));
+                const chunks = [];
+                res.on('data', (c) => chunks.push(c));
+                res.on('end', () => {
+                    const text = Buffer.concat(chunks).toString('utf8');
+                    const status = res.statusCode ?? 0;
+                    let parsed;
+                    try {
+                        parsed = text ? JSON.parse(text) : undefined;
+                    }
+                    catch {
+                        fail(new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', `relayfile control-plane returned non-JSON (status ${status}): ${text.slice(0, 200)}`, status));
+                        return;
+                    }
+                    if (status >= 200 && status < 300) {
+                        ok(parsed);
+                        return;
+                    }
+                    const err = parsed?.error;
+                    fail(new RelayfileControlPlaneError(err?.code ?? 'DAEMON_UNAVAILABLE', err?.message ?? `relayfile control-plane error (status ${status})`, status));
+                });
+            });
+            req.on('timeout', () => {
+                req.destroy(new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', `relayfile control-plane request timed out after ${this.requestTimeoutMs}ms (${opts.method} ${opts.path})`));
+            });
+            req.on('error', (err) => {
+                if (err instanceof RelayfileControlPlaneError) {
+                    fail(err);
+                    return;
+                }
+                // ENOENT (no socket file) / ECONNREFUSED (nothing listening) => daemon down.
+                fail(new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', err.code === 'ENOENT' || err.code === 'ECONNREFUSED'
+                    ? `relayfile control-plane is not running at ${this.socketPath} (${err.code})`
+                    : err.message, undefined));
+            });
+            if (payload)
+                req.write(payload);
+            req.end();
+        });
+    }
+    /** Connect (auto-starting the daemon if configured), version-negotiating once. */
+    async ensureReady() {
+        if (!this.ready) {
+            this.ready = this.connectAndNegotiate().catch((err) => {
+                // Don't cache a transient failure — let the next call retry.
+                this.ready = undefined;
+                throw err;
+            });
+        }
+        return this.ready;
+    }
+    async connectAndNegotiate() {
+        let hello;
+        try {
+            hello = await this.hello();
+        }
+        catch (err) {
+            if (!(err instanceof RelayfileControlPlaneError) || err.code !== 'DAEMON_UNAVAILABLE')
+                throw err;
+            if (!this.autoStart) {
+                throw new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', `relayfile control-plane is not running at ${this.socketPath}. ` +
+                    `Start it with \`relayfile control-plane serve\` (or unset RELAYFILE_REQUIRE_DAEMON to auto-start).`);
+            }
+            hello = await this.startDaemonAndConnect();
+        }
+        if (!hello.supportedApiVersions?.includes(RELAYFILE_API_VERSION)) {
+            throw new RelayfileControlPlaneError('VERSION_INCOMPATIBLE', `relayfile daemon speaks API v${hello.apiVersion} (supports ${hello.supportedApiVersions?.join(', ') || 'none'}); this client needs v${RELAYFILE_API_VERSION}. Upgrade relayfile (or agent-relay).`);
+        }
+        assertRelayfileVersion(hello.daemonVersion);
+    }
+    async startDaemonAndConnect() {
+        let child;
+        // A missing binary / bad RELAYFILE_BIN surfaces as an async 'error' event on
+        // the child (ENOENT), not a throw from spawn().
+        let spawnError;
+        try {
+            child = spawn(this.binary, ['control-plane', 'serve', '--sock', this.socketPath], {
+                detached: true,
+                stdio: 'ignore',
+            });
+            child.on('error', (err) => {
+                spawnError = err;
+            });
+        }
+        catch (err) {
+            throw new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', `failed to start relayfile control-plane (${err instanceof Error ? err.message : String(err)}). ` +
+                `Install relayfile or set RELAYFILE_BIN.`);
+        }
+        child.unref?.();
+        const deadline = Date.now() + this.startTimeoutMs;
+        let lastErr;
+        while (Date.now() < deadline) {
+            if (spawnError) {
+                throw new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', `failed to start relayfile control-plane (${spawnError.message}). ` +
+                    `Install relayfile or set RELAYFILE_BIN.`);
+            }
+            await sleep(100);
+            try {
+                return await this.hello();
+            }
+            catch (err) {
+                lastErr = err;
+            }
+        }
+        throw new RelayfileControlPlaneError('DAEMON_UNAVAILABLE', `relayfile control-plane did not become ready within ${this.startTimeoutMs}ms ` +
+            `(${lastErr instanceof Error ? lastErr.message : String(lastErr)}).`);
+    }
+    // ── endpoints ──────────────────────────────────────────────────────────────
+    hello() {
+        return this.rawRequest({ method: 'GET', path: '/v1/hello' });
+    }
+    resolvePath(provider, resource) {
+        return this.request({
+            method: 'POST',
+            path: '/v1/integrations/resolve-path',
+            body: { provider, resource },
+        });
+    }
+    bind(input) {
+        return this.request({ method: 'POST', path: '/v1/integrations/bind', body: input });
+    }
+    async listBindings() {
+        const res = await this.request({
+            method: 'GET',
+            path: '/v1/integrations/bindings',
+        });
+        return res.bindings ?? [];
+    }
+    unbind(provider, resource) {
+        return this.request({ method: 'POST', path: '/v1/integrations/unbind', body: { provider, resource } });
+    }
+    /** Returns the connection status, or null when the provider is not connected. */
+    async providerStatus(provider) {
+        try {
+            return await this.request({
+                method: 'GET',
+                path: '/v1/integrations/provider-status',
+                query: { provider },
+            });
+        }
+        catch (err) {
+            if (err instanceof RelayfileControlPlaneError && err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    connect(input) {
+        return this.request({ method: 'POST', path: '/v1/integrations/connect', body: input });
+    }
+    writebackSecret(channel, workspace) {
+        return this.request({
+            method: 'POST',
+            path: '/v1/integrations/writeback-secret',
+            body: { channel, ...(workspace ? { workspace } : {}) },
+        });
+    }
+    /** Endpoint request that ensures the daemon is up + version-compatible first. */
+    async request(opts) {
+        await this.ensureReady();
+        return this.rawRequest(opts);
+    }
+}

package/dist/generated/control-plane.d.ts

@@ -0,0 +1,601 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/v1/hello": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Negotiate control-plane API compatibility */
+        get: operations["hello"];
+        put?: never;
+        /** Negotiate control-plane API compatibility */
+        post: operations["helloPost"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/integrations/providers": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List known integration providers */
+        get: operations["listProviders"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/integrations/provider-status": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get connected provider status for a workspace */
+        get: operations["getProviderStatus"];
+        put?: never;
+        /** Get connected provider status for a workspace */
+        post: operations["getProviderStatusPost"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/integrations/connect": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Start or reuse a provider connection */
+        post: operations["connectProvider"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/integrations/resolve-path": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Resolve a provider-native resource to a canonical VFS glob */
+        post: operations["resolveResourcePath"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/integrations/bind": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Upsert a relay integration binding */
+        post: operations["bind"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/integrations/bindings": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List relay integration bindings */
+        get: operations["listBindings"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/integrations/unbind": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Remove relay integration bindings */
+        post: operations["unbind"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/integrations/writeback-secret": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Fetch the per-channel writeback URL and signing secret */
+        post: operations["getWritebackBinding"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        HelloRequest: {
+            /** Format: uint32 */
+            apiVersion?: number;
+        };
+        HelloResponse: {
+            daemonVersion: string;
+            /** Format: uint32 */
+            apiVersion: number;
+            supportedApiVersions: number[];
+        };
+        Provider: {
+            id: string;
+            displayName?: string;
+            configKey?: string;
+            vfsRoot?: string;
+            deprecated?: boolean;
+            backend?: string;
+            backends?: string[];
+            sources?: string[];
+            authMode?: string;
+            categories?: string[];
+            docs?: string;
+        };
+        ProviderStatusRequest: {
+            provider: string;
+            workspace?: string;
+            cloudApiUrl?: string;
+        };
+        ProviderStatus: {
+            provider: string;
+            status?: string;
+            lagSeconds?: number;
+            lastEventAt?: string;
+            connectionId?: string;
+            webhookHealthy?: boolean;
+            deprecated?: boolean;
+        };
+        ConnectProviderRequest: {
+            provider: string;
+            workspace?: string;
+            cloudApiUrl?: string;
+            backend?: string;
+            noOpen?: boolean;
+            timeout?: string;
+            waitSync?: boolean;
+        };
+        ConnectProviderResponse: {
+            provider: string;
+            output?: string;
+        };
+        ResolveResourcePathRequest: {
+            provider: string;
+            resource: string;
+        };
+        ResolveResourcePathResponse: {
+            provider: string;
+            resource: string;
+            pathGlob: string;
+            resolvedExact: boolean;
+            warning?: string;
+        };
+        BindRequest: {
+            provider: string;
+            resource: string;
+            channel: string;
+            webhookId: string;
+            webhookToken: string;
+            subscriptionId?: string;
+        };
+        BindResponse: {
+            binding: components["schemas"]["Binding"];
+            replaced: boolean;
+            warning?: string;
+        };
+        Binding: {
+            provider: string;
+            pathGlob: string;
+            channel: string;
+            webhookId: string;
+            webhookToken: string;
+            subscriptionId?: string;
+            createdAt?: string;
+            updatedAt?: string;
+        };
+        ListBindingsResponse: {
+            bindings: components["schemas"]["Binding"][];
+        };
+        UnbindRequest: {
+            provider: string;
+            resource?: string;
+        };
+        UnbindResponse: {
+            provider: string;
+            pathGlob: string;
+            removed: number;
+            warning?: string;
+        };
+        WritebackSecretRequest: {
+            workspace?: string;
+            channel: string;
+        };
+        WritebackSecret: {
+            url: string;
+            secret: string;
+        };
+        ErrorEnvelope: {
+            error: {
+                /** @enum {string} */
+                code: "INVALID_ARGUMENT" | "VERSION_INCOMPATIBLE" | "RESOURCE_UNRESOLVED" | "BINDING_NOT_FOUND" | "DAEMON_UNAVAILABLE";
+                message: string;
+            };
+        };
+    };
+    responses: {
+        /** @description Client and daemon API versions are incompatible */
+        VersionIncompatible: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorEnvelope"];
+            };
+        };
+        /** @description Requested provider or binding was not found */
+        NotFound: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorEnvelope"];
+            };
+        };
+        /** @description Provider-native resource could not be resolved */
+        ResourceUnresolved: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorEnvelope"];
+            };
+        };
+    };
+    parameters: {
+        ApiVersionHeader: 1;
+        ApiVersionQuery: number;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    hello: {
+        parameters: {
+            query?: {
+                apiVersion?: components["parameters"]["ApiVersionQuery"];
+            };
+            header?: {
+                "X-Relayfile-API-Version"?: components["parameters"]["ApiVersionHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Daemon version and supported API versions */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HelloResponse"];
+                };
+            };
+            426: components["responses"]["VersionIncompatible"];
+        };
+    };
+    helloPost: {
+        parameters: {
+            query?: never;
+            header?: {
+                "X-Relayfile-API-Version"?: components["parameters"]["ApiVersionHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["HelloRequest"];
+            };
+        };
+        responses: {
+            /** @description Daemon version and supported API versions */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HelloResponse"];
+                };
+            };
+            426: components["responses"]["VersionIncompatible"];
+        };
+    };
+    listProviders: {
+        parameters: {
+            query?: never;
+            header?: {
+                "X-Relayfile-API-Version"?: components["parameters"]["ApiVersionHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Provider catalog */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        providers: components["schemas"]["Provider"][];
+                    };
+                };
+            };
+        };
+    };
+    getProviderStatus: {
+        parameters: {
+            query: {
+                provider: string;
+                workspace?: string;
+                cloudApiUrl?: string;
+            };
+            header?: {
+                "X-Relayfile-API-Version"?: components["parameters"]["ApiVersionHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Provider status */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProviderStatus"];
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    getProviderStatusPost: {
+        parameters: {
+            query?: never;
+            header?: {
+                "X-Relayfile-API-Version"?: components["parameters"]["ApiVersionHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ProviderStatusRequest"];
+            };
+        };
+        responses: {
+            /** @description Provider status */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProviderStatus"];
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    connectProvider: {
+        parameters: {
+            query?: never;
+            header?: {
+                "X-Relayfile-API-Version"?: components["parameters"]["ApiVersionHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ConnectProviderRequest"];
+            };
+        };
+        responses: {
+            /** @description Connection command completed */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConnectProviderResponse"];
+                };
+            };
+        };
+    };
+    resolveResourcePath: {
+        parameters: {
+            query?: never;
+            header?: {
+                "X-Relayfile-API-Version"?: components["parameters"]["ApiVersionHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ResolveResourcePathRequest"];
+            };
+        };
+        responses: {
+            /** @description Resolved path glob */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ResolveResourcePathResponse"];
+                };
+            };
+            422: components["responses"]["ResourceUnresolved"];
+        };
+    };
+    bind: {
+        parameters: {
+            query?: never;
+            header?: {
+                "X-Relayfile-API-Version"?: components["parameters"]["ApiVersionHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["BindRequest"];
+            };
+        };
+        responses: {
+            /** @description Created or updated binding */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BindResponse"];
+                };
+            };
+        };
+    };
+    listBindings: {
+        parameters: {
+            query?: never;
+            header?: {
+                "X-Relayfile-API-Version"?: components["parameters"]["ApiVersionHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Existing bindings without one-time webhook token redaction */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ListBindingsResponse"];
+                };
+            };
+        };
+    };
+    unbind: {
+        parameters: {
+            query?: never;
+            header?: {
+                "X-Relayfile-API-Version"?: components["parameters"]["ApiVersionHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["UnbindRequest"];
+            };
+        };
+        responses: {
+            /** @description Removed binding count */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["UnbindResponse"];
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    getWritebackBinding: {
+        parameters: {
+            query?: never;
+            header?: {
+                "X-Relayfile-API-Version"?: components["parameters"]["ApiVersionHeader"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["WritebackSecretRequest"];
+            };
+        };
+        responses: {
+            /** @description Writeback URL and secret */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WritebackSecret"];
+                };
+            };
+        };
+    };
+}

package/dist/generated/control-plane.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { RelayfileControlPlaneClient, RelayfileControlPlaneError, RELAYFILE_API_VERSION, MIN_RELAYFILE_VERSION, assertRelayfileVersion, compareSemver, firstSemver, defaultRelayfileSocketPath, } from './client.js';
+export type { RelayfileClientOptions, HelloResponse, RelayfileBindingRecord, ResolvePathResult, BindResult, BindRequestBody, ConnectRequestBody, ConnectResult, ProviderStatusResult, WritebackSecretResult, } from './client.js';
+export type { components, paths, operations } from './generated/control-plane.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { RelayfileControlPlaneClient, RelayfileControlPlaneError, RELAYFILE_API_VERSION, MIN_RELAYFILE_VERSION, assertRelayfileVersion, compareSemver, firstSemver, defaultRelayfileSocketPath, } from './client.js';

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@relayfile/client",
+  "version": "0.10.17",
+  "description": "Typed client for the relayfile local control-plane (unix-socket HTTP/JSON), generated from the authoritative OpenAPI contract",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "codegen": "openapi-typescript ../../openapi/relayfile-control-plane-v1.openapi.yaml -o src/generated/control-plane.ts",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "openapi-typescript": "^7.13.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AgentWorkforce/relayfile",
+    "directory": "packages/client"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "relayfile",
+    "control-plane",
+    "client",
+    "integrations",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}