### Install @crowdstrike/foundry-js

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Install the foundry-js library using npm, yarn, or pnpm.

```sh
npm install @crowdstrike/foundry-js
# or
yarn add @crowdstrike/foundry-js
# or
pnpm add @crowdstrike/foundry-js
```

--------------------------------

### Execute API Integration Operation

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Execute a specific operation within an API Integration. Ensure the App is provisioned and the API Integration is configured. This example calls the 'Get Cities' operation.

```javascript
(async () => {
  // we assume, that API Integration was created and operation Get Cities exists
  
  const apiIntegration = falcon.apiIntegration({
    definitionId: '<api-integration-id from manifest.yml>',
    operationId: 'Get Cities',
  });

  const response = await apiIntegration.execute({
    request: {
      params: {
        path: {
          country: 'Spain'
        }
      }
    }
  });
  // response.resources?.[0]?.status_code === 200
  // date is at response.resources[0].response_body
});
```

--------------------------------

### Connect to Falcon Console

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Establish a connection to the Falcon Console when your application starts. If the connection is not established within 5 seconds, the app or extension may be dropped.

```javascript
import FalconApi from '@crowdstrike/foundry-js';

(async () => {
  const falcon = new FalconApi();
  
  await falcon.connect();
});
```

--------------------------------

### User Management API - Get Queries Users V1

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Retrieves a list of users. This is a GET request for user queries.

```APIDOC
## GET /userManagement/queries/users/v1

### Description
Retrieves a list of users within the system.

### Method
GET

### Endpoint
/userManagement/queries/users/v1

### Parameters
#### Query Parameters
- **No query parameters are explicitly documented for this operation in the source, but the example shows an empty object, implying it might accept optional parameters or no parameters at all.**
```

--------------------------------

### Devices API - Get Queries Devices V2

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Retrieves a list of devices based on filter criteria. This is a GET request for device queries.

```APIDOC
## GET /devices/queries/devices/v2

### Description
Retrieves a list of devices matching the specified filter. Supports pagination and sorting.

### Method
GET

### Endpoint
/devices/queries/devices/v2

### Parameters
#### Query Parameters
- **filter** (string) - Required - Filter string to narrow down the results (e.g., "platform_name:'Windows'").
- **limit** (integer) - Optional - Maximum number of results to return.
- **sort** (string) - Optional - Sorting criteria (e.g., "hostname.asc").
```

--------------------------------

### Working with Cloud Functions

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Provides a way to invoke Cloud Functions, supporting various HTTP methods (GET, POST, PATCH, PUT, DELETE) and allowing specification of path parameters and query parameters.

```APIDOC
## Working with Cloud Functions

### Description
Provides a way to invoke Cloud Functions, supporting various HTTP methods (GET, POST, PATCH, PUT, DELETE) and allowing specification of path parameters and query parameters.

### Method
```javascript
(async () => {
  const config = {
    name: 'CloudFunctionName',
    version: 1
  };
  
  const cloudFunction = falcon.cloudFunction(config);

  // you can specify path parameters that will be passsed to your Cloud Function. 
  // `id` and `mode` - example query params that your Cloud Function will receive 
  const getResponse = await cloudFunction.path('/?id=150&mode=compact')
    .get();

  // you can call different HTTP methods - GET, POST, PATCH, PUT, DELETE 
  const postResponse = await cloudFunction.path('/')
    .post({ name: 'test' });

  const patchResponse = cloudFunction.path('/')
    .patch({ name: 'test' });
  
  const putResponse = cloudFunction.path('/')
    .put({ name: 'test' });
  
  const deleteResponse = cloudFunction.path('/?id=100')
    .delete();
});
```
```

--------------------------------

### Devices API - Get Entities Devices V1

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Retrieves detailed information for specific device entities using their IDs. This is a GET request.

```APIDOC
## GET /devices/entities/devices/v1

### Description
Retrieves detailed information for a list of devices specified by their IDs.

### Method
GET

### Endpoint
/devices/entities/devices/v1

### Parameters
#### Query Parameters
- **ids** (array of strings) - Required - A list of device IDs for which to retrieve details.
```

--------------------------------

### Incidents API - Get Combined Crowdscores V1

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Fetches combined CrowdScores with optional limit. This is a GET request.

```APIDOC
## GET /incidents/combined/crowdscores/v1

### Description
Retrieves combined CrowdScore data for incidents.

### Method
GET

### Endpoint
/incidents/combined/crowdscores/v1

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of results to return.
```

--------------------------------

### Workflows API - Get Entities Execution Results V1

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Retrieves the results of a workflow execution. This is a GET request.

```APIDOC
## GET /workflows/entities/execution-results/v1

### Description
Fetches the results of a previously executed workflow.

### Method
GET

### Endpoint
/workflows/entities/execution-results/v1

### Parameters
#### Query Parameters
- **ids** (string) - Required - The ID of the workflow execution for which to retrieve results.
```

--------------------------------

### Accessing CrowdStrike Falcon API Namespaces

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Connect to the Falcon API and access various namespaces like alerts, incidents, and devices. Ensure you call `connect()` before accessing API methods. GET endpoints take URL params, POST/PATCH take a body.

