better-notion 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

better_notion/_sdk/client.py

@@ -99,6 +99,11 @@ class NotionClient:
         self._comment_cache: Cache[object] = Cache()
         # No cache for Block (too many)
 
+        # Plugin-managed resources (for SDK plugin system)
+        self._plugin_caches: dict[str, Cache[object]] = {}
+        self._plugin_managers: dict[str, object] = {}
+        self._plugin_models: dict[str, type] = {}
+
         # Search cache
         self._search_cache: dict[str, list[object]] = {}
 
@@ -259,10 +264,92 @@ class NotionClient:
 
         return results
 
+    # ===== SDK PLUGIN SYSTEM =====
+
+    def register_sdk_plugin(
+        self,
+        models: dict[str, type] | None = None,
+        caches: dict[str, "Cache"] | None = None,
+        managers: dict[str, object] | None = None,
+    ) -> None:
+        """Register an SDK plugin's resources with the client.
+
+        This method allows plugins to register custom models, caches, and
+        managers without modifying the core SDK.
+
+        Args:
+            models: Dict mapping model names to model classes
+            caches: Dict mapping cache names to Cache instances
+            managers: Dict mapping manager names to manager instances
+
+        Example:
+            >>> client.register_sdk_plugin(
+            ...     models={"Organization": Organization},
+            ...     caches={"organizations": Cache()},
+            ...     managers={"organizations": OrganizationManager(client)},
+            ... )
+        """
+        if models:
+            self._plugin_models.update(models)
+
+        if caches:
+            self._plugin_caches.update(caches)
+
+        if managers:
+            self._plugin_managers.update(managers)
+
+    def plugin_cache(self, name: str) -> "Cache | None":
+        """Access a plugin-registered cache.
+
+        Args:
+            name: Cache name (e.g., "organizations")
+
+        Returns:
+            Cache instance if found, None otherwise
+
+        Example:
+            >>> cache = client.plugin_cache("organizations")
+            >>> if cache and org_id in cache:
+            ...     org = cache[org_id]
+        """
+        return self._plugin_caches.get(name)
+
+    def plugin_manager(self, name: str) -> object | None:
+        """Access a plugin-registered manager.
+
+        Args:
+            name: Manager name (e.g., "organizations")
+
+        Returns:
+            Manager instance if found, None otherwise
+
+        Example:
+            >>> orgs_mgr = client.plugin_manager("organizations")
+            >>> if orgs_mgr:
+            ...     orgs = await orgs_mgr.list()
+        """
+        return self._plugin_managers.get(name)
+
+    def plugin_model(self, name: str) -> type | None:
+        """Access a plugin-registered model class.
+
+        Args:
+            name: Model name (e.g., "Organization")
+
+        Returns:
+            Model class if found, None otherwise
+
+        Example:
+            >>> OrgClass = client.plugin_model("Organization")
+            >>> if OrgClass:
+            ...     org = await OrgClass.get(org_id, client=client)
+        """
+        return self._plugin_models.get(name)
+
     # ===== CACHE MANAGEMENT =====
 
     def clear_all_caches(self) -> None:
-        """Clear all caches.
+        """Clear all caches including plugin caches.
 
         Example:
             >>> client.clear_all_caches()
@@ -272,8 +359,12 @@ class NotionClient:
         self._page_cache.clear()
         self._search_cache.clear()
 
+        # Clear plugin caches
+        for cache in self._plugin_caches.values():
+            cache.clear()
+
     def get_cache_stats(self) -> dict[str, dict[str, Any]]:
-        """Get statistics for all caches.
+        """Get statistics for all caches including plugin caches.
 
         Returns:
             Dict with stats for each cache
