@mearl/provider 2.13.0 → 2.15.0

package/dist/types.d.ts

@@ -1,6 +1,11 @@
 import type { ProviderAction } from './generated-provider-actions.js';
-export declare const MEARL_PROVIDER_PROTOCOL_VERSION = 1;
+export declare const MEARL_PROVIDER_PROTOCOL_VERSION = 2;
 export type { ProviderAction } from './generated-provider-actions.js';
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
 export type ProviderScreenshotKind = 'native' | 'reconstructed' | 'none';
 export interface ProviderCapabilities {
     actions: ProviderAction[];
@@ -17,27 +22,118 @@ export interface ProviderDescriptor {
     name: string;
     version: string;
     protocolVersion?: number;
+    builtin?: boolean;
 }
-export interface ProviderBrowserParameter {
-    key: string;
-    label: string;
-    required?: boolean;
-    placeholder?: string;
+export type ProviderInputComponent = 'cookie-sync' | 'switch';
+export interface ProviderInputVisibility {
+    field: string;
+    empty: boolean;
+}
+interface ProviderSchemaBase {
+    title?: string;
     description?: string;
+    default?: JsonValue;
+    /** Optional Mearl form component used to edit this schema value. */
+    component?: ProviderInputComponent;
+    /** Presentation-only default used by Mearl forms without changing runtime semantics. */
+    formDefault?: JsonValue;
+    /** Excludes an advanced runtime option from generated Mearl forms. */
+    formHidden?: boolean;
+    /** Places compact fields side by side in generated Mearl forms. */
+    formWidth?: 'half' | 'full';
+    /** Hides the optional badge without changing schema validation. */
+    formHideOptional?: boolean;
+    /** Conditionally displays and submits this field based on another form value. */
+    formVisibleWhen?: ProviderInputVisibility;
+}
+export interface ProviderStringSchema extends ProviderSchemaBase {
+    type: 'string';
+    secret?: boolean;
+    enum?: readonly string[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    placeholder?: string;
+}
+export interface ProviderNumberSchema extends ProviderSchemaBase {
+    type: 'number';
+    integer?: boolean;
+    minimum?: number;
+    maximum?: number;
+}
+export interface ProviderBooleanSchema extends ProviderSchemaBase {
+    type: 'boolean';
+}
+export interface ProviderArraySchema extends ProviderSchemaBase {
+    type: 'array';
+    items: ProviderInputSchema;
+    minItems?: number;
+    maxItems?: number;
+}
+export interface ProviderObjectSchema extends ProviderSchemaBase {
+    type: 'object';
+    properties: Record<string, ProviderInputSchema>;
+    required?: readonly string[];
+    oneOf?: readonly ProviderObjectSchema[];
+    not?: ProviderObjectSchema;
+    additionalProperties?: boolean;
+}
+export type ProviderInputSchema = ProviderStringSchema | ProviderNumberSchema | ProviderBooleanSchema | ProviderArraySchema | ProviderObjectSchema;
+export interface ProviderConfigurationDefinition {
+    inputSchema: ProviderObjectSchema;
 }
 export interface ProviderBrowserType {
     name: string;
-    parameters: ProviderBrowserParameter[];
+    documentationUrl?: string;
+    /** Provider-owned usage guidance rendered by `mearl <providerId>`. */
+    help?: readonly string[];
+    inputSchema: ProviderObjectSchema;
+    configuration?: ProviderConfigurationDefinition;
+}
+export type ProviderBrowserStatus = 'connected' | 'pairing' | 'running_disconnected' | 'stopped';
+export type ProviderOwnership = 'owned' | 'attached';
+export type ProviderPersistence = 'ephemeral' | 'persistent';
+export type ProviderBrowserOperation = 'start' | 'close' | 'detach' | 'deleteData' | 'access' | 'syncCookies';
+export type ProviderBrowserControl = {
+    kind: 'provider';
+    capabilities: ProviderCapabilities;
+} | {
+    kind: 'host';
+    transport: 'extension' | 'cdp';
+    browserId: string;
+    capabilities?: ProviderCapabilities;
+} | {
+    kind: 'none';
+};
+/** Common safe metadata; additional Provider-specific keys must also be non-secret JSON. */
+export type ProviderBrowserDetails = JsonObject & {
+    headless?: boolean;
+    createdAt?: string;
+    cdpPort?: number;
+    copiedCookies?: {
+        domains: string[];
+        count: number;
+    };
+};
+export interface ProviderBrowserReference {
+    kind: string;
+    id: string;
+    label?: string;
 }
 export interface ProviderBrowser {
-    /** Stable within this provider. Mearl prefixes it with the provider id globally. */
+    /** Stable within this provider. Mearl adds the Provider namespace globally. */
     browserId: string;
     name: string;
-    status?: 'connected' | 'pairing';
+    status: ProviderBrowserStatus;
+    control: ProviderBrowserControl;
+    ownership?: ProviderOwnership;
+    persistence: ProviderPersistence;
+    operations: ProviderBrowserOperation[];
     lastFocusedAt?: number;
-    capabilities: ProviderCapabilities;
-    /** Pairing metadata is valid only while status is pairing. */
     pairing?: ProviderPairingInfo;
+    references?: ProviderBrowserReference[];
+    /** Safe, non-secret metadata suitable for browser_list and remote connectors. */
+    details?: ProviderBrowserDetails;
 }
 export interface InstalledProviderManifest extends ProviderDescriptor {
     protocolVersion: number;
@@ -56,41 +152,78 @@ export interface ProviderPackageMetadata {
 export interface ProviderActionRequest {
     id: string;
     action: string;
-    data?: Record<string, unknown>;
+    data?: JsonObject;
     /** Provider-local browser id selected by the Mearl client. */
     browserId?: string;
     version?: string;
     controlSource?: string;
+    host?: ProviderHostContextData;
 }
 export interface ProviderActionContext {
     browserId: string;
     action: ProviderAction;
-    data: Record<string, unknown>;
+    data: JsonObject;
     controlSource?: string;
 }
-export type ProviderActionHandler = (context: ProviderActionContext) => Promise<unknown>;
-interface ProviderBrowserCreateResultBase {
+export interface ProviderHostServices {
+    request<T = JsonValue>(method: string, data?: JsonObject): Promise<T>;
+}
+/** Host-derived launch data carried over the local Provider protocol. */
+export interface ProviderHostContextData {
+    cookies?: JsonObject[];
+    userAgent?: string;
+}
+export interface ProviderContext {
+    host?: ProviderHostServices;
+    controlSource?: string;
+}
+export interface ProviderInstanceRequest {
     browserId: string;
-    name: string;
 }
-export type ProviderBrowserCreateResult = (ProviderBrowserCreateResultBase & {
-    status: 'connected';
-    pairing?: never;
-}) | (ProviderBrowserCreateResultBase & {
-    status: 'pairing';
-    pairing: ProviderPairingInfo;
-});
-export type ProviderBrowserCreateHandler = (parameters: Record<string, string>) => Promise<ProviderBrowserCreateResult>;
-export type ProviderBrowserDeleteHandler = (browserId: string) => Promise<unknown>;
-export interface ProviderServerOptions {
+export interface ProviderCloseRequest extends ProviderInstanceRequest {
+    deleteData?: boolean;
+}
+export interface ProviderSyncCookiesRequest extends ProviderInstanceRequest {
+    scope: JsonObject;
+}
+export interface ProviderAccess {
+    kind: string;
+    url: string;
+    sensitive: true;
+}
+export interface BrowserProviderDefinition {
     descriptor: ProviderDescriptor;
-    handleAction: ProviderActionHandler;
-    createBrowser: ProviderBrowserCreateHandler;
-    deleteBrowser: ProviderBrowserDeleteHandler;
+    browserType: ProviderBrowserType;
+    listBrowsers?: (context: ProviderContext) => ProviderBrowser[] | Promise<ProviderBrowser[]>;
+    launch: (options: JsonObject, context: ProviderContext) => Promise<ProviderBrowser>;
+    start?: (request: ProviderInstanceRequest, context: ProviderContext) => Promise<ProviderBrowser>;
+    close: (request: ProviderCloseRequest, context: ProviderContext) => Promise<unknown>;
+    detach?: (request: ProviderInstanceRequest, context: ProviderContext) => Promise<unknown>;
+    syncCookies?: (request: ProviderSyncCookiesRequest, context: ProviderContext) => Promise<unknown>;
+    getAccess?: (request: ProviderInstanceRequest, context: ProviderContext) => Promise<ProviderAccess>;
+    configure?: (options: JsonObject, context: ProviderContext) => Promise<unknown>;
+    handleAction?: (context: ProviderActionContext) => Promise<unknown>;
+}
+export interface ProviderRuntime {
+    readonly definition: BrowserProviderDefinition;
+    listBrowsers(context?: ProviderContext): Promise<ProviderBrowser[]>;
+    updateBrowsers(browsers: ProviderBrowser[]): void;
+    launch(options: JsonObject, context?: ProviderContext): Promise<ProviderBrowser>;
+    start(request: ProviderInstanceRequest, context?: ProviderContext): Promise<ProviderBrowser>;
+    close(request: ProviderCloseRequest, context?: ProviderContext): Promise<unknown>;
+    detach(request: ProviderInstanceRequest, context?: ProviderContext): Promise<unknown>;
+    syncCookies(request: ProviderSyncCookiesRequest, context?: ProviderContext): Promise<unknown>;
+    getAccess(request: ProviderInstanceRequest, context?: ProviderContext): Promise<ProviderAccess>;
+    configure(options: JsonObject, context?: ProviderContext): Promise<unknown>;
+    invokeAction(context: ProviderActionContext): Promise<unknown>;
+}
+export interface ProviderServerOptions {
+    definition: BrowserProviderDefinition;
     socketPath?: string;
 }
 export interface ProviderServer {
     readonly socketPath: string;
+    readonly runtime: ProviderRuntime;
     start(): Promise<void>;
     updateBrowsers(browsers: ProviderBrowser[]): void;
     touchBrowser(browserId: string): void;

package/dist/types.js

@@ -1 +1 @@
-export const MEARL_PROVIDER_PROTOCOL_VERSION = 1;
+export const MEARL_PROVIDER_PROTOCOL_VERSION = 2;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mearl/provider",
-  "version": "2.13.0",
-  "description": "Contracts and runtime utilities for external Mearl browser-control providers",
+  "version": "2.15.0",
+  "description": "Unified contracts and runtime utilities for built-in and external Mearl browser providers",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -35,7 +35,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@mearl/daemon-core": "2.13.0"
+    "@mearl/daemon-core": "2.15.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",