```typescript
import FalconApi from '@crowdstrike/foundry-js';

const falcon = new FalconApi();
await falcon.connect();

// --- Alerts ---
const alertIds = await falcon.api.alerts.getQueriesAlertsV2({
  filter: "status:'new'",
  limit: 50,
  offset: 0,
  sort: 'created_timestamp.desc',
  msspRouteCid: 'ABC123',
  includeHidden: false,
});
console.log('Alert IDs:', alertIds?.resources);

// --- Incidents ---
const incidentIds = await falcon.api.incidents.getQueriesIncidentsV1({
  filter: "status:'20'",  // status 20 = New
  limit: 10,
  sort: 'start.desc',
});
const incidents = await falcon.api.incidents.postEntitiesIncidentsGetV1({}, {});
const crowdscores = await falcon.api.incidents.getCombinedCrowdscoresV1({ limit: 10 });

// --- Devices ---
const deviceIds = await falcon.api.devices.getQueriesDevicesV2({
  filter: "platform_name:'Windows'",
  limit: 100,
  sort: 'hostname.asc',
});
const deviceDetails = await falcon.api.devices.getEntitiesDevicesV1({
  ids: deviceIds?.resources ?? [],
});
console.log('Device hostnames:', deviceDetails?.resources?.map((d: any) => d.hostname));

// --- Workflows: trigger on-demand workflow and poll result ---
const trigger = await falcon.api.workflows.postEntitiesExecuteV1(
  {},
  { name: 'SendAlertNotification', depth: 0, key: 'alert-uuid-5678' }
);
const executionId = trigger?.resources?.[0] as string;
const workflowResult = await falcon.api.workflows.getEntitiesExecutionResultsV1({
  ids: executionId,
});
console.log('Workflow output:', workflowResult?.resources?.[0]);

// --- Remote Response ---
const putFiles = await falcon.api.remoteResponse.getQueriesPutFilesV1({
  filter: "name:'remediation*'",
  limit: 20,
});
const fileDetails = await falcon.api.remoteResponse.getEntitiesPutFilesV2({
  ids: putFiles?.resources?.[0],
});

// --- User Management ---
const users = await falcon.api.userManagement.getQueriesUsersV1({});
```

--------------------------------

### Interact with Cloud Functions: GET, POST, PATCH, PUT, DELETE

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Invoke Cloud Functions using various HTTP methods. Path parameters can be specified for GET requests, and request bodies can be sent with POST, PATCH, and PUT requests.

```javascript
(async () => {
  const config = {
    name: 'CloudFunctionName',
    version: 1
  };
  
  const cloudFunction = falcon.cloudFunction(config);

  // you can specify path parameters that will be passsed to your Cloud Function. 
  // `id` and `mode` - example query params that your Cloud Function will receive 
  const getResponse = await cloudFunction.path('/?id=150&mode=compact')
    .get();

  // you can call different HTTP methods - GET, POST, PATCH, PUT, DELETE 
  const postResponse = await cloudFunction.path('/')
    .post({ name: 'test' });

  const patchResponse = cloudFunction.path('/')
    .patch({ name: 'test' });
  
  const putResponse = cloudFunction.path('/')
    .put({ name: 'test' });
  
  const deleteResponse = cloudFunction.path('/?id=100')
    .delete();
});
```

--------------------------------

### Remote Response API - Get Entities Put Files V2

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Retrieves details for specific put files using their IDs. This is a GET request.

```APIDOC
## GET /remoteResponse/entities/put-files/v2

### Description
Retrieves detailed information for a list of put files specified by their IDs.

### Method
GET

### Endpoint
/remoteResponse/entities/put-files/v2

### Parameters
#### Query Parameters
- **ids** (string) - Required - The ID of the put file for which to retrieve details.
```

--------------------------------

### Invoke Cloud Functions (FaaS) with HTTP Methods

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Use `falcon.cloudFunction()` to invoke Foundry FaaS. Reference functions by name or ID. The `.path()` builder helps construct URLs with query parameters. Supports GET, POST, PATCH, PUT, and DELETE methods. Ensure cleanup with `falcon.destroy()`.

```typescript
import FalconApi from '@crowdstrike/foundry-js';

const falcon = new FalconApi();
await falcon.connect();

// Reference a cloud function by name (preferred) or id
const fn = falcon.cloudFunction({ name: 'process-host-data', version: 1 });

// GET with query params parsed from the URL string
const getResult = await fn.path('/results?limit=10&format=json').get();
console.log('GET result:', getResult);

// POST with body and explicit query/header params
const postResult = await fn.path('/actions').post(
  { hostId: 'host-abc123', action: 'isolate' },              // request body
  { query: { dryRun: ['true'] }, header: { 'x-trace': ['req-001'] } }
);
console.log('POST result:', postResult);

// PATCH, PUT, DELETE follow the same pattern
const patchResult = await fn.path('/config').patch({ timeout: 60 });
const putResult   = await fn.path('/scripts/v2').put({ content: '#!/bin/bash\necho hi' });
const delResult   = await fn.path('/cache?key=stale-key').delete();

// Clean up polling interval if extension unmounts before result arrives
falcon.destroy(); // also calls fn.destroy() internally
```

