Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { NotFoundException } from '@nestjs/common';
import { AsyncLocalStorage } from 'async_hooks';
import type { HookManager, HookEvent } from '../hooks';
import type { LidMappingStore } from '../../engine/identity/lid-mapping-store.service';
import type { IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';
import { parseWaId, toNeutralJid } from '../../engine/identity/wa-id';
import { ConversationMappingConflict } from '../../modules/integration/conversation-mapping.service';
import { createLogger, UNPRINTABLE } from '../../common/services/logger.service';
import { isPluginActiveForSession, resolvePluginConfig } from './plugin-activation';
import { effectiveNetAllow, isNetHostAllowed, performPluginFetch } from './plugin-net';
import { buildConversationSendFacade, type ConversationMediaType } from './conversation-send-facade';
import { PluginHostServices } from './plugin-host-services';
import type { PluginMessagePort } from './plugin-host-ports';
import { PluginStorageService } from './plugin-storage.service';
import {
PluginCapabilityError,
PluginCapabilityPermission,
type PluginContext,
type PluginConversationsCapability,
type PluginEngineReadCapability,
type PluginHandoverCapability,
type PluginInstance,
type PluginLogger,
type PluginManifest,
type PluginMappingsCapability,
type PluginMessagingCapability,
type PluginNetCapability,
type PluginStorage,
} from './plugin.interfaces';
/**
* Translate a normalized conversation media send into the concrete MessageService media method for the
* envelope's type. Kept pure (no `this`) so the loader binds it directly and it can be unit-tested in
* isolation. The switch is exhaustive over ConversationMediaType — adding a type without a case is a
* compile error here rather than a silent runtime fall-through.
*/
export function dispatchConversationMedia(
svc: Pick<PluginMessagePort, 'sendImage' | 'sendVideo' | 'sendAudio' | 'sendDocument'>,
sessionId: string,
opts: { chatId: string; url: string; type: ConversationMediaType; caption?: string },
): Promise<unknown> {
const dto = { chatId: opts.chatId, url: opts.url, caption: opts.caption };
switch (opts.type) {
case 'image':
return svc.sendImage(sessionId, dto);
case 'video':
return svc.sendVideo(sessionId, dto);
case 'audio':
return svc.sendAudio(sessionId, dto);
case 'voice':
// A voice envelope is a PTT note: sendAudio with ptt classifies it as 'voice' and defaults the
// codec to audio/ogg;opus, so it renders as a WhatsApp voice bubble rather than an audio file.
return svc.sendAudio(sessionId, { ...dto, ptt: true });
case 'file':
return svc.sendDocument(sessionId, dto);
}
}
// Plugin code can pass anything to its logger, and reading a value can throw (a Proxy trap, a getter, a toString): what
// cannot be read is written as a marker, never thrown into the plugin.
/** The text of a plugin's log message: what String gives for it (a Symbol included), or the marker. */
const messageText = (message: unknown): string => {
try {
return String(message);
} catch {
return UNPRINTABLE;
}
};
/** The trace for a plugin's ctx.logger.error: an Error's message, or the text of whatever else was passed. */
const errorText = (error: unknown): string => {
try {
return error instanceof Error ? error.message : String(error);
} catch {
return UNPRINTABLE;
}
};
/** A prototype that is the root of a chain (Object.prototype of any realm, or none): what a plain record has. */
const isRootPrototype = (prototype: object | null): boolean =>
prototype === null || Object.getPrototypeOf(prototype) === null;
/**
* A plugin's log meta as the fields of the line: a plain record as it is, nothing as no fields, else as one field. An
* object whose prototype cannot be read (a Proxy whose getPrototypeOf trap throws, or a revoked one) is taken as a
* record, as spreading it took it: the logger copies it by its own properties or writes it as [Unreadable].
*/
const metaFields = (meta: unknown): Record<string, unknown> => {
if (meta === undefined || meta === null) return {};
if (typeof meta !== 'object') return { meta };
try {
return isRootPrototype(Object.getPrototypeOf(meta) as object | null) ? (meta as Record<string, unknown>) : { meta };
} catch {
return meta as Record<string, unknown>;
}
};
/**
* The capability surface a plugin actually touches: ctx.messages, ctx.engine, ctx.net, ctx.storage,
* ctx.conversations, ctx.handover, ctx.mappings — and the gates in front of every one of them.
*
* This is the security-review surface. A plugin supplies its own sessionId, so `assertSessionAllowed`
* (the static manifest boundary) and the operator-activation check are the boundary, not a
* convenience. Keeping them beside the verbs they guard means a reviewer reads one file rather than
* tracing gates through a loader that is otherwise about discovery, lifecycle and worker plumbing.
*
* It holds no plugin registry and no worker hosts: the loader owns those. Everything here is derived
* from the PluginInstance passed in.
*/
export class PluginCapabilityContext {
// Carries the firing event's sessionId across an in-process hook handler so ctx.config (a getter)
// resolves the per-session slice. Per async call tree, so concurrent sessions don't cross over.
private readonly hookSession = new AsyncLocalStorage<{ sessionId?: string }>();
constructor(
// The LOADER's logger, deliberately — a plugin's ctx.logger lines are prefixed with it, and that
// context is operator-visible. Creating a second logger here would silently retag every plugin
// log line the moment this moved out.
private readonly logger: ReturnType<typeof createLogger>,
private readonly hostServices: PluginHostServices,
private readonly hookManager: HookManager,
private readonly pluginStorage: PluginStorageService,
private readonly lidMappingStore?: LidMappingStore,
) {}
/**
* Enforce a plugin's declared manifest permissions at the capability boundary. A plugin may only
* use a capability whose permission string it declares in `manifest.permissions`; anything else
* (including a manifest with no permissions) is denied. Runs first in each capability verb so a
* missing grant fails fast and uniformly as a PluginCapabilityError.
*
* The message names the fix, not just the fault. A denial surfaces mid-run — the capability is
* checked when the verb is called, not at load — so it reaches the operator as a log line detached
* from whatever upgrade caused it, and it is the only text about the problem that arrives at the
* same time as the symptom. Naming `permissions` in the plugin's manifest.json turns "why is this
* plugin broken" into a one-line edit.
*/
private assertPermission(manifest: PluginManifest, permission: PluginCapabilityPermission): void {
if (!(manifest.permissions ?? []).includes(permission)) {
throw new PluginCapabilityError(
`Plugin ${manifest.id} is missing the '${permission}' permission required for this capability. ` +
`Add "${permission}" to the "permissions" array in the plugin's manifest.json, then reload the plugin.`,
);
}
}
/**
* Enforce a plugin's manifest session scope. Runs BEFORE any engine/message resolution —
* sessionId is supplied by the plugin, so this is the security boundary. Absent = ['*'].
*/
private assertSessionAllowed(manifest: PluginManifest, sessionId: string): void {
const allowed = manifest.sessions ?? ['*'];
if (!allowed.includes('*') && !allowed.includes(sessionId)) {
throw new PluginCapabilityError(`Plugin ${manifest.id} is not permitted to act on session ${sessionId}`);
}
}
/** Per-session activation gate: is this plugin currently activated for `sessionId`'s event? */
private isHookActive(plugin: PluginInstance, sessionId: string | undefined): boolean {
return isPluginActiveForSession(plugin.manifest.sessionScoped ?? true, plugin.activeSessions ?? ['*'], sessionId);
}
/**
* The capability session gate. A plugin may act on `sessionId` only if BOTH hold: its manifest scope
* allows the session (the static author boundary, assertSessionAllowed) AND the operator has activated
* the plugin for that session (the dynamic boundary, the same gate hook dispatch uses). manifest.sessions
* alone is not enough — a general adapter ships `['*']` and is scoped by operator activation, so without
* the activeSessions check a plugin activated for one session could reach another's engine/mappings/
* handover. Defaults (`activeSessions ?? ['*']`, `sessionScoped:false`) preserve every unrestricted flow.
*/
private assertSessionActive(plugin: PluginInstance, sessionId: string): void {
this.assertSessionAllowed(plugin.manifest, sessionId);
if (!this.isHookActive(plugin, sessionId)) {
throw new PluginCapabilityError(`Plugin ${plugin.manifest.id} is not activated for session ${sessionId}`);
}
}
/**
* Scope-check, then resolve the live engine for a session. getEngine returns undefined for an
* unknown OR unstarted session (no throw), so guard it into a defined PluginCapabilityError.
* A present-but-not-READY engine throws EngineNotReadyError from the adapter on use (→ 409).
*/
private resolveEngine(plugin: PluginInstance, sessionId: string): IWhatsAppEngine {
this.assertSessionActive(plugin, sessionId);
const engine = this.hostServices.getSessionPort().getEngine(sessionId);
if (!engine) {
throw new PluginCapabilityError(`Session ${sessionId} has no active engine (unknown or not started)`);
}
return engine;
}
/** Engine read capabilities: require the `engine:read` permission, then resolve the live engine. */
private resolveEngineRead(plugin: PluginInstance, sessionId: string): IWhatsAppEngine {
this.assertPermission(plugin.manifest, PluginCapabilityPermission.ENGINE_READ);
return this.resolveEngine(plugin, sessionId);
}
/**
* Definitive "this session row no longer exists" probe for the stale-mapping repair paths below.
* True ONLY on a clean not-found from the sessions table; any other failure (service unresolvable,
* DB error) returns false, so the cross-session fences stay fail-CLOSED when the answer is
* indeterminate. The runtime engine map can't answer this — a stopped session has no engine but
* still owns its mappings.
*/
private async isSessionGone(sessionId: string): Promise<boolean> {
try {
await this.hostServices.getSessionPort().findOne(sessionId);
return false;
} catch (error) {
return error instanceof NotFoundException;
}
}
createPluginContext(plugin: PluginInstance): PluginContext {
const hookSession = this.hookSession;
return {
pluginId: plugin.manifest.id,
manifest: plugin.manifest,
// Per-session: inside a hook, returns the override merged over the base for the firing session;
// outside a hook (lifecycle), the base config. A getter so it reflects live config edits too.
get config() {
return resolvePluginConfig(
plugin.config,
plugin.sessionConfig,
hookSession.getStore()?.sessionId,
plugin.manifest.sessionScoped !== false,
plugin.manifest,
);
},
hookManager: this.hookManager,
logger: this.buildPluginLogger(plugin),
storage: this.buildStorageCapability(plugin),
registerHook: (event, handler, priority) => {
// Wrap with the per-session activation gate so an in-process plugin only handles events for
// the sessions it is activated for (mirrors the sandboxed shim), and scope the firing
// sessionId so ctx.config resolves the right per-session slice for the handler.
this.hookManager.register(
plugin.manifest.id,
event,
async hookCtx => {
if (!this.isHookActive(plugin, hookCtx.sessionId)) return { continue: true };
return this.hookSession.run({ sessionId: hookCtx.sessionId }, () => handler(hookCtx));
},
priority,
);
},
// In-process built-ins are not reached by the ingress pipeline (it dispatches to sandbox hosts),
// so fail loud rather than silently never firing. Sandboxed plugins get a real registerWebhook
// from the worker bootstrap.
registerWebhook: () => {
throw new PluginCapabilityError(
`Plugin ${plugin.manifest.id}: registerWebhook (ingress) is only available to sandboxed plugins`,
);
},
messages: this.buildMessagesCapability(plugin),
engine: this.buildEngineReadCapability(plugin),
net: this.buildNetCapability(plugin),
conversations: this.buildConversationsCapability(plugin),
handover: this.buildHandoverCapability(plugin),
mappings: this.buildMappingsCapability(plugin),
};
}
// The plugin id is the host's field, passed apart from the plugin's meta so that a meta the logger cuts keeps it.
private buildPluginLogger(plugin: PluginInstance): PluginLogger {
return {
log: (message, meta) =>
this.logger.log(`[${plugin.manifest.id}] ${messageText(message)}`, metaFields(meta), {
pluginId: plugin.manifest.id,
}),
debug: (message, meta) =>
this.logger.debug(`[${plugin.manifest.id}] ${messageText(message)}`, metaFields(meta), {
pluginId: plugin.manifest.id,
}),
warn: (message, meta) =>
this.logger.warn(`[${plugin.manifest.id}] ${messageText(message)}`, metaFields(meta), {
pluginId: plugin.manifest.id,
}),
error: (message, error, meta) =>
this.logger.error(
`[${plugin.manifest.id}] ${messageText(message)}`,
error === undefined ? undefined : errorText(error),
metaFields(meta),
{ pluginId: plugin.manifest.id },
),
};
}
private buildMessagesCapability(plugin: PluginInstance): PluginMessagingCapability {
return {
sendText: async (sessionId, chatId, text) => {
// Validate permission + scope + that the session has a live engine BEFORE MessageService
// persists a pending row: a missing grant / dead session must fail with
// PluginCapabilityError, not a raw TypeError + orphaned row. resolveEngine also runs
// assertSessionActive.
this.assertPermission(plugin.manifest, PluginCapabilityPermission.MESSAGES_SEND);
this.resolveEngine(plugin, sessionId);
return this.hostServices.getMessagePort().sendText(sessionId, { chatId, text });
},
reply: async (sessionId, chatId, quotedMessageId, text) => {
this.assertPermission(plugin.manifest, PluginCapabilityPermission.MESSAGES_SEND);
this.resolveEngine(plugin, sessionId);
return this.hostServices.getMessagePort().reply(sessionId, { chatId, quotedMessageId, text });
},
} satisfies PluginMessagingCapability;
}
private buildEngineReadCapability(plugin: PluginInstance): PluginEngineReadCapability {
return {
getGroupInfo: async (sessionId, groupId) => this.resolveEngineRead(plugin, sessionId).getGroupInfo(groupId),
getContacts: async sessionId => this.resolveEngineRead(plugin, sessionId).getContacts(),
getContactById: async (sessionId, contactId) =>
this.resolveEngineRead(plugin, sessionId).getContactById(contactId),
checkNumberExists: async (sessionId, phone) => this.resolveEngineRead(plugin, sessionId).checkNumberExists(phone),
getChats: async sessionId => this.resolveEngineRead(plugin, sessionId).getChats(),
getChatHistory: async (sessionId, chatId, limit, includeMedia) =>
this.resolveEngineRead(plugin, sessionId).getChatHistory(
chatId,
// Clamp to the REST non-deep ceiling (MessageService.MAX_CHAT_HISTORY_LIMIT = 100) so an
// untrusted plugin can't request an unbounded history fetch. A non-finite limit (a sandboxed
// caller's arg is unvalidated) takes the default: NaN would reach the engine as "no limit".
Math.min(Math.max(typeof limit === 'number' && Number.isFinite(limit) ? Math.trunc(limit) : 50, 1), 100),
includeMedia ?? false,
),
canonicalChatId: async (sessionId, chatId) => {
this.resolveEngineRead(plugin, sessionId);
const parsed = parseWaId(chatId);
const phone =
parsed.kind === 'lid' ? await this.lidMappingStore?.findPhoneForLid?.(chatId).catch(() => null) : null;
return toNeutralJid(chatId, () => phone ?? null);
},
} satisfies PluginEngineReadCapability;
}
/**
* Per-plugin persistence, behind the permission its manifest must declare. The gate goes on all
* four verbs rather than on the factory, because the sandbox bridge routes a worker's `storage.*`
* through this same object — gating only the in-process handle would leave the sandboxed path,
* the one that actually runs untrusted code, ungated.
*
* No session gate: storage is keyed by plugin, not by session, so there is no session to check.
*
* Every verb is `async` so a denial arrives as a REJECTION. The backing implementation in
* PluginStorageService never throws synchronously — an unsafe key and an exceeded quota both come
* back as a rejected promise — so a synchronous gate would have been the only sync throw on this
* surface, escaping a plugin that handles failure with `.catch()` alone and taking down the caller
* instead of failing the capability.
*/
private buildStorageCapability(plugin: PluginInstance): PluginStorage {
const storage = this.pluginStorage.createPluginStorage(plugin.manifest.id);
const gate = (): void => this.assertPermission(plugin.manifest, PluginCapabilityPermission.STORAGE_USE);
return {
get: async <T = unknown>(key: string): Promise<T | null> => {
gate();
return storage.get<T>(key);
},
set: async <T = unknown>(key: string, value: T): Promise<void> => {
gate();
return storage.set<T>(key, value);
},
delete: async (key: string): Promise<void> => {
gate();
return storage.delete(key);
},
list: async (prefix?: string): Promise<string[]> => {
gate();
return storage.list(prefix);
},
} satisfies PluginStorage;
}
/**
* Config of every ENABLED instance of a plugin, for the outbound-host allowlist. A disabled
* instance is not a tenant the operator is running, so its host is not admitted.
*
* Best-effort: a plugin may be loaded in a host that exposes no instance service (and the store
* can fail), and neither is a reason to refuse a fetch the base config already allows.
*/
private async enabledInstanceConfigs(pluginId: string): Promise<Record<string, unknown>[]> {
try {
const rows = await this.hostServices.getPluginInstancePort().list(pluginId);
return rows.filter(row => row.enabled).map(row => row.config ?? {});
} catch {
return [];
}
}
private buildNetCapability(plugin: PluginInstance): PluginNetCapability {
return {
fetch: async (url, init) => {
// Two gates: the declared permission, then the effective host allowlist = manifest net.allow
// UNION the https origins of net.allowConfigHosts keys across the base config AND every per-session
// override. The host gate has no firing-session context for a sandboxed plugin's cap round-trip,
// so admit every operator-configured tenant host (all public + still SSRF-guarded at connect)
// rather than resolving a single, possibly wrong (base-only), one. The SSRF guard inside
// performPluginFetch still blocks internal IPs even when the host is allowlisted.
this.assertPermission(plugin.manifest, PluginCapabilityPermission.NET_FETCH);
const netConfigs = [
plugin.config ?? {},
...Object.values(plugin.sessionConfig ?? {}),
// The instance rows, because the scope-keyed store above holds only the LAST instance
// projected onto a scope. Dispatch hands each instance its own config, so without this a
// second instance sharing that scope is told to call a host the allowlist never saw and
// its fetch is refused — a config that is correct and unusable. Same policy as the slice:
// an operator-provisioned tenant host, still gated by allowConfigHosts and the SSRF guard.
...(await this.enabledInstanceConfigs(plugin.manifest.id)),
];
const allow = [
...new Set(
netConfigs.flatMap(cfg =>
effectiveNetAllow(plugin.manifest.net?.allow, plugin.manifest.net?.allowConfigHosts, cfg),
),
),
];
if (!isNetHostAllowed(allow, url)) {
throw new PluginCapabilityError(
`Plugin ${plugin.manifest.id} may not fetch ${url} — add its host to net.allow or net.allowConfigHosts`,
);
}
return performPluginFetch(url, init);
},
} satisfies PluginNetCapability;
}
private buildConversationsCapability(plugin: PluginInstance): PluginConversationsCapability {
return buildConversationSendFacade({
manifest: plugin.manifest,
assertPermission: this.assertPermission.bind(this),
assertSessionActive: (sessionId: string) => this.assertSessionActive(plugin, sessionId),
resolveChatId: async env => {
if (!env.instanceId || !env.source?.externalConversationId) {
throw new PluginCapabilityError(
`Plugin ${plugin.manifest.id}: conversation.send requires chatId, or both instanceId and source to resolve one`,
);
}
const mapping = await this.hostServices
.getConversationMappingPort()
.getByProvider(plugin.manifest.id, env.instanceId, env.source.externalConversationId);
if (!mapping) {
throw new PluginCapabilityError(
`Plugin ${plugin.manifest.id}: no conversation mapping for instance ${env.instanceId} / ${env.source.externalConversationId}`,
);
}
// Fail closed on a cross-session mapping: getByProvider keys on (pluginId, instanceId,
// providerConversationId) only, so a stale row can resolve to a chat owned by a DIFFERENT
// session than the envelope's. Parity with the assertSessionActive(m.sessionId) check on
// mappings.getByProvider below — never send through a session the mapping does not belong to.
// (mapping.sessionId is NOT NULL in the entity, so a plain inequality check suffices. The
// env.sessionId guard is for the type only — the facade rejects a missing sessionId first.)
if (env.sessionId && mapping.sessionId !== env.sessionId) {
// Repair path: the mapping's session was DELETED (operator re-paired under a new id), so
// the row is stale rather than cross-session. Rebind it to the envelope's session —
// already activation-gated by the facade — and let the send proceed; without this the
// dead session's rows bricked conversation.send permanently. A mapping owned by another
// EXISTING session is a genuine cross-session violation and still throws.
if (await this.isSessionGone(mapping.sessionId)) {
await this.hostServices.getConversationMappingPort().rebindSession(mapping.id, env.sessionId);
this.logger.warn(
`Rebound conversation mapping for instance ${env.instanceId} / ${env.source.externalConversationId} ` +
`from deleted session ${mapping.sessionId} to ${env.sessionId}`,
{ pluginId: plugin.manifest.id, action: 'conversation_mapping_rebound' },
);
return mapping.chatId;
}
throw new PluginCapabilityError(
`Plugin ${plugin.manifest.id}: conversation mapping for instance ${env.instanceId} / ${env.source.externalConversationId} belongs to session ${mapping.sessionId}, not ${env.sessionId}`,
);
}
return mapping.chatId;
},
// Re-establish the in-flight hook context around the downstream send, so a conversation.send made
// from a hook handler cannot re-fire that handler's own event (an echo loop through
// message:sending). Gate on an ALREADY-in-flight event (mirrors the worker-cap wrap's
// `inFlight.length > 0` check): a send from an ingress handler or any other top-level context
// carries none, and must NOT suppress message:sending for observers (audit/moderation, or the
// adapter's own mirror hook), which then see the reply.
runGuarded: (events, run) =>
(events as HookEvent[]).some(e => this.hookManager.isInFlight(e))
? this.hookManager.runInFlight(events as HookEvent[], run)
: run(),
sendText: (sessionId, opts) => this.hostServices.getMessagePort().sendText(sessionId, opts),
reply: (sessionId, opts) => this.hostServices.getMessagePort().reply(sessionId, opts),
sendMedia: (sessionId, opts) => dispatchConversationMedia(this.hostServices.getMessagePort(), sessionId, opts),
sendLocation: (sessionId, opts) => this.hostServices.getMessagePort().sendLocation(sessionId, opts),
} satisfies Parameters<typeof buildConversationSendFacade>[0]) satisfies PluginConversationsCapability;
}
private buildHandoverCapability(plugin: PluginInstance): PluginHandoverCapability {
return {
set: async (key, state) => {
// Same gate as conversation.send: flipping handover is part of owning the conversation, so
// it reuses CONVERSATION_SEND rather than adding a new permission.
this.assertPermission(plugin.manifest, PluginCapabilityPermission.CONVERSATION_SEND);
this.assertSessionActive(plugin, key.sessionId);
// The sandbox router checks this too; an in-process plain-JS plugin reaches here unchecked,
// and any other value would be stored and silently never hold the chat.
if (state !== 'bot' && state !== 'human' && state !== 'closed') {
throw new PluginCapabilityError(
`Plugin ${plugin.manifest.id}: handover state must be 'bot', 'human' or 'closed'`,
);
}
const mapping = await this.hostServices.getConversationMappingPort().get({
sessionId: key.sessionId,
chatId: key.chatId,
pluginId: plugin.manifest.id,
instanceId: key.instanceId,
});
if (!mapping) {
throw new PluginCapabilityError(
`Plugin ${plugin.manifest.id}: no conversation mapping for session ${key.sessionId} / chat ${key.chatId} / instance ${key.instanceId}`,
);
}
await this.hostServices.getConversationMappingPort().setHandover(mapping.id, state);
},
} satisfies PluginHandoverCapability;
}
private buildMappingsCapability(plugin: PluginInstance): PluginMappingsCapability {
return {
upsert: async (key, providerConversationId) => {
this.assertPermission(plugin.manifest, PluginCapabilityPermission.CONVERSATION_SEND);
this.assertSessionActive(plugin, key.sessionId);
const mappingKey = {
sessionId: key.sessionId,
chatId: key.chatId,
pluginId: plugin.manifest.id,
instanceId: key.instanceId,
};
try {
await this.hostServices.getConversationMappingPort().upsert(mappingKey, providerConversationId);
} catch (error) {
if (!(error instanceof ConversationMappingConflict)) throw error;
// The reverse unique key is held by another row. If that row's session was DELETED
// (operator re-paired under a new id), the adapter can never converge — the forward key
// carries the new sessionId, so every upsert bricks on the dead session's row. Supersede
// the stale row and retry once. A row owned by an EXISTING session is a genuine conflict
// and rethrows.
const stale = await this.hostServices
.getConversationMappingPort()
.getByProvider(plugin.manifest.id, key.instanceId, providerConversationId);
if (!stale || !(await this.isSessionGone(stale.sessionId))) throw error;
await this.hostServices.getConversationMappingPort().delete(stale.id);
await this.hostServices.getConversationMappingPort().upsert(mappingKey, providerConversationId);
}
},
get: async key => {
this.assertPermission(plugin.manifest, PluginCapabilityPermission.CONVERSATION_SEND);
this.assertSessionActive(plugin, key.sessionId);
const m = await this.hostServices.getConversationMappingPort().get({
sessionId: key.sessionId,
chatId: key.chatId,
pluginId: plugin.manifest.id,
instanceId: key.instanceId,
});
return m ? { providerConversationId: m.providerConversationId, handoverState: m.handoverState } : null;
},
getByProvider: async (instanceId, providerConversationId) => {
this.assertPermission(plugin.manifest, PluginCapabilityPermission.CONVERSATION_SEND);
const m = await this.hostServices
.getConversationMappingPort()
.getByProvider(plugin.manifest.id, instanceId, providerConversationId);
// Parity with get/upsert: a plugin may only read a mapping for a session it is activated for.
if (m) this.assertSessionActive(plugin, m.sessionId);
return m ? { sessionId: m.sessionId, chatId: m.chatId, handoverState: m.handoverState } : null;
},
} satisfies PluginMappingsCapability;
}
// ============================================================================
// Query Methods
// ============================================================================
}