@qapilot/appium-module 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @qapilot/appium-module
 
-Appium W3C WebDriver module for interacting with devices across **BrowserStack**, **LambdaTest**, and **local Appium** servers. Exposes a unified `invokeCommand` API that normalizes provider-specific differences (URLs, auth headers, capability formats) behind a single interface.
+A unified Appium W3C WebDriver client for **BrowserStack**, **LambdaTest**, and **local Appium** servers. One `invokeCommand` API, any provider, full TypeScript support.
 
 ## Installation
 
@@ -8,22 +8,21 @@ Appium W3C WebDriver module for interacting with devices across **BrowserStack**
 npm install @qapilot/appium-module
 ```
 
-If you plan to use the built-in HTTP server mode, also install `express`:
+No additional `@types` package is needed — types are bundled with the package.
 
-```bash
-npm install express
-```
+---
 
 ## Usage
 
-### Programmatic (library mode)
-
-Import `invokeCommand` and call any W3C WebDriver command against any supported provider.
+Import `invokeCommand` and call any supported command against any provider.
 
 ```typescript
 import { invokeCommand } from '@qapilot/appium-module';
+```
+
+### BrowserStack
 
-// Create a session on BrowserStack
+```typescript
 const session = await invokeCommand({
   commandName: 'createSession',
   provider: 'browserstack',
@@ -40,101 +39,88 @@ const session = await invokeCommand({
     },
   },
 });
-
-if (!session.success) {
-  throw new Error(session.error?.message);
-}
-
-const { sessionId } = session.data;
-
-// Find an element
-const element = await invokeCommand({
-  commandName: 'findElement',
-  provider: 'browserstack',
-  credentials: { username: process.env.BS_USER, accessKey: process.env.BS_KEY },
-  params: { sessionId, using: 'accessibility id', value: 'loginButton' },
-});
-
-// Click it
-await invokeCommand({
-  commandName: 'clickElement',
-  provider: 'browserstack',
-  credentials: { username: process.env.BS_USER, accessKey: process.env.BS_KEY },
-  params: { sessionId, elementId: element.data.elementId },
-});
-
-// Take a screenshot
-const screenshot = await invokeCommand({
-  commandName: 'getScreenshot',
-  provider: 'browserstack',
-  credentials: { username: process.env.BS_USER, accessKey: process.env.BS_KEY },
-  params: { sessionId },
-});
-
-// Delete the session
-await invokeCommand({
-  commandName: 'deleteSession',
-  provider: 'browserstack',
-  credentials: { username: process.env.BS_USER, accessKey: process.env.BS_KEY },
-  params: { sessionId },
-});
 ```
 
-### Local Appium
+### LambdaTest
 
 ```typescript
-import { invokeCommand } from '@qapilot/appium-module';
-
 const session = await invokeCommand({
   commandName: 'createSession',
-  provider: 'local',
+  provider: 'lambdatest',
   credentials: {
-    hubUrl: 'http://localhost:4723',
+    username: process.env.LT_USER,
+    accessKey: process.env.LT_KEY,
   },
   params: {
     capabilities: {
       platformName: 'Android',
-      'appium:automationName': 'UiAutomator2',
-      'appium:deviceName': 'emulator-5554',
+      'appium:deviceName': 'Galaxy S21',
+      'appium:app': 'lt://<app-id>',
     },
   },
 });
 ```
 
-### LambdaTest
+### Local Appium
 
 ```typescript
