lightweb-adapter-sdk 0.1.0__tar.gz

lightweb_adapter_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: make install
+
+      - name: Type check
+        run: make typecheck
+
+      - name: Lint
+        run: make lint
+
+      - name: Format check
+        run: make format-check
+
+      - name: Unit tests
+        run: make test-unit
+
+      - name: Conformance tests
+        run: make test-conformance
+
+      - name: Conformance independence check
+        run: make test-conformance-independence

lightweb_adapter_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,117 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: uv pip install -e ".[dev]"
+
+      - name: Build wheel and sdist
+        run: make build
+
+      - name: Verify version matches tag
+        shell: python
+        run: |
+          import re
+          import sys
+          from pathlib import Path
+
+          tag = "${{ github.ref_name }}"
+          tag_version = tag.lstrip("v")
+
+          dist = Path("dist")
+          wheel_files = list(dist.glob("lightweb_adapter_sdk-*.whl"))
+          sdist_files = list(dist.glob("lightweb_adapter_sdk-*.tar.gz"))
+
+          if not wheel_files or not sdist_files:
+              print("ERROR: No wheel or sdist found in dist/")
+              sys.exit(1)
+
+          wheel_name = wheel_files[0].stem
+          sdist_name = sdist_files[0].stem
+
+          wheel_version = re.match(r"lightweb_adapter_sdk-(.+)", wheel_name).group(1)
+          sdist_version = re.match(r"lightweb_adapter_sdk-(.+)", sdist_name).group(1)
+
+          if wheel_version != sdist_version:
+              print(f"ERROR: Wheel version ({wheel_version}) != sdist version ({sdist_version})")
+              sys.exit(1)
+
+          if wheel_version != tag_version:
+              print(f"ERROR: Built version ({wheel_version}) != tag ({tag_version})")
+              sys.exit(1)
+
+      - name: Run CI checks
+        run: |
+          uv pip install -e ".[dev]"
+          make typecheck
+          make lint
+          make format-check
+          make test
+          make test-conformance
+          make test-conformance-independence
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 5
+
+  publish-testpypi:
+    needs: [build]
+    runs-on: ubuntu-latest
+    if: contains(github.ref_name, 'rc')
+    environment: testpypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: [build]
+    runs-on: ubuntu-latest
+    if: ${{ !contains(github.ref_name, 'rc') }}
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

lightweb_adapter_sdk-0.1.0/.gitignore

@@ -0,0 +1,82 @@
+# Session state (per workflow described in CLAUDE.md)
+.claude/
+decisions-log/
+
+# OpenCode session state
+.opencode/
+
+# Local round-prompt staging
+prompts/
+
+# Python build artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# uv
+.uv/
+uv.lock
+
+# Type checkers
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# Test artifacts
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+*.py,cover
+.cache
+
+# ruff
+.ruff_cache/
+
+# Editors and OS
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Local environment overrides
+.env
+.env.local
+*.local

lightweb_adapter_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to the Lightweb adapter SDK are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). See [`CONVENTIONS.md`](CONVENTIONS.md) §1 for the SDK's specific versioning discipline, including what counts as a breaking change.
+
+Breaking changes are flagged with `**BREAKING:**` at the start of the entry, even within their category.
+
+The SDK is in 0.x until its contract has been validated by at least one production adapter. Per [`CONVENTIONS.md`](CONVENTIONS.md) §1.3, breaking changes may land in minor (0.X → 0.(X+1)) releases while in 0.x; pin against a specific minor version.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-19
+
+### Changed
+
+- Conformance suite is now fully adapter-agnostic: conformance tests no longer import from `lightweb_adapter_sdk.reference`. State inspection uses `list_accounts()` instead of `get_account()`. Fault injection uses the `FaultControl` Protocol instead of `FakeExampleAppServer.set_unreachable()`.
+- `ExampleAppUnreachable` now inherits from `AdapterUnreachable` to maintain compatibility with conformance assertions on the base type.
+
+### Changed (BREAKING)
+
+- `EventEnvelope.event_type` semantics: now follows the pattern `entitlements.<entity>.<verb>` (matching what the platform emits), not `entitlements.<app>.<verb>`. The class shape is unchanged; the docstring and parsing logic differ.
+- `EventEnvelope.member_id` source: now extracted from the platform envelope's `data.member_id` field, not from `subject.id`. The class shape is unchanged.
+
+### Removed (BREAKING)
+
+- `app_from_event_type(event_type: str) -> str` — helper's premise was incorrect (assumed app name in middle segment of event_type; in reality, middle segment is the entity type). No replacement; adapters know their own app and do not extract it from events.
+
+### Added
+
+- `AdapterUnreachable` exception in `lightweb_adapter_sdk.types` — a base exception type for target-app unreachability. Adapter authors should raise this or a subclass when their adapter detects the target app is unreachable.
+- `FaultControl` Protocol in `lightweb_adapter_sdk.conformance.fault_control` — defines the interface for fault injection in conformance tests (`inject_unreachable`, `inject_rate_limit`, `inject_auth_failure`, `reset`).
+- `ReferenceFaultControl` in `lightweb_adapter_sdk.reference.fault_control` — reference implementation of `FaultControl` for the example adapter.
+- `is_entitlement_change_event(env: EventEnvelope) -> bool` — returns `True` for the curated set of event types that trigger member-state-changing entitlement re-derivation. Adapter consumers use this to filter events that warrant a re-apply, ignoring informational events like `app_account.created` and `feature_key.registry_reloaded`.
+- PEP 561 `py.typed` marker. Downstream consumers' type checkers will now pick up SDK type annotations.
+- `nats-py >= 2.6` declared as runtime dependency for `JetStreamEventConsumer`. (The dependency was used at runtime by `JetStreamEventConsumer` since Round 4 began but was not declared in `pyproject.toml`; declaration was missed during the contract-reshape work. No API change.)

