> ## 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.

# KvInbox

> Class exported by @botmesh/core/spi.

Defined in: [durability/journal.ts:88](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L88)

[InboxJournal](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal.md) over a [DurableKv](https://botmesh.afaya.com.co/api/core/interfaces/DurableKv.md).

## Implements

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

## Constructors

### Constructor

```ts theme={null}
new KvInbox(kv, table?): KvInbox;
```

Defined in: [durability/journal.ts:90](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L90)

#### Parameters

| Parameter | Type | Default value | Description |
| - | - | - | - |
| `kv` | [`DurableKv`](https://botmesh.afaya.com.co/api/core/interfaces/DurableKv) | `undefined` | - |
| `table?` | `string` | `'inbox'` | The KV table (`'inbox'`, or `'inbox:<scope>'` for a scoped view). |

#### Returns

`KvInbox`

## Methods

### append()

```ts theme={null}
append(
   input, 
   now, 
   lease?
): Promise<{
  status: "appended" | "duplicate";
  record: InboxRecord;
}>;
```

Defined in: [durability/journal.ts:96](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L96)

Insert-if-absent by `id`. `'duplicate'` means the id is already known (any state);
the existing record is returned unchanged. With `lease`, a new record is created
already claimed (`processing`, token 1, 1 attempt), so no other claimer can take it
between the append and the claim.

#### Parameters

| Parameter | Type |
| - | - |
| `input` | [`InboxAppend`](https://botmesh.afaya.com.co/api/core/spi/type-aliases/InboxAppend) |
| `now` | `number` |
| `lease?` | [`LeaseOptions`](https://botmesh.afaya.com.co/api/core/spi/interfaces/LeaseOptions) |

#### Returns

`Promise`\<\{
`status`: `"appended"` | `"duplicate"`;
`record`: [`InboxRecord`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxRecord);
}>

#### Implementation of

[`InboxJournal`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal).[`append`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal#append)

***

### claim()

```ts theme={null}
claim(o): Promise<InboxRecord[]>;
```

Defined in: [durability/journal.ts:115](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L115)

Lease due records: `pending`/`failed` whose `nextAttemptAt <= now`, plus `processing`
records whose lease expired. Oldest `receivedAt` first. Each claimed record comes back
`processing` with a fresh `fencingToken` and `attempts + 1`.

#### Parameters

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

#### Returns

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

#### Implementation of

[`InboxJournal`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal).[`claim`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal#claim)

***

### claimOne()

```ts theme={null}
claimOne(id, o): Promise<InboxRecord | null>;
```

Defined in: [durability/journal.ts:138](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L138)

Lease one specific record when it is claimable (as [claim](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal.md#claim)); `null` when it is not.

#### Parameters

| Parameter | Type |
| - | - |
| `id` | `string` |
| `o` | [`LeaseOptions`](https://botmesh.afaya.com.co/api/core/spi/interfaces/LeaseOptions) |

#### Returns

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

#### Implementation of

[`InboxJournal`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal).[`claimOne`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal#claimone)

***

### ack()

```ts theme={null}
ack(
   id, 
   token, 
   now
): Promise<void>;
```

Defined in: [durability/journal.ts:154](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L154)

`processing` → `done`.

#### Parameters

| Parameter | Type |
| - | - |
| `id` | `string` |
| `token` | `number` |
| `now` | `number` |

#### Returns

`Promise`\<`void`>

#### Throws

when `token` is not the current claim.

#### Implementation of

[`InboxJournal`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal).[`ack`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal#ack)

***

### fail()

```ts theme={null}
fail(
   id, 
   token, 
   error, 
   o
): Promise<void>;
```

Defined in: [durability/journal.ts:158](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L158)

`processing` → `failed` (due at `retryAt`, default now) or `dead` (`dead: true`).

#### Parameters

| Parameter | Type |
| - | - |
| `id` | `string` |
| `token` | `number` |
| `error` | `string` |
| `o` | \{ `now`: `number`; `retryAt?`: `number`; `dead?`: `boolean`; } |
| `o.now` | `number` |
| `o.retryAt?` | `number` |
| `o.dead?` | `boolean` |

#### Returns

`Promise`\<`void`>

#### Throws

#### Implementation of

[`InboxJournal`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal).[`fail`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal#fail)

***

### release()

```ts theme={null}
release(
   id, 
   token, 
   now
): Promise<void>;
```

Defined in: [durability/journal.ts:164](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L164)

`processing` → `pending`, due now; the claim's attempt is not charged.

#### Parameters

| Parameter | Type |
| - | - |
| `id` | `string` |
| `token` | `number` |
| `now` | `number` |

#### Returns

`Promise`\<`void`>

#### Throws

#### Implementation of

[`InboxJournal`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal).[`release`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal#release)

***

### extend()

```ts theme={null}
extend(
   id, 
   token, 
   leaseUntil
): Promise<void>;
```

Defined in: [durability/journal.ts:168](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L168)

Extend the current lease (heartbeat).

#### Parameters

| Parameter | Type |
| - | - |
| `id` | `string` |
| `token` | `number` |
| `leaseUntil` | `number` |

#### Returns

`Promise`\<`void`>

#### Throws

#### Implementation of

[`InboxJournal`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal).[`extend`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal#extend)

***

### replay()

```ts theme={null}
replay(id, now): Promise<void>;
```

Defined in: [durability/journal.ts:172](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L172)

Operator replay: any record → `pending`, due now, attempts reset. No-op for an unknown id.

#### Parameters

| Parameter | Type |
| - | - |
| `id` | `string` |
| `now` | `number` |

#### Returns

`Promise`\<`void`>

#### Implementation of

[`InboxJournal`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal).[`replay`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal#replay)

***

### get()

```ts theme={null}
get(id): Promise<InboxRecord | undefined>;
```

Defined in: [durability/journal.ts:178](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L178)

#### Parameters

| Parameter | Type |
| - | - |
| `id` | `string` |

#### Returns

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

#### Implementation of

[`InboxJournal`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal).[`get`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal#get)

***

### list()

```ts theme={null}
list(filter?): Promise<InboxRecord[]>;
```

Defined in: [durability/journal.ts:183](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L183)

Records, optionally by state, oldest `receivedAt` first.

#### Parameters

| Parameter | Type |
| - | - |
| `filter?` | \{ `state?`: [`InboxState`](https://botmesh.afaya.com.co/api/core/spi/type-aliases/InboxState); `limit?`: `number`; } |
| `filter.state?` | [`InboxState`](https://botmesh.afaya.com.co/api/core/spi/type-aliases/InboxState) |
| `filter.limit?` | `number` |

#### Returns

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

#### Implementation of

[`InboxJournal`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal).[`list`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal#list)

***

### purge()

```ts theme={null}
purge(o): Promise<number>;
```

Defined in: [durability/journal.ts:189](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/journal.ts#L189)

Delete `done` records completed before `doneBefore` (and `dead` ones when `includeDead`). Returns the count.

#### Parameters

| Parameter | Type |
| - | - |
| `o` | \{ `doneBefore`: `number`; `includeDead?`: `boolean`; } |
| `o.doneBefore` | `number` |
| `o.includeDead?` | `boolean` |

#### Returns

`Promise`\<`number`>

#### Implementation of

[`InboxJournal`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal).[`purge`](https://botmesh.afaya.com.co/api/core/spi/interfaces/InboxJournal#purge)


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