> ## Documentation Index
> Fetch the complete documentation index at: https://botmesh.afaya.com.co/llms.txt
> Use this file to discover all available pages before exploring further.

# ChaosProvider<P>

> Class exported by @botmesh/core/testing.

Defined in: [testing/chaos.ts:445](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L445)

An `IProvider` that wraps another one and delivers its traffic adversarially
(see the module docs and [ChaosOptions](https://botmesh.afaya.com.co/api/core/testing/interfaces/ChaosOptions.md)). Pass it to `new Bot({ provider })`
and keep driving the wrapped provider (`chaos.inner.incoming(...)`).

Optional provider capabilities (`typing`, `markRead`, `downloadMedia`, …)
are exposed only when the wrapped provider has them, so feature detection
in the Bot keeps working.

## Type Parameters

| Type Parameter | Default type |
| - | - |
|  `P` *extends* [`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider) | [`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider) |

## Implements

* [`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider)

## Constructors

### Constructor

```ts theme={null}
new ChaosProvider<P>(inner, options?): ChaosProvider<P>;
```

Defined in: [testing/chaos.ts:493](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L493)

#### Parameters

| Parameter | Type |
| - | - |
| `inner` | `P` |
| `options?` | [`ChaosOptions`](https://botmesh.afaya.com.co/api/core/testing/interfaces/ChaosOptions) |

#### Returns

`ChaosProvider`\<`P`>

#### Throws

when an option is out of range.

## Properties

### inner

```ts theme={null}
readonly inner: P;
```

Defined in: [testing/chaos.ts:447](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L447)

The wrapped provider (drive it to simulate inbound traffic).

***

### id

```ts theme={null}
readonly id: string;
```

Defined in: [testing/chaos.ts:449](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L449)

Same id as the wrapped provider (store namespaces stay unchanged).

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`id`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#id)

***

### capabilities

```ts theme={null}
readonly capabilities: ProviderCapabilities;
```

Defined in: [testing/chaos.ts:451](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L451)

Same capabilities object as the wrapped provider.

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`capabilities`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#capabilities)

***

### seed

```ts theme={null}
readonly seed: number;
```

Defined in: [testing/chaos.ts:453](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L453)

Seed in use.

***

### log

```ts theme={null}
readonly log: ChaosLogEntry[] = [];
```

Defined in: [testing/chaos.ts:455](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L455)

Everything the kit injected, in order.

***

### delivered

```ts theme={null}
readonly delivered: InboundEvent[] = [];
```

Defined in: [testing/chaos.ts:457](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L457)

Every inbound event actually delivered to listeners (copies and replays included), in delivery order.

***

### ingest?

```ts theme={null}
ingest?: (rawEvent, headers?) => unknown;
```

Defined in: [testing/chaos.ts:459](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L459)

Push ingress for webhook transports (Cloud API POST, Telegram/Discord
webhook, Discord interaction endpoint). The host HTTP server calls this with
the raw body (and, optionally, the request headers for signature checks); the
provider normalizes and emits via onEvent. May return a value the host can
use as the HTTP status (e.g. 200 accepted / 403 bad signature). Socket-first
providers (Baileys, Discord gateway) omit it.

#### Parameters

| Parameter | Type |
| - | - |
| `rawEvent` | `unknown` |
| `headers?` | `Record`\<`string`, `string` \| `string`\[] \| `undefined`> |

#### Returns

`unknown`

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`ingest`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#ingest)

***

### downloadMedia?

```ts theme={null}
downloadMedia?: (ref) => Promise<Buffer<ArrayBufferLike> | ReadableStream>;
```

Defined in: [testing/chaos.ts:460](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L460)

Lazy media retrieval behind one signature for every download model.

#### Parameters

| Parameter | Type |
| - | - |
| `ref` | [`MediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/MediaRef) |

#### Returns

`Promise`\<`Buffer`\<`ArrayBufferLike`> | `ReadableStream`>

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`downloadMedia`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#downloadmedia)

***

### serializeMediaRef?

```ts theme={null}
serializeMediaRef?: (ref) => 
  | SerializedMediaRef
  | undefined;
```

Defined in: [testing/chaos.ts:461](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L461)

Durable journaling (`BotConfig.durability`): turn a live `MediaRef` into a JSON-safe,
versioned reference that [rehydrateMediaRef](https://botmesh.afaya.com.co/api/core/interfaces/IProvider.md#rehydratemediaref) can rebuild in another process, so a
replayed message (crash recovery, background retry) can still download its media.
Synchronous, cheap and side-effect free; a throw counts as "not durable". Return
`undefined` for a ref that must not be journaled (e.g. view-once media). Never include
credentials: the result is stored at rest with the inbound record.

#### Parameters

| Parameter | Type |
| - | - |
| `ref` | [`MediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/MediaRef) |

#### Returns

\| [`SerializedMediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/SerializedMediaRef)
\| `undefined`

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`serializeMediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#serializemediaref)

***

### rehydrateMediaRef?

```ts theme={null}
rehydrateMediaRef?: (stored, ref) => 
  | MediaRef
| Promise<MediaRef>;
```

Defined in: [testing/chaos.ts:462](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L462)

Rebuild the `MediaRef` of a replayed message from what [serializeMediaRef](https://botmesh.afaya.com.co/api/core/interfaces/IProvider.md#serializemediaref) wrote.
`ref` is the journaled ref without its token. Pure decoding: it must not need the
transport to be connected. `stored` comes from storage and is UNTRUSTED: reject an
invalid, unknown-version or tampered value with a `ProviderError`.

#### Parameters

| Parameter | Type |
| - | - |
| `stored` | [`SerializedMediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/SerializedMediaRef) |
| `ref` | `Omit`\<[`MediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/MediaRef), `"token"`> |

#### Returns

\| [`MediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/MediaRef)
\| `Promise`\<[`MediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/MediaRef)>

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`rehydrateMediaRef`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#rehydratemediaref)

***

### getMessage?

```ts theme={null}
getMessage?: (ref) => Promise<
  | InboundMessage<unknown>
| undefined>;
```

Defined in: [testing/chaos.ts:463](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L463)

Read-back seam for poll aggregation, quote-body resolution, retry decrypt.
Providers that don't need it no-op / omit it. Replaces the constructor-
injected `getMessage` callback baked into BaileysProvider today.

#### Parameters

| Parameter | Type |
| - | - |
| `ref` | [`MessageRef`](https://botmesh.afaya.com.co/api/core/interfaces/MessageRef) |

#### Returns

`Promise`\<
\| [`InboundMessage`](https://botmesh.afaya.com.co/api/core/interfaces/InboundMessage)\<`unknown`>
\| `undefined`>

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`getMessage`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#getmessage)

***

### markRead?

```ts theme={null}
markRead?: (refs) => Promise<void>;
```

Defined in: [testing/chaos.ts:464](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L464)

#### Parameters

| Parameter | Type |
| - | - |
| `refs` | [`MessageRef`](https://botmesh.afaya.com.co/api/core/interfaces/MessageRef)\[] |

#### Returns

`Promise`\<`void`>

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`markRead`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#markread)

***

### typing?

```ts theme={null}
typing?: (chatId, state?) => Promise<void>;
```

Defined in: [testing/chaos.ts:465](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L465)

#### Parameters

| Parameter | Type |
| - | - |
| `chatId` | `string` |
| `state?` | `"typing"` \| `"paused"` \| `"recording"` |

#### Returns

`Promise`\<`void`>

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`typing`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#typing)

***

### deleteMessage?

```ts theme={null}
deleteMessage?: (ref) => Promise<void>;
```

Defined in: [testing/chaos.ts:466](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L466)

#### Parameters

| Parameter | Type |
| - | - |
| `ref` | [`MessageRef`](https://botmesh.afaya.com.co/api/core/interfaces/MessageRef) |

#### Returns

`Promise`\<`void`>

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`deleteMessage`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#deletemessage)

***

### editMessage?

```ts theme={null}
editMessage?: (ref, content) => Promise<SendResult<unknown>>;
```

Defined in: [testing/chaos.ts:467](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L467)

#### Parameters

| Parameter | Type |
| - | - |
| `ref` | [`MessageRef`](https://botmesh.afaya.com.co/api/core/interfaces/MessageRef) |
| `content` | [`OutboundContent`](https://botmesh.afaya.com.co/api/core/type-aliases/OutboundContent) |

#### Returns

`Promise`\<[`SendResult`](https://botmesh.afaya.com.co/api/core/interfaces/SendResult)\<`unknown`>>

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`editMessage`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#editmessage)

***

### sendDraft?

```ts theme={null}
sendDraft?: (chatId, draftId, text, opts?) => Promise<void>;
```

Defined in: [testing/chaos.ts:468](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L468)

Show (or update) an ephemeral, not-yet-sent preview of a message being
generated. Same `draftId` → the same draft is updated in place. A draft is
NOT a message: the caller must still `send()` the final text. Only for
providers with `capabilities.streaming === 'draft'`; rejects (typed error)
where the transport refuses drafts (e.g. Telegram groups), and the caller
then falls back to edits or chunks.

#### Parameters

| Parameter | Type |
| - | - |
| `chatId` | `string` |
| `draftId` | `number` |
| `text` | `string` |
| `opts?` | [`DraftOptions`](https://botmesh.afaya.com.co/api/core/interfaces/DraftOptions) |

#### Returns

`Promise`\<`void`>

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`sendDraft`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#senddraft)

***

### acknowledgeInteraction?

```ts theme={null}
acknowledgeInteraction?: (interactionId, opts?) => Promise<void>;
```

Defined in: [testing/chaos.ts:469](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L469)

#### Parameters

| Parameter | Type |
| - | - |
| `interactionId` | `string` |
| `opts?` | \{ `text?`: `string`; `defer?`: `boolean`; } |
| `opts.text?` | `string` |
| `opts.defer?` | `boolean` |

#### Returns

`Promise`\<`void`>

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`acknowledgeInteraction`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#acknowledgeinteraction)

***

### canRenderForm?

```ts theme={null}
canRenderForm?: (form, opts?) => boolean;
```

Defined in: [testing/chaos.ts:470](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L470)

Whether a `form` OutboundContent for `form` (and `opts.nativeId`) can be
rendered natively right now, e.g. whether a WhatsApp Flow is mapped to it.
Only consulted when `capabilities.forms === 'native'`; when it returns
`false`, an auto-mode `flow().form()` asks field by field without sending
(and failing) a form message first. Absent = every form is renderable.

#### Parameters

| Parameter | Type |
| - | - |
| `form` | [`FormDefinition`](https://botmesh.afaya.com.co/api/core/interfaces/FormDefinition) |
| `opts?` | \{ `nativeId?`: `string`; } |
| `opts.nativeId?` | `string` |

#### Returns

`boolean`

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`canRenderForm`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#canrenderform)

***

### textFormatFor?

```ts theme={null}
textFormatFor?: (chatId) => TextFormat | undefined;
```

Defined in: [testing/chaos.ts:471](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L471)

Rich-text dialect of one chat, for providers that serve several channels
with different markup through one instance (e.g. Twilio: `whatsapp:` chats
render WhatsApp markup, SMS chats render none). Return `undefined` when the
chat's format is unknown; the core then falls back to
`capabilities.textFormat`. Exposed as `ctx.textFormat`. Must be synchronous
and cheap (it runs once per inbound message). Absent = every chat uses
`capabilities.textFormat`.

#### Parameters

| Parameter | Type |
| - | - |
| `chatId` | `string` |

#### Returns

[`TextFormat`](https://botmesh.afaya.com.co/api/core/type-aliases/TextFormat) | `undefined`

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`textFormatFor`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#textformatfor)

## Methods

### start()

```ts theme={null}
start(): Promise<void>;
```

Defined in: [testing/chaos.ts:534](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L534)

#### Returns

`Promise`\<`void`>

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`start`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#start)

***

### stop()

```ts theme={null}
stop(): Promise<void>;
```

Defined in: [testing/chaos.ts:537](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L537)

Cancels every pending delivery, buffered or held event, then stops the wrapped provider.

#### Returns

`Promise`\<`void`>

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`stop`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#stop)

***

### onEvent()

```ts theme={null}
onEvent(listener): () => void;
```

Defined in: [testing/chaos.ts:547](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L547)

Subscribe to the normalized event stream. Returns an unsubscriber.

#### Parameters

| Parameter | Type |
| - | - |
| `listener` | [`InboundListener`](https://botmesh.afaya.com.co/api/core/type-aliases/InboundListener) |

#### Returns

() => `void`

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`onEvent`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#onevent)

***

### send()

```ts theme={null}
send(
   chatId, 
   content, 
   options?
): Promise<SendResult<unknown>>;
```

Defined in: [testing/chaos.ts:558](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L558)

Send through the wrapped provider unless chaos decides this attempt fails
(scripted `attempts`, `probability`, or the connection is down), in which
case it rejects with a typed `ProviderError` and nothing reaches the
wrapped provider's outbox.

#### Parameters

| Parameter | Type |
| - | - |
| `chatId` | `string` |
| `content` | [`OutboundContent`](https://botmesh.afaya.com.co/api/core/type-aliases/OutboundContent) |
| `options?` | [`SendOptions`](https://botmesh.afaya.com.co/api/core/interfaces/SendOptions) |

#### Returns

`Promise`\<[`SendResult`](https://botmesh.afaya.com.co/api/core/interfaces/SendResult)\<`unknown`>>

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`send`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#send)

***

### disconnect()

```ts theme={null}
disconnect(options?): void;
```

Defined in: [testing/chaos.ts:577](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L577)

Simulate a connection drop: emits `{ state: 'closed', reason }`, then holds
inbound and fails sends (per options) until [reconnect](#reconnect). A finite
`downtimeMs` schedules the reconnect automatically; the default for a
manual drop is to stay down until `reconnect()` is called.

#### Parameters

| Parameter | Type |
| - | - |
| `options?` | \{ `reason?`: [`DisconnectReason`](https://botmesh.afaya.com.co/api/core/type-aliases/DisconnectReason); `downtimeMs?`: `number`; `retryAfterMs?`: `number`; } |
| `options.reason?` | [`DisconnectReason`](https://botmesh.afaya.com.co/api/core/type-aliases/DisconnectReason) |
| `options.downtimeMs?` | `number` |
| `options.retryAfterMs?` | `number` |

#### Returns

`void`

***

### reconnect()

```ts theme={null}
reconnect(): void;
```

Defined in: [testing/chaos.ts:602](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L602)

End a simulated drop: emits `connecting` then `ready`, redelivers the last
`replayOnReconnect` events (offline-sync duplicates), then delivers what
was held while down, in arrival order.

#### Returns

`void`

***

### replay()

```ts theme={null}
replay(count?): void;
```

Defined in: [testing/chaos.ts:621](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L621)

Redeliver (fresh copies of) the last `count` delivered inbound events — an explicit webhook retry.

#### Parameters

| Parameter | Type | Default value |
| - | - | - |
| `count?` | `number` | `1` |

#### Returns

`void`

***

### flush()

```ts theme={null}
flush(): void;
```

Defined in: [testing/chaos.ts:630](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L630)

Deliver whatever sits in the reorder window right now (permuted as configured).

#### Returns

`void`

***

### settle()

```ts theme={null}
settle(timeoutMs?): Promise<void>;
```

Defined in: [testing/chaos.ts:648](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L648)

Wait (real timers) until no chaos delivery, reorder flush, scheduled
reconnect or delayed send is pending, plus one macrotask so listeners can
dispatch. Events held by an indefinite drop do not count as pending.

#### Parameters

| Parameter | Type | Default value |
| - | - | - |
| `timeoutMs?` | `number` | `5000` |

#### Returns

`Promise`\<`void`>

#### Throws

if still busy after `timeoutMs` (default 5000).

## Accessors

### selfId

#### Get Signature

```ts theme={null}
get selfId(): string | null;
```

Defined in: [testing/chaos.ts:524](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L524)

The wrapped provider's self id (`null` when it has none: never `undefined`, see `IProvider.selfId`).

##### Returns

`string` | `null`

The bot's own user id once connected (for group mention matching). Optional.

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`selfId`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#selfid)

***

### connection

#### Get Signature

```ts theme={null}
get connection(): unknown;
```

Defined in: [testing/chaos.ts:526](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L526)

The wrapped provider's debug connection handle.

##### Returns

`unknown`

A single primary connection handle for DEBUGGING ONLY. Not a structural
guarantee of exactly one connection (Discord may hold many shard sockets).
Core must NOT reach through this for behavior.

#### Implementation of

[`IProvider`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider).[`connection`](https://botmesh.afaya.com.co/api/core/interfaces/IProvider#connection)

***

### connected

#### Get Signature

```ts theme={null}
get connected(): boolean;
```

Defined in: [testing/chaos.ts:528](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L528)

`false` while a simulated drop is in effect.

##### Returns

`boolean`

***

### sendAttempts

#### Get Signature

```ts theme={null}
get sendAttempts(): number;
```

Defined in: [testing/chaos.ts:530](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L530)

Number of `send()` calls so far (failed ones included).

##### Returns

`number`

***

### pending

#### Get Signature

```ts theme={null}
get pending(): number;
```

Defined in: [testing/chaos.ts:532](https://github.com/andresayac/botmesh/blob/main/packages/core/src/testing/chaos.ts#L532)

Scheduled deliveries, reorder/reconnect timers and delayed sends still outstanding.

##### Returns

`number`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.