Metadata-Version: 2.4
Name: integration-automation-patterns
Version: 0.18.0
Summary: Reference patterns for reliable enterprise integration, workflow automation, and system-of-record synchronization.
Author: Ashutosh Rana
License-Expression: MIT
Project-URL: Homepage, https://github.com/ashutoshrana/integration-automation-patterns
Project-URL: Issues, https://github.com/ashutoshrana/integration-automation-patterns/issues
Project-URL: Changelog, https://github.com/ashutoshrana/integration-automation-patterns/blob/main/CHANGELOG.md
Keywords: enterprise-integration,event-driven,workflow-automation,crm,erp,idempotency,system-of-record,integration-patterns,enterprise-architecture,circuit-breaker,saga-pattern,transactional-outbox,cdc,kafka,webhook
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Healthcare Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: Office/Business
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff>=0.4.0; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy>=1.0; extra == "typecheck"
Provides-Extra: kafka
Requires-Dist: kafka-python>=2.0; extra == "kafka"
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.130.0; extra == "fastapi"
Requires-Dist: httpx>=0.27.0; extra == "fastapi"
Provides-Extra: pydantic
Requires-Dist: pydantic>=2.12.0; extra == "pydantic"
Provides-Extra: all
Requires-Dist: integration-automation-patterns[fastapi,kafka,pydantic]; extra == "all"
Provides-Extra: dev
Requires-Dist: integration-automation-patterns[fastapi,lint,test,typecheck]; extra == "dev"
Dynamic: license-file

# integration-automation-patterns

[![CI](https://github.com/ashutoshrana/integration-automation-patterns/actions/workflows/ci.yml/badge.svg)](https://github.com/ashutoshrana/integration-automation-patterns/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/integration-automation-patterns.svg)](https://pypi.org/project/integration-automation-patterns/)
[![Python](https://img.shields.io/pypi/pyversions/integration-automation-patterns.svg)](https://pypi.org/project/integration-automation-patterns/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/integration-automation-patterns.svg)](https://pypi.org/project/integration-automation-patterns/)]

---

## The problem this solves

Enterprise systems that span CRM + ERP + messaging fail in predictable ways: duplicate event processing, partial transaction failures, and lost messages under retry. This library provides reference implementations of the patterns that solve these problems structurally — idempotent event envelopes, field-level authority boundaries, distributed saga orchestration, and transactional outbox — so integration logic is explicit, testable, and broker-agnostic.

---

## Architecture

```
Inbound Event
     │
     ▼
EventEnvelope
(event_id, idempotency_key, source, schema_version, metadata)
     │
     ├─ Duplicate Check ──────────────────────────────────────────┐
     │   event_id already processed? → skip, return cached result │
     │                                                             │
     ├─ Authority Check ──────────────────────────────────────────┤
     │   SyncBoundary.detect_conflict()                           │
     │   Which system owns this field?                            │
     │   Conflict → raise ConflictError, log authority boundary   │
     │                                                             │
     ├─ Retry Policy ─────────────────────────────────────────────┤
     │   Exponential backoff, max attempts                        │
     │   CircuitBreaker: CLOSED → OPEN → HALF_OPEN recovery       │
     │                                                             │
     └─ Outbox → DB Transaction → Reliable Publish ───────────────┘
         Write event in same DB tx as domain change
         Relay process delivers to broker independently
```

---

## Installation

```bash
pip install integration-automation-patterns
```

---

## 30-second example

```python
from integration_automation_patterns.event_envelope import EventEnvelope, DeliveryStatus
from integration_automation_patterns.sync_boundary import SyncBoundary, FieldAuthority

# Idempotent event envelope — safe to process multiple times
event = EventEnvelope(
    event_id="evt_8f3a1b",
    source="salesforce",
    event_type="contact.updated",
    payload={"email": "alice@example.com", "phone": "+1-555-0100"},
    schema_version="1.0",
)

# Field-level authority — who owns each field across systems?
boundary = SyncBoundary(
    authorities={
        "email": FieldAuthority(owner="salesforce", read_others=["erp", "itsm"]),
        "phone": FieldAuthority(owner="erp", read_others=["salesforce"]),
    }
)

conflicts = boundary.detect_conflict(
    incoming_system="salesforce",
    fields={"email": "alice@example.com", "phone": "+1-555-0100"},
)
# conflicts → {"phone": ConflictDetail(owner="erp", incoming_system="salesforce")}

if not conflicts:
    event.mark_delivered()
```

See [`docs/implementation-note-01.md`](./docs/implementation-note-01.md) for a full walkthrough.

---

## Pattern catalog

| Pattern | Class | Problem Solved |
|---------|-------|---------------|
| Idempotent Event | `EventEnvelope` | Duplicate processing under at-least-once delivery |
| Authority Model | `SyncBoundary` | Field-level conflict detection across systems |
| Circuit Breaker | `CircuitBreaker` | Cascading failure isolation with automatic recovery |
| Saga | `SagaOrchestrator` | Multi-step distributed transaction with compensation |
| Outbox | `OutboxPublisher` | Reliable event publish in the same DB transaction |
| Kafka Envelope | `KafkaEnvelope` | Partition routing, schema versioning, DLQ support |
| Webhook Validation | `WebhookHandler` | HMAC-SHA256 signature verification + idempotency |
| Change Data Capture | `CDCEvent` | Typed INSERT/UPDATE/DELETE with Debezium parsing |

---

## Repository structure

```
src/integration_automation_patterns/
├── event_envelope.py         # Reliable event transport + retry + delivery status
├── sync_boundary.py          # Bi-directional SOR sync with field authority
├── circuit_breaker.py        # CLOSED/OPEN/HALF_OPEN state machine
├── saga.py                   # Distributed saga orchestrator + compensation
├── outbox.py                 # Transactional outbox for at-least-once delivery
├── kafka_envelope.py         # Kafka-aware envelope: partition key, DLQ, schema
├── webhook_handler.py        # HMAC-SHA256 webhook verification
└── cdc_event.py              # Change Data Capture event types (Debezium-compatible)
docs/
├── architecture.md
├── implementation-note-01.md  # Event-driven integration reliability
├── implementation-note-02.md  # Idempotency in enterprise event processing
└── adr/
```

See [ECOSYSTEM.md](./ECOSYSTEM.md) for the full broker, connector, and framework coverage matrix.

---

## Published notes

- [Implementation Note 01](./docs/implementation-note-01.md) — Event-driven integration reliability
- [Implementation Note 02](./docs/implementation-note-02.md) — Idempotency in enterprise event processing

---

## Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. Run `pytest tests/ -v` to verify your changes before opening a pull request.

---

## Citation

If you use these patterns in research or production, please cite:

```bibtex
@software{rana2026iap,
  author    = {Rana, Ashutosh},
  title     = {integration-automation-patterns: Enterprise integration reliability patterns},
  year      = {2026},
  url       = {https://github.com/ashutoshrana/integration-automation-patterns},
  license   = {MIT}
}
```

Or use GitHub's "Cite this repository" button above (reads `CITATION.cff`).

---

## Part of the enterprise AI patterns trilogy

| Library | Focus | Regulation |
|---------|-------|-----------|
| [enterprise-rag-patterns](https://github.com/ashutoshrana/enterprise-rag-patterns) | What to retrieve | FERPA identity-scoped RAG |
| [regulated-ai-governance](https://github.com/ashutoshrana/regulated-ai-governance) | What agents may do | FERPA, HIPAA, GLBA policy enforcement |
| **integration-automation-patterns** | How data flows | Event-driven enterprise integration |

---

## License

MIT — see [LICENSE](LICENSE).
