@ineerajrajeev/aios-web-sdk 0.1.1

package/README.md

@@ -0,0 +1,278 @@
+# @ineerajrajeev/aios-web-sdk
+
+The official Browser JavaScript/TypeScript SDK for [aiOS](https://www.getaios.tech).
+
+Provides type-safe bindings for integrating web applications with local AI browser agents through the aiOS Safari Extension. The SDK manages structured page exports, dynamic security capability policies, component-level interaction constraints, and a secure consent-gated communication bridge.
+
+---
+
+## Installation
+
+Install the package from npm:
+
+```bash
+npm install @ineerajrajeev/aios-web-sdk
+```
+
+Or link it locally in your project:
+
+```json
+"dependencies": {
+  "@ineerajrajeev/aios-web-sdk": "^0.1.0"
+}
+```
+
+---
+
+## Getting Started
+
+Import and initialize the SDK early in your application lifecycle. This establishes a secure connection with the aiOS Safari Extension running in the user's browser.
+
+```typescript
+import { aiOS } from "@ineerajrajeev/aios-web-sdk";
+
+aiOS.init({
+  appId: "com.example.myapp",
+  requireConsent: true
+});
+```
+
+**Parameters**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `appId` | `string` | Yes | Unique reverse-domain identifier for your application. |
+| `requireConsent` | `boolean` | No (default: `true`) | When enabled, a consent modal is shown to the user before any page data is exported to the AI agent. |
+
+Once initialized, the SDK injects metadata into the page and begins listening for extension handshake messages. The aiOS Safari Extension will automatically detect the SDK's presence.
+
+---
+
+## API Reference
+
+### aiOS.setPagePolicy(policy)
+
+Controls what permissions an AI agent has on the current page. Use this to restrict or grant specific interaction capabilities. Setting `allowed: false` blocks all agent operations entirely.
+
+```typescript
+aiOS.setPagePolicy({
+  allowed: true,
+  capabilities: {
+    read: true,
+    write: false,
+    execute: true,
+    summarize: true
+  },
+  exportMode: "structured-only"
+});
+```
+
+**Parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `allowed` | `boolean` | Master switch. When `false`, all agent access to this page is denied. |
+| `userMessage` | `string` | Optional custom message shown to the agent when the page is blocked. |
+| `capabilities.read` | `boolean` | Allow the agent to read page content and extract data. |
+| `capabilities.write` | `boolean` | Allow the agent to fill forms and modify input values. |
+| `capabilities.execute` | `boolean` | Allow the agent to click buttons, follow links, scroll, and interact. |
+| `capabilities.summarize` | `boolean` | Allow the agent to generate summaries of page content. |
+| `exportMode` | `"structured-only"` or `"dom-allowed"` | Controls whether the agent can fall back to raw DOM scraping or must rely on SDK-provided structured data only. |
+
+**Use cases**: Block AI agents on sensitive pages (payment, authentication), restrict write access on read-only dashboards, or enforce structured-only data access on privacy-critical pages.
+
+---
+
+### aiOS.setPageContext(context)
+
+Describes the semantic purpose of the current page to the AI agent. This metadata helps the agent understand what the page is for, what actions it should take, and what information it may need from the user.
+
+```typescript
+aiOS.setPageContext({
+  pageType: "job_application",
+  title: "Software Engineer Application Form",
+  description: "A multi-step form collecting work history and qualifications.",
+  agentIntent: "Fill in the user's work history and submit the application form.",
+  seekFromUser: [
+    {
+      id: "salary_expectation",
+      label: "Salary",
+      description: "Desired yearly compensation",
+      inputType: "number"
+    }
+  ]
+});
+```
+
+**Parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pageType` | `string` | Page categorization (e.g. `"checkout"`, `"form"`, `"catalog"`, `"generic"`). |
+| `title` | `string` | Human-readable semantic title for the page. |
+| `description` | `string` | Summary of the page content and purpose. |
+| `agentIntent` | `string` | Natural language instructions describing what the AI agent should accomplish on this page. |
+| `seekFromUser` | `SeekField[]` | Optional list of input fields the agent should prompt the user for before proceeding. Each field includes `id`, `label`, `description`, and `inputType`. |
+
+**Use cases**: Guide agents through multi-step forms, provide context for product pages, or instruct agents to pause and ask the user for sensitive information like payment preferences.
+
+---
+
+### aiOS.defineZones(zones)
+
+Specifies the primary content area of the page and excludes irrelevant or sensitive DOM regions from AI agent access. This prevents the agent from interacting with promotional banners, cookie notices, navigation chrome, or other non-essential elements.
+
+```typescript
+aiOS.defineZones({
+  primary: "[data-app-content]",
+  excluded: [".promo-banner", "footer", ".cookie-notice"]
+});
+```
+
+**Parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `primary` | `string` | CSS selector for the main content container that the agent should focus on. |
+| `excluded` | `string[]` | Array of CSS selectors matching DOM elements the agent should ignore entirely. |
+
+**Use cases**: Focus the agent on the main product listing and hide sidebar ads, exclude footer navigation from agent discovery, or restrict agent attention to a specific form region.
+
+---
+
+### aiOS.markComponent(id, component)
+
+Registers a specific DOM element as a policy-managed interactive component. This gives the agent a named, typed handle for the element with explicit capability permissions, rather than relying on generic DOM discovery.
+
+```typescript
+aiOS.markComponent("checkout-btn", {
+  kind: "button",
+  label: "Proceed to Checkout",
+  selector: ".checkout-btn",
+  capabilities: ["clickable"],
+  visible: true
+});
+```
+
+**Parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | `string` | Unique identifier for this component registration. |
+| `component.kind` | `"button"`, `"input"`, `"link"`, `"cart"`, or `"custom"` | Semantic role of the element. |
+| `component.label` | `string` | Human-readable name describing the element's purpose. |
+| `component.selector` | `string` | CSS selector targeting the DOM element. |
+| `component.capabilities` | `string[]` | Granted interaction rights: `"clickable"`, `"readable"`, `"writable"`, or `"hidden"`. |
+| `component.visible` | `boolean` | Whether the component is currently visible and actionable. |
+
+**Use cases**: Expose checkout buttons for agent interaction, mark form fields as writable so agents can fill them, hide sensitive elements like delete buttons from agent access, or label cart items for structured data extraction.
+
+---
+
+### aiOS.unmarkComponent(id)
+
+Removes a previously registered component from the SDK's component registry. The element will no longer be exposed to the agent as a named interactive target.
+
+```typescript
+aiOS.unmarkComponent("checkout-btn");
+```
+
+**Parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | `string` | The component identifier that was used during `markComponent`. |
+
+**Use cases**: Clean up components when navigating away from a view, remove elements that are no longer relevant after a user action, or dynamically adjust available components based on application state.
+
+---
+
+### aiOS.publish(options)
+
+Compiles the current page context, registered components, and any custom data payload into a structured export package. If consent is required, a modal dialog is presented to the user for approval before the data is transmitted to the extension.
+
+Returns a `Promise<boolean>` that resolves to `true` if the user approved and the data was sent, or `false` if the user denied.
+
+```typescript
+const approved = await aiOS.publish({
+  schema: "cart.v1",
+  data: {
+    itemsCount: 3,
+    total: 89.99,
+    currency: "USD"
+  }
+});
+
+if (approved) {
+  console.log("Page data exported to aiOS.");
+} else {
+  console.log("User denied the export.");
+}
+```
+
+**Parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options.schema` | `string` | Optional schema identifier for the data payload (e.g. `"cart.v1"`, `"applicant.v1"`). |
+| `options.data` | `object` | Optional application-specific business data to include in the export (e.g. cart items, form state). |
+
+**Use cases**: Export shopping cart contents for comparison agents, send job application form data for auto-fill workflows, or share product catalog information with recommendation agents.
+
+---
+
+### aiOS.onEvent(type, handler)
+
+Subscribes to real-time events from the aiOS Safari Extension. This allows your application to react to agent activity, detect extension presence, and track compliance sessions. Returns an unsubscribe function.
+
+```typescript
+const unsubscribe = aiOS.onEvent("agent:active", (event) => {
+  console.log("Agent performed action:", event.payload.action);
+  console.log("Was it blocked?", event.payload.blocked);
+});
+
+// Clean up listener when no longer needed:
+unsubscribe();
+```
+
+**Parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `type` | `string` | Event type to listen for. |
+| `handler` | `Function` | Callback function invoked when the event fires. Receives the event object with a `payload` property. |
+
+**Available event types**
+
+| Event | Description |
+|-------|-------------|
+| `"extension:present"` | Fired when the aiOS Safari Extension is detected on the page. |
+| `"agent:active"` | Fired when an AI agent performs an action (click, type, scroll) on the page. Payload includes the action type and whether it was blocked by policy. |
+| `"agent:session-start"` | Fired when an AI agent begins a new interaction session. |
+| `"agent:session-end"` | Fired when an agent session concludes. |
+
+**Use cases**: Show a status indicator when the extension is connected, log agent actions for audit purposes, display real-time feedback when the agent interacts with page elements, or pause application logic during active agent sessions.
+
+---
+
+## Development
+
+```bash
+# Run the test suite
+npm run test
+
+# Build for production (ES modules + CommonJS + type declarations)
+npm run build
+
+# Watch mode during development
+npm run dev
+
+# TypeScript type checking
+npm run typecheck
+```
+
+---
+
+## What is Next
+
+This is the foundational release of the aiOS Web SDK. Many more capabilities are on the roadmap, including enhanced agent session management, richer event streams, multi-page workflow coordination, and deeper framework integrations for React, Vue, and Angular. Stay tuned at [getaios.tech](https://www.getaios.tech) for updates.