@@ -283,10 +374,11 @@ class NotionClient:
             >>> print(stats)
             {
                 'user_cache': {'hits': 100, 'misses': 5, 'size': 50, 'hit_rate': 0.95},
+                'plugin:organizations': {'hits': 50, 'misses': 2, 'size': 10, 'hit_rate': 0.96},
                 ...
             }
         """
-        return {
+        stats = {
             "user_cache": {
                 "hits": self._user_cache.stats.hits,
                 "misses": self._user_cache.stats.misses,
@@ -310,6 +402,17 @@ class NotionClient:
             }
         }
 
+        # Add plugin cache stats
+        for cache_name, cache in self._plugin_caches.items():
+            stats[f"plugin:{cache_name}"] = {
+                "hits": cache.stats.hits,
+                "misses": cache.stats.misses,
+                "size": cache.stats.size,
+                "hit_rate": cache.stats.hit_rate
+            }
+
+        return stats
+
     # ===== CONTEXT MANAGER =====
 
     async def __aenter__(self):

better_notion/_sdk/plugins.py

@@ -0,0 +1,180 @@
+"""SDK Plugin System for extending NotionClient functionality.
+
+This module provides the protocol interface for SDK-level plugins that need to:
+- Register custom model classes
+- Add dedicated caches to NotionClient
+- Create custom managers
+- Initialize plugin-specific resources
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from better_notion._sdk.cache import Cache
+    from better_notion._sdk.client import NotionClient
+    from better_notion._sdk.base.entity import BaseEntity
+
+
+class SDKPluginInterface(Protocol):
+    """
+    Protocol for SDK-level plugins that extend NotionClient functionality.
+
+    SDK plugins can register custom models, caches, and managers with the
+    NotionClient, enabling domain-specific extensions without modifying
+    the core SDK.
+
+    Example:
+        >>> class AgentsSDKPlugin:
+        ...     def register_models(self) -> dict[str, type[BaseEntity]]:
+        ...         return {"Organization": Organization}
+        ...
+        ...     def register_caches(self, client: NotionClient) -> dict[str, Cache]:
+        ...         return {"organizations": Cache()}
+        ...
+        ...     def register_managers(self, client: NotionClient) -> dict[str, Any]:
+        ...         return {"organizations": OrganizationManager(client)}
+    """
+
+    def register_models(self) -> dict[str, type[BaseEntity]]:
+        """Register custom model classes.
+
+        Model classes should inherit from BaseEntity and follow the
+        autonomous entity pattern (get, create, update methods).
+
+        Returns:
+            Dictionary mapping model names to model classes
+
+        Example:
+            >>> def register_models(self) -> dict[str, type[BaseEntity]]:
+            ...     return {
+            ...         "Organization": Organization,
+            ...         "Project": Project,
+            ...         "Task": Task,
+            ...     }
+        """
+        ...
+
+    def register_caches(self, client: "NotionClient") -> dict[str, "Cache"]:
+        """Register custom caches with the client.
+
+        Caches are stored in the client and accessible via
+        client.plugin_cache(name). Each cache should have a unique name
+        to avoid collisions with other plugins.
+
+        Args:
+            client: NotionClient instance to register caches with
+
+        Returns:
+            Dictionary mapping cache names to Cache instances
+
+        Example:
+            >>> def register_caches(self, client) -> dict[str, Cache]:
+            ...     return {
+            ...         "organizations": Cache(),
+            ...         "projects": Cache(),
+            ...         "tasks": Cache(),
+            ...     }
+        """
+        ...
+
+    def register_managers(self, client: "NotionClient") -> dict[str, Any]:
+        """Register custom managers with the client.
+
+        Managers are accessible via client.plugin_manager(name).
+        They typically provide convenience methods for working with
+        the plugin's models.
+
+        Args:
+            client: NotionClient instance
+
+        Returns:
+            Dictionary mapping manager names to manager instances
+
+        Example:
+            >>> def register_managers(self, client) -> dict[str, Any]:
+            ...     return {
+            ...         "organizations": OrganizationManager(client),
+            ...         "projects": ProjectManager(client),
+            ...     }
+        """
+        ...
+
+    def initialize(self, client: "NotionClient") -> None:
+        """Initialize plugin-specific resources.
+
+        Called after all registrations (models, caches, managers) are
+        complete. Use this for setup tasks like loading configuration,
+        validating resources, or establishing connections.
+
+        Args:
+            client: NotionClient instance
+
+        Example:
+            >>> def initialize(self, client) -> None:
+            ...     # Load database IDs from config
+            ...     db_ids = load_workspace_config()
+            ...     client._workspace_config = db_ids
+        """
+        ...
+
+    def get_info(self) -> dict[str, Any]:
+        """Return plugin metadata.
+
+        Returns:
+            Dictionary with plugin information
+
+        Example:
+            >>> def get_info(self) -> dict[str, Any]:
+            ...     return {
+            ...         "name": "agents-sdk",
+            ...         "version": "1.0.0",
+            ...         "description": "SDK extensions for agents workflow",
+            ...     }
+        """
+        ...
+
+
+class CombinedPluginInterface(Protocol):
+    """
+    Protocol for plugins that extend both CLI and SDK.
+
+    This allows a single plugin class to provide:
+    - CLI commands (via register_commands)
+    - SDK extensions (via register_models, register_caches, etc.)
+
+    Example:
+        >>> class AgentsPlugin(CombinedPluginInterface):
+        ...     def register_commands(self, app: typer.Typer) -> None:
+        ...         # Register CLI commands
+        ...         pass
+        ...
+        ...     def register_models(self) -> dict[str, type[BaseEntity]]:
+        ...         # Register SDK models
+        ...         return {"Organization": Organization}
+    """
+
+    def register_commands(self, app: Any) -> None:
+        """Register CLI commands with Typer app."""
+        ...
+
+    def register_models(self) -> dict[str, type[BaseEntity]]:
+        """Register custom model classes."""
+        ...
+
+    def register_caches(self, client: "NotionClient") -> dict[str, "Cache"]:
+        """Register custom caches."""
+        ...
+
+    def register_managers(self, client: "NotionClient") -> dict[str, Any]:
+        """Register custom managers."""
+        ...
+
+    def initialize(self, client: "NotionClient") -> None:
+        """Initialize plugin resources."""
+        ...
+
+    def get_info(self) -> dict[str, Any]:
+        """Return plugin metadata."""
+        ...

