OutboxJournal

Interface exported by @botmesh/core/spi.

Defined in: durability/types.ts:271

Persistence contract of the outbound journal.

Methods

put()

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

Defined in: durability/types.ts:276

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
now	number
lease?	LeaseOptions

Returns

Promise<{ status: "created" | "exists"; record: OutboxRecord; }>

---

begin()

begin(key, options): Promise<OutboxRecord | null>;

Defined in: durability/types.ts:281

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

Returns

Promise<OutboxRecord | null>

---

markSent()

markSent(
   key, 
   token, 
   result, 
   now
): Promise<void>;

Defined in: durability/types.ts:283

sending → sent with the provider ref.

Parameters

Parameter	Type
key	string
token	number
result	{ ref: MessageRef; }
result.ref	MessageRef
now	number

Returns

Promise<void>

Throws

---

extend()

extend(
   key, 
   token, 
   leaseUntil
): Promise<void>;

Defined in: durability/types.ts:285

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()

markFailed(
   key, 
   token, 
   error, 
   options
): Promise<void>;

Defined in: durability/types.ts:291

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
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()

claimDue(options): Promise<ClaimedSend[]>;

Defined in: durability/types.ts:297

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

Returns

Promise<ClaimedSend[]>

---

resolveAmbiguous()

resolveAmbiguous(
   key, 
   token, 
   to, 
   now
): Promise<void>;

Defined in: durability/types.ts:299

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()

get(key): Promise<OutboxRecord | undefined>;

Defined in: durability/types.ts:300

Parameters

Parameter	Type
key	string

Returns

Promise<OutboxRecord | undefined>

---

list()

list(filter?): Promise<OutboxRecord[]>;

Defined in: durability/types.ts:302

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

Parameters

Parameter	Type
filter?	{ state?: OutboxState; chatId?: string; limit?: number; }
filter.state?	OutboxState
filter.chatId?	string
filter.limit?	number

Returns

Promise<OutboxRecord[]>

---

retry()

retry(key, now): Promise<void>;

Defined in: durability/types.ts:304

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

Parameters

Parameter	Type
key	string
now	number

Returns

Promise<void>

---

discard()

discard(key): Promise<void>;

Defined in: durability/types.ts:306

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

Parameters

Parameter	Type
key	string

Returns

Promise<void>

---

purge()

purge(options): Promise<number>;

Defined in: durability/types.ts:308

Delete terminal records completed before before. Returns the count.

Parameters

Parameter	Type
options	{ before: number; }
options.before	number

Returns

Promise<number>