pycoinos 0.1.0__tar.gz

pycoinos-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gaelincho
+
+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.

pycoinos-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: pycoinos
+Version: 0.1.0
+Summary: A python helper for the coinos API
+Author-email: Gaelincho <g43l@proton.me>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/Gaelincho/pycoinos
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.33.1
+Dynamic: license-file
+
+# pycoinos
+
+This package serves as a python toolkit for interacting with the [Coinos API](https://coinos.io/docs).
+
+## Usage
+
+The main entry point for the package is the `Client` class. This class provides methods for interacting with the Coinos API.
+
+```python
+from pycoinos import Client
+
+client = Client("ey...") # your coinos token
+```
+
+The `Client` class has the following methods:
+
+- `me()`: Get your account details and balance.
+- `post_invoice()`: Create an invoice (lightning) or address (bitcoin).
+- `get_invoice()`: Fetch an invoice by passing a bitcoin address or lightning payment hash.
+- `post_payment()`: Send a lightning payment.
+- `bitcoin_payment()`: Send a bitcoin payment.
+- `send()`: Send an internal payment to another coinos user.
+- `get_payments()`: Get all payments sent or received by the current user.
+- `set_token()`: Update the token for the client.
+
+## Changelog
+
+- v0.1.0: Initial release
+
+## License
+
+Copyright (c) 2026 Gaelincho
+
+The pycoinos package is distributed under the [MIT License](./LICENSE).

pycoinos-0.1.0/README.md

@@ -0,0 +1,34 @@
+# pycoinos
+
+This package serves as a python toolkit for interacting with the [Coinos API](https://coinos.io/docs).
+
+## Usage
+
+The main entry point for the package is the `Client` class. This class provides methods for interacting with the Coinos API.
+
+```python
+from pycoinos import Client
+
+client = Client("ey...") # your coinos token
+```
+
+The `Client` class has the following methods:
+
+- `me()`: Get your account details and balance.
+- `post_invoice()`: Create an invoice (lightning) or address (bitcoin).
+- `get_invoice()`: Fetch an invoice by passing a bitcoin address or lightning payment hash.
+- `post_payment()`: Send a lightning payment.
+- `bitcoin_payment()`: Send a bitcoin payment.
+- `send()`: Send an internal payment to another coinos user.
+- `get_payments()`: Get all payments sent or received by the current user.
+- `set_token()`: Update the token for the client.
+
+## Changelog
+
+- v0.1.0: Initial release
+
+## License
+
+Copyright (c) 2026 Gaelincho
+
+The pycoinos package is distributed under the [MIT License](./LICENSE).

pycoinos-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "pycoinos"
+version = "0.1.0"
+description = "A python helper for the coinos API"
+readme = "README.md"
+authors = [{ name = "Gaelincho", email = "g43l@proton.me" }]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+dependencies = ["requests>=2.33.1"]
+
+[project.scripts]
+pycoinos = "pycoinos:main"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project.urls]
+homepage = "https://github.com/Gaelincho/pycoinos"

pycoinos-0.1.0/setup.cfg

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

pycoinos-0.1.0/src/pycoinos/__init__.py

@@ -0,0 +1,4 @@
+from .client import Client
+
+__all__ = ["Client"]
+__version__ = "0.1.0"

pycoinos-0.1.0/src/pycoinos/classes.py

@@ -0,0 +1,103 @@
+import warnings
+from dataclasses import dataclass
+from typing import Any
+
+from .constants import TYPES
+
+
+class SecretStr:
+    def __init__(self, value: str):
+        self.__value = value
+
+    def getsecret(self):
+        return self.__value
+
+    def __str__(self):
+        warnings.warn("You can access the secret value with `getsecret()`", UserWarning)
+        return "*" * len(self.__value)
+
+    def __repr__(self):
+        return str(self)
+
+    def __eq__(self, other):
+        return self.__value == other
+
+    def __hash__(self):
+        return hash(self.__value)
+
+    def __len__(self):
+        return len(self.__value)
+
+    def __bool__(self):
+        return bool(self.__value)
+
+
+@dataclass
+class BaseUser:
+    currency: str
+    id: str
+    npub: str
+    picture: str
+    pubkey: str
+    username: str
+
+
+@dataclass
+class User(BaseUser):
+    balance: float
+    currencies: list[str]
+    fiat: bool
+    locked: Any
+    locktime: int
+    nsec: SecretStr
+    prompt: bool
+
+
+@dataclass
+class BaseAddress:
+    aid: str
+    amount: float
+    created: int
+    currency: str
+    hash: str
+    id: str
+    items: list
+    own: bool
+    pending: float
+    rate: float
+    received: float
+    text: str
+    tip: Any
+    type: TYPES
+    uid: str
+    user: BaseUser | None
+
+
+@dataclass
+class Address(BaseAddress):
+    address_type: str
+
+
+@dataclass
+class Invoice(BaseAddress):
+    expiry: int
+    paymentHash: str
+    confirmed: bool | None
+    fee: float | None
+    ourfee: float | None
+    ref: str | None
+
+
+@dataclass
+class Payment(Address, Invoice):
+    iid: str
+    memo: str
+    hex: str
+
+
+@dataclass
+class Payments:
+    payments: list[Payment]
+    count: int
+    incoming: dict
+    outcoming: dict

pycoinos-0.1.0/src/pycoinos/client.py

@@ -0,0 +1,185 @@
+import warnings
+
+import requests as r
+
+from .classes import Address, Invoice, Payments, SecretStr, User
+from .constants import BASE_URL, TYPES
+
+
+class Client:
+    def __init__(self, token=None):
+        self._session = r.Session()
+        self.__token = token
+
+    def set_token(self, token):
+        self.__token = token
+
+    def me(self):
+        """Get your account details and balance."""
+
+        user: dict = self._session.get(
+            f"{BASE_URL}/me",
+            headers={
+                "Authorization": f"Bearer {self.__token}",
+                "Content-Type": "application/json",
+            },
+        ).json()
+
+        try:
+            user["nsec"] = SecretStr(user["nsec"])
+        except KeyError:
+            pass
+
+        return User(**user)
+
+    def post_invoice(
+        self,
+        type: TYPES = "lightning",
+        fiat: bool = False,
+        amount: float = -1,
+        webhook: str = None,
+        secret: str = None,
+    ) -> Invoice | Address:
+        """Create an invoice.
+        Args:
+            type: bitcoin or lightning
+            fiat: whether the amount is denominated in satoshis or local currency
+            amount: amount to be paid
+            webhook: remote endpoint to call when the invoice is paid
+            secret: a secret value passed to the webhook to authenticate the request
+
+        Returns:
+            Invoice (lightning) or Address (bitcoin)
+        """
+
+        if amount == -1:
+            raise ValueError("amount is required")
+
+        r = self._session.post(
+            f"{BASE_URL}/invoice",
+            headers={
+                "Authorization": f"Bearer {self.__token}",
+                "Content-Type": "application/json",
+            },
+            json={
+                "invoice": {
+                    "type": type,
+                    "fiat": fiat,
+                    "amount": amount,
+                    "webhook": webhook,
+                    "secret": secret,
+                }
+            },
+        ).json()
+
+        if r["type"] == "lightning":
+            return Invoice(**r)
+        if r["type"] == "bitcoin":
+            return Address(**r)
+
+        raise ValueError("unknown invoice type", r["type"], r)
+
+    def get_invoice(self, hash: str) -> Invoice | Address:
+        """Fetch an invoice by passing a bitcoin address or lightning payment hash."""
+
+        r = self._session.get(
+            f"{BASE_URL}/invoice/{hash}",
+            headers={
+                "Authorization": f"Bearer {self.__token}",
+                "Content-Type": "application/json",
+            },
+        ).json()
+
+        if r["type"] == "lightning":
+            return Invoice(**r)
+        if r["type"] == "bitcoin":
+            return Address(**r)
+
+        raise ValueError("unknown invoice type", r["type"], r)
+
+    def post_payment(self, payreq: str) -> Invoice:
+        """Send a lightning payment."""
+
+        r = self._session.post(
+            f"{BASE_URL}/payments",
+            headers={
+                "Authorization": f"Bearer {self.__token}",
+                "Content-Type": "application/json",
+            },
+            json={"payreq": payreq},
+        ).json()
+
+        if r["type"] == "lightning":
+            return Invoice(**r)
+        if r["type"] == "bitcoin":
+            raise NotImplementedError(
+                "bitcoin payments not supported with this endpoint"
+            )
+
+        raise ValueError("unknown invoice type", r["type"], r)
+
+    def send(self, amount: float, username: str) -> dict:
+        """Send an internal payment to another user."""
+
+        r = self._session.post(
+            f"{BASE_URL}/send",
+            headers={
+                "Authorization": f"Bearer {self.__token}",
+                "Content-Type": "application/json",
+            },
+            json={"amount": amount, "username": username},
+        )
+        return r.json()
+
+    def bitcoin_payment(self, amount: float, address: str) -> dict:
+        """Send a bitcoin payment. This function hasn't been tested."""
+
+        r = self._session.post(
+            f"{BASE_URL}/bitcoin/send",
+            headers={
+                "Authorization": f"Bearer {self.__token}",
+                "Content-Type": "application/json",
+            },
+            json={"amount": amount, "address": address},
+        )
+        warnings.warn(
+            "This function hasn't been tested. Use at your own risk", UserWarning
+        )
+        return r.json()
+
+    def get_payments(
+        self,
+        start: int | None = None,
+        end: int | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> Payments:
+        """Get all payments sent or received by the current user
+
+        Args:
+            start: only payments after this unix time
+            end: only payments before this unix time
+            limit: limit to this integer number of results
+            offset: start limiting from this integer offset
+        """
+
+        params = {}
+        if start is not None:
+            params["start"] = start
+        if end is not None:
+            params["end"] = end
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+
+        r = self._session.get(
+            f"{BASE_URL}/payments",
+            headers={
+                "Authorization": f"Bearer {self.__token}",
+                "Content-Type": "application/json",
+            },
+            params=params,
+        )
+
+        return Payments(**r.json())

pycoinos-0.1.0/src/pycoinos/constants.py

@@ -0,0 +1,4 @@
+from typing import Literal
+
+BASE_URL = "https://coinos.io/api"
+TYPES = Literal["lightning", "bitcoin"]

pycoinos-0.1.0/src/pycoinos.egg-info/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: pycoinos
+Version: 0.1.0
+Summary: A python helper for the coinos API
+Author-email: Gaelincho <g43l@proton.me>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/Gaelincho/pycoinos
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.33.1
+Dynamic: license-file
+
+# pycoinos
+
+This package serves as a python toolkit for interacting with the [Coinos API](https://coinos.io/docs).
+
+## Usage
+
+The main entry point for the package is the `Client` class. This class provides methods for interacting with the Coinos API.
+
+```python
+from pycoinos import Client
+
+client = Client("ey...") # your coinos token
+```
+
+The `Client` class has the following methods:
+
+- `me()`: Get your account details and balance.
+- `post_invoice()`: Create an invoice (lightning) or address (bitcoin).
+- `get_invoice()`: Fetch an invoice by passing a bitcoin address or lightning payment hash.
+- `post_payment()`: Send a lightning payment.
+- `bitcoin_payment()`: Send a bitcoin payment.
+- `send()`: Send an internal payment to another coinos user.
+- `get_payments()`: Get all payments sent or received by the current user.
+- `set_token()`: Update the token for the client.
+
+## Changelog
+
+- v0.1.0: Initial release
+
+## License
+
+Copyright (c) 2026 Gaelincho
+
+The pycoinos package is distributed under the [MIT License](./LICENSE).

pycoinos-0.1.0/src/pycoinos.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/pycoinos/__init__.py
+src/pycoinos/classes.py
+src/pycoinos/client.py
+src/pycoinos/constants.py
+src/pycoinos.egg-info/PKG-INFO
+src/pycoinos.egg-info/SOURCES.txt
+src/pycoinos.egg-info/dependency_links.txt
+src/pycoinos.egg-info/entry_points.txt
+src/pycoinos.egg-info/requires.txt
+src/pycoinos.egg-info/top_level.txt

pycoinos-0.1.0/src/pycoinos.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pycoinos-0.1.0/src/pycoinos.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pycoinos = pycoinos:main

pycoinos-0.1.0/src/pycoinos.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.33.1

pycoinos-0.1.0/src/pycoinos.egg-info/top_level.txt

@@ -0,0 +1 @@
+pycoinos