@pi-oxide/extension-js 0.12.4 → 0.13.0

package/shared/cross/manifest.d.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+
+export interface Command {
+    action: string;
+    params: unknown;
+    call_id?: number;
+    runId?: string;
+}
+export type AsyncError = {
+    message: string;
+    code: string;
+    category?: string;
+    hint?: string;
+    recovery?: string[];
+    details?: Record<string, unknown>;
+};
+export type AsyncResponse<T = unknown> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: AsyncError;
+};
+export interface ToolDocParam {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+}
+export interface ToolDoc {
+    action: string;
+    namespace: string;
+    description: string;
+    params: ToolDocParam[];
+    returns: {
+        type: string;
+        description: string;
+    };
+    errorCode: string;
+    errorCategory?: string;
+    example?: string;
+}
+export type ToolAgentMeta = {
+    prerequisites?: string[];
+    notes?: string[];
+    tags?: Array<"read" | "write" | "mutation" | "snapshot" | "navigation" | "chrome">;
+    relatedApis?: string[];
+};
+export interface ToolDefinition<P, R> {
+    action: string;
+    namespace: string;
+    description: string;
+    params: z.ZodSchema<P>;
+    returns: z.ZodSchema<R>;
+    handler: (params: P, callId?: number, runId?: string, signal?: AbortSignal) => Promise<R>;
+    paramTypes: ToolDocParam[];
+    returnType?: string;
+    returnDoc: string;
+    errorCode: string;
+    errorCategory?: string;
+    example?: string;
+}
+export type ExecutionContextId = string;
+export type CallContext = {
+    action: string;
+    callId?: number;
+    runId?: string;
+    signal?: AbortSignal;
+};
+export type JsCallSpec<P, R> = {
+    action: string;
+    namespace: string;
+    name: string;
+    description: string;
+    params: z.ZodSchema<P>;
+    returns: z.ZodSchema<R>;
+    fields?: string[];
+    aliases?: Array<{
+        namespace: string;
+        name: string;
+        fields?: string[];
+    }>;
+    owner: ExecutionContextId;
+    handler: (params: P, ctx: CallContext) => Promise<R>;
+    errorCode: string;
+    errorCategory?: string;
+    paramTypes?: ToolDocParam[];
+    returnType?: string;
+    returnDoc?: string;
+    /** Chrome permission required to use this API (e.g. "notifications", "cookies"). */
+    permission?: string;
+    /** Runnable example string for this API. */
+    example?: string;
+    /** Agent-facing metadata for this API. */
+    agentMeta?: ToolAgentMeta;
+};
+export type SerializableJsCallManifestEntry = {
+    action: string;
+    namespace: string;
+    name: string;
+    publicName: string;
+    description: string;
+    fields: string[] | null;
+    aliases: Array<{
+        namespace: string;
+        name: string;
+        fields: string[] | null;
+    }> | null;
+    owner: ExecutionContextId;
+    paramsDoc: ToolDocParam[];
+    returnsDoc: {
+        type: string;
+        description: string;
+    };
+    errorCode: string;
+    errorCategory?: string;
+    /** Chrome permission required to use this API (e.g. "notifications", "cookies"). */
+    permission?: string;
+    /** Runnable example string for this API. */
+    example?: string;
+    prerequisites?: string[];
+    notes?: string[];
+    tags?: string[];
+    relatedApis?: string[];
+};
+/** Rust/WASM often passes BTreeMap params as a JS Map; Zod object schemas need plain objects.
+ *  Native-parity chrome actions also JSON-round-trip in dispatch_handler; this covers relay paths. */
+export declare function coerceWasmParams(params: unknown): unknown;
+/** Convert a serializable manifest entry to the shape expected by WASM registerJsCall/registerJsCallBatch. */
+export declare function manifestEntryToWasm(entry: SerializableJsCallManifestEntry): Record<string, unknown>;

package/shared/cross/normalize-agent-error.d.ts

@@ -0,0 +1,17 @@
+import { contentScriptMissingError, isContentScriptConnectionError, labelNotFoundError, noTabError, notInteractableError, observationRequiredError, StaleRefCandidate, staleRefError, throwStructuredAgentError } from './agent-errors.js';
+import { AsyncError } from './manifest.js';
+
+export { contentScriptMissingError, isContentScriptConnectionError, labelNotFoundError, noTabError, notInteractableError, observationRequiredError, type StaleRefCandidate, staleRefError, throwStructuredAgentError, };
+export declare function normalizeAgentError(err: unknown, context?: {
+    tabId?: number;
+    url?: string;
+    action?: string;
+}): AsyncError;
+export declare function agentErrorResponse(err: unknown, context?: {
+    tabId?: number;
+    url?: string;
+    action?: string;
+}): {
+    ok: false;
+    error: AsyncError;
+};

