mecanik-api 1.0.0__py3-none-any.whl

mecanik_api/__init__.py

@@ -0,0 +1,6 @@
+"""Official Python client for the Mecanik API."""
+
+from .client import MecanikClient, MecanikError, Tools
+
+__all__ = ["MecanikClient", "MecanikError", "Tools"]
+__version__ = "1.0.0"

mecanik_api/client.py

@@ -0,0 +1,134 @@
+"""Official Python client for the Mecanik API.
+
+    from mecanik_api import MecanikClient
+
+    mecanik = MecanikClient(account_id="YOUR_UUID", token="YOUR_TOKEN")
+    result = mecanik.tools.security_headers(url="https://example.com")
+
+Get your account UUID and an API token from https://members.mecanik.dev
+(new accounts receive 100 free credits). Docs: https://api.mecanik.dev/docs
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import requests
+
+__all__ = ["MecanikClient", "MecanikError", "Tools"]
+
+
+class MecanikError(Exception):
+    """Raised when an endpoint returns ``success: false`` or a non-2xx status."""
+
+    def __init__(self, message: str, status: int, errors: list[dict]):
+        super().__init__(message)
+        self.status = status
+        self.errors = errors
+
+
+class MecanikClient:
+    def __init__(
+        self,
+        account_id: str,
+        token: str,
+        base_url: str = "https://api.mecanik.dev",
+        timeout: float = 30.0,
+        session: Optional[requests.Session] = None,
+    ):
+        if not account_id:
+            raise ValueError("account_id is required")
+        if not token:
+            raise ValueError("token is required")
+        self.account_id = account_id
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+        self.tools = Tools(self)
+
+    def raw(self, path: str, body: Optional[Dict[str, Any]] = None, method: str = "POST") -> Dict[str, Any]:
+        """Make a request and return the full ``{result, success, errors}`` envelope."""
+        url = f"{self.base_url}/v1/client/{self.account_id}{path}"
+        headers = {"Authorization": f"Bearer {self.token}"}
+        if method.upper() == "POST":
+            headers["Content-Type"] = "application/json"
+            resp = self._session.post(url, json=body or {}, headers=headers, timeout=self.timeout)
+        else:
+            resp = self._session.get(url, headers=headers, timeout=self.timeout)
+        try:
+            return resp.json()
+        except ValueError:
+            raise MecanikError(f"Invalid JSON response (HTTP {resp.status_code}).", resp.status_code, [])
+
+    def call(self, path: str, body: Optional[Dict[str, Any]] = None, method: str = "POST") -> Any:
+        """Call an endpoint and return just the ``result``; raises :class:`MecanikError` on failure."""
+        data = self.raw(path, body, method)
+        if not data.get("success"):
+            errors = data.get("errors") or []
+            first = errors[0] if errors else {}
+            raise MecanikError(first.get("message", "Request failed."), first.get("code", 0), errors)
+        return data.get("result")
+
+    def _tool(self, slug: str, body: Dict[str, Any]) -> Any:
+        return self.call(f"/tools/{slug}", body)
+
+    # Account
+    def account(self) -> Any:
+        return self.call("/account", method="GET")
+
+    def token_info(self) -> Any:
+        return self.call("/account/token", method="GET")
+
+    def credits(self) -> Any:
+        return self.call("/account/credits", method="GET")
+
+    def list_tools(self) -> Any:
+        return self.call("/tools", method="GET")
+
+
+class Tools:
+    def __init__(self, client: MecanikClient):
+        self._c = client
+
+    # AI-Powered
+    def ai_code_review(self, **body: Any) -> Any: return self._c._tool("ai-code-review", body)
+    def ai_content_summarize(self, **body: Any) -> Any: return self._c._tool("ai-content-summarize", body)
+    def ai_seo_generate(self, **body: Any) -> Any: return self._c._tool("ai-seo-generate", body)
+    def ai_translate(self, **body: Any) -> Any: return self._c._tool("ai-translate", body)
+    def ai_chat(self, **body: Any) -> Any: return self._c._tool("ai-chat", body)
+    def ai_image_generate(self, **body: Any) -> Any: return self._c._tool("ai-image-generate", body)
+    def ai_extract(self, **body: Any) -> Any: return self._c._tool("ai-extract", body)
+    def ai_alt_text(self, **body: Any) -> Any: return self._c._tool("ai-alt-text", body)
+    def ai_moderation(self, **body: Any) -> Any: return self._c._tool("ai-moderation", body)
+
+    # Security & Website Analysis
+    def security_headers(self, **body: Any) -> Any: return self._c._tool("security-headers", body)
+    def tls_check(self, **body: Any) -> Any: return self._c._tool("tls-check", body)
+    def tech_detect(self, **body: Any) -> Any: return self._c._tool("tech-detect", body)
+    def seo_analyze(self, **body: Any) -> Any: return self._c._tool("seo-analyze", body)
+    def dns_lookup(self, **body: Any) -> Any: return self._c._tool("dns-lookup", body)
+    def openapi_validate(self, **body: Any) -> Any: return self._c._tool("openapi-validate", body)
+    def subdomain_finder(self, **body: Any) -> Any: return self._c._tool("subdomain-finder", body)
+    def exposed_files(self, **body: Any) -> Any: return self._c._tool("exposed-files", body)
+
+    # Email Tools
+    def email_deliverability(self, **body: Any) -> Any: return self._c._tool("email-deliverability", body)
+    def email_validator(self, **body: Any) -> Any: return self._c._tool("email-validator", body)
+    def email_validator_bulk(self, **body: Any) -> Any: return self._c._tool("email-validator-bulk", body)
+
+    # Premium Reports
+    def website_audit(self, **body: Any) -> Any: return self._c._tool("website-audit", body)
+    def performance_audit(self, **body: Any) -> Any: return self._c._tool("performance-audit", body)
+    def broken_link_checker(self, **body: Any) -> Any: return self._c._tool("broken-link-checker", body)
+    def carbon_footprint(self, **body: Any) -> Any: return self._c._tool("carbon-footprint", body)
+
+    # Developer Utilities
+    def qr_generate(self, **body: Any) -> Any: return self._c._tool("qr-generate", body)
+    def placeholder_image(self, query: str) -> Any: return self._c.call(f"/tools/placeholder-image?{query}", method="GET")
+    def hash_generate(self, **body: Any) -> Any: return self._c._tool("hash-generate", body)
+    def jwt_decode(self, **body: Any) -> Any: return self._c._tool("jwt-decode", body)
+    def password_strength(self, **body: Any) -> Any: return self._c._tool("password-strength", body)
+    def cron_explain(self, **body: Any) -> Any: return self._c._tool("cron-explain", body)
+    def token_counter(self, **body: Any) -> Any: return self._c._tool("token-counter", body)
+    def json_to_code(self, **body: Any) -> Any: return self._c._tool("json-to-code", body)

mecanik_api-1.0.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: mecanik-api
+Version: 1.0.0
+Summary: Official Python client for the Mecanik API: AI, security analysis, email, reports and developer utility endpoints.
+Author: Mecanik
+License: MIT
+Project-URL: Homepage, https://mecanik.dev/en/api/
+Project-URL: Documentation, https://api.mecanik.dev/docs
+Project-URL: Source, https://github.com/Mecanik-Dev/mecanik-sdk-python
+Keywords: mecanik,api,sdk,security,ai,dns,seo,email-validation,developer-tools
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Dynamic: license-file
+
+# Mecanik API (Python)
+
+Official Python client for the [Mecanik API](https://mecanik.dev/en/api/): AI, security analysis, email, reports and developer utility endpoints. Pay-per-use credits, no subscription.
+
+**New accounts get 100 free credits.** Grab your account UUID and an API token at [members.mecanik.dev](https://members.mecanik.dev). Full reference: [api.mecanik.dev/docs](https://api.mecanik.dev/docs).
+
+## Install
+
+```bash
+pip install mecanik-api
+```
+
+## Quick start
+
+```python
+from mecanik_api import MecanikClient
+
+mecanik = MecanikClient(account_id="YOUR_ACCOUNT_UUID", token="YOUR_API_TOKEN")
+
+# Each tool returns just the `result`, and raises MecanikError on failure.
+headers = mecanik.tools.security_headers(url="https://example.com")
+print(headers["grade"], headers["score"])
+
+tokens = mecanik.tools.token_counter(text="Hello world", models=["gpt-4o", "claude-sonnet-4-6"])
+audit = mecanik.tools.website_audit(url="https://example.com")
+balance = mecanik.credits()  # {"credits": ...}
+```
+
+## Error handling
+
+```python
+from mecanik_api import MecanikError
+
+try:
+    mecanik.tools.dns_lookup(domain="example.com")
+except MecanikError as err:
+    print(err.status, str(err), err.errors)
+    # status 402 -> out of credits; 403 -> bad token; 429 -> rate limited
+```
+
+## Lower-level access
+
+```python
+# Full envelope {"result", "success", "errors"}
+res = mecanik.raw("/tools/dns-lookup", {"domain": "example.com"})
+
+# Any endpoint by path
+result = mecanik.call("/tools/hash-generate", {"input": "hello", "algorithm": "sha256"})
+```
+
+## Available tools
+
+`mecanik.tools.*` provides one method per endpoint:
+
+- **AI:** `ai_code_review`, `ai_content_summarize`, `ai_seo_generate`, `ai_translate`, `ai_chat`, `ai_image_generate`, `ai_extract`, `ai_alt_text`, `ai_moderation`
+- **Security:** `security_headers`, `tls_check`, `tech_detect`, `seo_analyze`, `dns_lookup`, `openapi_validate`, `subdomain_finder`, `exposed_files`
+- **Email:** `email_deliverability`, `email_validator`, `email_validator_bulk`
+- **Reports:** `website_audit`, `performance_audit`, `broken_link_checker`, `carbon_footprint`
+- **Utilities:** `qr_generate`, `placeholder_image`, `hash_generate`, `jwt_decode`, `password_strength`, `cron_explain`, `token_counter`, `json_to_code`
+
+Account helpers: `account()`, `token_info()`, `credits()`, `list_tools()`.
+
+The machine-readable spec is at [api.mecanik.dev/openapi.json](https://api.mecanik.dev/openapi.json).
+
+## License
+
+MIT

mecanik_api-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mecanik_api/__init__.py,sha256=Nby05l6yYVNYJUU5kLibB0_CMrIeWt6vmB7S2EHo9IE,182
+mecanik_api/client.py,sha256=QoDylXPfOWQkXmW0EA5Luc-fisBjt5Hcq9DOx7Xdccs,6478
+mecanik_api-1.0.0.dist-info/licenses/LICENSE,sha256=bXoa7yEvJOJUauesqgPXq9A4EuYj4xRf0SBVXqn3ZKM,1072
+mecanik_api-1.0.0.dist-info/METADATA,sha256=-IGO2c4i0cvgExHG4PNlvi3d0NoVvNbOcQlo6dyNzXU,3143
+mecanik_api-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mecanik_api-1.0.0.dist-info/top_level.txt,sha256=A6Z8oSU285fkY0Kn2onUkaZHixlv6ZDnds7EV5rIW7Q,12
+mecanik_api-1.0.0.dist-info/RECORD,,

mecanik_api-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mecanik_api-1.0.0.dist-info/licenses/LICENSE

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

mecanik_api-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mecanik_api