hermers 0.1.0__tar.gz

hermers-0.1.0/LICENSE

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

hermers-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: hermers
+Version: 0.1.0
+Summary: Official Hermers SDK - REST + gRPC clients (API key auth)
+Author: Aduki
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aduki-org/hermers-py
+Project-URL: Repository, https://github.com/aduki-org/hermers-py
+Project-URL: Documentation, https://aduki-org.github.io/hermers-py
+Project-URL: Issues, https://github.com/aduki-org/hermers-py/issues
+Keywords: hermes,hermers,sdk,rest,grpc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: grpcio
+Requires-Dist: protobuf
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Dynamic: license-file
+
+# hermers
+
+Open-source **Python** client for Hermers with REST and native gRPC in **one package**.
+
+The Hermers **server is private / proprietary**. This repository is the public SDK only and does
+not include or publish server source.
+
+| Client | Import | Default endpoint |
+| --- | --- | --- |
+| `Hermes` | `hermers` | `https://hermers.aduki.pro/v1` |
+| `HermesGrpc` | `hermers` | `grpc.aduki.pro:443` |
+
+## Requirements
+
+- Python **3.11+**
+
+## Install
+
+```bash
+pip install hermers
+```
+
+## Quickstart (REST)
+
+```python
+from hermers import Hermes
+
+hermes = Hermes("hm_live_xxxxxxxxxxxxxxxxxxxxxxxx")
+me = hermes.ready()
+print(me.tenant, me.user)
+
+contacts = hermes.contacts.list({"limit": 50})
+print(contacts["total"])
+```
+
+## Quickstart (gRPC)
+
+```python
+from hermers import HermesGrpc
+
+client = HermesGrpc("hm_live_xxxxxxxxxxxxxxxxxxxxxxxx")
+client.ready()
+print(client.me.tenant, client.me.user)
+
+mailboxes = client.mail.list_mailboxes()
+print(len(mailboxes.items))
+client.close()
+```
+
+For resource-by-resource examples, see `docs/rest/README.md` and `docs/grpc/README.md`.
+
+## Authentication
+
+**API key only**:
+
+- REST: `Authorization: Key <key>`
+- gRPC metadata: `authorization: Key <key>`
+
+The SDK does not expose login, password, or JWT refresh helpers. Prefer `ready()` before the first
+resource call. Callers never pass tenant/user hex for scoped resource methods because both clients
+cache `whoami`.
+
+## Resources
+
+REST properties:
+
+- `contacts`
+- `mail`
+- `keys`
+- `user`
+- `tenant`
+- `calendar`
+- `events`
+- `feeds`
+- `scheduling`
+
+gRPC properties:
+
+- `contacts`
+- `mail`
+- `feeds`
+- `storage`
+- `sync`
+- `security`
+- `spam`
+- `tier`
+- `usage`
+- `session`
+
+The clean top-level API stays available via `hermers.Hermes` / `hermers.HermesGrpc`, while the
+implementation is organized under `hermers.rest.*` and `hermers.grpc.*`.
+
+## Testing
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+# for live tests, set the API-key environment variable expected by the test suite
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+Without a live API key configured, the unit suites still run and the live REST/gRPC tests no-op.
+Never commit secrets or local environment files.
+
+## Docs
+
+Developer docs live under `docs/` and publish with
+**[mdBook](https://rust-lang.github.io/mdBook/)**.
+
+The book source is assembled from `docs/` plus this repository `README.md` into `book/`, then
+built into `site/` for GitHub Pages.
+
+Requires `mdbook` on `PATH`.
+
+```bash
+make docs-prepare
+make docs-build
+make docs-check
+make docs-serve
+make docs
+```
+
+## License
+
+MIT

hermers-0.1.0/README.md

@@ -0,0 +1,124 @@
+# hermers
+
+Open-source **Python** client for Hermers with REST and native gRPC in **one package**.
+
+The Hermers **server is private / proprietary**. This repository is the public SDK only and does
+not include or publish server source.
+
+| Client | Import | Default endpoint |
+| --- | --- | --- |
+| `Hermes` | `hermers` | `https://hermers.aduki.pro/v1` |
+| `HermesGrpc` | `hermers` | `grpc.aduki.pro:443` |
+
+## Requirements
+
+- Python **3.11+**
+
+## Install
+
+```bash
+pip install hermers
+```
+
+## Quickstart (REST)
+
+```python
+from hermers import Hermes
+
+hermes = Hermes("hm_live_xxxxxxxxxxxxxxxxxxxxxxxx")
+me = hermes.ready()
+print(me.tenant, me.user)
+
+contacts = hermes.contacts.list({"limit": 50})
+print(contacts["total"])
+```
+
+## Quickstart (gRPC)
+
+```python
+from hermers import HermesGrpc
+
+client = HermesGrpc("hm_live_xxxxxxxxxxxxxxxxxxxxxxxx")
+client.ready()
+print(client.me.tenant, client.me.user)
+
+mailboxes = client.mail.list_mailboxes()
+print(len(mailboxes.items))
+client.close()
+```
+
+For resource-by-resource examples, see `docs/rest/README.md` and `docs/grpc/README.md`.
+
+## Authentication
+
+**API key only**:
+
+- REST: `Authorization: Key <key>`
+- gRPC metadata: `authorization: Key <key>`
+
+The SDK does not expose login, password, or JWT refresh helpers. Prefer `ready()` before the first
+resource call. Callers never pass tenant/user hex for scoped resource methods because both clients
+cache `whoami`.
+
+## Resources
+
+REST properties:
+
+- `contacts`
+- `mail`
+- `keys`
+- `user`
+- `tenant`
+- `calendar`
+- `events`
+- `feeds`
+- `scheduling`
+
+gRPC properties:
+
+- `contacts`
+- `mail`
+- `feeds`
+- `storage`
+- `sync`
+- `security`
+- `spam`
+- `tier`
+- `usage`
+- `session`
+
+The clean top-level API stays available via `hermers.Hermes` / `hermers.HermesGrpc`, while the
+implementation is organized under `hermers.rest.*` and `hermers.grpc.*`.
+
+## Testing
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+# for live tests, set the API-key environment variable expected by the test suite
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+Without a live API key configured, the unit suites still run and the live REST/gRPC tests no-op.
+Never commit secrets or local environment files.
+
+## Docs
+
+Developer docs live under `docs/` and publish with
+**[mdBook](https://rust-lang.github.io/mdBook/)**.
+
+The book source is assembled from `docs/` plus this repository `README.md` into `book/`, then
+built into `site/` for GitHub Pages.
+
+Requires `mdbook` on `PATH`.
+
+```bash
+make docs-prepare
+make docs-build
+make docs-check
+make docs-serve
+make docs
+```
+
+## License
+
+MIT

hermers-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hermers"
+version = "0.1.0"
+description = "Official Hermers SDK - REST + gRPC clients (API key auth)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Aduki" }]
+keywords = ["hermes", "hermers", "sdk", "rest", "grpc"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Internet",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "grpcio",
+  "protobuf",
+]
+
+[project.urls]
+Homepage = "https://github.com/aduki-org/hermers-py"
+Repository = "https://github.com/aduki-org/hermers-py"
+Documentation = "https://aduki-org.github.io/hermers-py"
+Issues = "https://github.com/aduki-org/hermers-py/issues"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]

