> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobileboost.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

> API reference for the GPT Driver TypeScript SDK (gpt-driver-node)

The TypeScript SDK exposes a single `GptDriver` class. Import the default export and construct it with your WebdriverIO `browser`:

```js theme={null}
import GptDriver from "gpt-driver-node";

const gptDriver = new GptDriver({
    apiKey: "YOUR_API_KEY",
    driver: browser,
    serverConfig: { url: "http://127.0.0.1:4723/" },
});
```

## Constructor options

```ts theme={null}
new GptDriver(config: GptDriverConfig)
```

| Option                       | Type                   | Description                                                                                                                               |
| ---------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`                     | `string`               | **Required.** Your GPT Driver API key.                                                                                                    |
| `driver`                     | `WebDriver \| Browser` | An existing WebdriverIO / Appium session. The SDK runs on this session.                                                                   |
| `serverConfig.url`           | `URL \| string`        | The Appium server URL. Required whenever you pass a `driver`.                                                                             |
| `serverConfig.device`        | `object`               | `{ platform, deviceName, platformVersion }`. Required only when you do **not** pass a `driver` and want the SDK to start its own session. |
| `cachingMode`                | `CachingMode`          | Default caching for AI steps. One of `"NONE"`, `"FULL_SCREEN"`, `"INTERACTION_REGION"`. Defaults to `"NONE"`.                             |
| `testId`                     | `string`               | A label for this run, shown on the dashboard.                                                                                             |
| `appId`                      | `string`               | App identifier (`appPackage` on Android / `bundleId` on iOS). Auto-read from the session capabilities when omitted; set it to override.   |
| `additionalUserContext`      | `string`               | Free-text guidance passed to the AI on every AI step.                                                                                     |
| `maxWaitForStableScreenSecs` | `number`               | How long to wait for the screen to settle before an AI step.                                                                              |
| `organisationId`             | `string`               | Organisation identifier used for cache scoping.                                                                                           |

## AI commands

### aiExecute

Execute a natural-language instruction on the current screen. Optionally pass an `appiumHandler` to run native Appium code first and only fall back to AI if it throws (see [Deterministic execution](/engineer-tooling/appium-ts-deterministic-execution)).

```ts theme={null}
aiExecute(command: string, options?: {
    appiumHandler?: (driver) => Promise<any>;
    cachingMode?: CachingMode;
}): Promise<void>

// Options-object form
aiExecute(options: {
    command: string;
    appiumHandler?: (driver) => Promise<any>;
    cachingMode?: CachingMode;
}): Promise<void>
```

```js theme={null}
// Natural language only
await gptDriver.aiExecute("Tap the login button and wait for the home screen");

// Native-first, AI fallback
await gptDriver.aiExecute("Tap the Sign In button", {
    appiumHandler: async (driver) => { await driver.$("~sign-in-button").click(); },
});

// Override caching for this step
await gptDriver.aiExecute("Navigate to the settings page", { cachingMode: "FULL_SCREEN" });
```

### assert

Verify a condition without taking any action. Resolves if the condition holds, throws otherwise.

```ts theme={null}
assert(assertion: string, options?: { cachingMode?: CachingMode }): Promise<void>
```

```js theme={null}
await gptDriver.assert(`The total price is ${price}`);
```

### assertBulk

Check multiple conditions in one call. Throws if **any** condition fails.

```ts theme={null}
assertBulk(assertions: string[]): Promise<void>
```

```js theme={null}
await gptDriver.assertBulk([
    `The total price is ${price}`,
    "The VAT is calculated correctly",
    "The delivery date is shown in the format dd.mm.YYYY",
]);
```

### checkBulk

Check multiple conditions in one call. Returns an object with a `true` / `false` result per condition instead of throwing.

```ts theme={null}
checkBulk(conditions: string[]): Promise<Record<string, boolean>>
```

```js theme={null}
const results = await gptDriver.checkBulk([
    "The total price is shown",
    "The VAT is calculated correctly",
]);
```

### extract

Extract information from the current screen. Returns an object keyed by the values you asked for.

```ts theme={null}
extract(keys: string[]): Promise<Record<string, any>>
```

```js theme={null}
const flight = await gptDriver.extract([
    "departureAirportCode",
    "destinationAirportCode",
    "departureTime",
]);

await gptDriver.assertBulk([
    `departure airport is ${flight.departureAirportCode}`,
    `destination airport is ${flight.destinationAirportCode}`,
]);
```

### openDeepLinkUrl

Open a deep link in the app under test.

```ts theme={null}
openDeepLinkUrl(params: { url: string; package?: string; bundleId?: string }): Promise<void>
```

```js theme={null}
// Android
await gptDriver.openDeepLinkUrl({ url: "myapp://product/123", package: "com.example.app" });

// iOS
await gptDriver.openDeepLinkUrl({ url: "myapp://product/123", bundleId: "com.example.app" });
```

## Session lifecycle

The session starts automatically on the first AI command. Report the outcome at the end of a test so it is recorded on the dashboard.

```ts theme={null}
setSessionSucceeded(): Promise<void>
setSessionFailed(): Promise<void>
setSessionStatus(status: "succeeded" | "failed"): Promise<void>
```

```js theme={null}
await gptDriver.setSessionSucceeded();
```

## Caching

Caching reduces AI calls for repetitive executions. Set a default in the constructor, or override per call.

| Mode                 | Description                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------- |
| `NONE`               | No caching (default).                                                                                     |
| `FULL_SCREEN`        | Cache hit only if the full screen matches a previous successful execution.                                |
| `INTERACTION_REGION` | Cache hit if the interaction region matches (for example, the area around a tapped element). Recommended. |

```js theme={null}
// Default for the whole session
const gptDriver = new GptDriver({ /* ... */, cachingMode: "INTERACTION_REGION" });

// Override for a single step
await gptDriver.aiExecute("Navigate to settings", { cachingMode: "FULL_SCREEN" });
```