lynkora-sdk-python 0.1.0__tar.gz

lynkora_sdk_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lynkora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lynkora_sdk_python-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: lynkora-sdk-python
+Version: 0.1.0
+Summary: SDK Python para integração com a API de Actions/Subscribers do Lynkora Admin Service.
+License-Expression: MIT
+Project-URL: Homepage, https://docs.lynkora.dev/docs/para-desenvolvedores/sdks
+Project-URL: Repository, https://github.com/natanaeldeveloper/lynkora-api
+Project-URL: Issues, https://github.com/natanaeldeveloper/lynkora-api/issues
+Keywords: lynkora,billing,usage-based-billing,metering,sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# lynkora-sdk-python
+
+SDK Python pra integrar com a API pública do Lynkora — registrar assinantes e
+controlar consumo (reservar, confirmar, cancelar). Zero dependências de
+runtime (usa `urllib.request` da biblioteca padrão), cliente síncrono.
+
+Documentação completa dos endpoints: [docs.lynkora.dev/docs/para-desenvolvedores/sdks](https://docs.lynkora.dev/docs/para-desenvolvedores/sdks).
+
+## Instalação
+
+```bash
+pip install lynkora-sdk-python
+```
+
+## Uso
+
+```python
+import os
+from lynkora_sdk import LynkoraClient
+
+lynkora = LynkoraClient(
+    api_key=os.environ["LYNKORA_API_KEY"],
+    base_url="https://api.lynkora.dev",
+)
+
+result = lynkora.consume_action(
+    subscriber_id="sub_123",
+    action_slug="generate-report",
+)
+
+lynkora.confirm_consumption(result["reservationId"])
+```
+
+Erros da API chegam como `LynkoraApiError`, com `status_code`, a mensagem (via
+`str(err)`) e o corpo original da resposta em `body`:
+
+```python
+from lynkora_sdk import LynkoraApiError
+
+try:
+    lynkora.consume_action(subscriber_id="sub_123", action_slug="generate-report")
+except LynkoraApiError as err:
+    print(err.status_code, str(err), err.body)
+```
+
+## Escopo
+
+Só os 4 endpoints autenticados por `X-Api-Key`: `consume_action`,
+`confirm_consumption`, `cancel_consumption` e `register_subscriber`. Nada de
+painel administrativo nem cobrança — isso é feito direto pela API.
+
+## Licença
+
+MIT

lynkora_sdk_python-0.1.0/README.md

@@ -0,0 +1,54 @@
+# lynkora-sdk-python
+
+SDK Python pra integrar com a API pública do Lynkora — registrar assinantes e
+controlar consumo (reservar, confirmar, cancelar). Zero dependências de
+runtime (usa `urllib.request` da biblioteca padrão), cliente síncrono.
+
+Documentação completa dos endpoints: [docs.lynkora.dev/docs/para-desenvolvedores/sdks](https://docs.lynkora.dev/docs/para-desenvolvedores/sdks).
+
+## Instalação
+
+```bash
+pip install lynkora-sdk-python
+```
+
+## Uso
+
+```python
+import os
+from lynkora_sdk import LynkoraClient
+
+lynkora = LynkoraClient(
+    api_key=os.environ["LYNKORA_API_KEY"],
+    base_url="https://api.lynkora.dev",
+)
+
+result = lynkora.consume_action(
+    subscriber_id="sub_123",
+    action_slug="generate-report",
+)
+
+lynkora.confirm_consumption(result["reservationId"])
+```
+
+Erros da API chegam como `LynkoraApiError`, com `status_code`, a mensagem (via
+`str(err)`) e o corpo original da resposta em `body`:
+
+```python
+from lynkora_sdk import LynkoraApiError
+
+try:
+    lynkora.consume_action(subscriber_id="sub_123", action_slug="generate-report")
+except LynkoraApiError as err:
+    print(err.status_code, str(err), err.body)
+```
+
+## Escopo
+
+Só os 4 endpoints autenticados por `X-Api-Key`: `consume_action`,
+`confirm_consumption`, `cancel_consumption` e `register_subscriber`. Nada de
+painel administrativo nem cobrança — isso é feito direto pela API.
+
+## Licença
+
+MIT

lynkora_sdk_python-0.1.0/lynkora_sdk/__init__.py

@@ -0,0 +1,4 @@
+from .client import LynkoraClient
+from .errors import LynkoraApiError
+
+__all__ = ["LynkoraClient", "LynkoraApiError"]

lynkora_sdk_python-0.1.0/lynkora_sdk/client.py

@@ -0,0 +1,78 @@
+import json
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+from .errors import LynkoraApiError
+
+
+class LynkoraClient:
+    def __init__(self, api_key: str, base_url: str) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+
+    def register_subscriber(
+        self,
+        suite_id: str,
+        name: str,
+        email: str,
+        document: str | None = None,
+        metadata: dict | None = None,
+    ) -> dict:
+        body = {"name": name, "email": email}
+        if document is not None:
+            body["document"] = document
+        if metadata is not None:
+            body["metadata"] = metadata
+        return self._request(
+            "POST", f"/v1/suites/{suite_id}/subscribers/register", body
+        )
+
+    def consume_action(
+        self,
+        subscriber_id: str,
+        action_slug: str,
+        quantity: int | None = None,
+        metadata: dict | None = None,
+    ) -> dict:
+        body = {"subscriberId": subscriber_id, "actionSlug": action_slug}
+        if quantity is not None:
+            body["quantity"] = quantity
+        if metadata is not None:
+            body["metadata"] = metadata
+        return self._request("POST", "/v1/actions/consume", body)
+
+    def confirm_consumption(self, reservation_id: str) -> dict:
+        return self._request("POST", f"/v1/actions/confirm/{reservation_id}")
+
+    def cancel_consumption(self, reservation_id: str) -> None:
+        return self._request("POST", f"/v1/actions/cancel/{reservation_id}")
+
+    def _request(self, method: str, path: str, body: dict | None = None) -> object:
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        req = Request(
+            f"{self._base_url}{path}",
+            data=data,
+            method=method,
+            headers={
+                "X-Api-Key": self._api_key,
+                "Content-Type": "application/json",
+            },
+        )
+
+        try:
+            with urlopen(req) as response:
+                if response.status == 204:
+                    return None
+                return json.loads(response.read())
+        except HTTPError as e:
+            raw = e.read()
+            try:
+                error_body = json.loads(raw) if raw else None
+            except ValueError:
+                error_body = None
+            message = (
+                error_body.get("message")
+                if isinstance(error_body, dict) and error_body.get("message")
+                else e.reason
+            )
+            raise LynkoraApiError(e.code, message, error_body) from e

lynkora_sdk_python-0.1.0/lynkora_sdk/errors.py

@@ -0,0 +1,5 @@
+class LynkoraApiError(Exception):
+    def __init__(self, status_code: int, message: str, body: object) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body

lynkora_sdk_python-0.1.0/lynkora_sdk_python.egg-info/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: lynkora-sdk-python
+Version: 0.1.0
+Summary: SDK Python para integração com a API de Actions/Subscribers do Lynkora Admin Service.
+License-Expression: MIT
+Project-URL: Homepage, https://docs.lynkora.dev/docs/para-desenvolvedores/sdks
+Project-URL: Repository, https://github.com/natanaeldeveloper/lynkora-api
+Project-URL: Issues, https://github.com/natanaeldeveloper/lynkora-api/issues
+Keywords: lynkora,billing,usage-based-billing,metering,sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# lynkora-sdk-python
+
+SDK Python pra integrar com a API pública do Lynkora — registrar assinantes e
+controlar consumo (reservar, confirmar, cancelar). Zero dependências de
+runtime (usa `urllib.request` da biblioteca padrão), cliente síncrono.
+
+Documentação completa dos endpoints: [docs.lynkora.dev/docs/para-desenvolvedores/sdks](https://docs.lynkora.dev/docs/para-desenvolvedores/sdks).
+
+## Instalação
+
+```bash
+pip install lynkora-sdk-python
+```
+
+## Uso
+
+```python
+import os
+from lynkora_sdk import LynkoraClient
+
+lynkora = LynkoraClient(
+    api_key=os.environ["LYNKORA_API_KEY"],
+    base_url="https://api.lynkora.dev",
+)
+
+result = lynkora.consume_action(
+    subscriber_id="sub_123",
+    action_slug="generate-report",
+)
+
+lynkora.confirm_consumption(result["reservationId"])
+```
+
+Erros da API chegam como `LynkoraApiError`, com `status_code`, a mensagem (via
+`str(err)`) e o corpo original da resposta em `body`:
+
+```python
+from lynkora_sdk import LynkoraApiError
+
+try:
+    lynkora.consume_action(subscriber_id="sub_123", action_slug="generate-report")
+except LynkoraApiError as err:
+    print(err.status_code, str(err), err.body)
+```
+
+## Escopo
+
+Só os 4 endpoints autenticados por `X-Api-Key`: `consume_action`,
+`confirm_consumption`, `cancel_consumption` e `register_subscriber`. Nada de
+painel administrativo nem cobrança — isso é feito direto pela API.
+
+## Licença
+
+MIT

lynkora_sdk_python-0.1.0/lynkora_sdk_python.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+lynkora_sdk/__init__.py
+lynkora_sdk/client.py
+lynkora_sdk/errors.py
+lynkora_sdk_python.egg-info/PKG-INFO
+lynkora_sdk_python.egg-info/SOURCES.txt
+lynkora_sdk_python.egg-info/dependency_links.txt
+lynkora_sdk_python.egg-info/requires.txt
+lynkora_sdk_python.egg-info/top_level.txt
+tests/test_client.py
+tests/test_errors.py

lynkora_sdk_python-0.1.0/lynkora_sdk_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lynkora_sdk_python-0.1.0/lynkora_sdk_python.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+pytest>=8.0
+build>=1.0
+twine>=5.0

lynkora_sdk_python-0.1.0/lynkora_sdk_python.egg-info/top_level.txt

@@ -0,0 +1 @@
+lynkora_sdk

lynkora_sdk_python-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "lynkora-sdk-python"
+version = "0.1.0"
+description = "SDK Python para integração com a API de Actions/Subscribers do Lynkora Admin Service."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["lynkora", "billing", "usage-based-billing", "metering", "sdk"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://docs.lynkora.dev/docs/para-desenvolvedores/sdks"
+Repository = "https://github.com/natanaeldeveloper/lynkora-api"
+Issues = "https://github.com/natanaeldeveloper/lynkora-api/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "build>=1.0", "twine>=5.0"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["lynkora_sdk*"]

lynkora_sdk_python-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lynkora_sdk_python-0.1.0/tests/test_client.py

@@ -0,0 +1,100 @@
+from io import BytesIO
+from unittest.mock import patch
+from urllib.error import HTTPError, URLError
+
+import pytest
+
+from lynkora_sdk.client import LynkoraClient
+from lynkora_sdk.errors import LynkoraApiError
+
+BASE_URL = "https://admin.example.com"
+API_KEY = "test-api-key"
+
+
+class FakeResponse:
+    def __init__(self, status: int, body: bytes) -> None:
+        self.status = status
+        self._body = body
+
+    def read(self) -> bytes:
+        return self._body
+
+    def __enter__(self) -> "FakeResponse":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        return None
+
+
+@pytest.fixture
+def client() -> LynkoraClient:
+    return LynkoraClient(api_key=API_KEY, base_url=BASE_URL)
+
+
+def test_register_subscriber_posts_and_returns_body(client: LynkoraClient) -> None:
+    fake = FakeResponse(201, b'{"id": "sub-1", "status": "ACTIVE"}')
+    with patch("lynkora_sdk.client.urlopen", return_value=fake) as urlopen_mock:
+        result = client.register_subscriber(
+            suite_id="suite-1", name="Jane Doe", email="jane@example.com"
+        )
+
+    assert result == {"id": "sub-1", "status": "ACTIVE"}
+    req = urlopen_mock.call_args[0][0]
+    assert req.full_url == f"{BASE_URL}/v1/suites/suite-1/subscribers/register"
+    assert req.headers["X-api-key"] == API_KEY
+    assert req.data == b'{"name": "Jane Doe", "email": "jane@example.com"}'
+
+
+def test_consume_action_posts_and_returns_body(client: LynkoraClient) -> None:
+    fake = FakeResponse(201, b'{"reservationId": "res-1", "quantity": 1}')
+    with patch("lynkora_sdk.client.urlopen", return_value=fake) as urlopen_mock:
+        result = client.consume_action(
+            subscriber_id="sub-1", action_slug="sign_document"
+        )
+
+    assert result == {"reservationId": "res-1", "quantity": 1}
+    req = urlopen_mock.call_args[0][0]
+    assert req.full_url == f"{BASE_URL}/v1/actions/consume"
+    assert req.data == b'{"subscriberId": "sub-1", "actionSlug": "sign_document"}'
+
+
+def test_confirm_consumption_posts_and_returns_body(client: LynkoraClient) -> None:
+    fake = FakeResponse(200, b'{"usageEventId": "usage-1"}')
+    with patch("lynkora_sdk.client.urlopen", return_value=fake) as urlopen_mock:
+        result = client.confirm_consumption(reservation_id="res-1")
+
+    assert result == {"usageEventId": "usage-1"}
+    req = urlopen_mock.call_args[0][0]
+    assert req.full_url == f"{BASE_URL}/v1/actions/confirm/res-1"
+
+
+def test_cancel_consumption_returns_none_for_204(client: LynkoraClient) -> None:
+    fake = FakeResponse(204, b"")
+    with patch("lynkora_sdk.client.urlopen", return_value=fake) as urlopen_mock:
+        result = client.cancel_consumption(reservation_id="res-1")
+
+    assert result is None
+    req = urlopen_mock.call_args[0][0]
+    assert req.full_url == f"{BASE_URL}/v1/actions/cancel/res-1"
+
+
+def test_raises_lynkora_api_error_on_non_2xx(client: LynkoraClient) -> None:
+    error = HTTPError(
+        url=f"{BASE_URL}/v1/actions/consume",
+        code=429,
+        msg="Too Many Requests",
+        hdrs=None,
+        fp=BytesIO(b'{"message": "Cota de acoes excedida."}'),
+    )
+    with patch("lynkora_sdk.client.urlopen", side_effect=error):
+        with pytest.raises(LynkoraApiError) as exc_info:
+            client.consume_action(subscriber_id="sub-1", action_slug="sign_document")
+
+    assert exc_info.value.status_code == 429
+    assert exc_info.value.body == {"message": "Cota de acoes excedida."}
+
+
+def test_network_error_propagates_unwrapped(client: LynkoraClient) -> None:
+    with patch("lynkora_sdk.client.urlopen", side_effect=URLError("no route")):
+        with pytest.raises(URLError):
+            client.consume_action(subscriber_id="sub-1", action_slug="sign_document")

lynkora_sdk_python-0.1.0/tests/test_errors.py

@@ -0,0 +1,10 @@
+from lynkora_sdk.errors import LynkoraApiError
+
+
+def test_exposes_status_code_message_and_body() -> None:
+    err = LynkoraApiError(429, "Cota de acoes excedida.", {"message": "Cota de acoes excedida."})
+
+    assert isinstance(err, Exception)
+    assert err.status_code == 429
+    assert str(err) == "Cota de acoes excedida."
+    assert err.body == {"message": "Cota de acoes excedida."}