--------------------------------

### Remote Response API - Get Queries Put Files V1

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Retrieves a list of put files based on filter criteria. This is a GET request for put file queries.

```APIDOC
## GET /remoteResponse/queries/put-files/v1

### Description
Retrieves a list of put files matching the specified filter. Supports pagination and sorting.

### Method
GET

### Endpoint
/remoteResponse/queries/put-files/v1

### Parameters
#### Query Parameters
- **filter** (string) - Required - Filter string to narrow down the results (e.g., "name:'remediation*'").
- **limit** (integer) - Optional - Maximum number of results to return.
```

--------------------------------

### Incidents API - Get Queries Incidents V1

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Fetches a list of incidents based on filter criteria. This is a GET request for incident queries.

```APIDOC
## GET /incidents/queries/incidents/v1

### Description
Retrieves a list of incidents matching the specified filter. Supports pagination and sorting.

### Method
GET

### Endpoint
/incidents/queries/incidents/v1

### Parameters
#### Query Parameters
- **filter** (string) - Required - Filter string to narrow down the results (e.g., "status:'20'").
- **limit** (integer) - Optional - Maximum number of results to return.
- **sort** (string) - Optional - Sorting criteria (e.g., "start.desc").
```

--------------------------------

### Alerts API - Get Queries Alerts V2

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Retrieves a list of alerts with specified filters and sorting. This method maps to a GET request for alert queries.

```APIDOC
## GET /alerts/queries/alerts/v2

### Description
Retrieves a list of alerts based on the provided filter criteria. Supports pagination and sorting.

### Method
GET

### Endpoint
/alerts/queries/alerts/v2

### Parameters
#### Query Parameters
- **filter** (string) - Required - Filter string to narrow down the results (e.g., "status:'new'").
- **limit** (integer) - Optional - Maximum number of results to return.
- **offset** (integer) - Optional - Number of results to skip.
- **sort** (string) - Optional - Sorting criteria (e.g., "created_timestamp.desc").
- **msspRouteCid** (string) - Optional - Customer ID for MSSP routing.
- **includeHidden** (boolean) - Optional - Whether to include hidden alerts.
```

--------------------------------

### Incidents API - Post Entities Incidents Get V1

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Retrieves specific incident entities. This is a POST request.

```APIDOC
## POST /incidents/entities/incidents/v1

### Description
Retrieves detailed information for specific incident entities.

### Method
POST

### Endpoint
/incidents/entities/incidents/v1

### Parameters
#### Request Body
- **body** (object) - Required - An empty object is used as a placeholder in the example, but specific parameters may be required by the API for entity retrieval.
#### Query Parameters
- **No query parameters are explicitly documented for this operation in the source.**
```

--------------------------------

### FalconApi Class Initialization and Connection

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Demonstrates how to instantiate the FalconApi class, connect to the Falcon Console, and access initial context data. It also shows how to clean up the connection.

```APIDOC
## FalconApi Class Initialization and Connection

### Description
Instantiate the `FalconApi` class and call `connect()` to establish a connection with the Falcon Console. This is a prerequisite for using any other SDK features. The `connect()` call returns origin information and any initial context data.

### Method
```typescript
new FalconApi<LocalData = Record<string, any>>()
await falcon.connect()
falcon.destroy()
```

### Parameters
- `FalconApi` constructor can optionally accept a generic type for `LocalData`.

### Request Example
```typescript
import FalconApi from '@crowdstrike/foundry-js';

// Optionally type the LocalData you expect to receive from the console
interface MyExtensionData extends LocalData {
  detectionId: string;
  severity: number;
}

const falcon = new FalconApi<MyExtensionData>();

// connect() returns { origin: string, data?: MyExtensionData }
const { data } = await falcon.connect();

console.log('App ID:', falcon.appId);          // string
console.log('User:', data?.user.username);     // e.g. "alice@example.com"
console.log('CID:', data?.cid);                // customer ID
console.log('Theme:', data?.theme);            // 'theme-dark' | 'theme-light'
console.log('Locale:', data?.locale);          // e.g. 'en-us'
console.log('Timezone:', data?.timezone);      // e.g. 'America/New_York'
console.log('Permissions:', data?.permissions); // { canRead: true, canWrite: false }

// Clean up when extension unmounts
falcon.destroy();
```

### Response
#### Success Response (connect())
- `origin` (string) - The origin of the parent Falcon Console.
- `data` (MyExtensionData) - Optional initial context data provided by the console.

#### Response Example (connect())
```json
{
  "origin": "https://falcon.crowdstrike.com",
  "data": {
    "user": {"username": "alice@example.com"},
    "cid": "12345678-1234-1234-1234-1234567890ab",
    "theme": "theme-dark",
    "locale": "en-us",
    "timezone": "America/New_York",
    "permissions": {"canRead": true, "canWrite": false},
    "detectionId": "some-detection-id",
    "severity": 5
  }
}
```
```

