anaella 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,5 @@
1
+ .venv/
2
+ __pycache__/
3
+ .pytest_cache/
4
+ *.egg-info/
5
+ dist/
anaella-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Isaac Gounton
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
anaella-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,122 @@
1
+ Metadata-Version: 2.5
2
+ Name: anaella
3
+ Version: 0.1.0
4
+ Summary: Python client for Anaella, one API for agents: find, explain and run tools, connect accounts, publish posts.
5
+ Project-URL: Homepage, https://anaella.com
6
+ Project-URL: Documentation, https://anaella.com/for-agents
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Keywords: agents,anaella,api,automation,mcp,social media
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Typing :: Typed
13
+ Requires-Python: >=3.9
14
+ Requires-Dist: httpx<1,>=0.25
15
+ Requires-Dist: typing-extensions>=4.6
16
+ Description-Content-Type: text/markdown
17
+
18
+ # anaella
19
+
20
+ A small Python client for the [Anaella](https://anaella.com) `/v1` API, one API for agents: typed
21
+ tools (web research, SEO, images and video, documents, phone, meetings) plus the accounts you
22
+ connect (mail, calendars, Drive, Slack, ads, payments, social, WordPress and Ghost sites, any MCP
23
+ server). It mirrors [`@anaella/client`](https://www.npmjs.com/package/@anaella/client): same
24
+ calls, same response shapes.
25
+
26
+ ```sh
27
+ pip install anaella
28
+ ```
29
+
30
+ One runtime dependency (`httpx`), Python 3.9+.
31
+
32
+ ```python
33
+ from anaella import AnaellaClient
34
+
35
+ anaella = AnaellaClient() # reads ANAELLA_API_KEY (create one under Settings → API keys)
36
+
37
+ tools = anaella.find("unread emails") # capabilities for a task
38
+ spec = anaella.explain("email.messages.list") # its input schema and price
39
+ job = anaella.do("email.messages.list", {"query": "is:unread"})
40
+ done = anaella.wait_for_job(job["id"]) # async tools return a queued job
41
+ ```
42
+
43
+ Async code uses `AsyncAnaellaClient`, which has the same methods, awaited:
44
+
45
+ ```python
46
+ from anaella import AsyncAnaellaClient
47
+
48
+ async with AsyncAnaellaClient() as anaella:
49
+ job = await anaella.do("web.search", {"query": "anaella"})
50
+ ```
51
+
52
+ ## What it covers
53
+
54
+ - **Tools:** `find(q)`, `explain(id)`, `do(id, input)`, `job(id)`, `wait_for_job(id)`, `balance()`.
55
+ - **Accounts:** `list_channels()`, `create_connect_session()`, `connect_with_credentials()`,
56
+ `import_connection()`, `delete_channel(id)`, `request()` for raw calls to a connected account's API.
57
+ - **Social posts:** `create_post`, `update_post`, `list_posts`, `get_post`, `delete_post`,
58
+ `get_analytics`, `get_post_analytics`, plus `upload_urls` / `upload_files` for media.
59
+ - **Webhooks:** `create_webhook`, `list_webhooks`, `delete_webhook`, `get_webhook_deliveries`,
60
+ and `verify_webhook_signature` for the requests Anaella sends you.
61
+
62
+ Responses are plain dicts with the API's own keys (`job["costUsd"]`), typed with `TypedDict`s in
63
+ `anaella.types` for editors and type checkers. Request bodies are plain dicts too, so a new API
64
+ field works before the client knows about it.
65
+
66
+ ## Building for your own users
67
+
68
+ If your app lets *its* users connect their accounts, pass `external_user_id` on every call made
69
+ for one of them. Anaella then refuses a channel that isn't theirs (403 `end_user_mismatch`):
70
+
71
+ ```python
72
+ link = anaella.create_connect_session(
73
+ {"platform": "gmail", "externalUserId": "user_42", "returnUrl": "https://app.example.com/done"}
74
+ )
75
+ anaella.do("email.messages.list", {}, external_user_id="user_42")
76
+ anaella.list_channels(external_user_id="user_42")
77
+ ```
78
+
79
+ ## Errors
80
+
81
+ Any non-2xx response, and any network failure, raises `AnaellaApiError` with `status`, `code`,
82
+ `message`, and when present `details`, `next` (a connect or reconnect link) and `schema` (the JSON
83
+ Schema an `invalid_input` input should have matched):
84
+
85
+ ```python
86
+ from anaella import AnaellaApiError
87
+
88
+ try:
89
+ anaella.do("gsc.queries.list", {})
90
+ except AnaellaApiError as e:
91
+ if e.code == "channel_required":
92
+ print("Connect Search Console:", e.next)
93
+ elif e.code == "reconnect_required":
94
+ print("Reconnect:", e.next)
95
+ else:
96
+ raise
97
+ ```
98
+
99
+ Reads retry a gateway error (502, 503, 504) on their own. A write is sent once, since it may
100
+ have run.
101
+
102
+ ## Webhooks
103
+
104
+ ```python
105
+ from anaella import verify_webhook_signature
106
+
107
+ # raw_body: the request body exactly as received, before JSON parsing
108
+ if not verify_webhook_signature(raw_body, request.headers["X-Anaella-Signature"], secret):
109
+ return Response(status_code=401)
110
+ ```
111
+
112
+ ## Configuration
113
+
114
+ `AnaellaClient(api_key=None, *, base_url=None, timeout=60.0, http_client=None)`. The key falls
115
+ back to `ANAELLA_API_KEY` and the address to `ANAELLA_API_URL` (default
116
+ `https://api.anaella.com`). Pass your own `httpx.Client` / `httpx.AsyncClient` for proxies,
117
+ retries at the transport level, or tests. Use the client as a context manager (or call `close()`)
118
+ to release its connections.
119
+
120
+ ## License
121
+
122
+ MIT
@@ -0,0 +1,105 @@
1
+ # anaella
2
+
3
+ A small Python client for the [Anaella](https://anaella.com) `/v1` API, one API for agents: typed
4
+ tools (web research, SEO, images and video, documents, phone, meetings) plus the accounts you
5
+ connect (mail, calendars, Drive, Slack, ads, payments, social, WordPress and Ghost sites, any MCP
6
+ server). It mirrors [`@anaella/client`](https://www.npmjs.com/package/@anaella/client): same
7
+ calls, same response shapes.
8
+
9
+ ```sh
10
+ pip install anaella
11
+ ```
12
+
13
+ One runtime dependency (`httpx`), Python 3.9+.
14
+
15
+ ```python
16
+ from anaella import AnaellaClient
17
+
18
+ anaella = AnaellaClient() # reads ANAELLA_API_KEY (create one under Settings → API keys)
19
+
20
+ tools = anaella.find("unread emails") # capabilities for a task
21
+ spec = anaella.explain("email.messages.list") # its input schema and price
22
+ job = anaella.do("email.messages.list", {"query": "is:unread"})
23
+ done = anaella.wait_for_job(job["id"]) # async tools return a queued job
24
+ ```
25
+
26
+ Async code uses `AsyncAnaellaClient`, which has the same methods, awaited:
27
+
28
+ ```python
29
+ from anaella import AsyncAnaellaClient
30
+
31
+ async with AsyncAnaellaClient() as anaella:
32
+ job = await anaella.do("web.search", {"query": "anaella"})
33
+ ```
34
+
35
+ ## What it covers
36
+
37
+ - **Tools:** `find(q)`, `explain(id)`, `do(id, input)`, `job(id)`, `wait_for_job(id)`, `balance()`.
38
+ - **Accounts:** `list_channels()`, `create_connect_session()`, `connect_with_credentials()`,
39
+ `import_connection()`, `delete_channel(id)`, `request()` for raw calls to a connected account's API.
40
+ - **Social posts:** `create_post`, `update_post`, `list_posts`, `get_post`, `delete_post`,
41
+ `get_analytics`, `get_post_analytics`, plus `upload_urls` / `upload_files` for media.
42
+ - **Webhooks:** `create_webhook`, `list_webhooks`, `delete_webhook`, `get_webhook_deliveries`,
43
+ and `verify_webhook_signature` for the requests Anaella sends you.
44
+
45
+ Responses are plain dicts with the API's own keys (`job["costUsd"]`), typed with `TypedDict`s in
46
+ `anaella.types` for editors and type checkers. Request bodies are plain dicts too, so a new API
47
+ field works before the client knows about it.
48
+
49
+ ## Building for your own users
50
+
51
+ If your app lets *its* users connect their accounts, pass `external_user_id` on every call made
52
+ for one of them. Anaella then refuses a channel that isn't theirs (403 `end_user_mismatch`):
53
+
54
+ ```python
55
+ link = anaella.create_connect_session(
56
+ {"platform": "gmail", "externalUserId": "user_42", "returnUrl": "https://app.example.com/done"}
57
+ )
58
+ anaella.do("email.messages.list", {}, external_user_id="user_42")
59
+ anaella.list_channels(external_user_id="user_42")
60
+ ```
61
+
62
+ ## Errors
63
+
64
+ Any non-2xx response, and any network failure, raises `AnaellaApiError` with `status`, `code`,
65
+ `message`, and when present `details`, `next` (a connect or reconnect link) and `schema` (the JSON
66
+ Schema an `invalid_input` input should have matched):
67
+
68
+ ```python
69
+ from anaella import AnaellaApiError
70
+
71
+ try:
72
+ anaella.do("gsc.queries.list", {})
73
+ except AnaellaApiError as e:
74
+ if e.code == "channel_required":
75
+ print("Connect Search Console:", e.next)
76
+ elif e.code == "reconnect_required":
77
+ print("Reconnect:", e.next)
78
+ else:
79
+ raise
80
+ ```
81
+
82
+ Reads retry a gateway error (502, 503, 504) on their own. A write is sent once, since it may
83
+ have run.
84
+
85
+ ## Webhooks
86
+
87
+ ```python
88
+ from anaella import verify_webhook_signature
89
+
90
+ # raw_body: the request body exactly as received, before JSON parsing
91
+ if not verify_webhook_signature(raw_body, request.headers["X-Anaella-Signature"], secret):
92
+ return Response(status_code=401)
93
+ ```
94
+
95
+ ## Configuration
96
+
97
+ `AnaellaClient(api_key=None, *, base_url=None, timeout=60.0, http_client=None)`. The key falls
98
+ back to `ANAELLA_API_KEY` and the address to `ANAELLA_API_URL` (default
99
+ `https://api.anaella.com`). Pass your own `httpx.Client` / `httpx.AsyncClient` for proxies,
100
+ retries at the transport level, or tests. Use the client as a context manager (or call `close()`)
101
+ to release its connections.
102
+
103
+ ## License
104
+
105
+ MIT
@@ -0,0 +1,31 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "anaella"
7
+ version = "0.1.0"
8
+ description = "Python client for Anaella, one API for agents: find, explain and run tools, connect accounts, publish posts."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.9"
13
+ dependencies = ["httpx>=0.25,<1", "typing_extensions>=4.6"]
14
+ keywords = ["anaella", "agents", "api", "mcp", "social media", "automation"]
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3",
17
+ "Operating System :: OS Independent",
18
+ "Typing :: Typed",
19
+ ]
20
+
21
+ [project.urls]
22
+ Homepage = "https://anaella.com"
23
+ Documentation = "https://anaella.com/for-agents"
24
+
25
+ [tool.hatch.build.targets.wheel]
26
+ packages = ["src/anaella"]
27
+
28
+ [tool.pytest.ini_options]
29
+ testpaths = ["tests"]
30
+ asyncio_mode = "auto"
31
+ asyncio_default_fixture_loop_scope = "function"
@@ -0,0 +1,26 @@
1
+ """Python client for Anaella, one API for agents.
2
+
3
+ ```python
4
+ from anaella import AnaellaClient
5
+
6
+ anaella = AnaellaClient() # reads ANAELLA_API_KEY
7
+ print(anaella.find("unread emails"))
8
+ ```
9
+
10
+ `AsyncAnaellaClient` has the same methods, awaited.
11
+ """
12
+
13
+ from .client import AnaellaClient, AsyncAnaellaClient, UploadFile
14
+ from .errors import AnaellaApiError
15
+ from .webhooks import verify_webhook_signature
16
+
17
+ __version__ = "0.1.0"
18
+
19
+ __all__ = [
20
+ "AnaellaClient",
21
+ "AsyncAnaellaClient",
22
+ "AnaellaApiError",
23
+ "UploadFile",
24
+ "verify_webhook_signature",
25
+ "__version__",
26
+ ]
@@ -0,0 +1,198 @@
1
+ """Request building and response parsing shared by the sync and async clients."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from dataclasses import dataclass, field
7
+ from typing import Any, Dict, List, Mapping, Optional, Tuple
8
+ from urllib.parse import quote
9
+
10
+ from .errors import AnaellaApiError
11
+
12
+ DEFAULT_BASE_URL = "https://api.anaella.com"
13
+ GATEWAY = (502, 503, 504)
14
+ # Waits between tries of a read that met a gateway error (the proxy answers 502 for a moment
15
+ # during a deploy).
16
+ GATEWAY_RETRY_DELAYS = (0.5, 1.5)
17
+
18
+ _NO_BODY: Any = object()
19
+
20
+
21
+ @dataclass
22
+ class Req:
23
+ method: str
24
+ path: str
25
+ params: Optional[Dict[str, str]] = None
26
+ body: Any = _NO_BODY
27
+ headers: Dict[str, str] = field(default_factory=dict)
28
+ files: Optional[List[Tuple[str, Tuple[str, Any, str]]]] = None
29
+
30
+ @property
31
+ def has_body(self) -> bool:
32
+ return self.body is not _NO_BODY
33
+
34
+
35
+ def enc(value: str) -> str:
36
+ return quote(value, safe="")
37
+
38
+
39
+ def end_user(external_user_id: Optional[str]) -> Dict[str, str]:
40
+ """The end user a call is made for. Anaella then refuses a channel that isn't theirs."""
41
+ return {} if external_user_id is None else {"x-anaella-end-user": external_user_id}
42
+
43
+
44
+ def query(**values: Any) -> Optional[Dict[str, str]]:
45
+ out = {k: str(v) for k, v in values.items() if v is not None and v != ""}
46
+ return out or None
47
+
48
+
49
+ def is_gateway_error(e: BaseException) -> bool:
50
+ return isinstance(e, AnaellaApiError) and (e.status == 0 or e.status in GATEWAY)
51
+
52
+
53
+ def parse_error(status: int, raw: str) -> AnaellaApiError:
54
+ try:
55
+ parsed = json.loads(raw) if raw else None
56
+ except ValueError:
57
+ parsed = None
58
+ env = parsed.get("error") if isinstance(parsed, dict) else None
59
+ env = env if isinstance(env, dict) else {}
60
+ if env.get("message"):
61
+ message = str(env["message"])
62
+ elif status in GATEWAY:
63
+ message = f"Anaella is briefly unavailable (HTTP {status}). Try again in a moment."
64
+ else:
65
+ message = f"HTTP {status}" + (f": {raw[:200]}" if raw else "")
66
+ return AnaellaApiError(
67
+ status,
68
+ str(env.get("code") or "error"),
69
+ message,
70
+ env.get("details"),
71
+ env.get("next"),
72
+ env.get("schema"),
73
+ )
74
+
75
+
76
+ def parse_success(raw: str) -> Any:
77
+ if not raw:
78
+ return None
79
+ try:
80
+ return json.loads(raw)
81
+ except ValueError:
82
+ return None
83
+
84
+
85
+ # --- the API, one request per call -------------------------------------------------------------
86
+
87
+
88
+ def find(q: str = "", category: Optional[str] = None, limit: Optional[int] = None) -> Req:
89
+ return Req("GET", "/v1/find", query(q=q, category=category, limit=limit))
90
+
91
+
92
+ def explain(id: str) -> Req:
93
+ return Req("GET", f"/v1/explain/{enc(id)}")
94
+
95
+
96
+ def do(id: str, input: Any, external_user_id: Optional[str]) -> Req:
97
+ return Req("POST", f"/v1/do/{enc(id)}", body=input, headers=end_user(external_user_id))
98
+
99
+
100
+ def job(id: str, external_user_id: Optional[str]) -> Req:
101
+ return Req("GET", f"/v1/jobs/{enc(id)}", headers=end_user(external_user_id))
102
+
103
+
104
+ def balance() -> Req:
105
+ return Req("GET", "/v1/balance")
106
+
107
+
108
+ def list_channels(external_user_id: Optional[str], platform: Optional[str]) -> Req:
109
+ return Req("GET", "/v1/channels", query(externalUserId=external_user_id, platform=platform))
110
+
111
+
112
+ def create_connect_session(body: Mapping[str, Any], external_user_id: Optional[str]) -> Req:
113
+ return Req("POST", "/v1/connect/sessions", body=dict(body), headers=end_user(external_user_id))
114
+
115
+
116
+ def import_connection(body: Mapping[str, Any]) -> Req:
117
+ return Req("POST", "/v1/connect/import", body={**body, "oauthApp": "own"})
118
+
119
+
120
+ def connect_with_credentials(
121
+ platform: str, credentials: Mapping[str, str], external_user_id: Optional[str]
122
+ ) -> Req:
123
+ body: Dict[str, Any] = {"platform": platform, "credentials": dict(credentials)}
124
+ if external_user_id is not None:
125
+ body["externalUserId"] = external_user_id
126
+ return Req("POST", "/v1/connect/credentials", body=body)
127
+
128
+
129
+ def delete_channel(id: str, external_user_id: Optional[str]) -> Req:
130
+ return Req("DELETE", f"/v1/channels/{enc(id)}", headers=end_user(external_user_id))
131
+
132
+
133
+ def create_webhook(url: str, events: List[str]) -> Req:
134
+ return Req("POST", "/v1/webhooks", body={"url": url, "events": list(events)})
135
+
136
+
137
+ def list_webhooks() -> Req:
138
+ return Req("GET", "/v1/webhooks")
139
+
140
+
141
+ def delete_webhook(id: str) -> Req:
142
+ return Req("DELETE", f"/v1/webhooks/{enc(id)}")
143
+
144
+
145
+ def get_webhook_deliveries(id: str, limit: Optional[int], cursor: Optional[int]) -> Req:
146
+ return Req(
147
+ "GET", f"/v1/webhooks/{enc(id)}/deliveries", query(limit=limit, cursor=cursor)
148
+ )
149
+
150
+
151
+ def create_post(body: Mapping[str, Any], external_user_id: Optional[str]) -> Req:
152
+ return Req("POST", "/v1/posts", body=dict(body), headers=end_user(external_user_id))
153
+
154
+
155
+ def update_post(id: str, body: Mapping[str, Any], external_user_id: Optional[str]) -> Req:
156
+ return Req(
157
+ "PATCH", f"/v1/posts/{enc(id)}", body=dict(body), headers=end_user(external_user_id)
158
+ )
159
+
160
+
161
+ def list_posts(limit: Optional[int], cursor: Optional[int], external_user_id: Optional[str]) -> Req:
162
+ return Req(
163
+ "GET", "/v1/posts", query(limit=limit, cursor=cursor), headers=end_user(external_user_id)
164
+ )
165
+
166
+
167
+ def get_post(id: str, external_user_id: Optional[str]) -> Req:
168
+ return Req("GET", f"/v1/posts/{enc(id)}", headers=end_user(external_user_id))
169
+
170
+
171
+ def delete_post(id: str, external_user_id: Optional[str]) -> Req:
172
+ return Req("DELETE", f"/v1/posts/{enc(id)}", headers=end_user(external_user_id))
173
+
174
+
175
+ def get_analytics(period: Optional[str], external_user_id: Optional[str]) -> Req:
176
+ return Req("GET", "/v1/analytics", query(period=period), headers=end_user(external_user_id))
177
+
178
+
179
+ def get_post_analytics(id: str, period: Optional[str], external_user_id: Optional[str]) -> Req:
180
+ return Req(
181
+ "GET",
182
+ f"/v1/posts/{enc(id)}/analytics",
183
+ query(period=period),
184
+ headers=end_user(external_user_id),
185
+ )
186
+
187
+
188
+ def upload_urls(urls: List[str]) -> Req:
189
+ return Req("POST", "/v1/upload", body={"media": [{"url": u} for u in urls]})
190
+
191
+
192
+ def upload_files(files: List[Tuple[str, Any, Optional[str]]]) -> Req:
193
+ """`files`: (filename, bytes, content type) triples. The runtime sets the multipart boundary."""
194
+ return Req(
195
+ "POST",
196
+ "/v1/upload",
197
+ files=[("files", (name, data, ctype or "application/octet-stream")) for name, data, ctype in files],
198
+ )