hyperpocket 0.3.1__tar.gz → 0.3.3__tar.gz

{hyperpocket-0.3.1 → hyperpocket-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperpocket
-Version: 0.3.1
+Version: 0.3.3
 Summary: Building AI agent with hyperpocket tool in a flash
 Project-URL: Homepage, https://vessl-ai.github.io/hyperpocket
 Project-URL: Repository, https://github.com/vessl-ai/hyperpocket
@@ -193,32 +193,32 @@ Pocket provides way to use end user auth easily.
 
 - Supported methods
 
-    - [x] OAuth
-    - [x] Token
-    - [ ] Basic Auth (Username, Password)
+  - [x] OAuth
+  - [x] Token
+  - [ ] Basic Auth (Username, Password)
 
 - Supported OAuth Providers
 
-    - [x] Google
-    - [x] GitHub
-    - [x] Slack
-    - [x] Reddit
-    - [x] Calendly
-    - [ ] Facebook
-    - [ ] X (Previously Twitter)
-    - [ ] LinkedIn
-    - [ ] Discord
-    - [ ] Zoom
-    - [ ] Microsoft
-    - [ ] Spotify
-    - [ ] Twitch
+  - [x] Google
+  - [x] GitHub
+  - [x] Slack
+  - [x] Reddit
+  - [x] Calendly
+  - [ ] Facebook
+  - [ ] X (Previously Twitter)
+  - [ ] LinkedIn
+  - [ ] Discord
+  - [ ] Zoom
+  - [ ] Microsoft
+  - [ ] Spotify
+  - [ ] Twitch
 
 - Supported Token Providers
-    - [x] Notion
-    - [x] Slack
-    - [x] Linear
-    - [x] Gumloop
-    - [x] Github
+  - [x] Notion
+  - [x] Slack
+  - [x] Linear
+  - [x] Gumloop
+  - [x] Github
 
 You can manage your auths in request-wise level. (e.g. you can use different auths for different requests)
 
@@ -340,15 +340,15 @@ client_secret = "" # your slack client secret
 
 - While creating your github OAuth app, configuring your app's `Authorization callback URL` is different for your
   development environment and production environment.
-    - For local testing environment, you can use `https://localhost:8001/proxy/auth/<provider>/callback` for TLS enabled
-      redirect url. (ex. `https://localhost:8001/proxy/auth/github/callback`)
-        - **Note**: Default port for hyperpocket dev server is `8000`. If you are using a different port, make sure to
-          replace `8000` with your actual port number.
-        - **Note**: But for easy dev experience, you can use TLS proxy on port `8001` provided out-of-the-box.
-            - You can change the `proxy` prefix in settings.toml to your desired prefix with
-              `callback_url_rewrite_prefix` key.
-    - For production environment, you can use `https://yourdomain.com/auth/github/callback`
-        - **Note**: Make sure to replace `yourdomain.com` with your actual domain name that this app will be hosted on.
+  - For local testing environment, you can use `https://localhost:8001/proxy/auth/<provider>/callback` for TLS enabled
+    redirect url. (ex. `https://localhost:8001/proxy/auth/github/callback`)
+    - **Note**: Default port for hyperpocket dev server is `8000`. If you are using a different port, make sure to
+      replace `8000` with your actual port number.
+    - **Note**: But for easy dev experience, you can use TLS proxy on port `8001` provided out-of-the-box.
+      - You can change the `proxy` prefix in settings.toml to your desired prefix with
+        `callback_url_rewrite_prefix` key.
+  - For production environment, you can use `https://yourdomain.com/auth/github/callback`
+    - **Note**: Make sure to replace `yourdomain.com` with your actual domain name that this app will be hosted on.
 
 #### How to integrate SLACK OAuth app
 
@@ -359,19 +359,92 @@ client_secret = "" # your slack client secret
 - Redirect URLs :
   `{public_server_protocol}://{public_hostname}:[{public_server_port}]/{callback_url_rewrite_prefix}/auth/slack/oauth2/callback`
 - Scopes : What you want to request to user.
-    - Recommended scopes :
-        - channels:history,
-        - channels:read,
-        - chat:write,
-        - groups:history,
-        - groups:read,
-        - im:history,
-        - mpim:history,
-        - reactions:read,
-        - reactions:write,
-
-3. Set your Slack APP Client ID / Client Secret in `{WORKDIR}/settings.toml`
-
-## Special thanks
-
-- [tott](https://x.com/tott____) for drawing the cute possum in a pocket.
+  - Recommended scopes :
+    - channels:history,
+    - channels:read,
+    - chat:write,
+    - groups:history,
+    - groups:read,
+    - im:history,
+    - mpim:history,
+    - reactions:read,
+    - reactions:write,
+
+3. Set your Slack APP Client ID / Client Secret in `$HOME/.pocket/settings.toml`
+
+#### How to start adding a new token auth
+
+1. Generate boilerplate codes for token-based auth services ?
+
+```
+# service_name should be lowercase including underscore
+poetry run hyperpocket devtool create-token-auth-template {service_name}
+```
+
+It will generate boilerplate code lines for a new token-based auth service
+
+2. Extend AuthProvider enum to add your new auth provider.
+
+```python
+class AuthProvider(Enum):
+SERVICE = 'service'
+```
+
+3. Specify auth provider for tools
+
+1) github repo or local
+
+```toml
+[auth]
+auth_provider = "{service_name}"
+auth_handler = "{service_name}-token"
+scopes = []
+```
+
+2. function_tool
+
+```python
+@function_tool(
+    auth_provider=AuthProvider.SERVICE
+)
+def my_function(**kwargs):
+```
+
+#### How to Start Developing a New Tool
+
+1. Generate Boilerplate Template for the Tool
+
+```bash
+# tool_name must be lowercase and can include underscores
+poetry run hyperpocket devtool create-tool-template your_own_tool
+```
+
+This command will generate the boilerplate directory and files for a new tool.
+
+2. Configure the `config.toml`
+
+Define the language, `auth_provider`, scopes, and other required settings in the `config.toml` file.
+
+```toml
+# Example configuration
+name = "google_delete_calendar_events"
+description = "Delete Google Calendar events"
+language = "python"
+
+[auth]
+auth_provider = "google"
+scopes = ["https://www.googleapis.com/auth/calendar"]
+```
+
+3. Develop the Tool Logic
+
+Implement the `request_model` and the necessary functions for your tool's logic in the `__main__.py` file.
+
+4. Build Your Tool
+
+Use the Hyperpocket CLI to build your tool.
+
+```bash
+# Specify the tool_path or run the command inside the tool's directory
+poetry run hyperpocket devtool build-tool ./your-own-tool
+```

{hyperpocket-0.3.1 → hyperpocket-0.3.3}/README.md

@@ -168,32 +168,32 @@ Pocket provides way to use end user auth easily.
 
 - Supported methods
 
-    - [x] OAuth
-    - [x] Token
-    - [ ] Basic Auth (Username, Password)
+  - [x] OAuth
+  - [x] Token
+  - [ ] Basic Auth (Username, Password)
 
 - Supported OAuth Providers
 
-    - [x] Google
-    - [x] GitHub
-    - [x] Slack
-    - [x] Reddit
-    - [x] Calendly
-    - [ ] Facebook
-    - [ ] X (Previously Twitter)
-    - [ ] LinkedIn
-    - [ ] Discord
-    - [ ] Zoom
-    - [ ] Microsoft
-    - [ ] Spotify
-    - [ ] Twitch
+  - [x] Google
+  - [x] GitHub
+  - [x] Slack
+  - [x] Reddit
+  - [x] Calendly
+  - [ ] Facebook
+  - [ ] X (Previously Twitter)
+  - [ ] LinkedIn
+  - [ ] Discord
+  - [ ] Zoom
+  - [ ] Microsoft
+  - [ ] Spotify
+  - [ ] Twitch
 
 - Supported Token Providers
-    - [x] Notion
-    - [x] Slack
-    - [x] Linear
-    - [x] Gumloop
-    - [x] Github
+  - [x] Notion
+  - [x] Slack
+  - [x] Linear
+  - [x] Gumloop
+  - [x] Github
 
 You can manage your auths in request-wise level. (e.g. you can use different auths for different requests)
 
@@ -315,15 +315,15 @@ client_secret = "" # your slack client secret
 
 - While creating your github OAuth app, configuring your app's `Authorization callback URL` is different for your
   development environment and production environment.
-    - For local testing environment, you can use `https://localhost:8001/proxy/auth/<provider>/callback` for TLS enabled
-      redirect url. (ex. `https://localhost:8001/proxy/auth/github/callback`)
-        - **Note**: Default port for hyperpocket dev server is `8000`. If you are using a different port, make sure to
-          replace `8000` with your actual port number.
-        - **Note**: But for easy dev experience, you can use TLS proxy on port `8001` provided out-of-the-box.
-            - You can change the `proxy` prefix in settings.toml to your desired prefix with
-              `callback_url_rewrite_prefix` key.
-    - For production environment, you can use `https://yourdomain.com/auth/github/callback`
-        - **Note**: Make sure to replace `yourdomain.com` with your actual domain name that this app will be hosted on.
+  - For local testing environment, you can use `https://localhost:8001/proxy/auth/<provider>/callback` for TLS enabled
+    redirect url. (ex. `https://localhost:8001/proxy/auth/github/callback`)
+    - **Note**: Default port for hyperpocket dev server is `8000`. If you are using a different port, make sure to
+      replace `8000` with your actual port number.
+    - **Note**: But for easy dev experience, you can use TLS proxy on port `8001` provided out-of-the-box.
+      - You can change the `proxy` prefix in settings.toml to your desired prefix with
+        `callback_url_rewrite_prefix` key.
+  - For production environment, you can use `https://yourdomain.com/auth/github/callback`
+    - **Note**: Make sure to replace `yourdomain.com` with your actual domain name that this app will be hosted on.
 
 #### How to integrate SLACK OAuth app
 
@@ -334,19 +334,92 @@ client_secret = "" # your slack client secret
 - Redirect URLs :
   `{public_server_protocol}://{public_hostname}:[{public_server_port}]/{callback_url_rewrite_prefix}/auth/slack/oauth2/callback`
 - Scopes : What you want to request to user.
-    - Recommended scopes :
-        - channels:history,
-        - channels:read,
-        - chat:write,
-        - groups:history,
-        - groups:read,
-        - im:history,
-        - mpim:history,
-        - reactions:read,
-        - reactions:write,
-
-3. Set your Slack APP Client ID / Client Secret in `{WORKDIR}/settings.toml`
-
-## Special thanks
-
-- [tott](https://x.com/tott____) for drawing the cute possum in a pocket.
+  - Recommended scopes :
+    - channels:history,
+    - channels:read,
+    - chat:write,
+    - groups:history,
+    - groups:read,
+    - im:history,
+    - mpim:history,
+    - reactions:read,
+    - reactions:write,
+
+3. Set your Slack APP Client ID / Client Secret in `$HOME/.pocket/settings.toml`
+
+#### How to start adding a new token auth
+
+1. Generate boilerplate codes for token-based auth services ?
+
+```
+# service_name should be lowercase including underscore
+poetry run hyperpocket devtool create-token-auth-template {service_name}
+```
+
+It will generate boilerplate code lines for a new token-based auth service
+
+2. Extend AuthProvider enum to add your new auth provider.
+
+```python
+class AuthProvider(Enum):
+SERVICE = 'service'
+```
+
+3. Specify auth provider for tools
+
+1) github repo or local
+
+```toml
+[auth]
+auth_provider = "{service_name}"
+auth_handler = "{service_name}-token"
+scopes = []
+```
+
+2. function_tool
+
+```python
+@function_tool(
+    auth_provider=AuthProvider.SERVICE
+)
+def my_function(**kwargs):
+```
+
+#### How to Start Developing a New Tool
+
+1. Generate Boilerplate Template for the Tool
+
+```bash
+# tool_name must be lowercase and can include underscores
+poetry run hyperpocket devtool create-tool-template your_own_tool
+```
+
+This command will generate the boilerplate directory and files for a new tool.
+
+2. Configure the `config.toml`
+
+Define the language, `auth_provider`, scopes, and other required settings in the `config.toml` file.
+
+```toml
+# Example configuration
+name = "google_delete_calendar_events"
+description = "Delete Google Calendar events"
+language = "python"
+
+[auth]
+auth_provider = "google"
+scopes = ["https://www.googleapis.com/auth/calendar"]
+```
+
+3. Develop the Tool Logic
+
+Implement the `request_model` and the necessary functions for your tool's logic in the `__main__.py` file.
+
+4. Build Your Tool
+
+Use the Hyperpocket CLI to build your tool.
+
+```bash
+# Specify the tool_path or run the command inside the tool's directory
+poetry run hyperpocket devtool build-tool ./your-own-tool
+```

{hyperpocket-0.3.1 → hyperpocket-0.3.3}/hyperpocket/auth/provider.py

@@ -10,6 +10,7 @@ class AuthProvider(Enum):
     NOTION = "notion"
     REDDIT = "reddit"
     GUMLOOP = "gumloop"
+    X = "x"
 
     @classmethod
     def get_auth_provider(cls, auth_provider_name: str) -> "AuthProvider":

hyperpocket-0.3.3/hyperpocket/auth/x/context.py

@@ -0,0 +1,13 @@
+from hyperpocket.auth.context import AuthContext
+
+
+class XAuthContext(AuthContext):
+    _ACCESS_TOKEN_KEY: str = "X_AUTH_TOKEN"
+
+    def to_dict(self) -> dict[str, str]:
+        return {self._ACCESS_TOKEN_KEY: self.access_token}
+
+    def to_profiled_dict(self, profile: str) -> dict[str, str]:
+        return {
+            f"{profile.upper()}_{self._ACCESS_TOKEN_KEY}": self.access_token,
+        }

hyperpocket-0.3.3/hyperpocket/auth/x/oauth2_context.py

@@ -0,0 +1,29 @@
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from pydantic import Field
+
+from hyperpocket.auth.x.context import XAuthContext
+from hyperpocket.auth.x.oauth2_schema import XOAuth2Response
+
+
+class XOAuth2AuthContext(XAuthContext):
+    refresh_token: Optional[str] = Field(default=None, description="Refresh token")
+
+    @classmethod
+    def from_x_oauth2_response(cls, response: XOAuth2Response) -> "XOAuth2AuthContext":
+        description = f"X OAuth2 Context logged in with {response.scope} scopes"
+        now = datetime.now(tz=timezone.utc)
+
+        if response.expires_in:
+            expires_at = now + timedelta(seconds=response.expires_in)
+        else:
+            expires_at = None
+
+        return cls(
+            access_token=response.access_token,
+            refresh_token=response.refresh_token,
+            description=description,
+            expires_at=expires_at,
+            detail=response,
+        )

hyperpocket-0.3.3/hyperpocket/auth/x/oauth2_handler.py

@@ -0,0 +1,165 @@
+import base64
+import traceback
+from typing import Optional
+from urllib.parse import urlencode, urljoin, quote
+from uuid import uuid4
+
+import httpx
+
+from hyperpocket.auth.context import AuthContext
+from hyperpocket.auth.x.oauth2_context import XOAuth2AuthContext
+from hyperpocket.auth.x.oauth2_schema import (
+    XOAuth2Request,
+    XOAuth2Response,
+)
+from hyperpocket.auth.handler import AuthHandlerInterface, AuthProvider
+from hyperpocket.config import config
+from hyperpocket.futures import FutureStore
+
+
+class XOAuth2AuthHandler(AuthHandlerInterface):
+    _X_AUTH_URL = "https://x.com/i/oauth2/authorize"
+    _X_TOKEN_URL = "https://api.x.com/2/oauth2/token"
+
+    name: str = "x-oauth2"
+    description: str = "This handler is used to authenticate users using X OAuth."
+    scoped: bool = True
+
+    @staticmethod
+    def provider() -> AuthProvider:
+        return AuthProvider.X
+
+    @staticmethod
+    def provider_default() -> bool:
+        return True
+
+    @staticmethod
+    def recommended_scopes() -> set[str]:
+        return set()
+
+    def prepare(
+        self,
+        auth_req: XOAuth2Request,
+        thread_id: str,
+        profile: str,
+        future_uid: str,
+        *args,
+        **kwargs,
+    ) -> str:
+        redirect_uri = urljoin(
+            config().public_base_url + "/",
+            f"{config().callback_url_rewrite_prefix}/auth/x/oauth2/callback",
+        )
+        code_verifier = "challenge"  # TODO: implement code_verifier
+        code_challenge = code_verifier  # TODO: implement code_challenge with sha256
+        auth_url = self._make_auth_url(
+            auth_req, redirect_uri, future_uid, code_challenge, "plain"
+        )
+
+        FutureStore.create_future(
+            future_uid,
+            data={
+                "redirect_uri": redirect_uri,
+                "thread_id": thread_id,
+                "profile": profile,
+                "code_verifier": code_verifier,
+            },
+        )
+
+        return f"User needs to authenticate using the following URL: {auth_url}"
+
+    async def authenticate(
+        self, auth_req: XOAuth2Request, future_uid: str, *args, **kwargs
+    ) -> AuthContext:
+        future_data = FutureStore.get_future(future_uid)
+        auth_code = await future_data.future
+
+        async with httpx.AsyncClient() as client:
+            basic_token = f"{auth_req.client_id}:{auth_req.client_secret}"
+            basic_token_encoded = base64.b64encode(basic_token.encode()).decode()
+            resp = await client.post(
+                url=self._X_TOKEN_URL,
+                data={
+                    "code": auth_code,
+                    # "client_id": auth_req.client_id,
+                    # "client_secret": auth_req.client_secret,
+                    "redirect_uri": future_data.data["redirect_uri"],
+                    "code_verifier": future_data.data["code_verifier"],
+                    "grant_type": "authorization_code",
+                },
+                headers={
+                    "Authorization": f"Basic {basic_token_encoded}",
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+            )
+
+        if resp.status_code != 200:
+            raise Exception(
+                f"failed to authenticate. status_code : {resp.status_code}, {resp.json()}"
+            )
+
+        resp_json = resp.json()
+        auth_response = XOAuth2Response(**resp_json)
+        return XOAuth2AuthContext.from_x_oauth2_response(auth_response)
+
+    async def refresh(
+        self, auth_req: XOAuth2Request, context: AuthContext, *args, **kwargs
+    ) -> AuthContext:
+        x_context: XOAuth2AuthContext = context
+        last_oauth2_resp: XOAuth2Response = x_context.detail
+        refresh_token = x_context.refresh_token
+        if refresh_token is None:
+            raise Exception(
+                f"refresh token is None. last_oauth2_resp: {last_oauth2_resp}"
+            )
+
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(
+                url=self._X_TOKEN_URL,
+                data={
+                    "client_id": auth_req.client_id,
+                    "client_secret": auth_req.client_secret,
+                    "refresh_token": refresh_token,
+                    "grant_type": "refresh_token",
+                },
+            )
+
+            if resp.status_code != 200:
+                raise Exception(
+                    f"failed to authenticate. status_code : {resp.status_code}"
+                )
+
+            resp_json = resp.json()
+            if "refresh_token" not in resp_json:
+                resp_json["refresh_token"] = refresh_token
+
+            response = XOAuth2Response(**resp_json)
+            return XOAuth2AuthContext.from_google_oauth2_response(response)
+
+    def _make_auth_url(
+        self,
+        auth_req: XOAuth2Request,
+        redirect_uri: str,
+        state: str,
+        code_challenge: str,
+        code_challenge_method: str,
+    ) -> str:
+        params = {
+            "client_id": auth_req.client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": "code",
+            "scope": " ".join(auth_req.auth_scopes),
+            "code_challenge": code_challenge,
+            "code_challenge_method": code_challenge_method,
+            "state": state,
+        }
+        return f"{self._X_AUTH_URL}?{urlencode(params)}"
+
+    def make_request(
+        self, auth_scopes: Optional[list[str]] = None, **kwargs
+    ) -> XOAuth2Request:
+        return XOAuth2Request(
+            auth_scopes=auth_scopes,
+            client_id=config().auth.x.client_id,
+            client_secret=config().auth.x.client_secret,
+        )

hyperpocket-0.3.3/hyperpocket/auth/x/oauth2_schema.py

@@ -0,0 +1,18 @@
+from typing import Optional
+
+from pydantic import Field
+
+from hyperpocket.auth.schema import AuthenticateRequest, AuthenticateResponse
+
+
+class XOAuth2Request(AuthenticateRequest):
+    client_id: str
+    client_secret: str
+
+
+class XOAuth2Response(AuthenticateResponse):
+    access_token: str
+    expires_in: int
+    refresh_token: Optional[str] = Field(default=None)
+    scope: str
+    token_type: str

{hyperpocket-0.3.1 → hyperpocket-0.3.3}/hyperpocket/cli/__main__.py

@@ -6,6 +6,7 @@ from hyperpocket.cli.sync import sync
 from hyperpocket.cli.eject import eject
 from hyperpocket.cli.auth_token import create_token_auth_template
 from hyperpocket.cli.auth_oauth2 import create_oauth2_auth_template
+from hyperpocket.cli.tool import create_tool_template, build_tool
 
 @click.group()
 def cli():
@@ -20,6 +21,8 @@ def devtool():
 cli.add_command(devtool)
 devtool.add_command(create_token_auth_template)
 devtool.add_command(create_oauth2_auth_template)
+devtool.add_command(create_tool_template)
+devtool.add_command(build_tool)
 
 cli.add_command(pull)
 cli.add_command(sync)

hyperpocket-0.3.3/hyperpocket/cli/codegen/tool/__init__.py

@@ -0,0 +1,3 @@
+from .tool_main_template import get_tool_main_template
+
+__all__ = ["get_tool_main_template"]