--------------------------------

### Initialize and Connect FalconApi

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Instantiate the FalconApi class and connect to the Falcon Console. Ensure connect() is called before using other features, as it times out after 5 seconds.

```typescript
import FalconApi from '@crowdstrike/foundry-js';

// Optionally type the LocalData you expect to receive from the console
interface MyExtensionData extends LocalData {
  detectionId: string;
  severity: number;
}

const falcon = new FalconApi<MyExtensionData>();

// connect() returns { origin: string, data?: MyExtensionData }
const { data } = await falcon.connect();

console.log('App ID:', falcon.appId);          // string
console.log('User:', data?.user.username);     // e.g. "alice@example.com"
console.log('CID:', data?.cid);                // customer ID
console.log('Theme:', data?.theme);            // 'theme-dark' | 'theme-light'
console.log('Locale:', data?.locale);          // e.g. 'en-us'
console.log('Timezone:', data?.timezone);      // e.g. 'America/New_York'
console.log('Permissions:', data?.permissions); // { canRead: true, canWrite: false }

// Clean up when extension unmounts
falcon.destroy();
```

--------------------------------

### Connecting to Falcon Console

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Establishes a connection to the Falcon Console. If the connection is not established within 5 seconds, the application or extension will be dropped from loading.

```APIDOC
## Connecting to Falcon Console

### Description
Establishes a connection to the Falcon Console. If the connection is not established within 5 seconds, the application or extension will be dropped from loading.

### Method
```javascript
import FalconApi from '@crowdstrike/foundry-js';

(async () => {
  const falcon = new FalconApi();
  await falcon.connect();
});
```
```

--------------------------------

### falcon.ui.uploadFile()

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Opens the native file upload UI for specific upload types, such as 'remote-response'. Returns the upload API response.

```APIDOC
## `falcon.ui.uploadFile()` — File Upload Dialog

Opens the Falcon Console native file upload UI. Currently supports `'remote-response'` put-file uploads. Returns the upload API response after the user completes the upload interaction.

### Parameters

- **uploadType** (string) - Required - The type of upload, e.g., 'remote-response'.
- **fileDetails** (object) - Required - Details about the file to be uploaded.
  - **name** (string) - Required - The name of the file.
  - **description** (string) - Optional - A description for the file.
  - **comments_for_audit_log** (string) - Optional - Comments for the audit log.

### Request Example

```typescript
// Trigger the Remote Response put-file upload modal
const uploadResult = await falcon.ui.uploadFile('remote-response', {
  name: 'remediation-script.ps1',
  description: 'Automated remediation script for CVE-2024-1234',
  comments_for_audit_log: 'Uploaded by SOC analyst - incident #4892',
});

if (uploadResult?.resources?.[0]) {
  console.log('File uploaded successfully:', uploadResult.resources[0]);
} else {
  console.log('Upload cancelled or failed');
}
```
```

--------------------------------

### Navigation Utilities

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Provides methods to navigate within the Falcon Console or open external URLs.

```APIDOC
## Navigation Utilities

As the Page or UI extension will run inside a sandboxed iframe, the `navigateTo` method must be used to change the url of the parent context (Falcon Console).

To open an external url (in a new tab):

```javascript
falcon.navigation.navigateTo({
  path: 'https://www.github.com'
});
```

To navigate to a new url within Falcon Console:

```javascript
falcon.navigation.navigateTo({
  path: '/login',
  type: "falcon"
});
```
```

--------------------------------

### falcon.navigation.navigateTo()

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Navigates the parent Falcon Console window. Supports internal Falcon routes and external URLs.

```APIDOC
## `falcon.navigation.navigateTo()` — URL Navigation

Navigates the parent Falcon Console window since extensions run in sandboxed iframes and cannot directly manipulate `window.location`. Supports both internal Falcon routes (`type: 'falcon'`) and external URLs (`type: 'internal'` opens in new tab).

### Parameters

- **path** (string) - Required - The path or URL to navigate to.
- **type** (string) - Required - Specifies the type of navigation. 'falcon' for internal routes, 'internal' for external URLs.
- **target** (string) - Optional - The target window for navigation (e.g., '_self', '_blank').
- **metaKey** (boolean) - Optional - Simulates the meta key (Cmd on macOS).
- **ctrlKey** (boolean) - Optional - Simulates the control key.
- **shiftKey** (boolean) - Optional - Simulates the shift key.

### Request Example

```typescript
// Navigate within Falcon Console (same tab)
await falcon.navigation.navigateTo({
  path: '/investigate/detections',
  type: 'falcon',
  target: '_self',
});

// Open external URL in a new tab
await falcon.navigation.navigateTo({
  path: 'https://falcon.crowdstrike.com/documentation',
  type: 'internal',
  target: '_blank',
});

// Simulate modifier-key navigation (e.g. Cmd+Click behavior)
await falcon.navigation.navigateTo({
  path: '/endpoint-security/hosts',
  type: 'falcon',
  metaKey: true,   // macOS Cmd key
  ctrlKey: false,
  shiftKey: false,
});
```
```

--------------------------------

