@ineerajrajeev/aios-web-sdk 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,303 @@
+/** Protocol version shared with the Safari extension content script. */
+declare const PROTOCOL_VERSION: "1";
+type PageCapability = "read" | "write" | "execute" | "summarize";
+type ComponentCapability = "readable" | "summarizable" | "clickable" | "writable" | "selectable" | "scrollable" | "draggable" | "focusable" | "hidden";
+type PageType = "job_application" | "checkout" | "account_settings" | "inbox" | "document" | "form" | "dashboard" | "search_results" | "generic";
+type ExportMode = "structured-only" | "dom-allowed";
+type TrustTier = "verified-sdk" | "partial" | "unverified";
+type SeekInputType = "text" | "boolean" | "date" | "file" | "choice" | "number";
+interface PageCapabilities {
+    read?: boolean;
+    write?: boolean;
+    execute?: boolean;
+    summarize?: boolean;
+}
+interface PagePolicy {
+    /** When false the extension must block all agent access on this page. */
+    allowed: boolean;
+    reason?: string;
+    userMessage?: string;
+    capabilities?: PageCapabilities;
+    exportMode?: ExportMode;
+}
+interface SeekField {
+    /** Stable identifier, e.g. "work_authorization". */
+    id: string;
+    /** Short label shown in consent UI and agent prompts. */
+    label: string;
+    /** Why the agent needs this from the user. */
+    description: string;
+    inputType: SeekInputType;
+    required?: boolean;
+    choices?: string[];
+    sensitive?: boolean;
+    /** Optional link to a writable component id on the page. */
+    mapsToComponentId?: string;
+}
+interface PageContext {
+    pageType: PageType;
+    title: string;
+    description: string;
+    /** High-level instruction for the agent, e.g. how to help on a job application. */
+    agentIntent: string;
+    /** Fields the agent should seek from the user via askUser, not scrape. */
+    seekFromUser?: SeekField[];
+    policy: PagePolicy;
+}
+type ComponentKind = "button" | "textfield" | "textarea" | "text" | "link" | "select" | "checkbox" | "radio" | "scrollable" | "draggable" | "file" | "custom";
+interface ComponentDescriptor {
+    id: string;
+    kind: ComponentKind;
+    label?: string;
+    /** What this control does — reduces agent mistakes. */
+    description?: string;
+    capabilities: ComponentCapability[];
+    value?: string | number | boolean | Record<string, unknown> | null;
+    placeholder?: string;
+    required?: boolean;
+    sensitive?: boolean;
+    selector?: string;
+    visible?: boolean;
+    inputType?: string;
+    href?: string;
+    trusted?: boolean;
+    actionIntent?: "submit" | "cancel" | "navigate" | "download" | string;
+    options?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
+    childComponentIds?: string[];
+    mapsToSeekField?: string;
+    schema?: string;
+}
+interface ContentZones {
+    /** CSS selector for primary app content. */
+    primary?: string;
+    /** Selectors excluded from agent read/summarize/execute. */
+    excluded?: string[];
+}
+interface ConsentRecord {
+    approvalId: string;
+    approvedAt: number;
+    approvedBy: "user";
+    rememberSite?: boolean;
+}
+interface ConsentPreview {
+    title: string;
+    message: string;
+    pageType: PageType;
+    pageTitle: string;
+    agentIntent: string;
+    seekFromUser: SeekField[];
+    sensitiveFieldCount: number;
+    componentCount: number;
+    capabilities: PageCapabilities;
+}
+interface ConsentRequestOptions {
+    title?: string;
+    message?: string;
+    /** If true, user can opt to remember approval for this origin. */
+    allowRememberSite?: boolean;
+}
+interface StructuredPagePayload {
+    version: typeof PROTOCOL_VERSION;
+    appId: string;
+    route: string;
+    url: string;
+    page: PageContext;
+    data: Record<string, unknown>;
+    components: ComponentDescriptor[];
+    zones?: ContentZones;
+    meta: {
+        generatedAt: number;
+        source: "sdk";
+        trust: TrustTier;
+        consent: ConsentRecord;
+    };
+}
+interface InitOptions {
+    appId: string;
+    /** Require user consent before any payload reaches the extension. Default: true. */
+    requireConsent?: boolean;
+    /** SDK protocol version sent during handshake. */
+    version?: string;
+}
+interface ExportOptions {
+    schema?: string;
+    data?: Record<string, unknown>;
+    components?: ComponentDescriptor[];
+    page?: Partial<PageContext>;
+    zones?: ContentZones;
+}
+interface MarkComponentInput extends Omit<ComponentDescriptor, "id"> {
+    id?: string;
+}
+/** Messages posted from the page to the extension content script. */
+type BridgeMessageType = "aios-sdk:init" | "aios-sdk:policy" | "aios-sdk:context" | "aios-sdk:zones" | "aios-sdk:components" | "aios-sdk:export" | "aios-sdk:ping" | "aios-sdk:presence-query";
+/** Events the extension emits so integrated apps can detect AI agent usage. */
+type ExtensionEventType = "extension:present" | "extension:status" | "agent:session-start" | "agent:active" | "agent:session-end" | "agent:data-access";
+interface ExtensionPresentPayload {
+    extensionVersion: string;
+    contentScriptVersion: string;
+}
+interface ExtensionStatusPayload {
+    present: boolean;
+    agentSessionActive: boolean;
+    lastAgentActivityAt: number | null;
+    sessionId: string | null;
+    sdkConnected: boolean;
+    appId: string | null;
+}
+interface AgentSessionPayload {
+    sessionId: string;
+    route: string;
+}
+interface AgentActivePayload {
+    sessionId: string;
+    action: string;
+    capability: PageCapability | "navigate" | "unknown";
+    route: string;
+    appId: string | null;
+    sdkIntegrated: boolean;
+    success: boolean;
+    blocked?: boolean;
+    error?: string | null;
+    timestamp: number;
+}
+interface AgentDataAccessPayload {
+    sessionId: string | null;
+    route: string;
+    appId: string | null;
+    approvalId?: string;
+    source: "user-consent" | "agent-read";
+    action?: string;
+}
+type ExtensionEventPayload = ExtensionPresentPayload | ExtensionStatusPayload | AgentSessionPayload | AgentActivePayload | AgentDataAccessPayload;
+interface ExtensionEvent<T extends ExtensionEventPayload = ExtensionEventPayload> {
+    type: ExtensionEventType;
+    timestamp: number;
+    version: string;
+    payload: T;
+}
+type ExtensionEventHandler = (event: ExtensionEvent) => void;
+interface ExtensionStatus {
+    extensionPresent: boolean;
+    extensionVersion?: string;
+    contentScriptVersion?: string;
+    agentSessionActive: boolean;
+    lastAgentActivityAt: number | null;
+    sessionId: string | null;
+    sdkConnected: boolean;
+    appId: string | null;
+}
+interface BridgeMessage<T = unknown> {
+    source: "aios-sdk";
+    type: BridgeMessageType;
+    appId: string;
+    version: string;
+    timestamp: number;
+    payload: T;
+}
+declare global {
+    interface Window {
+        __aiOS_sdk__?: {
+            version: string;
+            appId: string;
+            connected: boolean;
+            extensionPresent?: boolean;
+            agentSessionActive?: boolean;
+        };
+        __aiOS_policy__?: PagePolicy;
+        __aiOS_context__?: PageContext;
+        __aiOS_zones__?: ContentZones;
+        __aiOS_components__?: Record<string, ComponentDescriptor>;
+        __aiOS_structured_data__?: StructuredPagePayload;
+        __aiOS_pending_export__?: StructuredPagePayload;
+    }
+}
+
+declare class AIOSClient {
+    private appId;
+    private initialized;
+    private requireConsent;
+    private pageContext;
+    private zones;
+    private components;
+    private pageData;
+    private schema;
+    private pendingExport;
+    private lastApprovedExport;
+    private readonly events;
+    init(options: InitOptions): this;
+    setPagePolicy(policy: Partial<PagePolicy>): this;
+    setPageContext(context: Partial<PageContext>): this;
+    defineZones(zones: ContentZones): this;
+    markComponent(id: string, component: MarkComponentInput): this;
+    unmarkComponent(id: string): this;
+    exportPageData(options?: ExportOptions): this;
+    prepareExport(options?: ExportOptions): StructuredPagePayload;
+    buildConsentPreview(): ConsentPreview;
+    requestConsent(options?: ConsentRequestOptions): Promise<boolean>;
+    flushApprovedExport(options?: {
+        rememberSite?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Convenience path: prepare payload, ask the user, and send only if approved.
+     */
+    publish(options?: ExportOptions & ConsentRequestOptions): Promise<boolean>;
+    getPendingExport(): StructuredPagePayload | null;
+    getApprovedExport(): StructuredPagePayload | null;
+    getPageContext(): PageContext;
+    getComponents(): ComponentDescriptor[];
+    ping(): void;
+    /**
+     * Subscribe to extension / agent lifecycle events (exam proctoring, compliance, UX).
+     * Returns an unsubscribe function.
+     */
+    onEvent(type: ExtensionEventType, handler: ExtensionEventHandler): () => void;
+    /** Fires when the aiOS browser extension content script is active on this page. */
+    onExtensionPresent(handler: ExtensionEventHandler): () => void;
+    /** Fires when the local aiOS agent performs any tool action on this page. */
+    onAgentActive(handler: ExtensionEventHandler): () => void;
+    /** Subscribe to every extension event. */
+    onAnyExtensionEvent(handler: ExtensionEventHandler): () => void;
+    offEvent(type: ExtensionEventType, handler: ExtensionEventHandler): void;
+    /** Latest extension + agent session snapshot (updated as events arrive). */
+    getExtensionStatus(): ExtensionStatus;
+    /** Ask the extension to respond with `extension:status` (also sent on init). */
+    queryExtensionPresence(): void;
+    private syncExtensionGlobals;
+    private buildPayload;
+    private syncState;
+    private assertInitialized;
+    private rememberConsentForSite;
+    private hasRememberedConsent;
+}
+declare const aiOS: AIOSClient;
+
+declare const EXTENSION_MESSAGE_SOURCE: "aios-extension";
+declare class ExtensionEventBus {
+    private listening;
+    private status;
+    private handlers;
+    private wildcardHandlers;
+    startListening(): void;
+    stopListening(): void;
+    on(type: ExtensionEventType, handler: ExtensionEventHandler): () => void;
+    onAny(handler: ExtensionEventHandler): () => void;
+    off(type: ExtensionEventType, handler: ExtensionEventHandler): void;
+    getStatus(): ExtensionStatus;
+    queryPresence(appId: string): void;
+    private onWindowMessage;
+    private onCustomEvent;
+    private ingestWireMessage;
+    private applyStatus;
+    private emit;
+}
+
+declare const DEFAULT_PAGE_POLICY: PagePolicy;
+declare const DEFAULT_UNINTEGRATED_POLICY: PagePolicy;
+declare function createDefaultPageContext(title?: string): PageContext;
+
+export { AIOSClient, type AgentActivePayload, type AgentDataAccessPayload, type AgentSessionPayload, type BridgeMessage, type BridgeMessageType, type ComponentCapability, type ComponentDescriptor, type ComponentKind, type ConsentPreview, type ConsentRecord, type ConsentRequestOptions, type ContentZones, DEFAULT_PAGE_POLICY, DEFAULT_UNINTEGRATED_POLICY, EXTENSION_MESSAGE_SOURCE, type ExportMode, type ExportOptions, type ExtensionEvent, ExtensionEventBus, type ExtensionEventHandler, type ExtensionEventPayload, type ExtensionEventType, type ExtensionPresentPayload, type ExtensionStatus, type ExtensionStatusPayload, type InitOptions, type MarkComponentInput, PROTOCOL_VERSION, type PageCapabilities, type PageContext, type PagePolicy, type PageType, type SeekField, type SeekInputType, type StructuredPagePayload, type TrustTier, aiOS, createDefaultPageContext };

package/dist/index.d.ts

@@ -0,0 +1,303 @@
+/** Protocol version shared with the Safari extension content script. */
+declare const PROTOCOL_VERSION: "1";
+type PageCapability = "read" | "write" | "execute" | "summarize";
+type ComponentCapability = "readable" | "summarizable" | "clickable" | "writable" | "selectable" | "scrollable" | "draggable" | "focusable" | "hidden";
+type PageType = "job_application" | "checkout" | "account_settings" | "inbox" | "document" | "form" | "dashboard" | "search_results" | "generic";
+type ExportMode = "structured-only" | "dom-allowed";
+type TrustTier = "verified-sdk" | "partial" | "unverified";
+type SeekInputType = "text" | "boolean" | "date" | "file" | "choice" | "number";
+interface PageCapabilities {
+    read?: boolean;
+    write?: boolean;
+    execute?: boolean;
+    summarize?: boolean;
+}
+interface PagePolicy {
+    /** When false the extension must block all agent access on this page. */
+    allowed: boolean;
+    reason?: string;
+    userMessage?: string;
+    capabilities?: PageCapabilities;
+    exportMode?: ExportMode;
+}
+interface SeekField {
+    /** Stable identifier, e.g. "work_authorization". */
+    id: string;
+    /** Short label shown in consent UI and agent prompts. */
+    label: string;
+    /** Why the agent needs this from the user. */
+    description: string;
+    inputType: SeekInputType;
+    required?: boolean;
+    choices?: string[];
+    sensitive?: boolean;
+    /** Optional link to a writable component id on the page. */
+    mapsToComponentId?: string;
+}
+interface PageContext {
+    pageType: PageType;
+    title: string;
+    description: string;
+    /** High-level instruction for the agent, e.g. how to help on a job application. */
+    agentIntent: string;
+    /** Fields the agent should seek from the user via askUser, not scrape. */
+    seekFromUser?: SeekField[];
+    policy: PagePolicy;
+}
+type ComponentKind = "button" | "textfield" | "textarea" | "text" | "link" | "select" | "checkbox" | "radio" | "scrollable" | "draggable" | "file" | "custom";
+interface ComponentDescriptor {
+    id: string;
+    kind: ComponentKind;
+    label?: string;
+    /** What this control does — reduces agent mistakes. */
+    description?: string;
+    capabilities: ComponentCapability[];
+    value?: string | number | boolean | Record<string, unknown> | null;
+    placeholder?: string;
+    required?: boolean;
+    sensitive?: boolean;
+    selector?: string;
+    visible?: boolean;
+    inputType?: string;
+    href?: string;
+    trusted?: boolean;
+    actionIntent?: "submit" | "cancel" | "navigate" | "download" | string;
+    options?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
+    childComponentIds?: string[];
+    mapsToSeekField?: string;
+    schema?: string;
+}
+interface ContentZones {
+    /** CSS selector for primary app content. */
+    primary?: string;
+    /** Selectors excluded from agent read/summarize/execute. */
+    excluded?: string[];
+}
+interface ConsentRecord {
+    approvalId: string;
+    approvedAt: number;
+    approvedBy: "user";
+    rememberSite?: boolean;
+}
+interface ConsentPreview {
+    title: string;
+    message: string;
+    pageType: PageType;
+    pageTitle: string;
+    agentIntent: string;
+    seekFromUser: SeekField[];
+    sensitiveFieldCount: number;
+    componentCount: number;
+    capabilities: PageCapabilities;
+}
+interface ConsentRequestOptions {
+    title?: string;
+    message?: string;
+    /** If true, user can opt to remember approval for this origin. */
+    allowRememberSite?: boolean;
+}
+interface StructuredPagePayload {
+    version: typeof PROTOCOL_VERSION;
+    appId: string;
+    route: string;
+    url: string;
+    page: PageContext;
+    data: Record<string, unknown>;
+    components: ComponentDescriptor[];
+    zones?: ContentZones;
+    meta: {
+        generatedAt: number;
+        source: "sdk";
+        trust: TrustTier;
+        consent: ConsentRecord;
+    };
+}
+interface InitOptions {
+    appId: string;
+    /** Require user consent before any payload reaches the extension. Default: true. */
+    requireConsent?: boolean;
+    /** SDK protocol version sent during handshake. */
+    version?: string;
+}
+interface ExportOptions {
+    schema?: string;
+    data?: Record<string, unknown>;
+    components?: ComponentDescriptor[];
+    page?: Partial<PageContext>;
+    zones?: ContentZones;
+}
+interface MarkComponentInput extends Omit<ComponentDescriptor, "id"> {
+    id?: string;
+}
+/** Messages posted from the page to the extension content script. */
+type BridgeMessageType = "aios-sdk:init" | "aios-sdk:policy" | "aios-sdk:context" | "aios-sdk:zones" | "aios-sdk:components" | "aios-sdk:export" | "aios-sdk:ping" | "aios-sdk:presence-query";
+/** Events the extension emits so integrated apps can detect AI agent usage. */
+type ExtensionEventType = "extension:present" | "extension:status" | "agent:session-start" | "agent:active" | "agent:session-end" | "agent:data-access";
+interface ExtensionPresentPayload {
+    extensionVersion: string;
+    contentScriptVersion: string;
+}
+interface ExtensionStatusPayload {
+    present: boolean;
+    agentSessionActive: boolean;
+    lastAgentActivityAt: number | null;
+    sessionId: string | null;
+    sdkConnected: boolean;
+    appId: string | null;
+}
+interface AgentSessionPayload {
+    sessionId: string;
+    route: string;
+}
+interface AgentActivePayload {
+    sessionId: string;
+    action: string;
+    capability: PageCapability | "navigate" | "unknown";
+    route: string;
+    appId: string | null;
+    sdkIntegrated: boolean;
+    success: boolean;
+    blocked?: boolean;
+    error?: string | null;
+    timestamp: number;
+}
+interface AgentDataAccessPayload {
+    sessionId: string | null;
+    route: string;
+    appId: string | null;
+    approvalId?: string;
+    source: "user-consent" | "agent-read";
+    action?: string;
+}
+type ExtensionEventPayload = ExtensionPresentPayload | ExtensionStatusPayload | AgentSessionPayload | AgentActivePayload | AgentDataAccessPayload;
+interface ExtensionEvent<T extends ExtensionEventPayload = ExtensionEventPayload> {
+    type: ExtensionEventType;
+    timestamp: number;
+    version: string;
+    payload: T;
+}
+type ExtensionEventHandler = (event: ExtensionEvent) => void;
+interface ExtensionStatus {
+    extensionPresent: boolean;
+    extensionVersion?: string;
+    contentScriptVersion?: string;
+    agentSessionActive: boolean;
+    lastAgentActivityAt: number | null;
+    sessionId: string | null;
+    sdkConnected: boolean;
+    appId: string | null;
+}
+interface BridgeMessage<T = unknown> {
+    source: "aios-sdk";
+    type: BridgeMessageType;
+    appId: string;
+    version: string;
+    timestamp: number;
+    payload: T;
+}
+declare global {
+    interface Window {
+        __aiOS_sdk__?: {
+            version: string;
+            appId: string;
+            connected: boolean;
+            extensionPresent?: boolean;
+            agentSessionActive?: boolean;
+        };
+        __aiOS_policy__?: PagePolicy;
+        __aiOS_context__?: PageContext;
+        __aiOS_zones__?: ContentZones;
+        __aiOS_components__?: Record<string, ComponentDescriptor>;
+        __aiOS_structured_data__?: StructuredPagePayload;
+        __aiOS_pending_export__?: StructuredPagePayload;
+    }
+}
+
+declare class AIOSClient {
+    private appId;
+    private initialized;
+    private requireConsent;
+    private pageContext;
+    private zones;
+    private components;
+    private pageData;
+    private schema;
+    private pendingExport;
+    private lastApprovedExport;
+    private readonly events;
+    init(options: InitOptions): this;
+    setPagePolicy(policy: Partial<PagePolicy>): this;
+    setPageContext(context: Partial<PageContext>): this;
+    defineZones(zones: ContentZones): this;
+    markComponent(id: string, component: MarkComponentInput): this;
+    unmarkComponent(id: string): this;
+    exportPageData(options?: ExportOptions): this;
+    prepareExport(options?: ExportOptions): StructuredPagePayload;
+    buildConsentPreview(): ConsentPreview;
+    requestConsent(options?: ConsentRequestOptions): Promise<boolean>;
+    flushApprovedExport(options?: {
+        rememberSite?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Convenience path: prepare payload, ask the user, and send only if approved.
+     */
+    publish(options?: ExportOptions & ConsentRequestOptions): Promise<boolean>;
+    getPendingExport(): StructuredPagePayload | null;
+    getApprovedExport(): StructuredPagePayload | null;
+    getPageContext(): PageContext;
+    getComponents(): ComponentDescriptor[];
+    ping(): void;
+    /**
+     * Subscribe to extension / agent lifecycle events (exam proctoring, compliance, UX).
+     * Returns an unsubscribe function.
+     */
+    onEvent(type: ExtensionEventType, handler: ExtensionEventHandler): () => void;
+    /** Fires when the aiOS browser extension content script is active on this page. */
+    onExtensionPresent(handler: ExtensionEventHandler): () => void;
+    /** Fires when the local aiOS agent performs any tool action on this page. */
+    onAgentActive(handler: ExtensionEventHandler): () => void;
+    /** Subscribe to every extension event. */
+    onAnyExtensionEvent(handler: ExtensionEventHandler): () => void;
+    offEvent(type: ExtensionEventType, handler: ExtensionEventHandler): void;
+    /** Latest extension + agent session snapshot (updated as events arrive). */
+    getExtensionStatus(): ExtensionStatus;
+    /** Ask the extension to respond with `extension:status` (also sent on init). */
+    queryExtensionPresence(): void;
+    private syncExtensionGlobals;
+    private buildPayload;
+    private syncState;
+    private assertInitialized;
+    private rememberConsentForSite;
+    private hasRememberedConsent;
+}
+declare const aiOS: AIOSClient;
+
+declare const EXTENSION_MESSAGE_SOURCE: "aios-extension";
+declare class ExtensionEventBus {
+    private listening;
+    private status;
+    private handlers;
+    private wildcardHandlers;
+    startListening(): void;
+    stopListening(): void;
+    on(type: ExtensionEventType, handler: ExtensionEventHandler): () => void;
+    onAny(handler: ExtensionEventHandler): () => void;
+    off(type: ExtensionEventType, handler: ExtensionEventHandler): void;
+    getStatus(): ExtensionStatus;
+    queryPresence(appId: string): void;
+    private onWindowMessage;
+    private onCustomEvent;
+    private ingestWireMessage;
+    private applyStatus;
+    private emit;
+}
+
+declare const DEFAULT_PAGE_POLICY: PagePolicy;
+declare const DEFAULT_UNINTEGRATED_POLICY: PagePolicy;
+declare function createDefaultPageContext(title?: string): PageContext;
+
+export { AIOSClient, type AgentActivePayload, type AgentDataAccessPayload, type AgentSessionPayload, type BridgeMessage, type BridgeMessageType, type ComponentCapability, type ComponentDescriptor, type ComponentKind, type ConsentPreview, type ConsentRecord, type ConsentRequestOptions, type ContentZones, DEFAULT_PAGE_POLICY, DEFAULT_UNINTEGRATED_POLICY, EXTENSION_MESSAGE_SOURCE, type ExportMode, type ExportOptions, type ExtensionEvent, ExtensionEventBus, type ExtensionEventHandler, type ExtensionEventPayload, type ExtensionEventType, type ExtensionPresentPayload, type ExtensionStatus, type ExtensionStatusPayload, type InitOptions, type MarkComponentInput, PROTOCOL_VERSION, type PageCapabilities, type PageContext, type PagePolicy, type PageType, type SeekField, type SeekInputType, type StructuredPagePayload, type TrustTier, aiOS, createDefaultPageContext };