Files
0pt/src/adapters/writeback-adapter.ts
T

72 lines
3.4 KiB
TypeScript

/**
* src/adapters/writeback-adapter.ts
* ===================================
* The adapter interface `ExternalWritebackService` (../services/
* external-writeback-service.ts) writes through. One implementation per
* external system (e.g. odoo-bills-adapter.ts's OdooBillsAdapter for Odoo
* Vendor Bills) -- the service itself has zero knowledge of Odoo, Salesforce,
* or any other concrete external system; it only knows "an adapter with this
* adapterId exists, is configured, and can write a record."
*/
export interface WritebackAdapterContext {
tenant_id: string;
project_id: string;
actor_id: string;
correlation_id: string;
}
export interface WritebackRequest {
recordType: string;
payload: Readonly<Record<string, unknown>>;
/** Same idempotency key the caller gave ExternalWritebackService -- forwarded so an adapter
* with its own persistent storage (unlike the generic service's in-memory claim) can ALSO
* claim defensively at its own layer. See WritebackAdapter.write's own doc comment. */
idempotencyKey: string;
}
export interface WritebackResult {
ok: boolean;
/** The external system's own id for the record that was created (or already existed --
* see WritebackAdapter.write's own doc comment on idempotent re-calls), when ok is true. */
externalId?: string;
/** A short, stable, machine-readable reason code when ok is false (e.g. "is_reminder",
* "duplicate", "odoo_http_500") -- NOT a free-form human sentence, so callers/tests can
* assert on it reliably. */
error?: string;
}
/**
* One external-system write adapter. Registered onto an
* `ExternalWritebackService` via `registerAdapter` under a stable `adapterId`
* (e.g. "odoo_bills") that `ExternalWriteRequest.adapter_id` references.
*/
export interface WritebackAdapter {
readonly adapterId: string;
/** Whether this adapter has everything it needs (base URL, credentials, etc) to actually
* write -- mirrors DocumentIntelligenceAdapter.isConfigured's "refuse to fabricate a result"
* convention (../adapters/document-intelligence-adapter.ts): an unconfigured adapter must
* never be silently treated as a no-op success. */
isConfigured(): boolean;
/**
* Writes one record to the external system.
*
* IDEMPOTENCY, TWO LAYERS (per this task's own instruction not to regress the proven
* idempotent-claim logic ported from v0-datahub's invoice-bridge.ts):
* 1. `ExternalWritebackService` (the caller) already claims `idempotencyKey` in its own
* in-memory map BEFORE ever calling this method, so under normal operation `write` is
* only ever called once per logical record, from one service instance.
* 2. That in-memory claim is process-local and does not survive a restart, nor protect a
* multi-instance deployment. An adapter backed by its own persistent storage (like
* OdooBillsAdapter, when a caller supplies an already-posted record's
* `existing_external_id` in the payload) MUST ALSO refuse to re-post a record that
* already carries an external id -- exactly the "Redan bokförd i Odoo... hoppar över"
* early-return invoice-bridge.ts's own `processInboxToOdoo` performs. This is the
* genuine defense-in-depth the original proven code had; a `WritebackAdapter`
* implementation with real persistent storage should follow the same doctrine.
*/
write(request: WritebackRequest, ctx: WritebackAdapterContext): Promise<WritebackResult>;
}