startupaid 0.1.0__tar.gz

startupaid-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.DS_Store

startupaid-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: startupaid
+Version: 0.1.0
+Summary: Official Python SDK for startupAid — send email & push, schedule social posts, and convert currency.
+Project-URL: Homepage, https://startupaid.org
+Project-URL: Source, https://github.com/StartupAid-Org/startupaid-python
+Author: startupAid
+License: MIT
+Keywords: api,currency,email,push,sdk,social,startupaid
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# startupaid
+
+Official Python SDK for [startupAid](https://startupaid.org) — send transactional
+email, send push, schedule social posts, and convert currency, all with your
+account API key. Pure standard library, no dependencies.
+
+## Install
+
+```bash
+pip install startupaid
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+```python
+from startupaid import Client
+
+sa = Client("sk_your_key")
+
+res = sa.convert("USD", "NGN", 100)
+print(f"100 USD = {res['result']} NGN")
+```
+
+Create an API key in your startupAid dashboard → **API Keys**.
+
+## Usage
+
+### Email
+
+```python
+msg = sa.send_email(
+    from_="Acme <hi@acme.com>",
+    to="user@example.com",
+    subject="Welcome",
+    body="<h1>Hi 👋</h1>",
+)
+status = sa.get_message(msg["id"])
+```
+
+### Currency
+
+```python
+sa.convert("USD", "EUR", 250)
+sa.rates("USD")
+sa.currencies()
+```
+
+### Push
+
+```python
+sa.send_push(
+    "app_id",
+    target={"userRef": "u_123"},
+    title="Your order shipped",
+    body="Track it in the app.",
+)
+```
+
+### Social
+
+```python
+channels = sa.list_channels()
+
+post = sa.schedule_post(
+    channels=[c["id"] for c in channels],
+    content="We just shipped 🚀",
+    # scheduled_for="2026-08-01T09:00:00Z"  # omit to publish now
+)
+
+sa.list_posts()
+```
+
+### Audiences
+
+```python
+sa.list_audiences()
+sa.add_contact("audience_id", email="new@example.com", first_name="Ada")
+```
+
+## Configuration
+
+```python
+Client(
+    "sk_your_key",
+    base_url="http://localhost:8080",  # self-host / testing
+    timeout=30.0,                       # per-request timeout (seconds)
+)
+```
+
+## Errors
+
+Non-2xx responses raise `StartupAidError` with the status code and message:
+
+```python
+from startupaid import StartupAidError
+
+try:
+    sa.convert("USD", "NGN", 1)
+except StartupAidError as err:
+    print(err.status, err.message)
+```
+
+Each method requires your account to be subscribed to the matching product
+(email, currency, push, social); otherwise the API returns an upgrade prompt.
+
+## License
+
+MIT

startupaid-0.1.0/README.md

@@ -0,0 +1,110 @@
+# startupaid
+
+Official Python SDK for [startupAid](https://startupaid.org) — send transactional
+email, send push, schedule social posts, and convert currency, all with your
+account API key. Pure standard library, no dependencies.
+
+## Install
+
+```bash
+pip install startupaid
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+```python
+from startupaid import Client
+
+sa = Client("sk_your_key")
+
+res = sa.convert("USD", "NGN", 100)
+print(f"100 USD = {res['result']} NGN")
+```
+
+Create an API key in your startupAid dashboard → **API Keys**.
+
+## Usage
+
+### Email
+
+```python
+msg = sa.send_email(
+    from_="Acme <hi@acme.com>",
+    to="user@example.com",
+    subject="Welcome",
+    body="<h1>Hi 👋</h1>",
+)
+status = sa.get_message(msg["id"])
+```
+
+### Currency
+
+```python
+sa.convert("USD", "EUR", 250)
+sa.rates("USD")
+sa.currencies()
+```
+
+### Push
+
+```python
+sa.send_push(
+    "app_id",
+    target={"userRef": "u_123"},
+    title="Your order shipped",
+    body="Track it in the app.",
+)
+```
+
+### Social
+
+```python
+channels = sa.list_channels()
+
+post = sa.schedule_post(
+    channels=[c["id"] for c in channels],
+    content="We just shipped 🚀",
+    # scheduled_for="2026-08-01T09:00:00Z"  # omit to publish now
+)
+
+sa.list_posts()
+```
+
+### Audiences
+
+```python
+sa.list_audiences()
+sa.add_contact("audience_id", email="new@example.com", first_name="Ada")
+```
+
+## Configuration
+
+```python
+Client(
+    "sk_your_key",
+    base_url="http://localhost:8080",  # self-host / testing
+    timeout=30.0,                       # per-request timeout (seconds)
+)
+```
+
+## Errors
+
+Non-2xx responses raise `StartupAidError` with the status code and message:
+
+```python
+from startupaid import StartupAidError
+
+try:
+    sa.convert("USD", "NGN", 1)
+except StartupAidError as err:
+    print(err.status, err.message)
+```
+
+Each method requires your account to be subscribed to the matching product
+(email, currency, push, social); otherwise the API returns an upgrade prompt.
+
+## License
+
+MIT

startupaid-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "startupaid"
+version = "0.1.0"
+description = "Official Python SDK for startupAid — send email & push, schedule social posts, and convert currency."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "startupAid" }]
+keywords = ["startupaid", "email", "push", "social", "currency", "api", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://startupaid.org"
+Source = "https://github.com/StartupAid-Org/startupaid-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/startupaid"]

startupaid-0.1.0/src/startupaid/__init__.py