better_notion/plugins/base.py

@@ -5,14 +5,20 @@ Plugins can extend the CLI by:
 1. Adding new commands (CommandPlugin)
 2. Providing data filters/formatters (DataPlugin)
 3. Combining both capabilities
+4. Extending the SDK with models, caches, and managers (SDKPlugin)
 """
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Any, Protocol
+from typing import TYPE_CHECKING, Any, Protocol
 
 import typer
 
+if TYPE_CHECKING:
+    from better_notion._sdk.cache import Cache
+    from better_notion._sdk.client import NotionClient
+    from better_notion._sdk.base.entity import BaseEntity
+
 
 class CommandPlugin(Protocol):
     """
@@ -148,6 +154,98 @@ class PluginInterface(ABC):
         """
         return {}
 
+    # ===== SDK EXTENSION METHODS (OPTIONAL) =====
+
+    def register_sdk_models(self) -> dict[str, type[BaseEntity]]:
+        """
+        Register custom SDK model classes.
+
+        Plugins can register domain-specific models that extend BaseEntity.
+        These models are accessible via client.plugin_model(name).
+
+        Default implementation returns empty dict.
+
+        Returns:
+            Dictionary mapping model names to model classes
+
+        Example:
+            >>> def register_sdk_models(self) -> dict[str, type[BaseEntity]]:
+            ...     return {
+            ...         "Organization": Organization,
+            ...         "Project": Project,
+            ...     }
+        """
+        return {}
+
+    def register_sdk_caches(self, client: "NotionClient") -> dict[str, "Cache"]:
+        """
+        Register custom SDK caches.
+
+        Plugins can register dedicated caches for their models.
+        These caches are accessible via client.plugin_cache(name).
+
+        Default implementation returns empty dict.
+
+        Args:
+            client: NotionClient instance
+
+        Returns:
+            Dictionary mapping cache names to Cache instances
+
+        Example:
+            >>> def register_sdk_caches(self, client) -> dict[str, Cache]:
+            ...     return {
+            ...         "organizations": Cache(),
+            ...         "projects": Cache(),
+            ...     }
+        """
+        return {}
+
+    def register_sdk_managers(self, client: "NotionClient") -> dict[str, Any]:
+        """
+        Register custom SDK managers.
+
+        Plugins can register managers that provide convenience methods
+        for working with their models. Managers are accessible via
+        client.plugin_manager(name).
+
+        Default implementation returns empty dict.
+
+        Args:
+            client: NotionClient instance
+
+        Returns:
+            Dictionary mapping manager names to manager instances
+
+        Example:
+            >>> def register_sdk_managers(self, client) -> dict[str, Any]:
+            ...     return {
+            ...         "organizations": OrganizationManager(client),
+            ...     }
+        """
+        return {}
+
+    def sdk_initialize(self, client: "NotionClient") -> None:
+        """
+        Initialize SDK plugin resources.
+
+        Called after all registrations are complete. Use this for
+        setup tasks like loading configuration, validating resources,
+        or establishing connections.
+
+        Default implementation does nothing.
+
+        Args:
+            client: NotionClient instance
+
+        Example:
+            >>> def sdk_initialize(self, client) -> None:
+            ...     # Load workspace configuration
+            ...     config = load_workspace_config()
+            ...     client._workspace_config = config
+        """
+        pass
+
     def validate(self) -> tuple[bool, list[str]]:
         """
         Validate the plugin structure and configuration.