### Write, Query, and Execute Saved Queries with LogScale

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Use `falcon.logscale` to write events, run dynamic queries, and execute pre-saved queries in LogScale. Ensure the FalconApi is connected before use. Results are logged to the console.

```typescript
import FalconApi from '@crowdstrike/foundry-js';

const falcon = new FalconApi();
await falcon.connect();

// Write an event to LogScale
const writeResult = await falcon.logscale.write(
  { name: 'my-function', version: '1' },   // identifies the log source
  {
    tag: 'my-app',
    tagSource: 'foundry-extension',
    testData: false,                         // set true to avoid polluting production logs
  }
);
console.log('Rows written:', (writeResult as any)?.resources?.[0]?.rows_written); // 1

// Run a dynamic ad-hoc query
const queryResult = await falcon.logscale.query({
  name: 'my-function',
  version: '1',
  search_query: '* | count()',
  start: '1h',     // look back 1 hour
} as any);
console.log('Event count:', (queryResult as any)?.resources?.[0]?.event_count);

// Execute a pre-saved query by its ID
const savedResult = await falcon.logscale.savedQuery({
  id: 'saved-query-uuid-1234',
  start: '30d',
  mode: 'sync',
} as any);
console.log('Saved query results:', (savedResult as any)?.resources);
```

--------------------------------

### Working with LogScale

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Facilitates interaction with LogScale for data ingestion and querying. Supports writing data, running dynamic queries, and executing saved queries.

```APIDOC
## Working with LogScale

### Description
Provides methods to interact with LogScale for data ingestion and querying. Supports writing data, running dynamic queries, and executing saved queries.

### Method
```javascript
(async () => {
  // write to LogScale
  const writeResult = await falcon.logscale.write({ test: 'check' });
  // writeResult.resources?.[0]?.rows_written === 1
  
  // run dynamic query
  const queryResult = await falcon.logscale.query({ search_query: "*", start: "1h" });
  // queryResult.resources?.[0]?.event_count > 0
  
  // run saved query
  const savedQueryResult = await falcon.logscale.savedQuery({ id: "<savedQueryId>", start: "30d", mode: 'sync' });
  // savedQueryResult.resources?.[0]?.event_count > 0
});
```
```

--------------------------------

### Open modal with UI extension using `openModal()`

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Use `falcon.ui.openModal()` to open a modal dialog rendering a registered UI extension. The function returns a Promise that resolves with data passed to `closeModal()`.

```typescript
import FalconApi from '@crowdstrike/foundry-js';

const falcon = new FalconApi();
await falcon.connect();

// Open a modal rendering a UI extension
const result = await falcon.ui.openModal({
  id: 'confirm-action-extension',
  type: 'extension',
}, 'Confirm Action', {
  path: '/confirm',          // initial hash route inside the extension iframe
  data: { actionId: 'quarantine', hostId: 'host-abc123' }, // passed as extra local data
  size: 'md',                // 'sm' | 'md' | 'lg' | 'xl' — default 'md'
  align: 'top',              // vertical alignment: 'top' or center (undefined)
});

if (result?.confirmed) {
  console.log('User confirmed with note:', result.note);
} else {
  console.log('Modal was dismissed');
}
```

--------------------------------

### Working with API Integration

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Allows execution of API Integrations after they have been provisioned and configured. It enables calling specific operations defined within an API Integration.

```APIDOC
## Working with API Integration

### Description
To call API Integration, App should be initially provisioned, and configuration for API Integration should be set up. It enables calling specific operations defined within an API Integration.

### Method
```javascript
(async () => {
  // we assume, that API Integration was created and operation Get Cities exists
  
  const apiIntegration = falcon.apiIntegration({
    definitionId: '<api-integration-id from manifest.yml>',
    operationId: 'Get Cities',
  });

  const response = await apiIntegration.execute({
    request: {
      params: {
        path: {
          country: 'Spain'
        }
      }
    }
  });
  // response.resources?.[0]?.status_code === 200
  // date is at response.resources[0].response_body
});
```
```

--------------------------------

### Integrate with External APIs using `apiIntegration`

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Call pre-provisioned external APIs with `falcon.apiIntegration()`. Specify `definitionId` from `manifest.yml` and `operationId`. Use `.execute()` with request parameters including path, query, headers, and an optional JSON body. Response includes status code and body.

```typescript
import FalconApi from '@crowdstrike/foundry-js';

const falcon = new FalconApi();
await falcon.connect();

// Assumes an API Integration named 'geo-api' with operation 'GetCitiesByCountry'
const geoApi = falcon.apiIntegration({
  definitionId: 'geo-api-definition-id',    // from manifest.yml api_integrations section
  operationId: 'GetCitiesByCountry',
});

const response = await geoApi.execute({
  request: {
    params: {
      path: { country: 'Spain' },           // path parameters
      query: { limit: 10 },                 // query parameters
      header: { 'Accept-Language': 'en' },  // custom headers
    },
    json: { additionalFilter: 'coastal' },  // optional JSON body
  },
});

// response.resources[0].status_code === 200
// response.resources[0].response_body contains the external API's response
const cities = response?.resources?.[0];
console.log('Status:', cities?.status_code);      // 200
console.log('Cities:', cities?.response_body);    // JSON from external API
```

