@medeo-plugin/sdk 0.0.0-stage → 0.7.0

package/dist/index.js

@@ -0,0 +1,309 @@
+export { METHODS, LIMITS } from "./registry.js";
+/** The `api_version` this SDK targets; `spec/api-v1.json` carries the same number. */
+export const API_VERSION = 1;
+/** Messages between this plugin's background worker and its own windows
+ * (64 KiB each, JSON). A worker message reaches every open window; a window
+ * message reaches the worker. Nothing is persisted or sent elsewhere. */
+export const channel = {
+    post: (message) => globalThis.medeoPlugin.post(message),
+    onMessage: (callback) => globalThis.medeoPlugin.onMessage(m => callback(m)),
+};
+export const events = {
+    on: (callback) => globalThis.medeoPlugin.onEvent(callback),
+    /** Call `pull` now and again whenever the channel signals new entries. A
+     * failed pull (e.g. a permission withdrawn meanwhile) waits for the next signal. */
+    onSignal(channel, pull) {
+        const run = () => { void Promise.resolve().then(pull).catch(() => { }); };
+        const off = globalThis.medeoPlugin.onEvent(event => { if (event.type === 'signal' && event.channel === channel)
+            run(); });
+        run();
+        return off;
+    },
+};
+/** Resolves on the next event for `id`, or after `fallbackMs` as a safety net. */
+function nextChange(id, fallbackMs) {
+    let off = () => { };
+    const promise = new Promise(resolve => {
+        const timer = setTimeout(resolve, fallbackMs);
+        const stop = globalThis.medeoPlugin.onEvent(event => { if (event.type === 'operation' && event.id === id) {
+            clearTimeout(timer);
+            resolve();
+        } });
+        off = () => { clearTimeout(timer); stop(); };
+    });
+    return { promise, off };
+}
+export const storage = {
+    get: (key) => globalThis.medeoPlugin.invoke('storage.get', { key }),
+    remove: (key) => globalThis.medeoPlugin.invoke('storage.remove', { key }),
+    set: (key, value) => globalThis.medeoPlugin.invoke('storage.set', { key, value }),
+};
+export const creation = { open: () => globalThis.medeoPlugin.invoke('creation.open') };
+export const commands = { run: (command) => globalThis.medeoPlugin.run(command) };
+export function definePlugin(definition) {
+    return { deactivate: () => undefined, ...definition };
+}
+/** Settings declared under `contributes.configuration`; the user edits them in the plugin center. */
+export const config = {
+    get: (key) => globalThis.medeoPlugin.invoke('config.get', { key }),
+    all: () => globalThis.medeoPlugin.invoke('config.get'),
+    set: (key, value) => globalThis.medeoPlugin.invoke('config.set', { key, value }),
+    /** Calls `listener` with all values after each change, from the user or the plugin. */
+    onDidChange(listener) {
+        return globalThis.medeoPlugin.onEvent(event => {
+            if (event.type === 'signal' && event.channel === 'config')
+                void config.all().then(listener).catch(() => { });
+        });
+    },
+};
+export const providers = {
+    list: () => globalThis.medeoPlugin.invoke('providers.list'),
+    require: async (id, version = 1) => {
+        const provider = (await providers.list()).find(p => p.id === id && p.version === version && p.available);
+        if (!provider)
+            throw new Error('provider_unavailable');
+        return provider;
+    },
+};
+export const resources = {
+    chooseDirectories: (access = {}) => globalThis.medeoPlugin.invoke('resources.choose_directories', access.full ? { full: true } : {}),
+    list: () => globalThis.medeoPlugin.invoke('resources.list'),
+    revoke: (id) => globalThis.medeoPlugin.invoke('resources.revoke', { id }),
+    requestDirectory: (path, reason, access = {}) => globalThis.medeoPlugin.invoke('resources.request_directory', { path, reason, ...(access.full ? { full: true } : {}) }),
+};
+/** Generic registered-provider entry point; the Host remains the authority. */
+export const capabilities = {
+    list: () => globalThis.medeoPlugin.invoke('capabilities.list'),
+    labels: () => globalThis.medeoPlugin.invoke('capabilities.labels'),
+    invoke: (method, args = {}) => globalThis.medeoPlugin.invoke(method, args),
+};
+export const clipboard = { read: () => globalThis.medeoPlugin.invoke('clipboard.read'), write: (text) => globalThis.medeoPlugin.invoke('clipboard.write', { text }) };
+export const system = { info: () => globalThis.medeoPlugin.invoke('system.info'), running: (rules) => capabilities.invoke('system.running', { rules }) };
+/** `runtime: "node"` plugins only (the `node` permission): moves up to 256 absolute
+ * paths to the OS Trash, the one thing Node cannot do itself. A failure does not stop the rest. */
+export const trash = (paths) => globalThis.medeoPlugin.invoke('system.trash', { paths });
+export const notifications = { show: (id, title, body) => globalThis.medeoPlugin.invoke('notifications.show', { id, title, body }), close: (id) => globalThis.medeoPlugin.invoke('notifications.close', { id }) };
+export const power = { start: (type) => globalThis.medeoPlugin.invoke('power.start', { type }), stop: (id) => globalThis.medeoPlugin.invoke('power.stop', { id }), state: () => globalThis.medeoPlugin.invoke('power.state') };
+export const shortcuts = { list: () => globalThis.medeoPlugin.invoke('shortcuts.list'), register: (id, accelerator, openUI = false) => globalThis.medeoPlugin.invoke('shortcuts.register', { id, accelerator, open_ui: openUI }), unregister: (id) => globalThis.medeoPlugin.invoke('shortcuts.unregister', { id }), events: () => globalThis.medeoPlugin.invoke('shortcuts.events') };
+/** `panel: true` (macOS): a frameless window floating over every app and Space that does not
+ * activate Medeo — the app the user was in keeps focus — opened at the pointer and hidden (not
+ * closed) when it loses focus; opening it again moves it to the pointer. `hide` keeps a window
+ * and its page alive for the next `open`/`focus`. */
+export const appWindows = { open: (options) => globalThis.medeoPlugin.invoke('windows.open', options), close: (id) => globalThis.medeoPlugin.invoke('windows.close', { id }), focus: (id) => globalThis.medeoPlugin.invoke('windows.focus', { id }), hide: (id) => globalThis.medeoPlugin.invoke('windows.hide', { id }), list: () => globalThis.medeoPlugin.invoke('windows.list') };
+export const tray = { set: (title, items, options = {}) => globalThis.medeoPlugin.invoke('tray.set', { title, items, ...options }), remove: () => globalThis.medeoPlugin.invoke('tray.remove'), events: () => globalThis.medeoPlugin.invoke('tray.events') };
+export const external = { open: (url) => globalThis.medeoPlugin.invoke('external.open', { url }) };
+export const permissions = { request: (permission, reason) => globalThis.medeoPlugin.invoke('permissions.request', { permission, reason }) };
+export const approvals = {
+    request: (request) => globalThis.medeoPlugin.invoke('approvals.request', { ...request }),
+    rules: () => globalThis.medeoPlugin.invoke('approvals.rules'),
+    forget: (action, pattern) => globalThis.medeoPlugin.invoke('approvals.forget', { action, pattern }),
+};
+export const agent = {
+    models: () => capabilities.invoke('agent.models', {}),
+    start: (messages, model) => capabilities.invoke('agent.start', { messages, ...(model ? { model } : {}) }),
+    state: (id) => operations.state(id),
+    cancel: (id) => operations.cancel(id),
+    release: (id) => operations.release(id),
+    /** Calls `onText` as the reply streams in; resolves with the final job. */
+    async follow(id, onText) {
+        for (;;) {
+            const change = nextChange(id, 2000);
+            const job = await agent.state(id);
+            onText(job);
+            if (job.status !== 'running') {
+                change.off();
+                return job;
+            }
+            await change.promise;
+            change.off();
+        }
+    },
+};
+export const applications = {
+    /** The whole inventory; plugins rank and filter it themselves. */
+    list: (refresh = false) => capabilities.invoke('applications.list', { refresh }),
+    launch: (id) => capabilities.invoke('applications.launch', { id }),
+    state: () => capabilities.invoke('applications.state', {}),
+};
+export const capture = {
+    status: (refresh = true) => capabilities.invoke('capture.status', { refresh }),
+    sources: (refresh = false, requestPermission = false) => capabilities.invoke('capture.sources', { refresh, request_permission: requestPermission }),
+    start: (source, options = {}) => capabilities.invoke('capture.start', { source, microphone: options.microphone ?? false, system_audio: options.systemAudio ?? false }),
+    state: () => capabilities.invoke('capture.state', {}),
+    stop: (id) => capabilities.invoke('capture.stop', { id }),
+    cancel: (id) => capabilities.invoke('capture.cancel', { id }),
+    recover: (id) => capabilities.invoke('capture.recover', { id }),
+    open: (id, mode = 'play') => capabilities.invoke('capture.open', { id, mode }),
+    previewURL: (id) => location.origin + '/_capture/' + encodeURIComponent(id) + '.mp4',
+};
+export const inputMethod = {
+    system: (refresh = false) => capabilities.invoke('input_method.system', { refresh }),
+    setup: () => capabilities.invoke('input_method.setup'),
+    remove: () => capabilities.invoke('input_method.remove'),
+    settings: () => capabilities.invoke('input_method.settings'),
+    status: () => capabilities.invoke('input_method.status'),
+    configure: (name) => capabilities.invoke('input_method.configure', { name }),
+    enable: () => capabilities.invoke('input_method.enable'),
+    disable: () => capabilities.invoke('input_method.disable'),
+    events: () => capabilities.invoke('input_method.events'),
+    respond: (id, candidates) => capabilities.invoke('input_method.respond', { id, candidates }),
+};
+export const network = {
+    origins: () => capabilities.invoke('network.origins'),
+    requestOrigin: (origin, reason) => capabilities.invoke('network.request_origin', { origin, reason }),
+    revokeOrigin: (origin) => capabilities.invoke('network.revoke_origin', { origin }),
+    request: (request) => capabilities.invoke('network.request', { ...request }),
+    state: (id) => operations.state(id),
+    read: (id, offset = 0, length = 32768) => capabilities.invoke('network.read', { id, offset, length }),
+    cancel: (id) => operations.cancel(id),
+    release: (id) => operations.release(id),
+    /** Resolves once the response has fully arrived; the job stays readable until released. */
+    async settled(id) { for (;;) {
+        const change = nextChange(id, 2000);
+        const state = await network.state(id);
+        if (state.status !== 'running') {
+            change.off();
+            return state;
+        }
+        await change.promise;
+        change.off();
+    } },
+    async text(id) {
+        const decoder = new TextDecoder();
+        let offset = 0, text = '';
+        for (;;) {
+            const part = await network.read(id, offset);
+            const bytes = Uint8Array.from(atob(part.data_base64), c => c.charCodeAt(0));
+            text += decoder.decode(bytes, { stream: !part.eof });
+            if (part.eof)
+                return text;
+            offset = part.next_offset;
+        }
+    },
+};
+export const files = {
+    backupPreview: (root, record) => capabilities.invoke('files.backup_preview', { root, record }),
+    archiveBackup: (preview) => capabilities.invoke('files.archive_backup', { preview }),
+    forgetPreview: (root, record) => capabilities.invoke('files.forget_preview', { root, record }),
+    forgetRecord: (preview) => capabilities.invoke('files.forget_record', { preview }),
+    historyPage: (root, cursor, limit = 50) => capabilities.invoke('files.history_page', { root, ...(cursor ? { cursor } : {}), limit }),
+    trashPreview: (root, path) => capabilities.invoke('files.trash_preview', { root, path }),
+    discardPreview: (preview) => capabilities.invoke('files.discard_preview', { preview }),
+    trash: (preview) => capabilities.invoke('files.trash', { preview }),
+    /** Breadth-first listings of a whole tree in one call. Hidden and `skip`
+     * directories are listed by their parent but not entered. */
+    listTree: (root, path = '', options = {}) => capabilities.invoke('files.list_tree', { root, path, ...options }),
+    /** Full-access roots only: move entries to the Trash without a Host confirmation.
+     * `stamp` is what `files.measure` returned; a changed entry is refused, not moved. */
+    trashDirect: (items) => capabilities.invoke('files.trash_direct', { items }),
+    watch: (root, path = '', recursive = false) => capabilities.invoke('files.watch', { root, path, recursive }),
+    watches: () => capabilities.invoke('files.watches'),
+    events: (id, after = 0) => capabilities.invoke('files.events', { id, after }),
+    unwatch: (id) => capabilities.invoke('files.unwatch', { id }),
+    roots: () => capabilities.invoke('files.roots'),
+    list: (root, path = '') => capabilities.invoke('files.list', { root, path }),
+    stat: (root, path = '') => capabilities.invoke('files.stat', { root, path }),
+    readText: (root, path, revision) => capabilities.invoke('files.read_text', { root, path, ...(revision ? { revision } : {}) }),
+    writeText: (root, path, text, revision) => capabilities.invoke('files.write_text', { root, path, text, revision }),
+    mkdir: (root, path) => capabilities.invoke('files.mkdir', { root, path }),
+    move: (root, path, destination, revision) => capabilities.invoke('files.move', { root, path, destination, revision }),
+    history: (root) => capabilities.invoke('files.history', { root }),
+    restore: (root, record) => capabilities.invoke('files.restore', { root, record }),
+    state: (id) => operations.state(id),
+    cancel: (id) => operations.cancel(id),
+    release: (id) => operations.release(id),
+    result: (job) => operations.wait(job),
+};
+async function secretOperation(method, args) {
+    const job = await capabilities.invoke('secrets.' + method, args);
+    const deadline = Date.now() + 30000;
+    for (;;) {
+        const change = nextChange(job.id, 1000);
+        const result = await capabilities.invoke('secrets.result', { id: job.id });
+        if (result.status !== 'running')
+            change.off();
+        if (result.status === 'completed')
+            return result.value ?? null;
+        if (result.status === 'failed')
+            throw Error(result.error ?? 'secrets_storage_failed');
+        if (Date.now() >= deadline) {
+            change.off();
+            throw Error('secrets_outcome_unknown');
+        }
+        await change.promise;
+        change.off();
+    }
+}
+export const secrets = {
+    get: (key) => secretOperation('get', { key }),
+    set: async (key, value) => { await secretOperation('set', { key, value }); },
+    remove: async (key) => { await secretOperation('remove', { key }); },
+};
+/** A loopback server is instance-owned and never survives Host restart. Keep the
+ * start token in private memory and serve requests in a worker for background use. */
+export const server = {
+    start: (options) => capabilities.invoke('server.start', { ...options }),
+    state: (id) => capabilities.invoke('server.state', { id }),
+    list: () => capabilities.invoke('server.state'),
+    events: (id, limit = 8) => capabilities.invoke('server.events', { id, limit }),
+    respond: (id, request, response) => capabilities.invoke('server.respond', { id, request, ...response }),
+    stop: (id) => capabilities.invoke('server.stop', { id }),
+};
+/** Text is formatted in Rust from the signed package. Render with textContent,
+ * never innerHTML. Register listeners before initial state fetch to avoid races. */
+export const i18n = {
+    state: () => capabilities.invoke('i18n.state'),
+    setLocale: (preference) => capabilities.invoke('i18n.setLocale', { preference }),
+    t: (key, params = {}) => capabilities.invoke('i18n.t', { key, params }),
+    /** Every message of the effective locale (default-locale fallback merged in). */
+    catalog: () => capabilities.invoke('i18n.catalog'),
+    onDidChangeLocale: (callback) => globalThis.medeoPlugin.onLocaleChanged(callback),
+};
+export const operations = {
+    state: (id) => capabilities.invoke('operations.state', { id }),
+    list: () => capabilities.invoke('operations.list'),
+    cancel: (id) => capabilities.invoke('operations.cancel', { id }),
+    release: (id) => capabilities.invoke('operations.release', { id }),
+    async wait(operation, signal) {
+        let value = operation;
+        while (value.status === 'running') {
+            if (signal?.aborted) {
+                await operations.cancel(value.id);
+                throw Error('cancelled');
+            }
+            const change = nextChange(value.id, 2000);
+            value = await operations.state(value.id);
+            if (value.status === 'running')
+                await change.promise;
+            change.off();
+        }
+        // Quick reads may come back settled and already released by the Host.
+        if (!value.released)
+            await operations.release(value.id);
+        if (value.status !== 'completed')
+            throw Error(value.error ?? value.status);
+        return value.result;
+    },
+};
+const nativeCall = (method, args = {}) => capabilities.invoke(method, args);
+function mediaProvider(kind) {
+    return {
+        status: () => nativeCall(kind + '.status'),
+        start: (maxSeconds = 300) => nativeCall(kind + '.start', { max_seconds: maxSeconds }),
+        stop: (id) => nativeCall(kind + '.stop', { id }),
+        state: (id) => nativeCall(kind + '.state', id ? { id } : {}),
+        read: (id, offset = 0, length = 32768) => nativeCall(kind + '.read', { id, offset, length }),
+        /** Same-origin URL for an `<audio>` / `<video>` element; plays once the record is "completed". */
+        previewURL: (record) => location.origin + '/_media/' + encodeURIComponent(record.id) + (record.extension === 'm4a' ? '.m4a' : '.mp4'),
+    };
+}
+export const camera = mediaProvider('camera'), microphone = mediaProvider('microphone'), systemAudio = mediaProvider('system_audio');
+export const accessibility = { status: () => nativeCall('accessibility.status'), request: () => nativeCall('accessibility.request'), windows: () => nativeCall('accessibility.windows'), focus: (id) => nativeCall('accessibility.focus', { id }), selectedText: (id) => nativeCall('accessibility.selected_text', { id }), insertText: (focus, text) => nativeCall('accessibility.insert_text', { id: focus, text }) };
+export const browserView = { open: (id, url, width = 1000, height = 720) => capabilities.invoke('browser.open', { id, url, width, height }), state: (id) => capabilities.invoke('browser.state', { id }), close: (id) => capabilities.invoke('browser.close', { id }) };
+export const printing = { print: (text) => capabilities.invoke('printing.print', { text }) };
+export const processes = { start: (executable, args = [], timeoutMs = 60000) => nativeCall('process.start', { executable, arguments: args, timeout_ms: timeoutMs }), state: (id) => nativeCall('process.state', { id }), write: (id, text) => nativeCall('process.write', { id, text }), stop: (id) => nativeCall('process.stop', { id }) };
+export const background = { schedule: (id, delayMs, payload = null, intervalMs = 0) => capabilities.invoke('background.schedule', { id, delay_ms: delayMs, interval_ms: intervalMs, payload }), list: () => capabilities.invoke('background.list'), cancel: (id) => capabilities.invoke('background.cancel', { id }), events: () => capabilities.invoke('background.events') };
+export const contacts = { status: () => nativeCall('contacts.status'), request: () => nativeCall('contacts.request'), list: (query = '', limit = 50) => nativeCall('contacts.list', { query, limit }), save: (contact) => nativeCall('contacts.save', contact) };
+export const calendar = { status: () => nativeCall('calendar.status'), request: () => nativeCall('calendar.request'), list: (startMs, endMs, limit = 50) => nativeCall('calendar.list', { start_ms: startMs, end_ms: endMs, limit }), save: (event) => nativeCall('calendar.save', event) };
+export const deviceLocation = { status: () => nativeCall('location.status'), request: () => nativeCall('location.request'), current: () => nativeCall('location.current') };
+export const devices = { choose: (transport) => nativeCall('devices.choose', { transport }), open: (id, baudRate = 115200) => nativeCall('devices.open', { id, baud_rate: baudRate }), list: () => nativeCall('devices.list'), read: (id, length = 4096) => nativeCall('devices.read', { id, length }), write: (id, dataBase64) => nativeCall('devices.write', { id, data_base64: dataBase64 }), close: (id) => nativeCall('devices.close', { id }) };