-import { invokeCommand } from '@qapilot/appium-module';
-
 const session = await invokeCommand({
   commandName: 'createSession',
-  provider: 'lambdatest',
+  provider: 'local',
   credentials: {
-    username: process.env.LT_USER,
-    accessKey: process.env.LT_KEY,
+    hubUrl: 'http://localhost:4723',
   },
   params: {
     capabilities: {
       platformName: 'Android',
-      'appium:deviceName': 'Galaxy S21',
-      'appium:app': 'lt://<app-id>',
+      'appium:automationName': 'UiAutomator2',
+      'appium:deviceName': 'emulator-5554',
     },
   },
 });
 ```
 
+---
+
 ## Supported Commands
 
-| Category | Commands |
-|----------|----------|
-| Session  | `createSession`, `getSession`, `deleteSession` |
-| Element  | `findElement`, `findElements`, `clickElement`, `setValue`, `clearElement`, `getElementText`, `getElementAttribute`, `getElementDisplayed`, `getElementRect`, `getElementLocation`, `getElementSize` |
-| Page     | `getScreenshot`, `getSource` |
-| Actions  | `performActions`, `touchPerform` |
-| Context  | `getContext`, `setContext`, `getContexts` |
-| Window   | `getWindow`, `getWindowHandles`, `switchWindow` |
-| Device   | `hideKeyboard`, `isKeyboardShown`, `pressKeycode`, `activateApp`, `terminateApp`, `setOrientation`, `setLocation` |
-| Script   | `executeScript`, `executeScriptSync` |
+All commands are invoked via `invokeCommand({ commandName, provider, credentials, params })`.
+
+| Category | Command | Key `params` |
+|----------|---------|--------------|
+| **Session** | `createSession` | `capabilities` |
+| | `getSession` | `sessionId` |
+| | `deleteSession` | `sessionId` |
+| **Element** | `findElement` | `sessionId`, `using`, `value` |
+| | `findElements` | `sessionId`, `using`, `value` |
+| | `clickElement` | `sessionId`, `elementId` |
+| | `setValue` | `sessionId`, `elementId`, `text` |
+| | `clearElement` | `sessionId`, `elementId` |
+| | `getElementText` | `sessionId`, `elementId` |
+| | `getElementAttribute` | `sessionId`, `elementId`, `attribute` |
+| | `getElementDisplayed` | `sessionId`, `elementId` |
+| | `getElementRect` | `sessionId`, `elementId` |
+| | `getElementLocation` | `sessionId`, `elementId` |
+| | `getElementSize` | `sessionId`, `elementId` |
+| **Page** | `getScreenshot` | `sessionId` |
+| | `getSource` | `sessionId` |
+| **Actions** | `performActions` | `sessionId`, `actions` |
+| | `touchPerform` | `sessionId`, `actions` |
+| **Context** | `getContext` | `sessionId` |
+| | `setContext` | `sessionId`, `name` |
+| | `getContexts` | `sessionId` |
+| **Window** | `getWindow` | `sessionId` |
+| | `getWindowHandles` | `sessionId` |
+| | `switchWindow` | `sessionId`, `handle` |
+| **Device** | `hideKeyboard` | `sessionId` |
+| | `isKeyboardShown` | `sessionId` |
+| | `pressKeycode` | `sessionId`, `keycode` |
+| | `activateApp` | `sessionId`, `appId` |
+| | `terminateApp` | `sessionId`, `appId` |
+| | `setOrientation` | `sessionId`, `orientation` |
+| | `setLocation` | `sessionId`, `latitude`, `longitude` |
+| **Script** | `executeScript` | `sessionId`, `script`, `args` |
+| | `executeScriptSync` | `sessionId`, `script`, `args` |
 
 Get the full list at runtime:
 
@@ -143,46 +129,56 @@ import { getSupportedCommands } from '@qapilot/appium-module';
 console.log(getSupportedCommands());
 ```
 
-## Extending
+---
 
-### Custom Providers
+## Response Shape
+
+Every `invokeCommand` call returns an `ExecuteResponse<T>`:
 
 ```typescript
-import { registerProvider, BaseProvider } from '@qapilot/appium-module';
-import type { IAppiumProvider, ProviderCredentials, AppiumServiceError } from '@qapilot/appium-module';
+{
+  success: boolean;
+  data?: T;       // present when success is true
+  error?: {       // present when success is false
+    message: string;
+    statusCode?: number;
+  };
+}
+```
 
-class SauceLabsProvider extends BaseProvider implements IAppiumProvider {
-  readonly name = 'saucelabs' as any;
-  protected readonly hubBaseUrl = 'https://ondemand.us-west-1.saucelabs.com';
-  protected readonly wdHubPath = '/wd/hub';
+Always check `success` before accessing `data`:
 
-  buildUrl(_sessionId: string | null, path: string, credentials: ProviderCredentials): string {
-    return `${this.buildBaseUrl(credentials)}${path}`;
-  }
+```typescript
+const result = await invokeCommand({ commandName: 'findElement', ... });
 
-  buildHeaders(credentials: ProviderCredentials): Record<string, string> {
-    return {
-      'Content-Type': 'application/json',
-      Authorization: this.buildBasicAuthHeader(credentials),
-    };
-  }
+if (!result.success) {
+  throw new Error(result.error?.message);
+}
 
-  normalizeCapabilities(caps: Record<string, unknown>): Record<string, unknown> {
-    return caps;
-  }
+const { elementId } = result.data;
+```
 
-  normalizeError(statusCode: number, body: unknown): AppiumServiceError {
-    return this.mapW3CError(statusCode, body);
-  }
+---
 
-  getDefaultCapabilities(): Record<string, unknown> {
-    return {};
-  }
-}
+## TypeScript Types
 
