@medeo-plugin/sdk 0.0.0-stage → 0.7.0

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# Plugin SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser-only TypeScript helpers. The platform owns identity; a plugin cannot supply an instance ID, private Host command or publisher claim. Paths in directory-consent requests are proposals, not authorization. Direct Node/system imports are unavailable; declared operations are brokered by the Host.
+
+```ts
+import { definePlugin, storage } from '@medeo-plugin/sdk';
+export const { activate, deactivate } = definePlugin({
+  activate(context) {
+    context.commands.register('counter.increment', async () => {
+      const counter = ((await storage.get<number>('counter')) ?? 0) + 1;
+      await storage.set('counter', counter);
+      return { counter };
+    });
+  },
+});
+```
+
+Declare `example.run` and `storage` in the manifest. UI code uses `commands.run('example.run')`. Worker module evaluation must only export its command table; capability access starts inside a command after activation. Commands must finish within 30 seconds. Reads/writes are limited to the plugin's own device-local configuration namespace. The UI window may close without stopping its worker.
+
+Protocol DTOs in `src/generated.ts` are generated from `platform-contract`; never edit them directly. See the guide in [docs/index.html](../../docs/index.html).
+
+`capabilities.list()` reports available methods separately from granted permissions. `permissions.request(name, reason)` displays trusted confirmation for a declared permission; it cannot expand the manifest's path/origin scopes. Revocation invalidates pending native results and disposes owned windows, shortcuts, menu-bar items and sleep blockers.
+
+Initial native helpers are `clipboard`, `system`, `notifications`, `shortcuts`, `appWindows`, `tray`, `external` and `power`. External URLs must match the manifest's `external_open` scopes. The full permission list is in [spec/api-v1.json](../../spec/api-v1.json).
+
+## Host-configured Agent API
+
+With the `agent_api` grant, `agent.start(messages, model?)` and `agent.models()` return asynchronous job IDs. Use `agent.state(id)`, `agent.jobs()` and `agent.cancel(id)` for progress/lifecycle. Configure the service in the trusted desktop Agent API settings tab; keys and endpoint overrides never enter this SDK. See [provider contract](../../docs/capabilities/agent-api.md) for limits, cancellation and restart semantics.

package/dist/generated.d.ts