better_notion/plugins/loader.py

@@ -13,10 +13,13 @@ import importlib.util
 import json
 import sys
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from better_notion.plugins.base import CommandPlugin
 
+if TYPE_CHECKING:
+    from better_notion._sdk.client import NotionClient
+
 
 class PluginLoader:
     """
@@ -242,3 +245,50 @@ class PluginLoader:
                 return True
 
         return False
+
+    def register_sdk_extensions(self, client: "NotionClient") -> None:
+        """
+        Register SDK extensions from all loaded plugins with a NotionClient.
+
+        This method iterates through all loaded plugins and registers their
+        SDK models, caches, and managers with the provided NotionClient instance.
+
+        Args:
+            client: NotionClient instance to register extensions with
+
+        Example:
+            >>> loader = PluginLoader()
+            >>> loader.discover()  # Load plugins first
+            >>> client = NotionClient(auth="...")
+            >>> loader.register_sdk_extensions(client)
+        """
+        # Get all loaded plugins
+        plugins = list(self.loaded_plugins.values())
+
+        # Also discover plugins if not already loaded
+        if not plugins:
+            plugins = self.discover()
+
+        # Register SDK extensions from each plugin
+        for plugin in plugins:
+            try:
+                # Register models
+                models = plugin.register_sdk_models()
+                if models:
+                    client._plugin_models.update(models)
+
+                # Register caches
+                caches = plugin.register_sdk_caches(client)
+                if caches:
+                    client._plugin_caches.update(caches)
+
+                # Register managers
+                managers = plugin.register_sdk_managers(client)
+                if managers:
+                    client._plugin_managers.update(managers)
+
+                # Initialize plugin
+                plugin.sdk_initialize(client)
+            except Exception:
+                # Continue with other plugins if one fails
+                continue

better_notion/plugins/official/agents.py

@@ -23,7 +23,9 @@ import typer
 
 from better_notion._cli.config import Config
 from better_notion._cli.response import format_error, format_success
+from better_notion._sdk.cache import Cache
 from better_notion._sdk.client import NotionClient
+from better_notion._sdk.plugins import CombinedPluginInterface
 from better_notion.plugins.base import PluginInterface
 from better_notion.utils.agents import (
     DependencyResolver,
@@ -40,17 +42,26 @@ def get_client() -> NotionClient:
     return NotionClient(auth=config.token, timeout=config.timeout)
 
 
-class AgentsPlugin(PluginInterface):
+class AgentsPlugin(CombinedPluginInterface):
     """
     Official agents workflow management plugin.
 
     This plugin provides tools for managing software development workflows
     through Notion databases, enabling AI agents to coordinate work on projects.
 
