querri 1.0.2__py3-none-any.whl

querri/resources/keys.py

@@ -0,0 +1,191 @@
+"""API key management resource."""
+
+from __future__ import annotations
+
+import builtins
+from typing import Any
+
+from .._base_client import AsyncHTTPClient, SyncHTTPClient
+from ..types.key import ApiKey, ApiKeyCreated
+
+
+class Keys:
+    """Synchronous API key management resource.
+
+    Usage::
+
+        new_key = client.keys.create(name="CI Pipeline", scopes=["data:read"])
+        keys = client.keys.list()
+    """
+
+    def __init__(self, http: SyncHTTPClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        name: str,
+        scopes: builtins.list[str],
+        expires_in_days: int | None = None,
+        source_scope: dict[str, Any] | None = None,
+        access_policy_ids: builtins.list[str] | None = None,
+        bound_user_id: str | None = None,
+        rate_limit_per_minute: int | None = None,
+        ip_allowlist: builtins.list[str] | None = None,
+    ) -> ApiKeyCreated:
+        """Create a new API key. Returns the plaintext secret once.
+
+        Args:
+            name: Display name for the key.
+            scopes: List of permission scopes.
+            expires_in_days: Days until expiration.
+            source_scope: Source access scope configuration.
+            access_policy_ids: Bound access policy UUIDs.
+            bound_user_id: User ID to bind RLS to.
+            rate_limit_per_minute: Rate limit override.
+            ip_allowlist: Allowed IP addresses.
+
+        Returns:
+            ApiKeyCreated with id, name, key_prefix, secret, scopes, status, etc.
+            The ``secret`` field is only returned on creation.
+        """
+        payload: dict[str, Any] = {"name": name, "scopes": scopes}
+        if expires_in_days is not None:
+            payload["expires_in_days"] = expires_in_days
+        if source_scope is not None:
+            payload["source_scope"] = source_scope
+        if access_policy_ids is not None:
+            payload["access_policy_ids"] = access_policy_ids
+        if bound_user_id is not None:
+            payload["bound_user_id"] = bound_user_id
+        if rate_limit_per_minute is not None:
+            payload["rate_limit_per_minute"] = rate_limit_per_minute
+        if ip_allowlist is not None:
+            payload["ip_allowlist"] = ip_allowlist
+        resp = self._http.post("/keys", json=payload)
+        return ApiKeyCreated.model_validate(resp.json())
+
+    def get(self, key_id: str) -> ApiKey:
+        """Get API key details (never returns the secret).
+
+        Args:
+            key_id: The key UUID.
+
+        Returns:
+            ApiKey object.
+        """
+        resp = self._http.get(f"/keys/{key_id}")
+        return ApiKey.model_validate(resp.json())
+
+    def list(self) -> builtins.list[ApiKey]:
+        """List API keys for the organization.
+
+        Returns:
+            List of ApiKey objects (secrets are never included).
+        """
+        resp = self._http.get("/keys")
+        body = resp.json()
+        return [ApiKey.model_validate(k) for k in body.get("data", [])]
+
+    def delete(self, key_id: str) -> dict[str, Any]:
+        """Revoke an API key.
+
+        Args:
+            key_id: The key UUID.
+
+        Returns:
+            Dict with id and status ("revoked").
+        """
+        resp = self._http.delete(f"/keys/{key_id}")
+        return resp.json()  # type: ignore[no-any-return]
+
+
+class AsyncKeys:
+    """Asynchronous API key management resource.
+
+    Usage::
+
+        new_key = await client.keys.create(name="CI Pipeline", scopes=["data:read"])
+        keys = await client.keys.list()
+    """
+
+    def __init__(self, http: AsyncHTTPClient) -> None:
+        self._http = http
+
+    async def create(
+        self,
+        *,
+        name: str,
+        scopes: builtins.list[str],
+        expires_in_days: int | None = None,
+        source_scope: dict[str, Any] | None = None,
+        access_policy_ids: builtins.list[str] | None = None,
+        bound_user_id: str | None = None,
+        rate_limit_per_minute: int | None = None,
+        ip_allowlist: builtins.list[str] | None = None,
+    ) -> ApiKeyCreated:
+        """Create a new API key. Returns the plaintext secret once.
+
+        Args:
+            name: Display name for the key.
+            scopes: List of permission scopes.
+            expires_in_days: Days until expiration.
+            source_scope: Source access scope configuration.
+            access_policy_ids: Bound access policy UUIDs.
+            bound_user_id: User ID to bind RLS to.
+            rate_limit_per_minute: Rate limit override.
+            ip_allowlist: Allowed IP addresses.
+
+        Returns:
+            ApiKeyCreated with id, name, key_prefix, secret, scopes, status, etc.
+            The ``secret`` field is only returned on creation.
+        """
+        payload: dict[str, Any] = {"name": name, "scopes": scopes}
+        if expires_in_days is not None:
+            payload["expires_in_days"] = expires_in_days
+        if source_scope is not None:
+            payload["source_scope"] = source_scope
+        if access_policy_ids is not None:
+            payload["access_policy_ids"] = access_policy_ids
+        if bound_user_id is not None:
+            payload["bound_user_id"] = bound_user_id
+        if rate_limit_per_minute is not None:
+            payload["rate_limit_per_minute"] = rate_limit_per_minute
+        if ip_allowlist is not None:
+            payload["ip_allowlist"] = ip_allowlist
+        resp = await self._http.post("/keys", json=payload)
+        return ApiKeyCreated.model_validate(resp.json())
+
+    async def get(self, key_id: str) -> ApiKey:
+        """Get API key details (never returns the secret).
+
+        Args:
+            key_id: The key UUID.
+
+        Returns:
+            ApiKey object.
+        """
+        resp = await self._http.get(f"/keys/{key_id}")
+        return ApiKey.model_validate(resp.json())
+
+    async def list(self) -> builtins.list[ApiKey]:
+        """List API keys for the organization.
+
+        Returns:
+            List of ApiKey objects (secrets are never included).
+        """
+        resp = await self._http.get("/keys")
+        body = resp.json()
+        return [ApiKey.model_validate(k) for k in body.get("data", [])]
+
+    async def delete(self, key_id: str) -> dict[str, Any]:
+        """Revoke an API key.
+
+        Args:
+            key_id: The key UUID.
+
+        Returns:
+            Dict with id and status ("revoked").
+        """
+        resp = await self._http.delete(f"/keys/{key_id}")
+        return resp.json()  # type: ignore[no-any-return]

