qurl-python 0.2.1__py3-none-any.whl

layerv_qurl/errors.py

@@ -0,0 +1,152 @@
+"""Error types for the qURL API client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class QURLError(Exception):
+    """Error raised for API-level errors (4xx/5xx responses).
+
+    Carries the full RFC 7807 Problem Details shape when the API provides
+    it: ``status``, ``code``, ``title``, ``detail``, plus the optional
+    ``type`` (problem-type URI) and ``instance`` (occurrence URI).
+
+    .. note::
+
+       ``detail`` is **always non-empty** on the instance — the
+       constructor falls back to ``title`` when the API omits detail
+       (RFC 7807 allows this). Use ``code`` / ``status`` / ``type`` to
+       distinguish between error cases rather than inspecting ``detail``
+       for the "was it absent?" signal.
+
+    .. note::
+
+       ``type`` shadows Python's built-in ``type()`` inside method
+       bodies. This is intentional — the name mirrors the RFC 7807 field
+       name and matches the other SDKs (``qurl-typescript``,
+       ``qurl-mcp``). The shadowing only matters inside ``QURLError``
+       method definitions; external code can still use ``type(err)``
+       safely since attribute access doesn't shadow the builtin in that
+       scope.
+
+    Catch specific subclasses for fine-grained handling::
+
+        try:
+            client.resolve("at_xxx")
+        except AuthenticationError:
+            print("Bad API key")
+        except NotFoundError:
+            print("qURL doesn't exist")
+        except RateLimitError as e:
+            print(f"Rate limited — retry in {e.retry_after}s")
+        except QURLError as e:
+            print(f"API error: {e.status} {e.code}")
+            if e.type:
+                print(f"  problem type: {e.type}")
+    """
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        code: str,
+        title: str,
+        detail: str | None = None,
+        type: str | None = None,
+        instance: str | None = None,
+        invalid_fields: dict[str, str] | None = None,
+        request_id: str | None = None,
+        retry_after: int | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> None:
+        # RFC 7807 leaves `detail` optional, and `title` is always present.
+        # When `detail` is `None` (omitted), fall back to `title` so the
+        # Exception message stays meaningful instead of producing
+        # "Title (403): None". An explicit empty string is stored as-is —
+        # the caller opted in. Uses `is not None` rather than truthiness
+        # so `detail=""` is distinguishable from "not provided".
+        message_detail = detail if detail is not None else title
+        super().__init__(f"{title} ({status}): {message_detail}")
+        self.status = status
+        self.code = code
+        self.title = title
+        self.detail = message_detail
+        self.type = type
+        self.instance = instance
+        self.invalid_fields = invalid_fields
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.meta = meta
+
+
+class AuthenticationError(QURLError):
+    """401 Unauthorized — invalid or missing API key."""
+
+
+class AuthorizationError(QURLError):
+    """403 Forbidden — valid key but insufficient permissions/scope."""
+
+
+class NotFoundError(QURLError):
+    """404 Not Found — resource does not exist."""
+
+
+class ConflictError(QURLError):
+    """409 Conflict — resource already exists or cannot be mutated in this state."""
+
+
+class GoneError(QURLError):
+    """410 Gone — resource lifecycle has closed."""
+
+
+class ValidationError(QURLError):
+    """400/422 — invalid request parameters.
+
+    Check :attr:`invalid_fields` for per-field details::
+
+        except ValidationError as e:
+            if e.invalid_fields:
+                for field, reason in e.invalid_fields.items():
+                    print(f"  {field}: {reason}")
+    """
+
+
+class RateLimitError(QURLError):
+    """429 Too Many Requests.
+
+    Check :attr:`retry_after` for the server-suggested wait time::
+
+        except RateLimitError as e:
+            if e.retry_after:
+                time.sleep(e.retry_after)
+    """
+
+
+class ServerError(QURLError):
+    """5xx server-side error."""
+
+
+class QURLNetworkError(Exception):
+    """Error raised for transport-level failures (DNS, connection refused)."""
+
+    def __init__(self, message: str, cause: Exception | None = None) -> None:
+        super().__init__(message)
+        self.__cause__ = cause
+
+
+class QURLTimeoutError(QURLNetworkError):
+    """Error raised when a request times out.
+
+    Subclass of :class:`QURLNetworkError` — caught by
+    ``except QURLNetworkError`` but can also be caught specifically::
+
+        try:
+            client.resolve("at_xxx")
+        except QURLTimeoutError:
+            print("Request timed out — server may be slow")
+        except QURLNetworkError:
+            print("Network issue — DNS, connection, etc.")
+        except QURLError:
+            print("API error — 4xx/5xx")
+    """

layerv_qurl/langchain.py

@@ -0,0 +1,159 @@
+"""LangChain tool integration for qURL.
+
+Install with: pip install qurl-python[langchain]
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+try:
+    from langchain_core.tools import BaseTool
+
+    _HAS_LANGCHAIN = True
+except ImportError:
+    _HAS_LANGCHAIN = False
+    BaseTool = object  # type: ignore[misc,assignment]
+
+if TYPE_CHECKING:
+    from langchain_core.callbacks import CallbackManagerForToolRun
+
+    from layerv_qurl.client import QURLClient
+
+__all__ = [
+    "CreateQURLTool",
+    "DeleteQURLTool",
+    "ListQURLsTool",
+    "QURLToolkit",
+    "ResolveQURLTool",
+]
+
+
+class CreateQURLTool(BaseTool):
+    """Create a secure, time-limited access link to a protected URL."""
+
+    name: str = "create_qurl"
+    description: str = (
+        "Create a qURL — a secure, time-limited access link. "
+        "Input should be a JSON string with 'target_url' (required), "
+        "and optionally 'expires_in' (e.g. '24h', '7d'), 'label'."
+    )
+    client: Any = None  # QURLClient, typed as Any for Pydantic compatibility
+
+    def _run(
+        self,
+        target_url: str,
+        expires_in: str = "24h",
+        label: str | None = None,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> str:
+        result = self.client.create(
+            target_url=target_url,
+            expires_in=expires_in,
+            label=label,
+        )
+        return (
+            f"Created qURL {result.resource_id}\n"
+            f"Link: {result.qurl_link}\n"
+            f"Site: {result.qurl_site}\n"
+            f"Expires: {result.expires_at or 'N/A'}"
+        )
+
+
+class ResolveQURLTool(BaseTool):
+    """Resolve a qURL access token to grant network access."""
+
+    name: str = "resolve_qurl"
+    description: str = (
+        "Resolve a qURL access token to gain network access to the protected resource. "
+        "Input should be the access token string (e.g. 'at_k8xqp9h2sj9lx7r4a')."
+    )
+    client: Any = None
+
+    def _run(
+        self,
+        access_token: str,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> str:
+        result = self.client.resolve(access_token)
+        grant = result.access_grant
+        target = result.target_url or "<redacted>"
+        lines = [
+            f"Resolved: {target}",
+            f"Resource: {result.resource_id}",
+        ]
+        if grant:
+            lines.append(f"Access expires in: {grant.expires_in}s")
+            lines.append(f"Granted to IP: {grant.src_ip}")
+        return "\n".join(lines)
+
+
+class ListQURLsTool(BaseTool):
+    """List active qURL links."""
+
+    name: str = "list_qurls"
+    description: str = "List active qURL links. Optionally filter by status (active, revoked)."
+    client: Any = None
+
+    def _run(
+        self,
+        status: str = "active",
+        limit: int = 10,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> str:
+        result = self.client.list(status=status, limit=limit)
+        if not result.qurls:
+            return "No qURLs found."
+        lines = []
+        for q in result.qurls:
+            target = q.target_url or "<redacted>"
+            expires = q.expires_at or "N/A"
+            lines.append(f"- {q.resource_id}: {target} [{q.status}] expires={expires}")
+        return "\n".join(lines)
+
+
+class DeleteQURLTool(BaseTool):
+    """Revoke a qURL, immediately ending all access."""
+
+    name: str = "delete_qurl"
+    description: str = "Revoke (delete) a qURL by resource ID (e.g. 'r_k8xqp9h2sj9')."
+    client: Any = None
+
+    def _run(
+        self,
+        resource_id: str,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> str:
+        self.client.delete(resource_id)
+        return f"qURL {resource_id} has been revoked."
+
+
+class QURLToolkit:
+    """LangChain toolkit providing all qURL tools.
+
+    Usage::
+
+        from layerv_qurl import QURLClient
+        from layerv_qurl.langchain import QURLToolkit
+
+        client = QURLClient(api_key="lv_live_xxx")
+        toolkit = QURLToolkit(client=client)
+        tools = toolkit.get_tools()
+    """
+
+    def __init__(self, client: QURLClient) -> None:
+        if not _HAS_LANGCHAIN:
+            raise ImportError(
+                "langchain-core is required for LangChain integration. "
+                "Install with: pip install qurl-python[langchain]"
+            )
+        self.client = client
+
+    def get_tools(self) -> list[BaseTool]:
+        """Return all qURL tools configured with the client."""
+        return [
+            CreateQURLTool(client=self.client),
+            ResolveQURLTool(client=self.client),
+            ListQURLsTool(client=self.client),
+            DeleteQURLTool(client=self.client),
+        ]