@digelim/adaptor

@digelim/adaptor is the outbound publication layer in the signal -> pulse -> core -> action -> adaptor pipeline. It normalizes resolved action results into a stable external contract and delivers them through pull APIs, webhooks, and realtime streams.

Repository: https://github.com/DiogoAngelim/adaptor
License: MIT

Install

npm install @digelim/adaptor

What You Get

• a deterministic normalization boundary for positive, negative, and null
• typed payload schemas for adapted results and downstream envelopes
• webhook subscription and delivery primitives
• authenticated WebSocket streaming
• publication gating for confidence, policy support, safety, and suppression reasons

Quick Start

import { createAdaptorModule } from "@digelim/adaptor";

const adaptor = await createAdaptorModule({
  PORT: "4200",
  LOG_LEVEL: "info",
});

await adaptor.app.listen({ port: 4200, host: "0.0.0.0" });

Validate a resolved action result before adapting it:

import { resolvedActionResultSchema } from "@digelim/adaptor";

const result = resolvedActionResultSchema.parse({
  resultId: "result_123",
  actionId: "action_123",
  requestId: "req_1001",
  decisionId: "dec_9001",
  streamId: "stream_orders",
  entityId: "order_42",
  signalId: "sig_77",
  intent: "EXECUTE",
  finalStatus: "COMPLETED",
  terminalOutcome: "SUCCESS",
  confidence: 0.94,
  expectedBehavior: "reserve internal fulfillment capacity",
  policyVersion: "policy.orders.v7",
  reasonCodes: [],
  attemptCount: 1,
  startedAt: new Date().toISOString(),
  completedAt: new Date().toISOString(),
  traceId: "trace_abc123",
  metadata: { source: "action" },
});

HTTP Surface

curl -X POST http://127.0.0.1:4200/internal/resolved-action-results \
  -H 'content-type: application/json' \
  -H 'x-api-key: test-key' \
  -d @resolved-result.json

Available routes:

• GET /health
• GET /ready
• POST /internal/resolved-action-results
• GET /adapted-results
• GET /adapted-results/:id
• GET /streams/:streamId/adapted-results
• POST /webhooks
• GET /webhooks
• PATCH /webhooks/:id
• GET /ws

Public Exports

• createAdaptorModule
• resolvedActionResultSchema
• adaptedResultSchema
• downstreamEnvelopeSchema
• domain constants and types from ./domain
• server bootstrap through @digelim/adaptor/server

Delivery Model

• normalized decisions: positive, negative, null
• realtime publication for authenticated subscribers
• filterable webhooks with signatures and retries
• cursor-based adapted result reads for downstream consumers

Development

npm install
npm run typecheck
npm test
npm run build

Release Notes

• changelog: CHANGELOG.md
• release process: RELEASING.md