Metadata-Version: 2.4
Name: mpt-extension-sdk
Version: 6.0.0
Summary: Extensions SDK for SoftwareONE Marketplace Platform
Author: SoftwareOne AG
License: Apache-2.0 license
License-File: LICENSE
Requires-Python: <4,>=3.12
Requires-Dist: azure-identity==1.25.*
Requires-Dist: azure-keyvault-secrets==4.10.*
Requires-Dist: azure-monitor-opentelemetry-exporter==1.0.0b46
Requires-Dist: click==8.3.*
Requires-Dist: debugpy==1.8.*
Requires-Dist: django-ninja==1.1.*
Requires-Dist: django==4.2.*
Requires-Dist: gunicorn==25.3.*
Requires-Dist: opentelemetry-api==1.39.0
Requires-Dist: opentelemetry-instrumentation-django==0.60.*
Requires-Dist: opentelemetry-instrumentation-logging==0.60.*
Requires-Dist: opentelemetry-instrumentation-requests==0.60.*
Requires-Dist: opentelemetry-sdk==1.39.0
Requires-Dist: pyfiglet==1.0.*
Requires-Dist: pyjwt==2.12.*
Requires-Dist: requests==2.33.*
Requires-Dist: rich==15.0.*
Requires-Dist: typing-extensions==4.15.*
Requires-Dist: uvicorn-worker==0.4.*
Requires-Dist: watchfiles==1.1.*
Description-Content-Type: text/markdown

# SDK Usage

This guide shows how to build on top of `mpt-extension-sdk`.

## Install The SDK

Install the package in a consumer project:

```bash
pip install mpt-extension-sdk
```

```bash
uv add mpt-extension-sdk
```

## Create An Extension

Start with the `Extension` primitive. It gives you an event registry and an API surface.

```python
from mpt_extension_sdk.core.extension import Extension

ext = Extension()


@ext.events.listener("orders")
def process_order(client, event):
    """Process order events."""
```

## Add A Validation Endpoint

Use the built-in Ninja API when your extension needs HTTP endpoints.

```python
from mpt_extension_sdk.core.extension import Extension
from mpt_extension_sdk.core.security import JWTAuth

ext = Extension()


def jwt_secret_callback(client, claims):
    """Return the webhook secret used for JWT validation."""
    return "your-webhook-secret"


@ext.api.post("/v1/orders/validate", auth=JWTAuth(jwt_secret_callback))
def process_order_validation(request, order):
    """Validate an incoming order."""
    return {"status": "accepted"}
```

## Build A Processing Pipeline

Use `Pipeline` for multi-step processing flows.

```python
from mpt_extension_sdk.flows.pipeline import Pipeline


class ValidateOrderStep:
    def process(self, client, context) -> None:
        """Validate the order payload."""


class ProcessOrderStep:
    def process(self, client, context) -> None:
        """Run the main order logic."""


pipeline = Pipeline(
    ValidateOrderStep(),
    ProcessOrderStep(),
)
```

## Run An Extension

Use the `swoext` CLI when running an extension built on top of the SDK:

```bash
swoext run
swoext run api --debug --reload
swoext run consumer
swoext django <command>
swoext shell
```

## Configure The Runtime

The SDK commonly relies on:

- `MPT_API_BASE_URL`
- `MPT_API_TOKEN`
- `MPT_PRODUCTS_IDS`
- `EXT_WEBHOOKS_SECRETS`

Example configuration:

```dotenv
EXT_WEBHOOKS_SECRETS={"PRD-1111-1111":"<webhook-secret-for-product>"}
MPT_API_BASE_URL=https://api.s1.show
MPT_API_TOKEN=<your-api-token>
MPT_PRODUCTS_IDS=PRD-1111-1111
MPT_PORTAL_BASE_URL=https://portal.s1.show
```

Use `MPT_API_BASE_URL` without `/v1` or `/public/v1`. See [configuration.md](configuration.md) for the environment-variable reference and [migrations.md](migrations.md) for the compatibility note behind that rule.

## What The SDK Provides

- an `Extension` primitive with event listener registration and a Django Ninja API surface
- runtime wiring for the `swoext` CLI and packaged Django app configuration
- reusable helpers for Marketplace HTTP, Key Vault, Airtable, telemetry, and RQL concerns
- pipeline primitives for multi-step processing flows
