knowledge2 0.4.0__py3-none-any.whl

sdk/resources/auth.py

@@ -0,0 +1,138 @@
+"""Authentication resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+from sdk._request_options import RequestOptions
+from sdk._validation import require_str
+from sdk.resources._mixin_base import RequesterMixin
+from sdk.types import (
+    ApiKeyCreateResponse,
+    ApiKeyListResponse,
+    ApiKeyRevokeResponse,
+    ApiKeyRotateResponse,
+    WhoAmIResponse,
+)
+
+
+class AuthMixin(RequesterMixin):
+    def create_api_key(
+        self,
+        org_id: str,
+        name: str,
+        scopes: dict[str, Any] | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> ApiKeyCreateResponse:
+        """Create a new API key for the given organisation.
+
+        Args:
+            org_id: Organisation that will own the key.
+            name: Human-readable name for the key.
+            scopes: Optional scope restrictions for the key.
+
+        Returns:
+            The newly created API key, including the raw secret (shown only once).
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        org_id = require_str(org_id, "org_id")
+        payload: dict[str, Any] = {"org_id": org_id, "name": name}
+        if scopes is not None:
+            payload["scopes"] = scopes
+        data = self._request(
+            "POST", "/v1/auth/api-keys", json=payload, request_options=request_options
+        )
+        return self._maybe_validate(data, "ApiKeyCreateResponse")
+
+    def list_api_keys(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> ApiKeyListResponse:
+        """List all API keys visible to the current credentials.
+
+        Returns:
+            A list of API key metadata objects.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        data = self._request("GET", "/v1/auth/api-keys", request_options=request_options)
+        return self._maybe_validate(data, "ApiKeyListResponse")
+
+    def revoke_api_key(
+        self,
+        key_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> ApiKeyRevokeResponse:
+        """Revoke an API key so it can no longer be used for authentication.
+
+        Args:
+            key_id: Unique identifier of the API key to revoke.
+
+        Returns:
+            Confirmation of the revocation.
+
+        Raises:
+            NotFoundError: If the key does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        key_id = require_str(key_id, "key_id")
+        data = self._request(
+            "POST", f"/v1/auth/api-keys/{key_id}:revoke", request_options=request_options
+        )
+        return self._maybe_validate(data, "ApiKeyRevokeResponse")
+
+    def rotate_api_key(
+        self,
+        key_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> ApiKeyRotateResponse:
+        """Rotate an API key, generating a new secret and invalidating the old one.
+
+        Args:
+            key_id: Unique identifier of the API key to rotate.
+
+        Returns:
+            The rotated key with the new raw secret (shown only once).
+
+        Raises:
+            NotFoundError: If the key does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        key_id = require_str(key_id, "key_id")
+        data = self._request(
+            "POST", f"/v1/auth/api-keys/{key_id}:rotate", request_options=request_options
+        )
+        return self._maybe_validate(data, "ApiKeyRotateResponse")
+
+    def get_whoami(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> WhoAmIResponse:
+        """Return information about the current API key.
+
+        Returns:
+            A dict containing ``org_id``, ``key_id``, ``name``,
+            ``scopes``, and other metadata for the authenticated key.
+        """
+        data = self._request("GET", "/v1/auth/whoami", request_options=request_options)
+        return self._maybe_validate(data, "WhoAmIResponse")
+
+    def fetch_whoami(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> WhoAmIResponse:
+        """Return information about the current API key.
+
+        .. deprecated::
+            Use :meth:`get_whoami` instead.
+        """
+        warnings.warn(
+            "fetch_whoami() is deprecated, use get_whoami() instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.get_whoami(request_options=request_options)

sdk/resources/console.py

@@ -0,0 +1,411 @@
+"""Console resource mixin for the Knowledge2 SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sdk._request_options import RequestOptions
+from sdk._validation import require_str
+from sdk.resources._mixin_base import RequesterMixin
+from sdk.types import (
+    ApiKeyCreateResponse,
+    ApiKeyListResponse,
+    ApiKeyRevokeResponse,
+    ConsoleBootstrapResponse,
+    ConsoleMeResponse,
+    ConsoleOrgResponse,
+    ConsoleProjectItem,
+    ConsoleProjectListResponse,
+    ConsoleSummaryResponse,
+    InviteAcceptResponse,
+    InviteCreateResponse,
+    InviteListResponse,
+    MemberRemoveResponse,
+    MemberUpdateResponse,
+    TeamListResponse,
+)
+
+
+class ConsoleMixin(RequesterMixin):
+    def console_me(
+        self,
+        *,
+        project_id: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> ConsoleMeResponse:
+        """Retrieve the current console user profile.
+
+        Args:
+            project_id: Optional project context to include in the response.
+
+        Returns:
+            The authenticated user's console profile information.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        params: dict[str, Any] = {}
+        if project_id is not None:
+            params["project_id"] = project_id
+        data = self._request(
+            "GET", "/v1/console/me", params=params or None, request_options=request_options
+        )
+        return self._maybe_validate(data, "ConsoleMeResponse")
+
+    def console_bootstrap(
+        self,
+        *,
+        org_name: str | None = None,
+        project_name: str | None = None,
+        email: str | None = None,
+        name: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> ConsoleBootstrapResponse:
+        """Bootstrap a new console session, creating org/project if needed.
+
+        Args:
+            org_name: Name for the organisation to create or associate.
+            project_name: Name for the default project to create.
+            email: Contact email for the new organisation.
+            name: Display name for the user.
+
+        Returns:
+            Bootstrap result containing created or existing org/project details.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        payload: dict[str, Any] = {}
+        if org_name is not None:
+            payload["org_name"] = org_name
+        if project_name is not None:
+            payload["project_name"] = project_name
+        if email is not None:
+            payload["email"] = email
+        if name is not None:
+            payload["name"] = name
+        data = self._request(
+            "POST", "/v1/console/bootstrap", json=payload, request_options=request_options
+        )
+        return self._maybe_validate(data, "ConsoleBootstrapResponse")
+
+    def console_summary(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> ConsoleSummaryResponse:
+        """Retrieve a high-level summary of the console (corpora, jobs, etc.).
+
+        Returns:
+            Aggregated summary statistics for the current organisation.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        data = self._request("GET", "/v1/console/summary", request_options=request_options)
+        return self._maybe_validate(data, "ConsoleSummaryResponse")
+
+    def console_projects(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> ConsoleProjectListResponse:
+        """List all projects visible in the console.
+
+        Returns:
+            A list of console project summaries.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        data = self._request("GET", "/v1/console/projects", request_options=request_options)
+        return self._maybe_validate(data, "ConsoleProjectListResponse")
+
+    def console_get_project(
+        self,
+        project_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> ConsoleProjectItem:
+        """Retrieve details of a single console project.
+
+        Args:
+            project_id: Unique identifier of the project.
+
+        Returns:
+            Detailed project information.
+
+        Raises:
+            NotFoundError: If the project does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        project_id = require_str(project_id, "project_id")
+        data = self._request(
+            "GET", f"/v1/console/projects/{project_id}", request_options=request_options
+        )
+        return self._maybe_validate(data, "ConsoleProjectItem")
+
+    def console_update_project(
+        self,
+        project_id: str,
+        *,
+        name: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> ConsoleProjectItem:
+        """Update a console project's settings.
+
+        Args:
+            project_id: Unique identifier of the project to update.
+            name: New display name for the project.
+
+        Returns:
+            The updated project information.
+
+        Raises:
+            NotFoundError: If the project does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        project_id = require_str(project_id, "project_id")
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        data = self._request(
+            "PATCH",
+            f"/v1/console/projects/{project_id}",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "ConsoleProjectItem")
+
+    def console_get_org(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> ConsoleOrgResponse:
+        """Retrieve the current organisation's console profile.
+
+        Returns:
+            Organisation details including name and settings.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        data = self._request("GET", "/v1/console/org", request_options=request_options)
+        return self._maybe_validate(data, "ConsoleOrgResponse")
+
+    def console_update_org(
+        self,
+        *,
+        name: str | None = None,
+        contact_email: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> ConsoleOrgResponse:
+        """Update the current organisation's settings.
+
+        Args:
+            name: New display name for the organisation.
+            contact_email: New contact email address.
+
+        Returns:
+            The updated organisation details.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if contact_email is not None:
+            payload["contact_email"] = contact_email
+        data = self._request(
+            "PATCH", "/v1/console/org", json=payload, request_options=request_options
+        )
+        return self._maybe_validate(data, "ConsoleOrgResponse")
+
+    def console_list_team(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> TeamListResponse:
+        """List all team members in the current organisation.
+
+        Returns:
+            A list of team member records with roles.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        data = self._request("GET", "/v1/console/team", request_options=request_options)
+        return self._maybe_validate(data, "TeamListResponse")
+
+    def console_list_invites(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> InviteListResponse:
+        """List pending team invitations for the current organisation.
+
+        Returns:
+            A list of pending invitation records.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        data = self._request("GET", "/v1/console/invites", request_options=request_options)
+        return self._maybe_validate(data, "InviteListResponse")
+
+    def console_create_invite(
+        self,
+        email: str,
+        role: str = "member",
+        request_options: RequestOptions | None = None,
+    ) -> InviteCreateResponse:
+        """Invite a new member to the current organisation.
+
+        Args:
+            email: Email address of the person to invite.
+            role: Role to assign (e.g. ``"member"``, ``"admin"``).
+
+        Returns:
+            The created invitation record.
+
+        Raises:
+            ConflictError: If an invitation for this email already exists.
+            Knowledge2Error: If the API request fails.
+        """
+        payload = {"email": email, "role": role}
+        data = self._request(
+            "POST", "/v1/console/invites", json=payload, request_options=request_options
+        )
+        return self._maybe_validate(data, "InviteCreateResponse")
+
+    def console_accept_invite(
+        self,
+        token: str,
+        request_options: RequestOptions | None = None,
+    ) -> InviteAcceptResponse:
+        """Accept a pending team invitation.
+
+        Args:
+            token: The invitation token received via email.
+
+        Returns:
+            Confirmation of the accepted invitation.
+
+        Raises:
+            NotFoundError: If the invitation token is invalid or expired.
+            Knowledge2Error: If the API request fails.
+        """
+        token = require_str(token, "token")
+        data = self._request(
+            "POST", f"/v1/console/invites/{token}/accept", request_options=request_options
+        )
+        return self._maybe_validate(data, "InviteAcceptResponse")
+
+    def console_update_member_role(
+        self,
+        membership_id: str,
+        role: str,
+        request_options: RequestOptions | None = None,
+    ) -> MemberUpdateResponse:
+        """Update a team member's role within the organisation.
+
+        Args:
+            membership_id: Unique identifier of the membership to update.
+            role: New role to assign (e.g. ``"member"``, ``"admin"``).
+
+        Returns:
+            The updated membership record.
+
+        Raises:
+            NotFoundError: If the membership does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        membership_id = require_str(membership_id, "membership_id")
+        payload = {"role": role}
+        data = self._request(
+            "PATCH",
+            f"/v1/console/team/{membership_id}",
+            json=payload,
+            request_options=request_options,
+        )
+        return self._maybe_validate(data, "MemberUpdateResponse")
+
+    def console_remove_member(
+        self,
+        membership_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> MemberRemoveResponse:
+        """Remove a member from the organisation.
+
+        Args:
+            membership_id: Unique identifier of the membership to remove.
+
+        Returns:
+            Confirmation of the member removal.
+
+        Raises:
+            NotFoundError: If the membership does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        membership_id = require_str(membership_id, "membership_id")
+        data = self._request(
+            "DELETE", f"/v1/console/team/{membership_id}", request_options=request_options
+        )
+        return self._maybe_validate(data, "MemberRemoveResponse")
+
+    def console_list_api_keys(
+        self,
+        request_options: RequestOptions | None = None,
+    ) -> ApiKeyListResponse:
+        """List API keys managed through the console.
+
+        Returns:
+            A list of API key metadata objects.
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        data = self._request("GET", "/v1/console/api-keys", request_options=request_options)
+        return self._maybe_validate(data, "ApiKeyListResponse")
+
+    def console_create_api_key(
+        self,
+        name: str,
+        access: str = "retrieval",
+        request_options: RequestOptions | None = None,
+    ) -> ApiKeyCreateResponse:
+        """Create a new API key through the console.
+
+        Args:
+            name: Human-readable name for the key.
+            access: Access level for the key (e.g. ``"retrieval"``, ``"admin"``).
+
+        Returns:
+            The newly created API key, including the raw secret (shown only once).
+
+        Raises:
+            Knowledge2Error: If the API request fails.
+        """
+        payload = {"name": name, "access": access}
+        data = self._request(
+            "POST", "/v1/console/api-keys", json=payload, request_options=request_options
+        )
+        return self._maybe_validate(data, "ApiKeyCreateResponse")
+
+    def console_revoke_api_key(
+        self,
+        key_id: str,
+        request_options: RequestOptions | None = None,
+    ) -> ApiKeyRevokeResponse:
+        """Revoke an API key through the console.
+
+        Args:
+            key_id: Unique identifier of the API key to revoke.
+
+        Returns:
+            Confirmation of the revocation.
+
+        Raises:
+            NotFoundError: If the key does not exist.
+            Knowledge2Error: If the API request fails.
+        """
+        key_id = require_str(key_id, "key_id")
+        data = self._request(
+            "POST", f"/v1/console/api-keys/{key_id}:revoke", request_options=request_options
+        )
+        return self._maybe_validate(data, "ApiKeyRevokeResponse")