querri/resources/policies.py

@@ -0,0 +1,492 @@
+"""Access policy resources — maps to /access endpoints."""
+
+from __future__ import annotations
+
+import builtins
+from typing import Any
+
+from .._base_client import AsyncHTTPClient, SyncHTTPClient
+from .._convenience import async_setup_policy, sync_setup_policy
+from .._pagination import AsyncCursorPage, SyncCursorPage
+from ..types.policy import (
+    Policy,
+    PolicyAssignResponse,
+    PolicyDeleteResponse,
+    PolicyRemoveUserResponse,
+    PolicyReplaceResponse,
+    PolicyUpdateResponse,
+    ResolvedAccess,
+    SourceColumns,
+)
+
+
+class Policies:
+    """Synchronous access policy management.
+
+    Usage::
+
+        policy = client.policies.create(
+            name="Sales Team",
+            source_ids=["src_..."],
+            row_filters=[{"column": "region", "values": ["US"]}],
+        )
+    """
+
+    def __init__(self, http: SyncHTTPClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        name: str,
+        description: str | None = None,
+        source_ids: builtins.list[str] | None = None,
+        row_filters: builtins.list[dict[str, Any]] | None = None,
+    ) -> Policy:
+        """Create an access policy.
+
+        Args:
+            name: Policy name.
+            description: Optional description.
+            source_ids: List of source IDs this policy applies to.
+            row_filters: List of row filter dicts with ``column`` and ``values`` keys.
+        """
+        body: dict[str, Any] = {"name": name}
+        if description is not None:
+            body["description"] = description
+        if source_ids is not None:
+            body["source_ids"] = source_ids
+        if row_filters is not None:
+            body["row_filters"] = row_filters
+        resp = self._http.post("/access/policies", json=body)
+        return Policy.model_validate(resp.json())
+
+    def get(self, policy_id: str) -> Policy:
+        """Get policy details including assigned user IDs.
+
+        Args:
+            policy_id: The policy UUID.
+        """
+        resp = self._http.get(f"/access/policies/{policy_id}")
+        return Policy.model_validate(resp.json())
+
+    def list(
+        self,
+        *,
+        name: str | None = None,
+        limit: int = 25,
+        after: str | None = None,
+    ) -> SyncCursorPage[Policy]:
+        """List access policies for the organization with cursor pagination.
+
+        Args:
+            name: Filter by exact policy name.
+            limit: Maximum number of policies per page (1-200).
+            after: Cursor for the next page.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if name is not None:
+            params["name"] = name
+        if after is not None:
+            params["after"] = after
+        return SyncCursorPage(self._http, "/access/policies", Policy, params=params)
+
+    def update(
+        self,
+        policy_id: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        source_ids: builtins.list[str] | None = None,
+        row_filters: builtins.list[dict[str, Any]] | None = None,
+    ) -> PolicyUpdateResponse:
+        """Update an access policy.
+
+        Args:
+            policy_id: The policy UUID.
+            name: New name.
+            description: New description.
+            source_ids: New source IDs.
+            row_filters: New row filters.
+        """
+        body: dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        if source_ids is not None:
+            body["source_ids"] = source_ids
+        if row_filters is not None:
+            body["row_filters"] = row_filters
+        resp = self._http.patch(f"/access/policies/{policy_id}", json=body)
+        return PolicyUpdateResponse.model_validate(resp.json())
+
+    def delete(self, policy_id: str) -> PolicyDeleteResponse:
+        """Delete an access policy and all its user assignments.
+
+        Args:
+            policy_id: The policy UUID.
+        """
+        resp = self._http.delete(f"/access/policies/{policy_id}")
+        return PolicyDeleteResponse.model_validate(resp.json())
+
+    def assign_users(
+        self,
+        policy_id: str,
+        *,
+        user_ids: builtins.list[str],
+    ) -> PolicyAssignResponse:
+        """Assign users to a policy.
+
+        Idempotent: already-assigned users are silently skipped.
+
+        Args:
+            policy_id: The policy UUID.
+            user_ids: List of WorkOS user IDs to assign.
+        """
+        resp = self._http.post(
+            f"/access/policies/{policy_id}/users",
+            json={"user_ids": user_ids},
+        )
+        return PolicyAssignResponse.model_validate(resp.json())
+
+    def remove_user(
+        self,
+        policy_id: str,
+        user_id: str,
+    ) -> PolicyRemoveUserResponse:
+        """Remove a user from a policy.
+
+        Args:
+            policy_id: The policy UUID.
+            user_id: The WorkOS user ID to remove.
+        """
+        resp = self._http.delete(f"/access/policies/{policy_id}/users/{user_id}")
+        return PolicyRemoveUserResponse.model_validate(resp.json())
+
+    def resolve(
+        self,
+        *,
+        user_id: str,
+        source_id: str,
+    ) -> ResolvedAccess:
+        """Preview resolved access for a user+source combination.
+
+        Returns the effective row filters and SQL WHERE clause that would
+        be applied when querying the given source as the given user.
+
+        Args:
+            user_id: WorkOS user ID.
+            source_id: Source UUID.
+        """
+        resp = self._http.post(
+            "/access/resolve",
+            json={"user_id": user_id, "source_id": source_id},
+        )
+        return ResolvedAccess.model_validate(resp.json())
+
+    def columns(
+        self,
+        *,
+        source_id: str | None = None,
+    ) -> builtins.list[SourceColumns]:
+        """Discover filterable columns for RLS rule building.
+
+        Returns column names and types from data sources so you can
+        construct valid ``row_filters`` for access policies.
+
+        Args:
+            source_id: Optional source ID to filter to a single source.
+        """
+        params: dict[str, Any] = {}
+        if source_id is not None:
+            params["source_id"] = source_id
+        resp = self._http.get("/access/columns", params=params)
+        body = resp.json()
+        return [SourceColumns.model_validate(s) for s in body.get("data", [])]
+
+    def replace_user_policies(
+        self, user_id: str, *, policy_ids: builtins.list[str]
+    ) -> PolicyReplaceResponse:
+        """Atomically replace all policy assignments for a user.
+
+        Removes any existing policy assignments and replaces them with the
+        provided set. This prevents policy accumulation from repeated
+        ``get_session()`` calls.
+
+        Args:
+            user_id: The user ID whose policies to replace.
+            policy_ids: Complete set of policy IDs to assign. Pass ``[]`` to
+                remove all policies.
+        """
+        resp = self._http.put(
+            f"/access/users/{user_id}/policies",
+            json={"policy_ids": policy_ids},
+        )
+        return PolicyReplaceResponse.model_validate(resp.json())
+
+    def setup(
+        self,
+        *,
+        name: str,
+        sources: builtins.list[str] | None = None,
+        row_filters: dict[str, Any] | None = None,
+        users: builtins.list[str] | None = None,
+        description: str | None = None,
+    ) -> Policy:
+        """Create a policy and assign users in one call.
+
+        Args:
+            name: Policy name.
+            sources: Source IDs this policy applies to.
+            row_filters: Dict of column -> values for row filtering.
+            users: User IDs to assign to the policy.
+            description: Optional policy description.
+
+        Returns:
+            Created Policy object.
+        """
+        return sync_setup_policy(
+            self._http,
+            name=name,
+            sources=sources,
+            row_filters=row_filters,
+            users=users,
+            description=description,
+        )
+
+
+class AsyncPolicies:
+    """Asynchronous access policy management.
+
+    Usage::
+
+        policy = await client.policies.create(
+            name="Sales Team",
+            source_ids=["src_..."],
+            row_filters=[{"column": "region", "values": ["US"]}],
+        )
+    """
+
+    def __init__(self, http: AsyncHTTPClient) -> None:
+        self._http = http
+
+    async def create(
+        self,
+        *,
+        name: str,
+        description: str | None = None,
+        source_ids: builtins.list[str] | None = None,
+        row_filters: builtins.list[dict[str, Any]] | None = None,
+    ) -> Policy:
+        """Create an access policy.
+
+        Args:
+            name: Policy name.
+            description: Optional description.
+            source_ids: List of source IDs this policy applies to.
+            row_filters: List of row filter dicts with ``column`` and ``values`` keys.
+        """
+        body: dict[str, Any] = {"name": name}
+        if description is not None:
+            body["description"] = description
+        if source_ids is not None:
+            body["source_ids"] = source_ids
+        if row_filters is not None:
+            body["row_filters"] = row_filters
+        resp = await self._http.post("/access/policies", json=body)
+        return Policy.model_validate(resp.json())
+
+    async def get(self, policy_id: str) -> Policy:
+        """Get policy details including assigned user IDs.
+
+        Args:
+            policy_id: The policy UUID.
+        """
+        resp = await self._http.get(f"/access/policies/{policy_id}")
+        return Policy.model_validate(resp.json())
+
+    def list(
+        self,
+        *,
+        name: str | None = None,
+        limit: int = 25,
+        after: str | None = None,
+    ) -> AsyncCursorPage[Policy]:
+        """List access policies for the organization with cursor pagination.
+
+        Args:
+            name: Filter by exact policy name.
+            limit: Maximum number of policies per page (1-200).
+            after: Cursor for the next page.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if name is not None:
+            params["name"] = name
+        if after is not None:
+            params["after"] = after
+        return AsyncCursorPage(self._http, "/access/policies", Policy, params=params)
+
+    async def update(
+        self,
+        policy_id: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        source_ids: builtins.list[str] | None = None,
+        row_filters: builtins.list[dict[str, Any]] | None = None,
+    ) -> PolicyUpdateResponse:
+        """Update an access policy.
+
+        Args:
+            policy_id: The policy UUID.
+            name: New name.
+            description: New description.
+            source_ids: New source IDs.
+            row_filters: New row filters.
+        """
+        body: dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if description is not None:
+            body["description"] = description
+        if source_ids is not None:
+            body["source_ids"] = source_ids
+        if row_filters is not None:
+            body["row_filters"] = row_filters
+        resp = await self._http.patch(f"/access/policies/{policy_id}", json=body)
+        return PolicyUpdateResponse.model_validate(resp.json())
+
+    async def delete(self, policy_id: str) -> PolicyDeleteResponse:
+        """Delete an access policy and all its user assignments.
+
+        Args:
+            policy_id: The policy UUID.
+        """
+        resp = await self._http.delete(f"/access/policies/{policy_id}")
+        return PolicyDeleteResponse.model_validate(resp.json())
+
+    async def assign_users(
+        self,
+        policy_id: str,
+        *,
+        user_ids: builtins.list[str],
+    ) -> PolicyAssignResponse:
+        """Assign users to a policy.
+
+        Idempotent: already-assigned users are silently skipped.
+
+        Args:
+            policy_id: The policy UUID.
+            user_ids: List of WorkOS user IDs to assign.
+        """
+        resp = await self._http.post(
+            f"/access/policies/{policy_id}/users",
+            json={"user_ids": user_ids},
+        )
+        return PolicyAssignResponse.model_validate(resp.json())
+
+    async def remove_user(
+        self,
+        policy_id: str,
+        user_id: str,
+    ) -> PolicyRemoveUserResponse:
+        """Remove a user from a policy.
+
+        Args:
+            policy_id: The policy UUID.
+            user_id: The WorkOS user ID to remove.
+        """
+        resp = await self._http.delete(f"/access/policies/{policy_id}/users/{user_id}")
+        return PolicyRemoveUserResponse.model_validate(resp.json())
+
+    async def resolve(
+        self,
+        *,
+        user_id: str,
+        source_id: str,
+    ) -> ResolvedAccess:
+        """Preview resolved access for a user+source combination.
+
+        Returns the effective row filters and SQL WHERE clause that would
+        be applied when querying the given source as the given user.
+
+        Args:
+            user_id: WorkOS user ID.
+            source_id: Source UUID.
+        """
+        resp = await self._http.post(
+            "/access/resolve",
+            json={"user_id": user_id, "source_id": source_id},
+        )
+        return ResolvedAccess.model_validate(resp.json())
+
+    async def columns(
+        self,
+        *,
+        source_id: str | None = None,
+    ) -> builtins.list[SourceColumns]:
+        """Discover filterable columns for RLS rule building.
+
+        Returns column names and types from data sources so you can
+        construct valid ``row_filters`` for access policies.
+
+        Args:
+            source_id: Optional source ID to filter to a single source.
+        """
+        params: dict[str, Any] = {}
+        if source_id is not None:
+            params["source_id"] = source_id
+        resp = await self._http.get("/access/columns", params=params)
+        body = resp.json()
+        return [SourceColumns.model_validate(s) for s in body.get("data", [])]
+
+    async def replace_user_policies(
+        self, user_id: str, *, policy_ids: builtins.list[str]
+    ) -> PolicyReplaceResponse:
+        """Atomically replace all policy assignments for a user.
+
+        Removes any existing policy assignments and replaces them with the
+        provided set. This prevents policy accumulation from repeated
+        ``get_session()`` calls.
+
+        Args:
+            user_id: The user ID whose policies to replace.
+            policy_ids: Complete set of policy IDs to assign. Pass ``[]`` to
+                remove all policies.
+        """
+        resp = await self._http.put(
+            f"/access/users/{user_id}/policies",
+            json={"policy_ids": policy_ids},
+        )
+        return PolicyReplaceResponse.model_validate(resp.json())
+
+    async def setup(
+        self,
+        *,
+        name: str,
+        sources: builtins.list[str] | None = None,
+        row_filters: dict[str, Any] | None = None,
+        users: builtins.list[str] | None = None,
+        description: str | None = None,
+    ) -> Policy:
+        """Create a policy and assign users in one call.
+
+        Args:
+            name: Policy name.
+            sources: Source IDs this policy applies to.
+            row_filters: Dict of column -> values for row filtering.
+            users: User IDs to assign to the policy.
+            description: Optional policy description.
+
+        Returns:
+            Created Policy object.
+        """
+        return await async_setup_policy(
+            self._http,
+            name=name,
+            sources=sources,
+            row_filters=row_filters,
+            users=users,
+            description=description,
+        )