-    Commands:
-        - init: Initialize a new workspace with all databases
-        - init-project: Initialize a new project with .notion file
-        - role: Manage project role
+    CLI Commands:
+        - agents init: Initialize a new workspace with all databases
+        - agents init-project: Initialize a new project with .notion file
+        - agents role: Manage project role
+        - orgs: Organizations CRUD commands
+        - projects: Projects CRUD commands
+        - versions: Versions CRUD commands
+        - tasks: Tasks CRUD and workflow commands
+
+    SDK Extensions:
+        - Organization, Project, Version, Task models
+        - Dedicated caches for each entity type
+        - Managers for convenient operations
     """
 
     def register_commands(self, app: typer.Typer) -> None:
@@ -335,6 +346,140 @@ class AgentsPlugin(PluginInterface):
         # Register agents app to main CLI
         app.add_typer(agents_app)
 
+        # Import and register CRUD commands
+        from better_notion.plugins.official import agents_cli
+
+        # Organizations commands
+        orgs_app = typer.Typer(name="orgs", help="Organizations management commands")
+        orgs_app.command("list")(agents_cli.orgs_list)
+        orgs_app.command("get")(agents_cli.orgs_get)
+        orgs_app.command("create")(agents_cli.orgs_create)
+        app.add_typer(orgs_app)
+
+        # Projects commands
+        projects_app = typer.Typer(name="projects", help="Projects management commands")
+        projects_app.command("list")(projects_list_with_cli := lambda **kwargs: agents_cli.projects_list(**kwargs))
+        projects_app.command("get")(projects_get_with_cli := lambda project_id: agents_cli.projects_get(project_id))
+        projects_app.command("create")(lambda **kwargs: agents_cli.projects_create(**kwargs))
+        app.add_typer(projects_app)
+
+        # Versions commands
+        versions_app = typer.Typer(name="versions", help="Versions management commands")
+        versions_app.command("list")(lambda **kwargs: agents_cli.versions_list(**kwargs))
+        versions_app.command("get")(lambda version_id: agents_cli.versions_get(version_id))
+        versions_app.command("create")(lambda **kwargs: agents_cli.versions_create(**kwargs))
+        app.add_typer(versions_app)
+
+        # Tasks commands
+        tasks_app = typer.Typer(name="tasks", help="Tasks management commands")
+        tasks_app.command("list")(lambda **kwargs: agents_cli.tasks_list(**kwargs))
+        tasks_app.command("get")(lambda task_id: agents_cli.tasks_get(task_id))
+        tasks_app.command("create")(lambda **kwargs: agents_cli.tasks_create(**kwargs))
+        tasks_app.command("next")(lambda **kwargs: agents_cli.tasks_next(**kwargs))
+        tasks_app.command("claim")(lambda task_id: agents_cli.tasks_claim(task_id))
+        tasks_app.command("start")(lambda task_id: agents_cli.tasks_start(task_id))
+        tasks_app.command("complete")(lambda **kwargs: agents_cli.tasks_complete(**kwargs))
+        tasks_app.command("can-start")(lambda task_id: agents_cli.tasks_can_start(task_id))
+        app.add_typer(tasks_app)
+
+        # Ideas commands
+        ideas_app = typer.Typer(name="ideas", help="Ideas management commands")
+        ideas_app.command("list")(lambda **kwargs: agents_cli.ideas_list(**kwargs))
+        ideas_app.command("get")(lambda idea_id: agents_cli.ideas_get(idea_id))
+        ideas_app.command("create")(lambda **kwargs: agents_cli.ideas_create(**kwargs))
+        ideas_app.command("review")(lambda count: agents_cli.ideas_review(count))
+        ideas_app.command("accept")(lambda idea_id: agents_cli.ideas_accept(idea_id))
+        ideas_app.command("reject")(lambda idea_id, reason: agents_cli.ideas_reject(idea_id, reason))
+        app.add_typer(ideas_app)
+
+        # Work Issues commands
+        work_issues_app = typer.Typer(name="work-issues", help="Work Issues management commands")
+        work_issues_app.command("list")(lambda **kwargs: agents_cli.work_issues_list(**kwargs))
+        work_issues_app.command("get")(lambda issue_id: agents_cli.work_issues_get(issue_id))
+        work_issues_app.command("create")(lambda **kwargs: agents_cli.work_issues_create(**kwargs))
+        work_issues_app.command("resolve")(lambda issue_id, resolution: agents_cli.work_issues_resolve(issue_id, resolution))
+        work_issues_app.command("blockers")(lambda project_id: agents_cli.work_issues_blockers(project_id))
+        app.add_typer(work_issues_app)
+
+        # Incidents commands
+        incidents_app = typer.Typer(name="incidents", help="Incidents management commands")
+        incidents_app.command("list")(lambda **kwargs: agents_cli.incidents_list(**kwargs))
+        incidents_app.command("get")(lambda incident_id: agents_cli.incidents_get(incident_id))
+        incidents_app.command("create")(lambda **kwargs: agents_cli.incidents_create(**kwargs))
+        incidents_app.command("resolve")(lambda incident_id, resolution: agents_cli.incidents_resolve(incident_id, resolution))
+        incidents_app.command("mttr")(lambda **kwargs: agents_cli.incidents_mttr(**kwargs))
+        incidents_app.command("sla-violations")(lambda: agents_cli.incidents_sla_violations())
+        app.add_typer(incidents_app)
+
+    def register_sdk_models(self) -> dict[str, type]:
+        """Register workflow entity models."""
+        from better_notion.plugins.official.agents_sdk.models import (
+            Idea,
+            Incident,
+            Organization,
+            Project,
+            Task,
+            Version,
+            WorkIssue,
+        )
+
+        return {
+            "Organization": Organization,
+            "Project": Project,
+            "Version": Version,
+            "Task": Task,
+            "Idea": Idea,
+            "WorkIssue": WorkIssue,
+            "Incident": Incident,
+        }
+
+    def register_sdk_caches(self, client: NotionClient) -> dict[str, Cache]:
+        """Register dedicated caches for workflow entities."""
+        return {
+            "organizations": Cache(),
+            "projects": Cache(),
+            "versions": Cache(),
+            "tasks": Cache(),
+            "ideas": Cache(),
+            "work_issues": Cache(),
+            "incidents": Cache(),
+        }
+
+    def register_sdk_managers(self, client: NotionClient) -> dict:
+        """Register custom managers for workflow entities."""
+        from better_notion.plugins.official.agents_sdk.managers import (
+            IdeaManager,
+            IncidentManager,
+            OrganizationManager,
+            ProjectManager,
+            TaskManager,
+            VersionManager,
+            WorkIssueManager,
+        )
+
+        return {
+            "organizations": OrganizationManager(client),
+            "projects": ProjectManager(client),
+            "versions": VersionManager(client),
+            "tasks": TaskManager(client),
+            "ideas": IdeaManager(client),
+            "work_issues": WorkIssueManager(client),
+            "incidents": IncidentManager(client),
+        }
+
+    def sdk_initialize(self, client: NotionClient) -> None:
+        """Initialize plugin resources."""
+        import json
+        from pathlib import Path
+
+        config_path = Path.home() / ".notion" / "workspace.json"
+
+        if config_path.exists():
+            with open(config_path) as f:
+                client._workspace_config = json.load(f)
+        else:
+            client._workspace_config = {}
+
     def get_info(self) -> dict[str, str | bool | list]:
         """Return plugin metadata."""
         return {