--------------------------------

### Manage Collections: Write, Read, Search, List, Delete

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Interact with collections to store and retrieve data. Supports writing, reading, searching (exact match on name, not FQL), listing with pagination, and deleting records.

```javascript
(async () => {
  const sampleData = {
    "name": "John",
    "age": 42,
    "aliases": ["Doe", "Foundry"]
  };
  
  const collection = falcon
    .collection({collection: '<collectionName>' });

  // to write a collection
  const result = await collection.write('test-key', sampleData);

  // read collection
  const record = await collection.read('test-key');
  // record.age === 42
  
  // search collection, `filter` does NOT use FQL (Falcon Query Language). An exact match for the name has to be used in this example below
  const searchResult = await collection.search({ filter: `name:'exact-name-value'` });

  // list the object keys in the collection, pagination is supported using; `start`, `end` and `limit`.
  const listResult = await collection.list({ start, end, limit });
  
  // deletes record
  const deleteResponse = await collection.delete('test-key');
});
```

--------------------------------

### Execute On-Demand Workflow

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Call an on-demand workflow by providing its configuration. This snippet shows how to initiate a workflow execution and then retrieve its results.

```javascript
(async () => {
  const config = { name: 'WorkflowName', depth: 0 };

  const pendingResult = await falcon.api.workflows.postEntitiesExecuteV1({}, config);

  const result = await falcon.api.workflows.getEntitiesExecutionResultsV1({ ids: triggerResult.resources[0] });  
});
```

--------------------------------

### Working with Workflows

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Provides methods to interact with Foundry Workflows, including triggering on-demand workflows and retrieving their execution results.

```APIDOC
## Working with Workflows

### Description
To call on-demand workflow and retrieve execution results.

### Method
```javascript
(async () => {
  const config = { name: 'WorkflowName', depth: 0 };

  const pendingResult = await falcon.api.workflows.postEntitiesExecuteV1({}, config);

  const result = await falcon.api.workflows.getEntitiesExecutionResultsV1({ ids: triggerResult.resources[0] });  
});
```
```

--------------------------------

### Simulate modifier-key navigation using `navigateTo()`

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Simulate modifier-key navigation, such as Cmd+Click, by setting `metaKey: true` in the `navigateTo()` options for internal Falcon routes.

```typescript
import FalconApi from '@crowdstrike/foundry-js';

const falcon = new FalconApi();
await falcon.connect();

// Simulate modifier-key navigation (e.g. Cmd+Click behavior)
await falcon.navigation.navigateTo({
  path: '/endpoint-security/hosts',
  type: 'falcon',
  metaKey: true,   // macOS Cmd key
  ctrlKey: false,
  shiftKey: false,
});
```

--------------------------------

### falcon.collection()

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Creates a handle to a named Foundry Collection (key-value store) for performing CRUD, search, and list operations.

```APIDOC
## `falcon.collection()` — Custom Object Storage

Creates a handle to a named Foundry Collection (key-value store). Supports write, read, delete, search (FQL-like filter), and paginated list operations. The collection name must match one defined in the app's manifest.

### Parameters

- **collectionConfig** (object) - Required - Configuration for the collection.
  - **collection** (string) - Required - The name of the collection.

### Collection Operations

#### `write(key, value)`

Writes a record to the collection.

- **key** (string) - Required - The unique key for the record.
- **value** (object) - Required - The data to store.

#### `read(key)`

Reads a record from the collection by its key.

- **key** (string) - Required - The key of the record to read.

#### `search(options)`

Searches for records within the collection using a filter.

- **options** (object) - Required - Search options.
  - **filter** (string) - Required - An exact-match filter string (e.g., `theme:'dark'`).
  - **offset** (string) - Optional - Pagination offset.
  - **sort** (string) - Optional - Sorting criteria.
  - **limit** (number) - Optional - Maximum number of results.

#### `list(options)`

Lists all keys in the collection with pagination.

- **options** (object) - Optional - Listing options.
  - **start** (string) - Optional - Starting key for listing.
  - **end** (string) - Optional - Ending key for listing.
  - **limit** (number) - Optional - Maximum number of keys to return.

#### `delete(key)`

Deletes a record from the collection by its key.

- **key** (string) - Required - The key of the record to delete.

### Request Example

```typescript
const collection = falcon.collection({ collection: 'user-preferences' });

// Write a record
await collection.write('user-alice', {
  theme: 'dark',
  itemsPerPage: 25,
  favoriteHosts: ['host-001', 'host-002'],
});

// Read a record by key
const prefs = await collection.read('user-alice') as {
  resources?: Array<{ theme: string; itemsPerPage: number }>
};
console.log('Theme:', prefs?.resources?.[0]?.theme); // 'dark'

// Search with an exact-match filter (NOT full FQL)
const searchResult = await collection.search({
  filter: `theme:'dark'`,
  offset: '',
  sort: '',
  limit: 50,
});
console.log('Dark-theme users:', searchResult);

