# Domain events

Events published to the platform event bus for cross-system coordination. B2B **emits** and **consumes** as noted.

**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`

## Event envelope

```json
{
  "id": "evt_01H...",
  "type": "org.registration_submitted",
  "occurred_at": "2026-03-01T09:00:00Z",
  "org_id": "org_01HNEW",
  "actor_id": "usr_01HNEW",
  "payload": { ... },
  "schema_version": "1"
}
```

## Catalog

### Organisation

| Event | Emitter | Consumers | Payload |
|-------|---------|-----------|---------|
| `org.registration_submitted` | B2B API | Admin, CRM | `registration_id`, `org_id`, `company`, `super_user` (no password) |
| `org.registration_requested` | B2B API | Admin, CRM | `request_id`, `contact_name`, `channel`, `email?`, `phone?`, `message?` |
| `org.activated` | Admin API | B2B, Ecom | `org_id`, `commercial`, `activated_by`, `activated_at` |

#### Sample: org.registration_submitted

```json
{
  "type": "org.registration_submitted",
  "org_id": "org_01HNEW",
  "payload": {
    "registration_id": "oreg_01HABC",
    "company": {
      "legal_name": "Gamma Industries PLC",
      "tin": "0011223344",
      "approx_headcount": 200
    },
    "super_user_email": "hanna@gamma.et"
  }
}
```

#### Sample: org.activated

```json
{
  "type": "org.activated",
  "org_id": "org_01HNEW",
  "payload": {
    "status": "active",
    "commercial": {
      "credit_limit": { "amount": "2000000.00", "currency": "ETB" },
      "price_list_id": "pl_corporate_2026",
      "contract_start": "2026-04-01",
      "contract_end": "2027-03-31"
    }
  }
}
```

---

### Migration

| Event | Emitter | Consumers | Payload |
|-------|---------|-----------|---------|
| `migration.job_started` | B2B API | Admin (audit), internal | `job_id`, `dataset_type`, `org_id` |
| `migration.job_completed` | B2B API | Admin (audit), internal | `job_id`, `commit_result` |
| `migration.job_failed` | B2B API | Admin (audit), internal | `job_id`, `error_code`, `message` |

#### Sample: migration.job_completed

```json
{
  "type": "migration.job_completed",
  "org_id": "org_01HQXYZ",
  "payload": {
    "job_id": "mig_01HJOB001",
    "dataset_type": "members",
    "commit_result": {
      "created": 487,
      "updated": 10,
      "skipped": 3,
      "failed": 0
    }
  }
}
```

---

### Prescriptions

| Event | Emitter | Consumers | Payload |
|-------|---------|-----------|---------|
| `prescription.submitted` | B2B API | Admin (pharmacist queue) | `prescription_id`, `member_id`, `customer_id`, `page_count` |
| `prescription.review_updated` | Admin API | B2B, Ecom, Mob | `prescription_id`, `status`, `query_message?`, `medicine_lines?` |

#### Sample: prescription.submitted

```json
{
  "type": "prescription.submitted",
  "org_id": "org_01HQXYZ",
  "payload": {
    "prescription_id": "rx_01H001",
    "member_id": "mbr_01HMEM001",
    "customer_id": "cus_01HSHARED",
    "page_count": 2,
    "submitted_at": "2026-03-10T08:00:00Z"
  }
}
```

**Clinical withhold:** `prescription.submitted` event must **not** include image URLs or clinical content — Admin fetches via secure internal API.

#### Sample: prescription.review_updated (consumed by B2B)

```json
{
  "type": "prescription.review_updated",
  "payload": {
    "prescription_id": "rx_01H001",
    "status": "approved",
    "reviewed_at": "2026-03-11T10:00:00Z",
    "days_supply": 30,
    "refill_due_at": "2026-04-10"
  }
}
```

Medicine lines included in consumer payload for MEMBER/SUPER_USER views only — filtered at API layer for HR/Finance.

---

## Webhook delivery (future)

```
POST https://client.example/webhooks/gishen
X-Gishen-Signature: sha256=...
```

Retry: exponential backoff, 3 days max.

## B2B responsibilities

| Action | Event |
|--------|-------|
| Self-register completes | Emit `org.registration_submitted` |
| Request form submitted | Emit `org.registration_requested` |
| Migration commit starts/ends | Emit `migration.job_*` |
| Member submits Rx | Emit `prescription.submitted` |
| Admin activates org | **Consume** `org.activated` → unlock entitlements |
| Pharmacist reviews Rx | **Consume** `prescription.review_updated` → update member UI |

## Related docs

- [Organisation entity](../entities/organisation.md)
- [Migration job entity](../entities/migration-job.md)
- [Prescription entity](../entities/prescription.md)
- [Gishen Admin coordination](../../coordination/gishen-admin.md)