Metadata-Version: 2.5
Name: mpt-extension-sdk
Version: 6.11.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: fastapi[standard]==0.162.*
Requires-Dist: mpt-api-client==6.5.*
Requires-Dist: mrok==0.10.9
Requires-Dist: opentelemetry-api==1.45.2
Requires-Dist: opentelemetry-exporter-otlp-proto-http==1.45.2
Requires-Dist: opentelemetry-instrumentation-fastapi==0.66b2
Requires-Dist: opentelemetry-instrumentation-httpx==0.66b2
Requires-Dist: opentelemetry-instrumentation-logging==0.66b2
Requires-Dist: opentelemetry-sdk==1.45.2
Requires-Dist: pydantic==2.14.*
Requires-Dist: typer==0.26.*
Provides-Extra: azure-monitor
Requires-Dist: azure-monitor-opentelemetry-exporter==1.0.0b59; extra == 'azure-monitor'
Description-Content-Type: text/markdown

# SDK Usage

This guide is the entry point for building an extension package on top of `mpt-extension-sdk`.
Topic-specific examples live in smaller documents under [`sdk_usage/`](sdk_usage/).

## Usage Topics

- [Extension application](sdk_usage/application.md): install the SDK, shape an extension package, create `ExtensionApp`,
  include routers, register startup hooks, and configure the runtime.
- [Event routes](sdk_usage/events.md): register task and non-task event handlers.
- [Schedule routes](sdk_usage/schedules.md): register periodic work and read the schedule delivery.
- [Task-based execution](sdk_usage/tasks.md): handler outcomes, task reporting, time limits, and the delivery
  protocol shared by schedules, task-backed events, and deferred API calls.
- [Authenticated API routes](sdk_usage/api.md): expose authenticated endpoints, validate bodies,
  read request/auth context, return API responses, and use pagination.
- [Webhook routes](sdk_usage/webhooks.md): declare platform webhooks, read the typed order, account or
  request context, and answer with `WebhookResponse` or `WebhookError`.
- [UI plugs](sdk_usage/plugs.md): register `PlugRouter` providers, group plugs under nested navigation containers,
  declare modal (open-by-id) plugs, and reference static assets.
- [Contexts and pipelines](sdk_usage/contexts-and-pipelines.md): adapt execution contexts, compose pipelines, drive the step
  lifecycle and flow control, use pipeline hooks, and declare status transitions.
- [Immutable snapshots](sdk_usage/immutable-snapshots.md): treat MPT models as immutable, update parameters with the `with_*`
  helpers, and refresh after a write.
- [Error handling](sdk_usage/error-handling.md): raise typed step/pipeline errors and let the SDK map them to event responses or task transitions.
- [Settings](sdk_usage/settings.md): the runtime, extension, and account settings layers and the environment-variable helpers.
- [Observability](sdk_usage/observability.md): SDK tracing, the `azure-monitor` extra, and extension-defined spans with `trace_span`.
- [CLI and metadata](sdk_usage/cli.md): the `mpt-ext` commands and `meta.yaml` generation/validation.
- [Marketplace services](sdk_usage/marketplace-services.md): use `ctx.mpt_api_service` from handlers and pipeline steps.

## Runtime Commands

An extension built on the SDK is run through the packaged `mpt-ext` CLI. The commands and their
contract are documented in [CLI and metadata](sdk_usage/cli.md).
