primitivedotdev 0.1.1__tar.gz

primitivedotdev-0.1.1/.gitignore

@@ -0,0 +1,19 @@
+.DS_Store
+.direnv/
+/.envrc
+/flake.nix
+/flake.lock
+node_modules/
+sdk-node/node_modules/
+sdk-node/dist/
+sdk-node/*.tsbuildinfo
+sdk-python/.venv/
+sdk-python/dist/
+sdk-python/.coverage
+sdk-python/.pytest_cache/
+sdk-python/.ruff_cache/
+sdk-python/**/*.pyc
+sdk-python/**/__pycache__/
+.internal/
+.vite/
+dist/

primitivedotdev-0.1.1/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: primitivedotdev
+Version: 0.1.1
+Summary: Official Primitive Python SDK for webhook verification and validation
+Project-URL: Homepage, https://primitive.dev
+Project-URL: Repository, https://github.com/primitivedotdev/sdks
+Project-URL: Issues, https://github.com/primitivedotdev/sdks/issues
+Author-email: Primitive <support@primitive.dev>
+License: MIT
+Keywords: email,hmac,primitive,signature,webhook
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: jsonschema<5,>=4.24.0
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: typing-extensions>=4.12.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# `primitivedotdev`
+
+Official Primitive Python SDK for webhook verification and validation.
+
+This package helps you:
+
+- verify Primitive webhook signatures
+- parse webhook request bodies
+- validate webhook payloads against the canonical JSON schema
+- work with typed `email.received` events in Python
+
+Validated events are returned as generated Pydantic models derived from the canonical JSON schema.
+
+## Requirements
+
+- Python `>=3.10`
+
+## Installation
+
+```bash
+pip install primitivedotdev
+```
+
+## Basic Usage
+
+```python
+from primitive import PrimitiveWebhookError, handle_webhook
+
+
+def webhook_handler(body: bytes, headers: dict[str, str]) -> dict[str, object]:
+    try:
+        event = handle_webhook(
+            body=body,
+            headers=headers,
+            secret="whsec_...",
+        )
+
+        print("Email from:", event.email.headers.from_)
+        print("Subject:", event.email.headers.subject)
+        return {"received": True}
+    except PrimitiveWebhookError as error:
+        return {"error": error.code, "message": str(error)}
+```
+
+## Core API
+
+### Main functions
+
+- `handle_webhook(...)`
+  - verifies the webhook signature
+  - decodes and parses the request body
+  - validates the payload
+  - returns a typed `EmailReceivedEvent`
+- `parse_webhook_event(input)`
+  - parses a JSON payload into a known webhook event or `dict`
+  - validates known event types against the canonical schema
+  - raises `WebhookValidationError` for malformed known events
+- `validate_email_received_event(input)`
+  - validates an `email.received` payload and returns the typed event
+- `safe_validate_email_received_event(input)`
+  - returns a `ValidationSuccess` or `ValidationFailure`
+- `verify_webhook_signature(...)`
+  - verifies `Primitive-Signature`
+- `validate_email_auth(auth)`
+  - computes a verdict from SPF, DKIM, and DMARC results
+
+### Helpful exports
+
+- `email_received_event_json_schema`
+- `WEBHOOK_VERSION`
+- `PrimitiveWebhookError`
+- `WebhookVerificationError`
+- `WebhookPayloadError`
+- `WebhookValidationError`
+- `RawEmailDecodeError`
+
+### Types and models
+
+The package exports the main webhook models and helper types, including:
+
+- `EmailReceivedEvent`
+- `WebhookEvent`
+- `UnknownEvent`
+- `EmailAuth`
+- `EmailAnalysis`
+- `ParsedData`
+- `RawContent`
+- `WebhookAttachment`
+
+## Parsing Events
+
+- `parse_webhook_event(input)` strictly validates known event types such as `email.received`
+- malformed known events raise `WebhookValidationError`
+- unknown future event types are returned as dictionaries for forward compatibility
+
+## JSON Schema
+
+The webhook payload contract is defined by the canonical JSON schema in the repository and is exported by this package as `email_received_event_json_schema`.
+
+The SDK uses that schema to generate:
+
+- the packaged schema artifact
+- Pydantic models
+- runtime validation behavior
+
+## Error Handling
+
+All SDK-specific runtime errors extend `PrimitiveWebhookError` and include a stable error `code`.
+
+```python
+from primitive import PrimitiveWebhookError
+
+try:
+    ...
+except PrimitiveWebhookError as error:
+    print(error.code, error)
+```
+
+## Development
+
+From `sdks/sdk-python`:
+
+```bash
+uv sync --dev
+uv run python scripts/generate_schema_module.py
+uv run python scripts/generate_models.py
+uv run pytest
+uv run ruff check .
+uv run basedpyright
+uv run python -m build
+```
+
+Or from repo root `sdks/`:
+
+```bash
+make python-sync
+make python-check
+make python-build
+```
+
+## Repository Layout
+
+```text
+sdks/
+  json-schema/
+    email-received-event.schema.json
+  sdk-python/
+    src/primitive/
+      models_generated.py
+      schema.py
+      schemas/email_received_event.schema.json
+      validation.py
+      webhook.py
+    scripts/
+      generate_models.py
+      generate_schema_module.py
+```