-registerProvider(new SauceLabsProvider());
+All types are exported from the main entry point:
+
+```typescript
+import type {
+  ExecuteRequest,
+  ExecuteResponse,
+  ProviderName,
+  ProviderCredentials,
+  AppiumServiceError,
+  IAppiumProvider,
+} from '@qapilot/appium-module';
 ```
 
+---
+
+## Extending
+
 ### Custom Commands
 
 ```typescript
@@ -205,64 +201,45 @@ class ShakeDeviceCommand extends BaseCommand<{ sessionId: string }, void> {
 registerCommand(new ShakeDeviceCommand());
 ```
 
-## HTTP Server Mode
-
-The package also ships a standalone Express HTTP server that exposes the command invoker over REST. This is useful when you want to call Appium from a language other than Node.js, or from a microservice over HTTP.
-
-```bash
-# Run the server directly
-npx @qapilot/appium-module/server
-
-# Or in your own project (after installing express):
-node node_modules/@qapilot/appium-module/dist/server.js
-```
+### Custom Providers
 
-### `POST /api/v1/execute`
+```typescript
+import { registerProvider, BaseProvider } from '@qapilot/appium-module';
+import type { IAppiumProvider, ProviderCredentials, AppiumServiceError } from '@qapilot/appium-module';
 
-```json
-{
-  "commandName": "findElement",
-  "provider": "browserstack",
-  "credentials": { "username": "...", "accessKey": "..." },
-  "params": { "sessionId": "abc123", "using": "xpath", "value": "//button" }
-}
-```
+class SauceLabsProvider extends BaseProvider implements IAppiumProvider {
+  readonly name = 'saucelabs' as any;
+  protected readonly hubBaseUrl = 'https://ondemand.us-west-1.saucelabs.com';
+  protected readonly wdHubPath = '/wd/hub';
 
-### `GET /api/v1/commands` — list all registered commands
-### `GET /api/v1/providers` — list all registered providers
-### `GET /api/v1/health` — liveness probe
+  buildUrl(_sessionId: string | null, path: string, credentials: ProviderCredentials): string {
+    return `${this.buildBaseUrl(credentials)}${path}`;
+  }
 
-Environment variables for server mode:
+  buildHeaders(credentials: ProviderCredentials): Record<string, string> {
+    return {
+      'Content-Type': 'application/json',
+      Authorization: this.buildBasicAuthHeader(credentials),
+    };
+  }
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PORT` | `8000` | HTTP port to listen on |
-| `NODE_ENV` | `development` | Set to `production` for JSON logging |
-| `LOG_LEVEL` | `info` | Pino log level |
-| `LOCAL_APPIUM_URL` | `http://localhost:4723` | Default URL for the `local` provider |
+  normalizeCapabilities(caps: Record<string, unknown>): Record<string, unknown> {
+    return caps;
+  }
 
-## TypeScript
+  normalizeError(statusCode: number, body: unknown): AppiumServiceError {
+    return this.mapW3CError(statusCode, body);
+  }
 
-All types are exported from the main entry point:
+  getDefaultCapabilities(): Record<string, unknown> {
+    return {};
+  }
+}
 
-```typescript
-import type {
-  ExecuteRequest,
-  ExecuteResponse,
-  ProviderName,
-  ProviderCredentials,
-  AppiumServiceError,
-  IAppiumProvider,
-} from '@qapilot/appium-module';
+registerProvider(new SauceLabsProvider());
 ```
 
-## Publishing
-
-```bash
-npm run build        # compile TypeScript to dist/
-npm login            # authenticate with npm
-npm publish --access public
-```
+---
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qapilot/appium-module",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Appium W3C WebDriver module for interacting with devices across BrowserStack, LambdaTest, and local Appium servers",
   "type": "module",
   "main": "dist/index.js",