package/shared/cross/page-specs.d.ts

@@ -0,0 +1,7 @@
+import { JsCallSpec } from './manifest.js';
+
+export declare const AWAIT_PROMISE_NOTE = "Returns a Promise; await before reading the result. For a cell's last line, use `page.snapshot()` without a leading await so the cell returns the settled value.";
+export type ContentScriptToolSpec<P = unknown, R = unknown> = Omit<JsCallSpec<P, R>, "owner" | "handler"> & {
+    handlerKey: string;
+};
+export declare const PAGE_TOOL_SPECS: readonly ContentScriptToolSpec[];

package/shared/cross/schemas/chrome.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+export declare const ChromeRuntimeSendMessageParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeTabsQueryParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeTabsCreateParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeTabsUpdateParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeTabsRemoveParamsSchema: z.ZodUnion<[z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeTabsGetParamsSchema: z.ZodUnion<[z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeTabsReloadParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeTabsSendMessageParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeAlarmsCreateParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeAlarmsClearParamsSchema: z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeActionSetBadgeTextParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeActionSetBadgeBackgroundColorParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeActionSetTitleParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeActionSetIconParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeContextMenusCreateParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeContextMenusRemoveParamsSchema: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeWindowsGetAllParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeWindowsCreateParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeWindowsUpdateParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeWindowsRemoveParamsSchema: z.ZodUnion<[z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeSidePanelSetOptionsParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeCookiesGetParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeCookiesSetParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeCookiesRemoveParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeCookiesGetAllParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** Opaque argument array for native-parity Chrome API transport. */
+export declare const NativeArgsSchema: z.ZodArray<z.ZodUnknown, "many">;
+export declare const ChromeBookmarksSearchParamsSchema: z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeBookmarksCreateParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeBookmarksRemoveParamsSchema: z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeHistorySearchParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeHistoryDeleteUrlParamsSchema: z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeNotificationsCreateParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeNotificationsClearParamsSchema: z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeScriptingExecuteScriptParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeTabGroupsQueryParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeTabGroupsGetParamsSchema: z.ZodUnion<[z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeTabGroupsUpdateParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeTabsGroupParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeTabsUngroupParamsSchema: z.ZodUnion<[z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeSessionsGetRecentlyClosedParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeSessionsRestoreParamsSchema: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeSessionsGetDevicesParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeDownloadsDownloadParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeDownloadsSearchParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeDownloadsEraseParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeDownloadsPauseParamsSchema: z.ZodUnion<[z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeDownloadsResumeParamsSchema: z.ZodUnion<[z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeDownloadsCancelParamsSchema: z.ZodUnion<[z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeDownloadsOpenParamsSchema: z.ZodUnion<[z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeDownloadsShowParamsSchema: z.ZodUnion<[z.ZodNumber, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const ChromeSystemCpuGetInfoParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeSystemMemoryGetInfoParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const ChromeSystemStorageGetInfoParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;

package/shared/cross/schemas/clipboard.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+
+export declare const ClipboardReadParamsSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const ClipboardWriteParamsSchema: z.ZodUnion<[z.ZodTuple<[z.ZodUnion<[z.ZodObject<{
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+}, {
+    text: string;
+}>, z.ZodString]>], null>, z.ZodObject<{
+    text: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    value?: string | undefined;
+    text?: string | undefined;
+}, {
+    value?: string | undefined;
+    text?: string | undefined;
+}>]>;

package/shared/cross/schemas/fs.d.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+
+export declare const FsPathParamsSchema: z.ZodObject<{
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+}, {
+    path: string;
+}>;
+export declare const FsCopyParamsSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    from: string;
+    to: string;
+}, {
+    from: string;
+    to: string;
+}>;
+export declare const FsWriteParamsSchema: z.ZodObject<{
+    path: z.ZodString;
+    data: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    data: string;
+}, {
+    path: string;
+    data: string;
+}>;
+export declare const FsReadRangeParamsSchema: z.ZodObject<{
+    path: z.ZodString;
+    offset: z.ZodEffects<z.ZodUnion<[z.ZodBigInt, z.ZodNumber]>, bigint, number | bigint>;
+    len: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    offset: bigint;
+    len: number;
+}, {
+    path: string;
+    offset: number | bigint;
+    len: number;
+}>;
+export declare const FsUpdateParamsSchema: z.ZodObject<{
+    path: z.ZodString;
+    offset: z.ZodEffects<z.ZodUnion<[z.ZodBigInt, z.ZodNumber]>, bigint, number | bigint>;
+    data: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    data: string;
+    offset: bigint;
+}, {
+    path: string;
+    data: string;
+    offset: number | bigint;
+}>;
+export declare const FsHashParamsSchema: z.ZodObject<{
+    path: z.ZodString;
+    algo: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    algo: string;
+}, {
+    path: string;
+    algo?: string | undefined;
+}>;

package/shared/cross/schemas/helpers.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+
+export declare const bigintLike: () => z.ZodEffects<z.ZodUnion<[z.ZodBigInt, z.ZodNumber]>, bigint, number | bigint>;
+export declare const refIdString: () => z.ZodString;
+export declare const requireRefIdLabelOrCoordinates: (data: {
+    refId?: string;
+    label?: string;
+    x?: number;
+    y?: number;
+    __invalidPositional?: unknown;
+}, ctx: z.RefinementCtx) => void;
+/** All element actions accept refId or label (runner + content-script). */
+export declare const elementTargetParams: (extra?: z.ZodRawShape) => z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    __invalidPositional: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    refId: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    refId?: string | undefined;
+    label?: string | undefined;
+    __invalidPositional?: string | number | undefined;
+}, {
+    refId?: string | undefined;
+    label?: string | undefined;
+    __invalidPositional?: string | number | undefined;
+}>, {
+    refId?: string | undefined;
+    label?: string | undefined;
+    __invalidPositional?: string | number | undefined;
+}, {
+    refId?: string | undefined;
+    label?: string | undefined;
+    __invalidPositional?: string | number | undefined;
+}>, {
+    refId?: string | undefined;
+    label?: string | undefined;
+    __invalidPositional?: string | number | undefined;
+}, unknown>;
+export declare const tabIdField: {
+    tabId: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodBigInt]>>;
+};
+export declare const tabElementTargetParams: (extra?: z.ZodRawShape) => z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    refId: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    tabId: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodBigInt]>>;
+    __invalidPositional: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    tabId?: number | bigint | undefined;
+    refId?: string | undefined;
+    label?: string | undefined;
+    __invalidPositional?: string | number | undefined;
+}, {
+    tabId?: number | bigint | undefined;
+    refId?: string | undefined;
+    label?: string | undefined;
+    __invalidPositional?: string | number | undefined;
+}>, {
+    tabId?: number | bigint | undefined;
+    refId?: string | undefined;
+    label?: string | undefined;
+    __invalidPositional?: string | number | undefined;
+}, {
+    tabId?: number | bigint | undefined;
+    refId?: string | undefined;
+    label?: string | undefined;
+    __invalidPositional?: string | number | undefined;
+}>, {
+    tabId?: number | bigint | undefined;
+    refId?: string | undefined;
+    label?: string | undefined;
+    __invalidPositional?: string | number | undefined;
+}, unknown>;

package/shared/cross/schemas/host.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+export declare const HostCallParamsSchema: z.ZodObject<{
+    action: z.ZodString;
+    params: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    action: z.ZodString;
+    params: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    action: z.ZodString;
+    params: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+}, z.ZodTypeAny, "passthrough">>;
+/** JSON-serializable values returned by eval/host handlers (array before record — Zod union order). */
+export declare const JsonSerializableResultSchema: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnknown, "many">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const HostCallResultSchema: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnknown, "many">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;

package/shared/cross/schemas/network.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+
+export declare const FetchParamsSchema: z.ZodObject<{
+    url: z.ZodString;
+    method: z.ZodDefault<z.ZodString>;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    timeout: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodBigInt, z.ZodNumber]>, bigint, number | bigint>>;
+    store: z.ZodOptional<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    url: z.ZodString;
+    method: z.ZodDefault<z.ZodString>;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    timeout: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodBigInt, z.ZodNumber]>, bigint, number | bigint>>;
+    store: z.ZodOptional<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    url: z.ZodString;
+    method: z.ZodDefault<z.ZodString>;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    timeout: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodBigInt, z.ZodNumber]>, bigint, number | bigint>>;
+    store: z.ZodOptional<z.ZodBoolean>;
+    options: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+}, z.ZodTypeAny, "passthrough">>;
+export declare const SleepParamsSchema: z.ZodObject<{
+    duration: z.ZodEffects<z.ZodUnion<[z.ZodBigInt, z.ZodNumber]>, bigint, number | bigint>;
+}, "strip", z.ZodTypeAny, {
+    duration: bigint;
+}, {
+    duration: number | bigint;
+}>;