@@ -0,0 +1,210 @@
+"""Official Python SDK for startupAid.
+
+Send transactional email, send push, schedule social posts, and convert currency
+with your account API key.
+
+    from startupaid import Client
+
+    sa = Client("sk_your_key")
+    res = sa.convert("USD", "NGN", 100)
+    print(res["result"])
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+__all__ = ["Client", "StartupAidError", "DEFAULT_BASE_URL", "__version__"]
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.startupaid.org"
+
+
+class StartupAidError(Exception):
+    """Raised when the API responds with a non-2xx status."""
+
+    def __init__(self, status: int, message: str) -> None:
+        super().__init__(f"startupaid: {status}: {message}")
+        self.status = status
+        self.message = message
+
+
+class Client:
+    """A startupAid API client.
+
+    Args:
+        api_key: Your account API key.
+        base_url: Override the API base URL (self-hosting / testing).
+        timeout: Per-request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ---- transport ----
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        query: dict[str, Any] | None = None,
+        body: Any | None = None,
+    ) -> Any:
+        url = self.base_url + path
+        if query:
+            clean = {k: v for k, v in query.items() if v is not None}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean)
+
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Authorization", f"Bearer {self.api_key}")
+        req.add_header("Accept", "application/json")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                text = resp.read().decode()
+                return json.loads(text) if text else {}
+        except urllib.error.HTTPError as exc:
+            text = exc.read().decode()
+            message = text.strip()
+            try:
+                parsed = json.loads(text)
+                if isinstance(parsed, dict) and parsed.get("error"):
+                    message = str(parsed["error"])
+            except ValueError:
+                pass
+            raise StartupAidError(exc.code, message) from None
+
+    # ---- Email ----
+
+    def send_email(
+        self,
+        *,
+        from_: str,
+        to: str,
+        subject: str | None = None,
+        body: str | None = None,
+        template: str | None = None,
+        variables: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a transactional email. Provide ``body`` (HTML) or a ``template``."""
+        payload: dict[str, Any] = {"from": from_, "to": to}
+        if subject is not None:
+            payload["subject"] = subject
+        if body is not None:
+            payload["body"] = body
+        if template is not None:
+            payload["template"] = template
+        if variables is not None:
+            payload["variables"] = variables
+        return self._request("POST", "/v1/send", body=payload)
+
+    def get_message(self, message_id: str) -> dict[str, Any]:
+        """Look up a sent email's status by id."""
+        return self._request("GET", f"/v1/messages/{urllib.parse.quote(message_id)}")
+
+    # ---- Currency ----
+
+    def convert(self, from_: str, to: str, amount: float = 1) -> dict[str, Any]:
+        """Convert an amount between two currencies at live rates."""
+        return self._request("GET", "/v1/convert", query={"from": from_, "to": to, "amount": amount})
+
+    def rates(self, base: str) -> dict[str, Any]:
+        """Exchange rates for a base currency against all supported currencies."""
+        return self._request("GET", f"/v1/rates/{urllib.parse.quote(base)}")
+
+    def currencies(self) -> Any:
+        """List supported currencies."""
+        return self._request("GET", "/v1/currencies")
+
+    # ---- Push ----
+
+    def send_push(
+        self,
+        app_id: str,
+        *,
+        target: dict[str, Any],
+        title: str | None = None,
+        body: str | None = None,
+        link: str | None = None,
+        data: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Send a push notification to devices in a push app.
+
+        ``target`` selects recipients, e.g. ``{"userRef": "u_1"}``,
+        ``{"tokens": [...]}`` or ``{"all": True}``.
+        """
+        payload: dict[str, Any] = {"target": target}
+        if title is not None:
+            payload["title"] = title
+        if body is not None:
+            payload["body"] = body
+        if link is not None:
+            payload["link"] = link
+        if data is not None:
+            payload["data"] = data
+        return self._request("POST", f"/v1/push/apps/{urllib.parse.quote(app_id)}/send", body=payload)
+
+    # ---- Social ----
+
+    def list_channels(self) -> list[dict[str, Any]]:
+        """List connected social channels (use their ids with ``schedule_post``)."""
+        return self._request("GET", "/v1/social/channels").get("channels", [])
+
+    def schedule_post(
+        self,
+        *,
+        channels: list[str],
+        content: str,
+        image_url: str | None = None,
+        scheduled_for: str | None = None,
+    ) -> dict[str, Any]:
+        """Schedule or immediately publish a post. Omit ``scheduled_for`` to publish now."""
+        payload: dict[str, Any] = {"channels": channels, "content": content}
+        if image_url is not None:
+            payload["imageUrl"] = image_url
+        if scheduled_for is not None:
+            payload["scheduledFor"] = scheduled_for
+        return self._request("POST", "/v1/social/schedule", body=payload)
+
+    def list_posts(self) -> list[dict[str, Any]]:
+        """List social posts with delivery status."""
+        return self._request("GET", "/v1/social/posts").get("posts", [])
+
+    # ---- Audiences ----
+
+    def list_audiences(self) -> list[dict[str, Any]]:
+        """List mailing lists."""
+        return self._request("GET", "/v1/audiences").get("audiences", [])
+
+    def add_contact(
+        self,
+        audience_id: str,
+        *,
+        email: str,
+        first_name: str | None = None,
+        last_name: str | None = None,
+    ) -> dict[str, Any]:
+        """Add a contact to a mailing list."""
+        payload: dict[str, Any] = {"email": email}
+        if first_name is not None:
+            payload["firstName"] = first_name
+        if last_name is not None:
+            payload["lastName"] = last_name
+        return self._request("POST", f"/v1/audiences/{urllib.parse.quote(audience_id)}/contacts", body=payload)