Metadata-Version: 2.4
Name: netserve-schema-sdk
Version: 2.0.0
Summary: NetServe Schema Registry — Shared Python enums and Pydantic v2 event models (Envelope V2)
Author-email: Kingsley Simeon <formulaking07@gmail.com>
License: UNLICENSED
Project-URL: Repository, https://github.com/netserve-africa/netserve-schema-registry
Keywords: netserve,schema,events,pydantic
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0.0

# netserve-schema-sdk

NetServe Schema Registry — Shared Python enums and Pydantic v2 event models for all NetServe domain events across 20 modules (134 events).

## Installation

```bash
pip install netserve-schema-sdk==1.0.0
```

Always pin to an exact version. Do **not** use `>=` or `~=` — this is a contract package.

## Requirements

- Python ≥ 3.10
- pydantic ≥ 2.0.0

## Usage

```python
from netserve_schema.generated.models import OrderCreatedEvent, BuyerBehaviorRecordedEvent
from netserve_schema.shared_enums import OrderStatus, VendorStatus

# Validate an inbound event
raw = {
    "eventType": "order.created.v1",
    "correlationId": "req-abc-123",
    "timestamp": "2026-05-25T10:00:00Z",
    "payload": {
        "orderId": "order-xyz",
        "userId": "user-abc",
        "storeIds": ["store-1"],
        "totalKobo": 25000,
        "itemCount": 2,
        "isQrOrder": False,
        "checkoutSessionId": "chk-def",
    }
}
event = OrderCreatedEvent(**raw)
print(event.payload.order_id)   # "order-xyz"
print(event.payload.total_kobo) # 25000

# Use enums
status = OrderStatus.PENDING
assert status == "PENDING"  # str enum
```

## Top-level import (convenience)

```python
# Import everything from the top-level package
from netserve_schema import OrderCreatedEvent, OrderStatus
```

## Available Exports

### `netserve_schema.shared_enums`

All Prisma enums as Python `str, Enum` subclasses (JSON-safe serialization):

- `OrderStatus` — PENDING, CONFIRMED, PREPARING, READY_FOR_PICKUP, OUT_FOR_DELIVERY, COMPLETED, CANCELLED, FAILED, REFUNDED
- `VendorStatus` — PENDING, ACTIVE, SUSPENDED, REJECTED
- `UserRole` — BUYER, VENDOR, ADMIN, SUPER_ADMIN, SUPPORT
- `ProductStatus` — DRAFT, ACTIVE, ARCHIVED
- `DeliveryStatus` — PENDING, ASSIGNED, PICKED_UP, IN_TRANSIT, DELIVERED, FAILED, RETURNED
- `NotificationChannel` — PUSH, IN_APP, EMAIL, SMS
- 20+ additional enums — see `netserve_schema/shared_enums/__init__.py`

### `netserve_schema.generated.models`

Pydantic v2 models with `Field(alias="camelCase")` + `populate_by_name: True`:

| Class | Event type |
|-------|-----------|
| `OrderCreatedEvent` | `order.created.v1` |
| `OrderCompletedEvent` | `order.completed.v1` |
| `OrderCancelledEvent` | `order.cancelled.v1` |
| `BuyerBehaviorRecordedEvent` | `buyer.behavior.recorded.v1` |
| `BuyerAffinityUpdatedEvent` | `buyer.affinity.updated.v1` |
| `BuyerStreakUpdatedEvent` | `buyer.streak.updated.v1` |
| `InventoryStockUpdatedEvent` | `inventory.stock.updated.v1` |
| `InventoryOutOfStockEvent` | `inventory.product.out_of_stock.v1` |
| `IntelligenceIntentSignalEvent` | `intelligence.intent.signal.generated.v1` |
| `IntelligenceAffinityUpdatedEvent` | `intelligence.affinity.updated.v1` |
| `AuthLoginSucceededEvent` | `auth.login.succeeded.v1` |
| `LogisticsDispatchCreatedEvent` | `logistics.dispatch.created.v1` |
| `LogisticsDeliveryCompletedEvent` | `logistics.delivery.completed.v1` |
| `CommunityViralSignalEvent` | `community.viral_signal.generated.v1` |

### Union Types

```python
from netserve_schema.generated.models import AnyOrderEvent, AnyInventoryEvent, AnyIntelligenceEvent
```

## Field Naming Convention

All models use camelCase JSON aliases with snake_case Python attributes:

```python
event = OrderCreatedEvent(**json_data)
event.payload.order_id         # snake_case Python access
event.payload.model_dump(by_alias=True)["orderId"]  # camelCase JSON output
```

## Version Policy

This package follows the NetServe Schema Registry semver rules:

- **MAJOR** — breaking change (field removed, type changed, event removed)
- **MINOR** — additive change (new event, new optional field)
- **PATCH** — editorial (description updates, constraint relaxation)

## Source

Generated from: `contracts/events/` in [netserve-schema-registry](https://github.com/netserve-africa/netserve-schema-registry)

Do not edit generated files directly — raise a PR in the schema registry instead.