// List all keys with pagination
const keyList = await collection.list({ start: '', end: '', limit: 100 });
console.log('Keys:', keyList);

// Delete a record
await collection.delete('user-alice');
```
```

--------------------------------

### LogScale Log Ingestion & Querying

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Interact with your custom LogScale repository to write events, run dynamic queries, and execute saved queries.

```APIDOC
## `falcon.logscale.write`

### Description
Writes an event to LogScale. This method is used for ingesting logs and telemetry data.

### Method
`write(sourceIdentifier, eventData)`

### Parameters
#### `sourceIdentifier` (object) - Required
An object that identifies the log source.
- `name` (string) - The name of the function or source.
- `version` (string) - The version of the function or source.

#### `eventData` (object) - Required
An object containing the data to be written to LogScale.
- `tag` (string) - A tag for the event.
- `tagSource` (string) - The source of the tag.
- `testData` (boolean) - Set to true to avoid polluting production logs.

### Request Example
```typescript
await falcon.logscale.write(
  { name: 'my-function', version: '1' },
  {
    tag: 'my-app',
    tagSource: 'foundry-extension',
    testData: false,
  }
);
```

### Response
#### Success Response
Returns information about the write operation, including the number of rows written.
- `resources[0].rows_written` (number) - The number of rows successfully written.
```

```APIDOC
## `falcon.logscale.query`

### Description
Runs a dynamic ad-hoc query against LogScale. This method allows for real-time data exploration.

### Method
`query(queryOptions)`

### Parameters
#### `queryOptions` (object) - Required
An object containing the query parameters.
- `name` (string) - The name of the log source to query.
- `version` (string) - The version of the log source.
- `search_query` (string) - The LogScale query string.
- `start` (string) - The time range to look back, e.g., '1h' for 1 hour.

### Request Example
```typescript
await falcon.logscale.query({
  name: 'my-function',
  version: '1',
  search_query: '* | count()',
  start: '1h',
});
```

### Response
#### Success Response
Returns the results of the query.
- `resources[0].event_count` (number) - The count of events matching the query.
```

```APIDOC
## `falcon.logscale.savedQuery`

### Description
Executes a pre-saved query in LogScale by its ID. Useful for running predefined analytical queries.

### Method
`savedQuery(queryOptions)`

### Parameters
#### `queryOptions` (object) - Required
An object containing the saved query parameters.
- `id` (string) - The unique identifier of the saved query.
- `start` (string) - The time range for the query, e.g., '30d' for 30 days.
- `mode` (string) - The execution mode, e.g., 'sync'.

### Request Example
```typescript
await falcon.logscale.savedQuery({
  id: 'saved-query-uuid-1234',
  start: '30d',
  mode: 'sync',
});
```

### Response
#### Success Response
Returns the results of the saved query.
- `resources` (array) - An array containing the query results.
```

--------------------------------

### Open external URL in new tab using `navigateTo()`

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Use `falcon.navigation.navigateTo()` to open external URLs. Set `type: 'internal'` and `target: '_blank'` to open the URL in a new browser tab.

```typescript
import FalconApi from '@crowdstrike/foundry-js';

const falcon = new FalconApi();
await falcon.connect();

// Open external URL in a new tab
await falcon.navigation.navigateTo({
  path: 'https://falcon.crowdstrike.com/documentation',
  type: 'internal',
  target: '_blank',
});
```

--------------------------------

### Navigate within Falcon Console using `navigateTo()`

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Use `falcon.navigation.navigateTo()` to navigate within the Falcon Console. Specify `type: 'falcon'` for internal routes and `target: '_self'` to open in the same tab.

```typescript
import FalconApi from '@crowdstrike/foundry-js';

const falcon = new FalconApi();
await falcon.connect();

// Navigate within Falcon Console (same tab)
await falcon.navigation.navigateTo({
  path: '/investigate/detections',
  type: 'falcon',
  target: '_self',
});
```

--------------------------------

### Working with Collections

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Enables interaction with Foundry Collections for data storage and retrieval. Supports writing, reading, searching, listing, and deleting records within a collection.

```APIDOC
## Working with Collections

### Description
Provides methods to interact with Foundry Collections for data storage and retrieval. Supports writing, reading, searching, listing, and deleting records.

### Method
```javascript
(async () => {
  const sampleData = {
    "name": "John",
    "age": 42,
    "aliases": ["Doe", "Foundry"]
  };
  
  const collection = falcon
    .collection({collection: '<collectionName>' });

  // to write a collection
  const result = await collection.write('test-key', sampleData);

  // read collection
  const record = await collection.read('test-key');
  // record.age === 42
  
  // search collection, `filter` does NOT use FQL (Falcon Query Language). An exact match for the name has to be used in this example below
  const searchResult = await collection.search({ filter: `name:'exact-name-value'` });

  // list the object keys in the collection, pagination is supported using; `start`, `end` and `limit`.
  const listResult = await collection.list({ start, end, limit });
  
  // deletes record
  const deleteResponse = await collection.delete('test-key');
});
```
```

--------------------------------

