72 lines
3.4 KiB
TypeScript
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>;
|
|
}
|