integration.fake-outbox-adapter

@lssm-tech/integration.fake-outbox-adapter

Website: https://contractspec.io

Fake/sandbox outbox adapter for builder delivery loop testing.

What It Provides

• Simulated outbox adapter for testing builder delivery loop transitions without real provider SDKs or credentials.
• Supports fake and sandbox modes only; rejects production mode.
• Implements preflight checks, draft preparation, submission, receipt generation, and rollback.
• Idempotency key tracking and duplicate detection.
• Configurable latency simulation and failure rates for testing.

When to Use

• Testing builder-delivery-loop transitions in development/staging.
• CI/CD integration tests that don't require real provider sends.
• Local development where real credentials aren't available.
• Never use in production - this adapter is explicitly designed to reject production mode.

Usage

import { createFakeOutboxAdapter } from '@lssm-tech/integration.fake-outbox-adapter';

const adapter = createFakeOutboxAdapter({
  mode: 'sandbox',
  simulateLatencyMs: 100,
  failureRate: 0.1, // 10% simulated failure rate
});

// Preflight check
const preflight = await adapter.preflight({
  loopId: 'loop-123',
  idempotencyKey: 'unique-key-123',
  billingOSRefs: ['billing-ref-1'],
  companyOSRefs: ['company-ref-1'],
  operatorApprovalRef: 'approval-123',
});

if (preflight.canProceed) {
  // Prepare draft
  const draft = await adapter.prepareDraft(input, preflight);
  
  // Submit
  const submission = await adapter.submit(draft, {
    draftId: draft.draftId,
    loopId: 'loop-123',
    idempotencyKey: 'unique-key-123',
    approvalStillValid: true,
    revisionAtSubmission: 1,
  });
  
  // Get receipt
  const receipt = await adapter.getReceipt({
    submissionId: submission.submissionId,
    idempotencyKey: 'unique-key-123',
  });
}

Architecture

• Pure TypeScript implementation with no external provider dependencies.
• In-memory storage for drafts, submissions, and receipts.
• Fails closed on production mode detection.
• Supports idempotency for safe retry semantics.

Safety

• Always rejects production mode - set rejectProductionMode: true (default).
• Requires idempotency keys for all operations.
• Requires operator approval references.
• Duplicate idempotency keys return existing receipts (idempotent).

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run test — bun test
• bun run lint:check — biome check .