### falcon.events - Subscribing to Console Events

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Utilize the `falcon.events` emitter to subscribe to 'data' events for context updates and 'broadcast' events for inter-extension communication.

```APIDOC
## falcon.events — Subscribing to Console Events

### Description
An [Emittery](https://github.com/sindresorhus/emittery) event emitter that allows your extension to listen for events from the Falcon Console. It fires a `data` event when new context data is pushed to the extension and a `broadcast` event when another extension sends a message.

### Method
```typescript
falcon.events.on('data', handler)
falcon.events.on('broadcast', handler)
unsubscribeData()
unsubscribeBroadcast()
```

### Parameters
- `'data'` (string): Event name for context data updates.
- `'broadcast'` (string): Event name for messages sent from other extensions.
- `handler` (function): The callback function to execute when the event is fired.

### Request Example
```typescript
import FalconApi from '@crowdstrike/foundry-js';

const falcon = new FalconApi();
await falcon.connect();

// Listen for context data updates (e.g. user navigates to a different detection)
const unsubscribeData = falcon.events.on('data', (newData) => {
  console.log('Updated detection ID:', newData.detectionId);
  console.log('Updated severity:', newData.severity);
});

// Listen for broadcast messages from sibling extensions
const unsubscribeBroadcast = falcon.events.on('broadcast', (payload) => {
  console.log('Received broadcast:', payload);
  // payload is whatever was passed to falcon.sendBroadcast(payload)
});

// Stop listening later
unsubscribeData();
unsubscribeBroadcast();
```
```

--------------------------------

### Navigate to New URL within Falcon Console

Source: https://github.com/crowdstrike/foundry-js/blob/main/README.md

Use this to navigate to a new URL within the Falcon Console. Ensure the path is a valid route within the console.

```javascript
falcon.navigation.navigateTo({
  path: '/login',
  type: "falcon",
});
```

--------------------------------

### Interact with custom object storage using `collection()`

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Use `falcon.collection()` to create a handle to a named Foundry Collection for custom object storage. Supports write, read, delete, search, and list operations.

```typescript
import FalconApi from '@crowdstrike/foundry-js';

const falcon = new FalconApi();
await falcon.connect();

const collection = falcon.collection({ collection: 'user-preferences' });

// Write a record
await collection.write('user-alice', {
  theme: 'dark',
  itemsPerPage: 25,
  favoriteHosts: ['host-001', 'host-002'],
});

// Read a record by key
const prefs = await collection.read('user-alice') as {
  resources?: Array<{ theme: string; itemsPerPage: number }>
};
console.log('Theme:', prefs?.resources?.[0]?.theme); // 'dark'

// Search with an exact-match filter (NOT full FQL)
const searchResult = await collection.search({
  filter: `theme:'dark'`,
  offset: '',
  sort: '',
  limit: 50,
});
console.log('Dark-theme users:', searchResult);

// List all keys with pagination
const keyList = await collection.list({ start: '', end: '', limit: 100 });
console.log('Keys:', keyList);

// Delete a record
await collection.delete('user-alice');
```

--------------------------------

### falcon.ui.openModal() / falcon.ui.closeModal()

Source: https://context7.com/crowdstrike/foundry-js/llms.txt

Opens and closes modal dialogs within the Falcon Console. `openModal` renders a UI extension and returns data passed from `closeModal`.

```APIDOC
## `falcon.ui.openModal()` / `falcon.ui.closeModal()` — Modal Windows

Opens a modal dialog within the Falcon Console rendering any registered UI extension or page. Returns a Promise that resolves with data passed to `closeModal()`, or `undefined` if the user dismisses it.

### `falcon.ui.openModal()` Parameters

- **extension** (object) - Required - An object specifying the extension to open. Must contain an `id` property.
  - **id** (string) - Required - The ID of the UI extension to render.
  - **type** (string) - Required - The type of the extension, typically 'extension'.
- **title** (string) - Required - The title of the modal dialog.
- **options** (object) - Optional - Configuration options for the modal.
  - **path** (string) - Optional - Initial hash route inside the extension iframe.
  - **data** (object) - Optional - Data passed to the extension.
  - **size** (string) - Optional - Size of the modal ('sm', 'md', 'lg', 'xl'). Defaults to 'md'.
  - **align** (string) - Optional - Vertical alignment ('top' or 'center').

### `falcon.ui.closeModal()` Parameters

- **data** (object) - Optional - Data to pass back to the caller of `openModal`.

### Request Example

```typescript
// Open a modal rendering a UI extension
const result = await falcon.ui.openModal({
  id: 'confirm-action-extension',
  type: 'extension'
}, 'Confirm Action', {
  path: '/confirm',
  data: { actionId: 'quarantine', hostId: 'host-abc123' },
  size: 'md',
  align: 'top',
});

if (result?.confirmed) {
  console.log('User confirmed with note:', result.note);
} else {
  console.log('Modal was dismissed');
}

// Inside the modal extension — close and return data to caller
falcon.ui.closeModal({ confirmed: true, note: 'Approved by analyst' });

// Close without returning data
falcon.ui.closeModal();
```
```