Metadata-Version: 2.4
Name: lightweb-adapter-sdk
Version: 0.2.4
Summary: Published Python SDK for the Lightweb adapter contract
Project-URL: Homepage, https://github.com/lightweb/adapter-sdk
Project-URL: Repository, https://github.com/lightweb/adapter-sdk
Project-URL: Issues, https://github.com/lightweb/adapter-sdk/issues
Project-URL: Changelog, https://github.com/lightweb/adapter-sdk/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/lightweb/adapter-sdk/docs
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: adapter,contract,entitlements,lightweb,provisioning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: nats-py>=2.6
Requires-Dist: pydantic>=2.0
Provides-Extra: conformance
Requires-Dist: pytest-asyncio>=0.23; extra == 'conformance'
Requires-Dist: pytest>=8.0; extra == 'conformance'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: hypothesis; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# Lightweb adapter SDK

The published Python SDK for the Lightweb adapter contract.

> **Status: pre-1.0, under active development.** The SDK is not yet released to PyPI. The first 0.1.0 release will follow once initial implementation rounds are complete. See [`CHANGELOG.md`](CHANGELOG.md) for release history.

## What this is

[Lightweb](https://github.com/lightweb/platform) is a community-owned, deployable platform template for hosting self-hosted alternatives to common web services — files, chat, code, meetings. The platform separates *what a member is entitled to* (the entitlements service, source of truth) from *how those entitlements are provisioned into specific apps* (one adapter per app: NextCloud, Matrix, Gitea, Jitsi, and others).

This SDK publishes the contract those adapters implement. It's six methods, a handful of shared types, an event envelope, and a conformance suite that every adapter is expected to pass.

If you want to build an adapter for a new app, this is the library you depend on. If you want to understand how the platform's adapter layer works without writing one, [`docs/contract.md`](docs/contract.md) is the canonical specification.

## The contract, briefly

Every adapter implements six methods:

- `capabilities()` — declares which feature keys this adapter handles and what enforcement it offers.
- `apply(member, entitlements)` — idempotent; makes the target app's state match the desired entitlements.
- `disable(member)` — soft-disable; blocks access while preserving data.
- `reconcile(member, entitlements)` — read-only; returns a drift report comparing app state to desired state.
- `health()` — the adapter and its target app are reachable.
- `list_accounts(cursor)` — optional; pages through every account in the app for whole-system reconciliation.

There is no `delete`. Deletion is destructive, asymmetric, and out of the contract by design; it's handled separately as a gated, human-approved workflow in the platform's reconciler.

The full specification is in [`docs/contract.md`](docs/contract.md).

## Quick start

Install:

```bash
pip install lightweb-adapter-sdk
```

A minimal adapter:

```python
from lightweb_adapter_sdk.adapter import Adapter
from lightweb_adapter_sdk.types import (
    Member, Entitlement, AppAccount, DriftReport,
    Capabilities, HealthStatus, AccountListPage,
)


class MyAdapter:
    """Adapter for MyApp."""

    def capabilities(self) -> Capabilities:
        ...

    def apply(self, member: Member, entitlements: list[Entitlement]) -> AppAccount:
        ...

    def disable(self, member: Member) -> None:
        ...

    def reconcile(self, member: Member) -> DriftReport:
        ...

    def health(self) -> HealthStatus:
        ...

    def list_accounts(self, cursor: str | None = None) -> AccountListPage:
        ...


# Verify the adapter satisfies the contract structurally:
adapter: Adapter = MyAdapter()
```

The `Adapter` is a `typing.Protocol`; your class doesn't have to inherit from it. If it has the right method signatures, it satisfies the contract.

The conformance suite verifies your adapter meets the contract's *behavioral* requirements (not just its structural ones). See [`docs/conformance.md`](docs/conformance.md) for how to run it against your adapter.

## Documentation

- [`docs/contract.md`](docs/contract.md) — the canonical contract specification. The authority on what an adapter must do.
- [`docs/conformance.md`](docs/conformance.md) — how to wire the conformance suite into your adapter's CI.
- [`docs/event-consumer.md`](docs/event-consumer.md) — JetStream event consumer conventions.
- [`docs/testkit.md`](docs/testkit.md) — the testkit for adapter authors.
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — repository orientation; what's where and why.

For the broader architectural context — *why* the adapter contract exists in this shape — see the Lightweb HLD in the platform monorepo at `lightweb/platform`'s `docs/hld.md`, especially §4.

## Status

The SDK is pre-1.0. The current implementation is structured as a sequence of rounds, with Round 5 targeting the first 0.1.0 release. 1.0 follows once the contract has been validated by at least one production adapter.

## Relationship to the Lightweb platform

The platform monorepo (`lightweb/platform`) is AGPLv3 and contains the bespoke spine services and first-party adapters that ship with Lightweb. The platform's first-party adapters consume this SDK the same way third-party adapters do — as a pinned PyPI dependency, not as a source-level inclusion.

This SDK is Apache 2.0. The license boundary is structural: the SDK is the *contract* third parties implement against, and a permissive license is appropriate for a contract definition.

The SDK has no code-level dependency on the platform monorepo. It does mirror some platform-side artifacts (event envelope schemas, the entitlements service's API shape), but those are vendored as generated bindings, not pulled dynamically.

## License

Apache License 2.0. See [`LICENSE`](LICENSE) for the full text.

## Code of conduct

Project participants are expected to follow the [Contributor Covenant](https://www.contributor-covenant.org/).