@@ -0,0 +1,497 @@
+export type JsonValue = number | string | boolean | Array<JsonValue> | {
+    [key in string]?: JsonValue;
+} | null;
+export type Permission = "storage" | "creation_open" | {
+    "file_access": Array<string>;
+} | {
+    "file_full_access": Array<string>;
+} | {
+    "network": Array<string>;
+} | "agent_api" | "clipboard_read" | "clipboard_write" | "screen_capture" | "camera" | "microphone" | "system_audio" | "applications" | "global_shortcuts" | "notifications" | "tray" | "app_windows" | "accessibility" | "input_method" | {
+    "external_open": Array<string>;
+} | {
+    "browser_view": Array<string>;
+} | "system_info" | "secrets" | "background_tasks" | "power" | {
+    "process_spawn": Array<string>;
+} | "local_server" | "printing" | "contacts" | "calendar" | "location" | "device_access" | {
+    "approvals": Array<string>;
+} | "node";
+export type PluginCommand = {
+    id: string;
+    title: string;
+};
+export type PluginLocalization = {
+    default_locale: string;
+    catalogs: {
+        [key in string]?: string;
+    };
+};
+export type Runtime = "sandbox" | "node";
+export type GrantScope = "once" | "run" | "always";
+export type ApprovalRule = {
+    action: string;
+    /**
+     * The rule key, or a prefix ending in `*`.
+     */
+    pattern: string;
+    allow: boolean;
+    /**
+     * `run` rules belong to the running instance; `always` rules are stored.
+     */
+    scope: GrantScope;
+};
+export type ApprovalRecord = {
+    action: string;
+    rule_key: string;
+    /**
+     * `allow` or `deny`.
+     */
+    decision: string;
+    /**
+     * `once`, `run`, `always`, or `rule` when a remembered rule decided.
+     */
+    scope: string;
+    time_ms: number;
+};
+export type TargetPlatform = "macos" | "windows";
+export type Engines = {
+    medeo?: string;
+};
+export type InstallSourceKind = "file" | "folder" | "github" | "npm" | "dev";
+export type InstallSource = {
+    kind: InstallSourceKind;
+    /**
+     * A file path, folder path, `owner/repo[#tag-prefix]` or npm package name.
+     */
+    locator: string;
+    /**
+     * The release tag or npm version the package was taken from.
+     */
+    version?: string;
+};
+export type ConfigType = "string" | "number" | "boolean";
+export type ConfigProperty = {
+    type: ConfigType;
+    default: JsonValue;
+    title: string;
+    description?: string;
+    /**
+     * Allowed values; the plugin center shows a choice.
+     */
+    enum?: Array<JsonValue>;
+};
+export type Configuration = {
+    properties: {
+        [key in string]?: ConfigProperty;
+    };
+};
+export type Keybinding = {
+    command: string;
+    key: string;
+};
+export type Menus = {
+    /**
+     * Command ids shown in the main window's Plugins menu.
+     */
+    app?: Array<string>;
+};
+export type Contributes = {
+    configuration?: Configuration;
+    keybindings?: Array<Keybinding>;
+    menus?: Menus;
+};
+export type Manifest = {
+    localization?: PluginLocalization;
+    id: string;
+    name: string;
+    /**
+     * One sentence the plugin center shows under the name; translated as
+     * `plugin.description` in the plugin's catalogs.
+     */
+    description?: string;
+    /**
+     * The plugin's icon, at the package root: `icon.svg` or `icon.png`.
+     */
+    icon?: string;
+    version: string;
+    api_version: number;
+    worker: string;
+    ui: string | null;
+    permissions: Array<Permission>;
+    commands: Array<PluginCommand>;
+    runtime?: Runtime;
+    /**
+     * When Medeo starts the plugin: `onStartup`, `onCommand:<id>`,
+     * `onSchedule`, `onShortcut`. Without any, it starts when used.
+     */
+    activation_events?: Array<string>;
+    contributes?: Contributes;
+    /**
+     * Operating systems the plugin runs on; empty means all.
+     */
+    platforms?: Array<TargetPlatform>;
+    /**
+     * The Medeo versions the plugin needs; absent means any that loads format 2.
+     */
+    engines?: Engines;
+};
+export type PackageFile = {
+    size: number;
+    sha256: string;
+};
+export type PackageIndex = {
+    manifest: Manifest;
+    files: {
+        [key in string]?: PackageFile;
+    };
+};
+export type Asset = {
+    mime: string;
+    path: string;
+    size: number;
+    sha256: string;
+};
+export type PackageSignature = {
+    format: number;
+    public_key: string;
+    signature: string;
+    index: string;
+};
+export type PackageInfo = {
+    manifest: Manifest;
+    digest: string;
+    publisher: string;
+    /**
+     * Bytes of all signed files, i.e. the installed size. Records written
+     * before this field existed are backfilled at start.
+     */
+    size: number;
+    /**
+     * What this build accepted but does not understand (`unknown_contribution:<key>`);
+     * shown at install and in the developer log, never a reason to refuse.
+     */
+    warnings?: Array<string>;
+};
+export type CapabilityDescriptor = {
+    permission: string;
+    group: string;
+    version: number;
+    scoped: boolean;
+    methods: Array<string>;
+    available_methods: Array<string>;
+    granted: boolean;
+    declared: boolean;
+    os_authorization: string;
+};
+export type DirectoryGrant = {
+    id: string;
+    name: string;
+    available: boolean;
+    /**
+     * Full access: view and move to the Trash without a Host confirmation.
+     */
+    full: boolean;
+};
+export type NetworkOrigin = {
+    origin: string;
+    declared: boolean;
+    allowed: boolean;
+};
+export type InstalledPlugin = {
+    localization: JsonValue;
+    id: string;
+    active: string | null;
+    versions: Array<PackageInfo>;
+    grants: Array<Permission>;
+    directories: Array<DirectoryGrant>;
+    network_origins: Array<NetworkOrigin>;
+    /**
+     * For resident (`onStartup`) plugins: whether the user lets it run in
+     * the background. Other plugins run only while in use and ignore it.
+     */
+    enabled: boolean;
+    resident: boolean;
+    /**
+     * User-owned macOS Dock launcher preference; plugins cannot modify it.
+     */
+    dock: boolean;
+    /**
+     * User-owned: whether the plugin's menu-bar icon (`tray`) is shown; plugins cannot modify it.
+     */
+    menu_bar: boolean;
+    instance: string | null;
+    /**
+     * Permission ids granted to the running instance only (`run` scope).
+     */
+    session_grants: Array<string>;
+    /**
+     * Permission ids the user refused with "don't ask again".
+     */
+    denied: Array<string>;
+    /**
+     * Remembered `approvals.request` answers.
+     */
+    approval_rules: Array<ApprovalRule>;
+    /**
+     * The active version's icon as a `data:` URL, when the package has one.
+     */
+    icon?: string;
+    /**
+     * Where the plugin was installed from, when Main recorded it.
+     */
+    source?: InstallSource;
+};
+export type Instance = {
+    id: string;
+    plugin_id: string;
+    digest: string;
+    manifest: Manifest;
+};
+export type Task = {
+    id: string;
+    plugin_id: string;
+    instance: string;
+    command: string;
+    status: string;
+    result: JsonValue | null;
+    /**
+     * Unix milliseconds; absent for rows written before times were recorded.
+     */
+    created_ms: number | null;
+    finished_ms: number | null;
+};
+export type Snapshot = {
+    protocol: number;
+    plugins: Array<InstalledPlugin>;
+    tasks: Array<Task>;
+};
+export type HostEvent = {
+    "type": "operation";
+    instance: string;
+    id: string;
+    method: string;
+    status: string;
+    revision?: number;
+} | {
+    "type": "signal";
+    instance: string;
+    channel: string;
+} | {
+    "type": "wake";
+    plugin_id: string;
+};
+export type Command = {
+    "op": "ping";
+} | {
+    "op": "shortcuts_list";
+} | {
+    "op": "shortcut_validate";
+    target: string;
+    accelerator: string;
+} | {
+    "op": "shortcut_save";
+    target: string;
+    accelerator: string;
+} | {
+    "op": "shortcut_remove";
+    target: string;
+} | {
+    "op": "system_locale";
+    locale: string;
+} | {
+    "op": "plugin_locale";
+    plugin_id: string;
+    locale: string;
+} | {
+    "op": "approve";
+    instance: string;
+    ticket: string;
+    approved: boolean;
+    /**
+     * Without it an approval is stored (`always`) and a refusal asks again next time.
+     */
+    scope?: GrantScope;
+} | {
+    "op": "capture_stop";
+    id: string;
+} | {
+    "op": "capture_asset";
+    instance: string;
+    id: string;
+} | {
+    "op": "media_asset";
+    instance: string;
+    id: string;
+} | {
+    "op": "agent_settings";
+} | {
+    "op": "agent_configure";
+    endpoint: string;
+    model: string;
+    encrypted_key: string | null;
+    key: string;
+    persist: boolean;
+} | {
+    "op": "agent_remove";
+} | {
+    "op": "agent_test";
+    action: string;
+    id: string | null;
+} | {
+    "op": "snapshot";
+} | {
+    "op": "capability_catalog";
+} | {
+    "op": "grant_permission";
+    plugin_id: string;
+    digest: string;
+    permission: string;
+} | {
+    "op": "forget_approval_rule";
+    plugin_id: string;
+    action: string;
+    pattern: string;
+} | {
+    "op": "approval_log";
+    plugin_id: string;
+} | {
+    "op": "revoke_permission";
+    plugin_id: string;
+    permission: string;
+} | {
+    "op": "network_origin_revoke";
+    plugin_id: string;
+    origin: string;
+} | {
+    "op": "configure_capabilities";
+    methods: Array<string>;
+} | {
+    "op": "capability_result";
+    instance: string;
+    ticket: string;
+    result: JsonValue | null;
+    error: string | null;
+} | {
+    "op": "quiesce";
+    plugin_id: string;
+} | {
+    "op": "resource_grant";
+    instance: string;
+    directories: Array<string>;
+    full: boolean;
+} | {
+    "op": "resource_revoke";
+    plugin_id: string;
+    grant_id: string;
+} | {
+    "op": "inspect";
+    package_file: string;
+} | {
+    "op": "install";
+    package_file: string;
+    digest: string;
+    grants: Array<Permission>;
+    /**
+     * Recorded with the plugin (plugin center "Source"); absent for older callers.
+     */
+    source?: InstallSource;
+} | {
+    "op": "pack_dir";
+    directory: string;
+    key_file: string;
+    output: string;
+    /**
+     * Stamp a content-derived `-dev.h<hash>` version like the toolchain's `dev` does.
+     */
+    development: boolean;
+} | {
+    "op": "prepare";
+    plugin_id: string;
+    digest: string;
+} | {
+    "op": "commit";
+    instance: string;
+} | {
+    "op": "abort";
+    instance: string;
+} | {
+    "op": "stop";
+    plugin_id: string;
+} | {
+    "op": "busy";
+    plugin_id: string;
+} | {
+    "op": "deactivate";
+    plugin_id: string;
+} | {
+    "op": "dock_set";
+    plugin_id: string;
+    enabled: boolean;
+} | {
+    "op": "menu_bar_set";
+    plugin_id: string;
+    enabled: boolean;
+} | {
+    "op": "keep_running";
+    plugin_id: string;
+    enabled: boolean;
+} | {
+    "op": "uninstall";
+    plugin_id: string;
+} | {
+    "op": "config_state";
+    plugin_id: string;
+} | {
+    "op": "config_set";
+    plugin_id: string;
+    key: string;
+    value: JsonValue;
+} | {
+    "op": "package_dir";
+    instance: string;
+} | {
+    "op": "remove_version";
+    plugin_id: string;
+    digest: string;
+} | {
+    "op": "grants";
+    plugin_id: string;
+    grants: Array<Permission>;
+} | {
+    "op": "asset";
+    instance: string;
+    path: string;
+} | {
+    "op": "invoke";
+    instance: string;
+    method: string;
+    args: JsonValue;
+    /**
+     * Main sets this when the caller is one of the plugin's windows rather
+     * than its background worker; `ui` methods require it.
+     */
+    ui?: boolean;
+} | {
+    "op": "task_start";
+    instance: string;
+    command: string;
+} | {
+    "op": "task_finish";
+    instance: string;
+    task: string;
+    result: JsonValue | null;
+    failed: boolean;
+} | {
+    "op": "labels";
+    locale: string;
+};
+export type Request = {
+    version: number;
+    id: number;
+    command: Command;
+};
+export type Response = {
+    id: number;
+    result: JsonValue | null;
+    error: string | null;
+};

package/dist/generated.js

@@ -0,0 +1 @@
+export {};