lightweb_adapter_sdk-0.1.0/LICENSE

@@ -0,0 +1,197 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions to
+that Work or Derivative Works thereof, that is intentionally submitted
+to Licensor for inclusion in the Work by the copyright owner or by an
+individual or Legal Entity authorized to submit on behalf of the
+copyright owner. For the purposes of this definition, "submitted" means
+any form of electronic, verbal, or written communication sent to the
+Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work
+and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated
+in this section) patent license to make, have made, use, offer to sell,
+sell, import, and otherwise transfer the Work, where such license
+applies only to those patent claims licensable by such Contributor that
+are necessarily infringed by their Contribution(s) alone or by
+combination of their Contribution(s) with the Work to which such
+Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a
+lawsuit) alleging that the Work or a Contribution incorporated within
+the Work constitutes direct or contributory patent infringement, then
+any patent licenses granted to You under this License for that Work
+shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work
+or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You meet the
+following conditions:
+
+  (a) You must give any other recipients of the Work or Derivative
+  Works a copy of this License; and
+
+  (b) You must cause any modified files to carry prominent notices
+  stating that You changed the files; and
+
+  (c) You must retain, in the Source form of any Derivative Works that
+  You distribute, all copyright, patent, trademark, and attribution
+  notices from the Source form of the Work, excluding those notices
+  that do not pertain to any part of the Derivative Works; and
+
+  (d) If the Work includes a "NOTICE" text file as part of its
+  distribution, then any Derivative Works that You distribute must
+  include a readable copy of the attribution notices contained within
+  such NOTICE file, excluding those notices that do not pertain to any
+  part of the Derivative Works, in at least one of the following
+  places: within a NOTICE text file distributed as part of the
+  Derivative Works; within the Source form or documentation, if
+  provided along with the Derivative Works; or, within a display
+  generated by the Derivative Works, if and wherever such third-party
+  notices normally appear. The contents of the NOTICE file are for
+  informational purposes only and do not modify the License. You may
+  add Your own attribution notices within Derivative Works that You
+  distribute, alongside or as an addendum to the NOTICE text from the
+  Work, provided that such additional attribution notices cannot be
+  construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may
+provide additional or different license terms and conditions for use,
+reproduction, or distribution of Your modifications, or for any such
+Derivative Works as a whole, provided Your use, reproduction, and
+distribution of the Work otherwise complies with the conditions stated
+in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work by
+You to the Licensor shall be under the terms and conditions of this
+License, without any additional terms or conditions. Notwithstanding the
+above, nothing herein shall supersede or modify the terms of any
+separate license agreement you may have executed with the Licensor
+regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed
+to in writing, Licensor provides the Work (and each Contributor
+provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied, including, without
+limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
+MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely
+responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your
+exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise, unless
+required by applicable law (such as deliberate and grossly negligent
+acts) or agreed to in writing, shall any Contributor be liable to You
+for damages, including any direct, indirect, special, incidental, or
+consequential damages of any character arising as a result of this
+License or out of the use or inability to use the Work (including but
+not limited to damages for loss of goodwill, work stoppage, computer
+failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility
+of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the
+Work or Derivative Works thereof, You may choose to offer, and charge a
+fee for, acceptance of support, warranty, indemnity, or other liability
+obligations and/or rights consistent with this License. However, in
+accepting such obligations, You may act only on Your own behalf and on
+Your sole responsibility, not on behalf of any other Contributor, and
+only if You agree to indemnify, defend, and hold each Contributor
+harmless for any liability incurred by, or claims asserted against, such
+Contributor by reason of your accepting any such warranty or additional
+liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include the
+brackets!)  The text should be enclosed in the appropriate comment
+syntax for the file format. We also recommend that a file or class name
+and description of purpose be included on the same "printed page" as the
+copyright notice for easier identification within third-party archives.
+
+Copyright 2025 Lightweb
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

lightweb_adapter_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: lightweb-adapter-sdk
+Version: 0.1.0
+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
+Requires-Dist: pytest-asyncio>=0.23
+Requires-Dist: pytest>=8.0
+Provides-Extra: dev
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: mypy; 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/).