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

# OutboxJournal

> Interface exported by @botmesh/core/spi.

Defined in: [durability/types.ts:271](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L271)

Persistence contract of the outbound journal.

## Methods

### put()

```ts theme={null}
put(
   record, 
   now, 
   lease?
): Promise<{
  status: "created" | "exists";
  record: OutboxRecord;
}>;
```

Defined in: [durability/types.ts:276](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L276)

Insert-if-absent by `key`; on conflict the existing record is returned unchanged (`'exists'`).
With `lease`, a new record is created already begun (`sending`, token 1, 1 attempt).

#### Parameters

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

#### Returns

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

***

### begin()

```ts theme={null}
begin(key, options): Promise<OutboxRecord | null>;
```

Defined in: [durability/types.ts:281](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L281)

`pending`/`failed` (due or not) → `sending` under a fresh token: the persisted
"about to call the provider" marker. `null` when the record is missing or in another state.

#### Parameters

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

#### Returns

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

***

### markSent()

```ts theme={null}
markSent(
   key, 
   token, 
   result, 
   now
): Promise<void>;
```

Defined in: [durability/types.ts:283](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L283)

`sending` → `sent` with the provider ref.

#### Parameters

| Parameter | Type |
| - | - |
| `key` | `string` |
| `token` | `number` |
| `result` | \{ `ref`: [`MessageRef`](https://botmesh.afaya.com.co/api/core/interfaces/MessageRef); } |
| `result.ref` | [`MessageRef`](https://botmesh.afaya.com.co/api/core/interfaces/MessageRef) |
| `now` | `number` |

#### Returns

`Promise`\<`void`>

#### Throws

***

### extend()

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

Defined in: [durability/types.ts:285](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L285)

Extend the lease of a `sending` record (heartbeat while the provider call runs).

#### Parameters

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

#### Returns

`Promise`\<`void`>

#### Throws

***

### markFailed()

```ts theme={null}
markFailed(
   key, 
   token, 
   error, 
   options
): Promise<void>;
```

Defined in: [durability/types.ts:291](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L291)

`sending` → `failed` (due at `retryAt`) or `dead`. With `refund`, the claim made no
provider call (a split part deferred behind an earlier one): the attempt it counted is
given back, so waiting never uses up the record's retries.

#### Parameters

| Parameter | Type |
| - | - |
| `key` | `string` |
| `token` | `number` |
| `error` | [`OutboxError`](https://botmesh.afaya.com.co/api/core/spi/interfaces/OutboxError) |
| `options` | \{ `now`: `number`; `retryAt?`: `number`; `dead?`: `boolean`; `refund?`: `boolean`; } |
| `options.now` | `number` |
| `options.retryAt?` | `number` |
| `options.dead?` | `boolean` |
| `options.refund?` | `boolean` |

#### Returns

`Promise`\<`void`>

#### Throws

***

### claimDue()

```ts theme={null}
claimDue(options): Promise<ClaimedSend[]>;
```

Defined in: [durability/types.ts:297](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L297)

Lease due `pending`/`failed` records and `sending` records whose lease expired
(returned with `ambiguous: true`), oldest `createdAt` first. Claimed records come back
`sending` under a fresh token.

#### Parameters

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

#### Returns

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

***

### resolveAmbiguous()

```ts theme={null}
resolveAmbiguous(
   key, 
   token, 
   to, 
   now
): Promise<void>;
```

Defined in: [durability/types.ts:299](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L299)

Settle an ambiguous claim: `'unknown'` (terminal) or `'pending'` (send again).

#### Parameters

| Parameter | Type |
| - | - |
| `key` | `string` |
| `token` | `number` |
| `to` | `"unknown"` \| `"pending"` |
| `now` | `number` |

#### Returns

`Promise`\<`void`>

#### Throws

***

### get()

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

Defined in: [durability/types.ts:300](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L300)

#### Parameters

| Parameter | Type |
| - | - |
| `key` | `string` |

#### Returns

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

***

### list()

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

Defined in: [durability/types.ts:302](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L302)

Records, optionally by state and chat, oldest `createdAt` first.

#### Parameters

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

#### Returns

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

***

### retry()

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

Defined in: [durability/types.ts:304](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L304)

Operator retry: `failed`/`dead`/`unknown` → `pending`, due now.

#### Parameters

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

#### Returns

`Promise`\<`void`>

***

### discard()

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

Defined in: [durability/types.ts:306](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L306)

Operator discard: delete the record (a later send with the same key goes out again).

#### Parameters

| Parameter | Type |
| - | - |
| `key` | `string` |

#### Returns

`Promise`\<`void`>

***

### purge()

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

Defined in: [durability/types.ts:308](https://github.com/andresayac/botmesh/blob/main/packages/core/src/durability/types.ts#L308)

Delete terminal records completed before `before`. Returns the count.

#### Parameters

| Parameter | Type |
| - | - |
| `options` | \{ `before`: `number`; } |
| `options.before` | `number` |

#### Returns

`Promise`\<`number`>


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