hermers-0.1.0/setup.cfg

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

hermers-0.1.0/src/hermers/__init__.py

@@ -0,0 +1,18 @@
+from .client import BASE_URL, Hermes, HermesOptions, Identity, new
+from .errors import HermesError, HermesGrpcError
+from .grpc.client import BASE_ENDPOINT, GrpcIdentity, HermesGrpc, HermesGrpcOptions, connect
+
+__all__ = [
+    "BASE_ENDPOINT",
+    "BASE_URL",
+    "GrpcIdentity",
+    "Hermes",
+    "HermesError",
+    "HermesGrpc",
+    "HermesGrpcError",
+    "HermesGrpcOptions",
+    "HermesOptions",
+    "Identity",
+    "connect",
+    "new",
+]

hermers-0.1.0/src/hermers/client.py

@@ -0,0 +1,3 @@
+from .rest.client import BASE_URL, Hermes, HermesOptions, HttpClient, Identity, new
+
+__all__ = ["BASE_URL", "Hermes", "HermesOptions", "HttpClient", "Identity", "new"]

hermers-0.1.0/src/hermers/crypto.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import hashlib
+import secrets
+
+
+def generate_key() -> str:
+    return f"hm_live_{secrets.token_urlsafe(24)}"
+
+
+def hash_key(raw_key: str) -> str:
+    return hashlib.sha256(raw_key.encode("utf-8")).hexdigest()
+
+
+def prefix_key(raw_key: str, *, limit: int = 16) -> str:
+    return raw_key[:limit]

hermers-0.1.0/src/hermers/errors.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True)
+class ErrorPayload:
+    message: str
+    status: int = 0
+    code: str = "unknown_error"
+    field: str | None = None
+    request_id: str | None = None
+    body: Any = None
+
+
+class HermesError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str = "unknown_error",
+        field: str | None = None,
+        request_id: str | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.field = field
+        self.request_id = request_id
+        self.body = body
+
+    @classmethod
+    def from_http(cls, status: int, status_text: str, body: Any) -> "HermesError":
+        if isinstance(body, dict) and isinstance(body.get("error"), dict):
+            error = body["error"]
+            return cls(
+                str(error.get("message") or status_text or "Request failed"),
+                status=status,
+                code=str(error.get("code") or "request_failed"),
+                field=error.get("field"),
+                request_id=error.get("request_id"),
+                body=body,
+            )
+        return cls(status_text or "Request failed", status=status, code="request_failed", body=body)
+
+
+class HermesGrpcError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "UNKNOWN",
+        details: str | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.details = details
+        self.body = body
+
+    @classmethod
+    def from_rpc_error(cls, err: Exception) -> "HermesGrpcError":
+        code = getattr(getattr(err, "code", lambda: None)(), "name", "UNKNOWN")
+        details = getattr(err, "details", lambda: None)()
+        return cls(details or str(err), code=code, details=details, body=err)