primitivedotdev-0.1.1/README.md

@@ -0,0 +1,157 @@
+# `primitivedotdev`
+
+Official Primitive Python SDK for webhook verification and validation.
+
+This package helps you:
+
+- verify Primitive webhook signatures
+- parse webhook request bodies
+- validate webhook payloads against the canonical JSON schema
+- work with typed `email.received` events in Python
+
+Validated events are returned as generated Pydantic models derived from the canonical JSON schema.
+
+## Requirements
+
+- Python `>=3.10`
+
+## Installation
+
+```bash
+pip install primitivedotdev
+```
+
+## Basic Usage
+
+```python
+from primitive import PrimitiveWebhookError, handle_webhook
+
+
+def webhook_handler(body: bytes, headers: dict[str, str]) -> dict[str, object]:
+    try:
+        event = handle_webhook(
+            body=body,
+            headers=headers,
+            secret="whsec_...",
+        )
+
+        print("Email from:", event.email.headers.from_)
+        print("Subject:", event.email.headers.subject)
+        return {"received": True}
+    except PrimitiveWebhookError as error:
+        return {"error": error.code, "message": str(error)}
+```
+
+## Core API
+
+### Main functions
+
+- `handle_webhook(...)`
+  - verifies the webhook signature
+  - decodes and parses the request body
+  - validates the payload
+  - returns a typed `EmailReceivedEvent`
+- `parse_webhook_event(input)`
+  - parses a JSON payload into a known webhook event or `dict`
+  - validates known event types against the canonical schema
+  - raises `WebhookValidationError` for malformed known events
+- `validate_email_received_event(input)`
+  - validates an `email.received` payload and returns the typed event
+- `safe_validate_email_received_event(input)`
+  - returns a `ValidationSuccess` or `ValidationFailure`
+- `verify_webhook_signature(...)`
+  - verifies `Primitive-Signature`
+- `validate_email_auth(auth)`
+  - computes a verdict from SPF, DKIM, and DMARC results
+
+### Helpful exports
+
+- `email_received_event_json_schema`
+- `WEBHOOK_VERSION`
+- `PrimitiveWebhookError`
+- `WebhookVerificationError`
+- `WebhookPayloadError`
+- `WebhookValidationError`
+- `RawEmailDecodeError`
+
+### Types and models
+
+The package exports the main webhook models and helper types, including:
+
+- `EmailReceivedEvent`
+- `WebhookEvent`
+- `UnknownEvent`
+- `EmailAuth`
+- `EmailAnalysis`
+- `ParsedData`
+- `RawContent`
+- `WebhookAttachment`
+
+## Parsing Events
+
+- `parse_webhook_event(input)` strictly validates known event types such as `email.received`
+- malformed known events raise `WebhookValidationError`
+- unknown future event types are returned as dictionaries for forward compatibility
+
+## JSON Schema
+
+The webhook payload contract is defined by the canonical JSON schema in the repository and is exported by this package as `email_received_event_json_schema`.
+
+The SDK uses that schema to generate:
+
+- the packaged schema artifact
+- Pydantic models
+- runtime validation behavior
+
+## Error Handling
+
+All SDK-specific runtime errors extend `PrimitiveWebhookError` and include a stable error `code`.
+
+```python
+from primitive import PrimitiveWebhookError
+
+try:
+    ...
+except PrimitiveWebhookError as error:
+    print(error.code, error)
+```
+
+## Development
+
+From `sdks/sdk-python`:
+
+```bash
+uv sync --dev
+uv run python scripts/generate_schema_module.py
+uv run python scripts/generate_models.py
+uv run pytest
+uv run ruff check .
+uv run basedpyright
+uv run python -m build
+```
+
+Or from repo root `sdks/`:
+
+```bash
+make python-sync
+make python-check
+make python-build
+```
+
+## Repository Layout
+
+```text
+sdks/
+  json-schema/
+    email-received-event.schema.json
+  sdk-python/
+    src/primitive/
+      models_generated.py
+      schema.py
+      schemas/email_received_event.schema.json
+      validation.py
+      webhook.py
+    scripts/
+      generate_models.py
+      generate_schema_module.py
+```