# Initiating Interactions from io.Connect

Source: https://docs.interop.io/manager/apis/initiating-interactions-from-io-connect/index.html

## Overview

Available since @interopio/manager-api 4.2.0

The [`@interopio/manager-api`](https://www.npmjs.com/package/@interopio/manager-api) library provides a `ManagerLib` export that can be included as an additional library when initializing the [`@interopio/desktop`](https://www.npmjs.com/package/@interopio/desktop) library in **io.Connect Desktop** projects and the [`@interopio/browser-platform`](https://www.npmjs.com/package/@interopio/browser-platform) and [`@interopio/browser`](https://www.npmjs.com/package/@interopio/browser) libraries in **io.Connect Browser** projects.

This enables interacting with **io.Manager** from interop-enabled apps running in **io.Connect Desktop** and **io.Connect Browser** - retrieving the connection state, subscribing for connection state changes, and refreshing platform data such as available apps, Layouts, system configurations, and more.

The following sections describe how to use the `ManagerLib` export in **io.Connect Desktop** and **io.Connect Browser** projects and provide a comprehensive API reference.

> ℹ️ *For details on configuring your **io.Connect Desktop** and **io.Connect Browser** platforms to connect to the **io.Manager** Server, see the [Configuration > Platform](https://docs.interop.io/manager/configuration/platform/index.md) section.*

## io.Connect Desktop

Available since io.Connect Desktop 10.3

To use the functionalities provided by the `ManagerLib` export in **io.Connect Desktop** client apps, you must include it in the `libraries` array of the configuration object for initializing the `@interopio/desktop` library.

When the io.Connect library has been initialized, a new `manager` property will be added to the io.Connect API object and the available methods will become accessible via the `io.manager` object:

```javascript
import IODesktop from "@interopio/desktop";
import { ManagerLib } from "@interopio/manager-api/desktop";

// Including the `ManagerLib` export as an additional library.
const config = { libraries: [ManagerLib] };

const io = await IODesktop(config);

// Retrieving the state of the connection to io.Manager.
const connectionState = await io.manager.getConnectionState();

// Providing a handler and subscribing for changes in the connection state.
const handler = connectionState => console.log(`Connection state: ${JSON.stringify(connectionState)}`);

const unsubscribe = await io.manager.onConnectionStateChange(handler);

// Refreshing the available apps and Layouts.
const dataToFetch = {
    layouts: true,
    applications: true
};

await io.manager.fetchData(dataToFetch);
```

> ℹ️ *For more details on the available methods, see the [API Reference](#api_reference) section.*

## io.Connect Browser

Available since io.Connect Browser 4.3

### Main App

To use the functionalities provided by the `ManagerLib` export in the [Main app](https://docs.interop.io/browser/developers/browser-platform/overview/index.md) of your **io.Connect Browser** project, you must include it in the `libraries` array of the `browser` object inside the configuration object for initializing the `@interopio/browser-platform` library.

When the io.Connect library has been initialized, a new `manager` property will be added to the io.Connect API object and the available methods will become accessible via the `io.manager` object:

```javascript
import IOBrowserPlatform from "@interopio/browser-platform";
import { ManagerLib } from "@interopio/manager-api/browser";

const config = {
    licenseKey: "my-license-key",
    browser: {
        // Including the `ManagerLib` export as an additional library.
        libraries: [ManagerLib]
    },
    manager: {
        // Settings for connecting to io.Manager.
    }
};

const { io } = await IOBrowserPlatform(config);

// Retrieving the state of the connection to io.Manager.
const connectionState = await io.manager.getConnectionState();

// Providing a handler and subscribing for changes in the connection state.
const handler = connectionState => console.log(`Connection state: ${JSON.stringify(connectionState)}`);

const unsubscribe = await io.manager.onConnectionStateChange(handler);

// Refreshing the available apps and Layouts.
const dataToFetch = {
    layouts: true,
    applications: true
};

await io.manager.fetchData(dataToFetch);
```

> ℹ️ *For more details on the available methods, see the [API Reference](#api_reference) section.*

### Browser Clients

To use the functionalities provided by the `ManagerLib` export in [Browser Client](https://docs.interop.io/browser/developers/browser-client/overview/index.md) apps running in **io.Connect Browser**, you must include it in the `libraries` array of the configuration object for initializing the `@interopio/browser` library.

When the io.Connect library has been initialized, a new `manager` property will be added to the io.Connect API object and the available methods will become accessible via the `io.manager` object:

```javascript
import IOBrowser from "@interopio/browser";
import { ManagerLib } from "@interopio/manager-api/browser";

// Including the `ManagerLib` export as an additional library.
const config = { libraries: [ManagerLib] };

const io = await IOBrowser(config);

// Retrieving the state of the connection to io.Manager.
const connectionState = await io.manager.getConnectionState();

// Providing a handler and subscribing for changes in the connection state.
const handler = connectionState => console.log(`Connection state: ${JSON.stringify(connectionState)}`);

const unsubscribe = await io.manager.onConnectionStateChange(handler);

// Refreshing the available apps and Layouts.
const dataToFetch = {
    layouts: true,
    applications: true
};

await io.manager.fetchData(dataToFetch);
```

> ℹ️ *For more details on the available methods, see the [API Reference](#api_reference) section.*

## API Reference

The following sections describe the methods and types exposed by the `ManagerLibAPI` interface. They are accessible via the `io.manager` object after the `ManagerLib` export has been included as an additional library when initializing your **io.Connect Desktop** or **io.Connect Browser** project.

### Failure Modes

When an `io.manager.*` method is called but isn't usable in the current session, it fails with an `Error` carrying a `code` property:

- `"METHOD_NOT_AVAILABLE"` - the host **io.Connect** platform doesn't provide the method. For a subscription method the error is thrown synchronously; otherwise the returned `Promise` rejects.
- `"SERVER_DISABLED"` - **io.Manager** is disabled in the **io.Connect** platform.
- `"SERVER_INCOMPATIBLE"` - the connected **io.Manager** Server is too old to support the method.

To avoid these errors, call [`checkCapability()`](#methods-checkcapability) with the method's `API_METHOD_*` identifier before calling - its [`CapabilityStatus`](#types-capabilitystatus) reports `available`, and when it is `false`, a `reason` equal to the `code` above. The `getConnectionState()`, `onConnectionStateChange()`, `checkCapability()`, and `checkCapabilities()` methods stay usable while **io.Manager** is disabled.

## Methods

The following core methods are available directly on the `io.manager` object. Domain operations are grouped under the `io.manager.layouts`, `io.manager.users`, `io.manager.groups`, and `io.manager.configs` namespaces, documented in the sections below.

### getConnectionState()

Retrieves information related to the state of the connection to **io.Manager**.

*Signature:*

```typescript
getConnectionState(): Promise<IOManagerConnectionState>;
```

*Returns:* `Promise` that resolves with an [`IOManagerConnectionState`](#types-iomanagerconnectionstate) object.

### onConnectionStateChange()

Notifies when the state of the connection to **io.Manager** changes.

*Signature:*

```typescript
onConnectionStateChange(
    callback: (connectionState: IOManagerConnectionState) => void
): Promise<UnsubscribeFunction>;
```

*Parameters:*

| Parameter | Type | Description |
|-----------|------|-------------|
| `callback` | `function` | Callback function for handling the event. Accepts as an argument an [`IOManagerConnectionState`](#types-iomanagerconnectionstate) object describing the new connection state. |

*Returns:* `Promise` that resolves with an `UnsubscribeFunction` that can be used to stop tracking the event.

### fetchData()

Triggers data refresh from **io.Manager**. You can specify the types of data to be refreshed (e.g. the available apps, Layouts, system configurations).

*Signature:*

```typescript
fetchData(args: FetchDataArgs): Promise<void>;
```

*Parameters:*

| Parameter | Type | Description |
|-----------|------|-------------|
| `args` | `object` | [`FetchDataArgs`](#types-fetchdataargs) object where each key corresponds to a type of data that can be refreshed. |

*Returns:* `Promise` that resolves with `void`.

### checkCapability()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Checks whether a given client-side capability is usable in the current session and, when it is not, why. Use this method to feature-gate code paths and to render the right message when a feature is unavailable.

The `capability` argument is drawn from the [`ClientCapability`](#types-clientcapability) enumeration. Two kinds of identifier are supported:

- Platform-level capabilities (e.g., `ADVANCED_LAYOUTS`) describe behavioral flags advertised by the **io.Connect** platform itself.

- Method-level capabilities (prefixed with `API_METHOD_`) provide information whether the specified method can be successfully invoked at the moment - `available` is `true` only when the host io.Connect platform provides the method, **io.Manager** is enabled, and the connected **io.Manager** Server supports it.

When `available` is `false` for a method-level capability, the returned [`CapabilityStatus`](#types-capabilitystatus) carries a `reason` property of type [`CapabilityUnavailableReason`](#types-capabilityunavailablereason) - the same value the method carries in the `code` property of its thrown `Error`, so one mapping handles both this check and a `catch` block. Unrecognized identifiers resolve with `{ available: false }`.

*Signature:*

```typescript
checkCapability(capability: ClientCapability): Promise<CapabilityStatus>;
```

*Parameters:*

| Parameter | Type | Description |
|-----------|------|-------------|
| `capability` | `ClientCapability` | The capability to probe. See [`ClientCapability`](#types-clientcapability) for the supported identifiers. |

*Returns:* `Promise` that resolves with a [`CapabilityStatus`](#types-capabilitystatus) object.

```javascript
import { ClientCapability } from "@interopio/manager-api/desktop";

const checkConflictStatus = await io.manager.checkCapability(ClientCapability.API_METHOD_LAYOUTS_CHECK_CONFLICT);

if (checkConflictStatus.available) {
    // Run the pre-save conflict check.
} else {
    // checkConflictStatus.reason: "METHOD_NOT_AVAILABLE" | "SERVER_DISABLED" | "SERVER_INCOMPATIBLE".
    showUnavailableHint(checkConflictStatus.reason);
}
```

### checkCapabilities()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Checks every client-side capability at once, returning a map from each [`ClientCapability`](#types-clientcapability) identifier to its [`CapabilityStatus`](#types-capabilitystatus). Useful for gating a set of features (e.g. a settings panel) in a single call.

*Signature:*

```typescript
checkCapabilities(): Promise<Record<ClientCapability, CapabilityStatus>>;
```

*Returns:* `Promise` that resolves with a record from each [`ClientCapability`](#types-clientcapability) to its [`CapabilityStatus`](#types-capabilitystatus).

```javascript
import { ClientCapability } from "@interopio/manager-api/desktop";

const caps = await io.manager.checkCapabilities();

if (caps[ClientCapability.API_METHOD_LAYOUTS_CHECK_CONFLICT].available) {
    // Run the pre-save conflict check.
}
```

## Layouts

Layout operations, available under `io.manager.layouts`.

### checkConflict()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Checks whether saving a Layout with the given identity would conflict with an existing Layout. Use this method before submitting a save (e.g., from a Save or Share Workspace flow) to prompt the user when the chosen name is already taken, instead of catching a failure from the server after the fact. Requires **io.Manager** 4.0 or later.

*Signature:*

```typescript
checkConflict(
    request: CheckLayoutConflictRequest
): Promise<CheckLayoutConflictResult>;
```

*Parameters:*

| Parameter | Type | Description |
|-----------|------|-------------|
| `request` | `object` | [`CheckLayoutConflictRequest`](#types-checklayoutconflictrequest) object describing the Layout identity to check. |

*Returns:* `Promise` that resolves with a [`CheckLayoutConflictResult`](#types-checklayoutconflictresult) object. The result is a discriminated union - narrow on its `kind` field to read the matching `conflict`:

```javascript
const result = await io.manager.layouts.checkConflict({
    type: "Workspace",
    name: "my-workspace",
    accessLevel: "private"
});

if (result.kind === "advanced" && result.conflict) {
    // Prompt the user before overwriting `result.conflict`.
} else if (result.kind === "legacy" && result.conflict) {
    // Prompt the user before overwriting `result.conflict`.
} else {
    // No conflict - the Layout can be saved cleanly.
}
```

## Users

User queries, available under `io.manager.users`.

### query()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Looks up users known to **io.Manager** by name. Results are de-duplicated and sorted alphabetically. Requires **io.Manager** 4.0 or later.

*Signature:*

```typescript
query(args: QueryByNameRequest): Promise<QueryUsersResponse>;
```

*Parameters:*

| Parameter | Type | Description |
|-----------|------|-------------|
| `args` | `object` | [`QueryByNameRequest`](#types-querybynamerequest) object describing the search term and an optional result cap. |

*Returns:* `Promise` that resolves with a [`QueryUsersResponse`](#types-queryusersresponse) object.

## Groups

Group queries, available under `io.manager.groups`.

### query()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Looks up groups known to **io.Manager** by name. Both the groups **io.Manager** has on record and the groups declared in the `auth_extra_groups` server configuration property are matched; the built-in permission groups are never returned. Results are de-duplicated and sorted alphabetically. Requires **io.Manager** 4.0 or later.

*Signature:*

```typescript
query(args: QueryByNameRequest): Promise<QueryGroupsResponse>;
```

*Parameters:*

| Parameter | Type | Description |
|-----------|------|-------------|
| `args` | `object` | [`QueryByNameRequest`](#types-querybynamerequest) object describing the search term and an optional result cap. |

*Returns:* `Promise` that resolves with a [`QueryGroupsResponse`](#types-querygroupsresponse) object.

## Configs

Config-file access, available under `io.manager.configs`.

Only the custom config files an administrator has added in **io.Manager** are available here. The config files the **io.Connect** platform itself consumes - `system.json`, `themes.json`, `stickywindows.json`, `channels.json`, `logger.json` and `browser-platform.json` - are not exposed to apps: naming one of them produces the same result as naming a config file that has never been set. The comparison is case-insensitive and covers the whole name, so `SYSTEM.JSON` is treated as a platform config file, while a custom config file named `system` (without the extension) is not.

### list()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Returns the names of the custom config files set in **io.Manager**.

*Signature:*

```typescript
list(): Promise<string[]>;
```

*Returns:* `Promise` that resolves with an array of the custom config file names set in **io.Manager**.

### get()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Returns the raw string contents of the named custom config file, or `undefined` if it isn't set.

*Signature:*

```typescript
get(name: string): Promise<string | undefined>;
```

*Parameters:*

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `string` | The name of the custom config file to read. |

*Returns:* `Promise` that resolves with the raw string contents of the named custom config file, or `undefined` if it isn't set. A platform config file name always resolves with `undefined`.

### onChange()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Subscribes to changes in the custom config files set in **io.Manager**. On subscribe, the callback fires once per currently-set file (filtered by `options.name` when set); thereafter it fires on every add, modify, or remove. A removal is signaled by `value: undefined`. A platform config file never raises an event, so naming one in `options.name` produces a subscription that never fires.

*Signature:*

```typescript
onChange(
    callback: (event: ConfigChangeEvent) => void,
    options?: OnConfigChangeOptions
): Promise<UnsubscribeFunction>;
```

*Parameters:*

| Parameter | Type | Description |
|-----------|------|-------------|
| `callback` | `function` | Callback function for handling the event. Accepts as an argument a [`ConfigChangeEvent`](#types-configchangeevent) object describing the change. |
| `options` | `object` | Optional [`OnConfigChangeOptions`](#types-onconfigchangeoptions) object. When omitted, the callback receives events for every custom config file. |

*Returns:* `Promise` that resolves with an `UnsubscribeFunction` that can be used to stop tracking the event.

```javascript
// Subscribing for changes to a specific config file.
const unsubscribe = await io.manager.configs.onChange(event => {
    if (event.value === undefined) {
        // The config file was removed.
    } else {
        // The config file was added or modified.
    }
}, { name: "my-config.json" });
```

## Types

### CapabilityStatus

Available since @interopio/manager-api 5.0.0

The usability of an `io.manager` member in the current session, returned by [`checkCapability()`](#methods-checkcapability).

| Property | Type | Description |
|----------|------|-------------|
| `available` | `boolean` | Whether the member is usable right now. |
| `reason` | [`CapabilityUnavailableReason`](#types-capabilityunavailablereason) | When `available` is `false`, why the member is unavailable. Populated only for method-level (`API_METHOD_*`) capabilities; platform-level capabilities report availability without a reason. |

### CapabilityUnavailableReason

Available since @interopio/manager-api 5.0.0

The reason an `io.manager` member is not usable. The same value the member carries on its thrown `Error`'s `code`, so a single mapping serves both [`checkCapability()`](#methods-checkcapability) and a `catch` block.

| Member | Value | Description |
|--------|-------|-------------|
| `METHOD_NOT_AVAILABLE` | `"METHOD_NOT_AVAILABLE"` | The hosting **io.Connect** platform does not provide the member. Permanent for that platform. |
| `SERVER_DISABLED` | `"SERVER_DISABLED"` | The member is provided, but **io.Manager** is disabled. Recoverable by enabling **io.Manager**. |
| `SERVER_INCOMPATIBLE` | `"SERVER_INCOMPATIBLE"` | The member is provided and io.Manager is enabled, but the connected **io.Manager** Server is too old to support it. Resolved by upgrading the server. |

### CheckLayoutConflictRequest

Available since @interopio/manager-api 5.0.0

Describes the Layout identity to check. Passed as an argument to the [`layouts.checkConflict()`](#layouts-checkconflict) method.

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Optional ID of an existing Layout being updated. When provided, that Layout is excluded from the conflict check, so renaming a Layout to its own current name does not count as a conflict. |
| `type` | `string` | The Layout type. |
| `name` | `string` | The Layout name. |
| `accessLevel` | `"private" \| "shared" \| "public"` | Optional access level. Defaults to `"private"` when omitted. Always treated as `"private"` when using legacy Layouts. |

### CheckLayoutConflictResult

Available since @interopio/manager-api 5.0.0

Describes the result returned by [`layouts.checkConflict()`](#layouts-checkconflict). The result is a discriminated union - the `kind` field selects the Layout flavor the check was resolved against and the shape of the matching `conflict`. Narrow on `kind` to read the conflicting Layout safely.

| Property | Type | Description |
|----------|------|-------------|
| `kind` | `"advanced" \| "legacy"` | Selects the Layout flavor the check was resolved against. |
| `conflict` | `UserAdvancedLayoutDefinition \| UserLayoutDefinitionV2` | The existing conflicting Layout when a collision was detected, or absent when the Layout can be saved cleanly. The shape is `UserAdvancedLayoutDefinition` when `kind` is `"advanced"` and `UserLayoutDefinitionV2` when `kind` is `"legacy"`. |

### ClientCapability

Available since @interopio/manager-api 5.0.0

Enumerates the client-side capabilities recognized by [`checkCapability()`](#methods-checkcapability). Exported from the `@interopio/manager-api/desktop` and `@interopio/manager-api/browser` subpath entry points. Unrecognized identifiers passed at runtime resolve with `{ available: false }`.

Each `API_METHOD_*` member corresponds to a method on the `io.manager` object. An `available: true` status from [`checkCapability()`](#methods-checkcapability) for one of these members means the corresponding `io.manager.*` method is usable in the current session - the host **io.Connect** platform provides it, **io.Manager** is enabled, and the connected **io.Manager** Server supports it.

| Member | Value | Description |
|--------|-------|-------------|
| `ADVANCED_LAYOUTS` | `"ADVANCED_LAYOUTS"` | Advertised when the **io.Connect** platform supports advanced Layouts. *Requires **io.Connect Desktop** 10.5 (unreleased).* |
| `API_METHOD_GET_CONNECTION_STATE` | `"API_METHOD_GET_CONNECTION_STATE"` | Advertised when [`io.manager.getConnectionState()`](#methods-getconnectionstate) is usable in the current session. |
| `API_METHOD_FETCH_DATA` | `"API_METHOD_FETCH_DATA"` | Advertised when [`io.manager.fetchData()`](#methods-fetchdata) is usable in the current session. |
| `API_METHOD_ON_CONNECTION_STATE_CHANGE` | `"API_METHOD_ON_CONNECTION_STATE_CHANGE"` | Advertised when [`io.manager.onConnectionStateChange()`](#methods-onconnectionstatechange) is usable in the current session. |
| `API_METHOD_LAYOUTS_CHECK_CONFLICT` | `"API_METHOD_LAYOUTS_CHECK_CONFLICT"` | Advertised when [`io.manager.layouts.checkConflict()`](#layouts-checkconflict) is usable in the current session. |
| `API_METHOD_USERS_QUERY` | `"API_METHOD_USERS_QUERY"` | Advertised when [`io.manager.users.query()`](#users-query) is usable in the current session. |
| `API_METHOD_GROUPS_QUERY` | `"API_METHOD_GROUPS_QUERY"` | Advertised when [`io.manager.groups.query()`](#groups-query) is usable in the current session. |
| `API_METHOD_CONFIGS_LIST` | `"API_METHOD_CONFIGS_LIST"` | Advertised when [`io.manager.configs.list()`](#configs-list) is usable in the current session. |
| `API_METHOD_CONFIGS_GET` | `"API_METHOD_CONFIGS_GET"` | Advertised when [`io.manager.configs.get()`](#configs-get) is usable in the current session. |
| `API_METHOD_CONFIGS_ON_CHANGE` | `"API_METHOD_CONFIGS_ON_CHANGE"` | Advertised when [`io.manager.configs.onChange()`](#configs-onchange) is usable in the current session. |

### ConfigChangeEvent

Available since @interopio/manager-api 5.0.0

Describes a per-entry change notification emitted by [`configs.onChange()`](#configs-onchange).

| Property | Type | Description |
|----------|------|-------------|
| `name` | `string` | The name of the config file. |
| `value` | `string \| undefined` | The raw string contents of the config file after the change, or `undefined` if it was removed. |

### FetchDataArgs

Arguments accepted by [`fetchData()`](#methods-fetchdata). Each property is an opt-in toggle for refreshing the corresponding category of **io.Manager** data.

| Property | Type | Description |
|----------|------|-------------|
| `applications` | `boolean` | When `true`, refreshes the set of apps available to this user. |
| `layouts` | `boolean` | When `true`, refreshes the set of Layouts available to this user. |
| `commands` | `boolean` | When `true`, refreshes the set of commands available to this user. |
| `configs` | `boolean` | When `true`, refreshes the set of config entries available to this user. |
| `preferences` | `boolean` | When `true`, refreshes the set of preferences available to this user. |

### IOManagerConnectionState

Describes the current connection state of the **io.Manager** client.

| Property | Type | Description |
|----------|------|-------------|
| `baseUrl` | `string` | The base URL of the **io.Manager** Server. |
| `cacheEnabled` | `boolean` | If `true`, client-side caching is enabled. |
| `disconnectionError` | `Error` | The error that caused the disconnection. Present only when the client was disconnected by one. |
| `isConnected` | `boolean` | If `true`, the client is currently connected to the **io.Manager** Server. |
| `serverEnabled` | `boolean` | If `true`, the **io.Manager** Server is enabled in the **io.Connect** platform. |

### OnConfigChangeOptions

Available since @interopio/manager-api 5.0.0

Options object accepted by [`configs.onChange()`](#configs-onchange).

| Property | Type | Description |
|----------|------|-------------|
| `name` | `string` | Optional. When set, the subscription only fires for changes to the named custom config file (and the initial subscribe event is filtered to that file). When omitted, the callback receives events for every custom config file. |

### QueriedGroup

Available since @interopio/manager-api 5.0.0

Describes a group entry returned by [`groups.query()`](#groups-query).

| Property | Type | Description |
|----------|------|-------------|
| `name` | `string` | The group name. |

### QueriedUser

Available since @interopio/manager-api 5.0.0

Describes a user entry returned by [`users.query()`](#users-query).

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | The user ID. |

### QueryByNameRequest

Available since @interopio/manager-api 5.0.0

Describes the arguments passed to [`users.query()`](#users-query) and [`groups.query()`](#groups-query).

| Property | Type | Description |
|----------|------|-------------|
| `name` | `string` | The name to look up. Matching is case-insensitive and partial. A name shorter than three characters returns no results. |
| `limit` | `number` | Optional maximum number of items to return. When omitted, all matches are returned. |

### QueryGroupsResponse

Available since @interopio/manager-api 5.0.0

Describes the result returned by [`groups.query()`](#groups-query).

| Property | Type | Description |
|----------|------|-------------|
| `groups` | `QueriedGroup[]` | The matching groups, de-duplicated and sorted alphabetically by name. See [`QueriedGroup`](#types-queriedgroup). |

### QueryUsersResponse

Available since @interopio/manager-api 5.0.0

Describes the result returned by [`users.query()`](#users-query).

| Property | Type | Description |
|----------|------|-------------|
| `users` | `QueriedUser[]` | The matching users, de-duplicated and sorted alphabetically by ID. See [`QueriedUser`](#types-querieduser). |

### UserAdvancedLayoutDefinition

Available since @interopio/manager-api 5.0.0

Describes an advanced Layout owned by or accessible to the calling user. Returned as the `conflict` value of a [`CheckLayoutConflictResult`](#types-checklayoutconflictresult) when `kind` is `"advanced"`. The full type definition is exported from the [`@interopio/manager-api`](https://www.npmjs.com/package/@interopio/manager-api) library.

### UserLayoutDefinitionV2

Available since @interopio/manager-api 5.0.0

Describes a legacy Layout owned by or accessible to the calling user. Returned as the `conflict` value of a [`CheckLayoutConflictResult`](#types-checklayoutconflictresult) when `kind` is `"legacy"`. The full type definition is exported from the [`@interopio/manager-api`](https://www.npmjs.com/package/@interopio/manager-api) library.