hermers-0.1.0/src/hermers/generated/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# grpc_tools generates sibling imports like `import contact_pb2`.
+# Put this package directory on sys.path so those imports resolve.
+pkg_dir = str(Path(__file__).resolve().parent)
+if pkg_dir not in sys.path:
+    sys.path.append(pkg_dir)

hermers-0.1.0/src/hermers/generated/contact_pb2.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: contact.proto
+# Protobuf Python Version: 7.35.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    7,
+    35,
+    1,
+    '',
+    'contact.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\rcontact.proto\x12\x0ehermes.contact\x1a\x1fgoogle/protobuf/timestamp.proto\"\xac\x01\n\x07\x43ontact\x12\x0b\n\x03hex\x18\x01 \x01(\t\x12\x0e\n\x06tenant\x18\x02 \x01(\t\x12\r\n\x05owner\x18\x03 \x01(\t\x12\r\n\x05vcard\x18\x04 \x01(\t\x12\x0c\n\x04\x65tag\x18\x05 \x01(\t\x12+\n\x07\x63reated\x18\x06 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12+\n\x07updated\x18\x07 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"8\n\x07ListReq\x12\x0e\n\x06tenant\x18\x01 \x01(\t\x12\x0e\n\x06\x63ursor\x18\x02 \x01(\t\x12\r\n\x05limit\x18\x03 \x01(\r\"@\n\x08ListResp\x12&\n\x05items\x18\x01 \x03(\x0b\x32\x17.hermes.contact.Contact\x12\x0c\n\x04next\x18\x02 \x01(\t\"\x15\n\x06GetReq\x12\x0b\n\x03hex\x18\x01 \x01(\t\"9\n\tCreateReq\x12\x0e\n\x06tenant\x18\x01 \x01(\t\x12\r\n\x05owner\x18\x02 \x01(\t\x12\r\n\x05vcard\x18\x03 \x01(\t\"5\n\tUpdateReq\x12\x0b\n\x03hex\x18\x01 \x01(\t\x12\r\n\x05vcard\x18\x02 \x01(\t\x12\x0c\n\x04\x65tag\x18\x03 \x01(\t\"\x18\n\tRemoveReq\x12\x0b\n\x03hex\x18\x01 \x01(\t\"\x0c\n\nRemoveResp\"D\n\x07SyncReq\x12\x0e\n\x06tenant\x18\x01 \x01(\t\x12)\n\x05since\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"E\n\x08SyncResp\x12(\n\x07\x63hanged\x18\x01 \x03(\x0b\x32\x17.hermes.contact.Contact\x12\x0f\n\x07removed\x18\x02 \x03(\t2\xfb\x02\n\x0e\x43ontactService\x12\x39\n\x04List\x12\x17.hermes.contact.ListReq\x1a\x18.hermes.contact.ListResp\x12\x36\n\x03Get\x12\x16.hermes.contact.GetReq\x1a\x17.hermes.contact.Contact\x12<\n\x06\x43reate\x12\x19.hermes.contact.CreateReq\x1a\x17.hermes.contact.Contact\x12<\n\x06Update\x12\x19.hermes.contact.UpdateReq\x1a\x17.hermes.contact.Contact\x12?\n\x06Remove\x12\x19.hermes.contact.RemoveReq\x1a\x1a.hermes.contact.RemoveResp\x12\x39\n\x04Sync\x12\x17.hermes.contact.SyncReq\x1a\x18.hermes.contact.SyncRespb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'contact_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_CONTACT']._serialized_start=67
+  _globals['_CONTACT']._serialized_end=239
+  _globals['_LISTREQ']._serialized_start=241
+  _globals['_LISTREQ']._serialized_end=297
+  _globals['_LISTRESP']._serialized_start=299
+  _globals['_LISTRESP']._serialized_end=363
+  _globals['_GETREQ']._serialized_start=365
+  _globals['_GETREQ']._serialized_end=386
+  _globals['_CREATEREQ']._serialized_start=388
+  _globals['_CREATEREQ']._serialized_end=445
+  _globals['_UPDATEREQ']._serialized_start=447
+  _globals['_UPDATEREQ']._serialized_end=500
+  _globals['_REMOVEREQ']._serialized_start=502
+  _globals['_REMOVEREQ']._serialized_end=526
+  _globals['_REMOVERESP']._serialized_start=528
+  _globals['_REMOVERESP']._serialized_end=540
+  _globals['_SYNCREQ']._serialized_start=542
+  _globals['_SYNCREQ']._serialized_end=610
+  _globals['_SYNCRESP']._serialized_start=612
+  _globals['_SYNCRESP']._serialized_end=681
+  _globals['_CONTACTSERVICE']._serialized_start=684
+  _globals['_CONTACTSERVICE']._serialized_end=1063
+# @@protoc_insertion_point(module_scope)