feat: bulk sharing - invite multiple collaborators in one API call (Issue #73)

- Core: add_collaborators_bulk() on SharingMixin
- Services: invite_collaborators_bulk() with upfront validation
- MCP: notebook_share_batch tool with recipients list + confirm
- CLI: nlm share batch <notebook> 'emails' --role viewer
- 10 new unit tests for bulk sharing
- Version bump to 0.4.0

Author: jacob-bd

CHANGELOG.md

@@ -4,10 +4,18 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-## [Unreleased / 0.3.21]
+## [0.4.0] - 2026-03-05
+
+### Added
+- **Bulk Sharing (`notebook_share_batch`)** — Invite multiple collaborators to a notebook in a single API call (Issue #73). Supports mixed roles (viewer/editor) per recipient.
+  - Core: `add_collaborators_bulk(notebook_id, recipients)` on `SharingMixin`
+  - Service: `invite_collaborators_bulk(client, notebook_id, recipients)` with upfront validation
+  - MCP: `notebook_share_batch` tool with `recipients` list and `confirm` flag
+  - CLI: `nlm share batch <notebook> "a@gmail.com,b@gmail.com" --role viewer`
+- **10 new unit tests** for bulk sharing (core + services)
 
 ### Fixed
-- **Version mismatch (Patch)** — Bump internal `__version__` string in `__init__.py` to correctly report as `0.3.21` (was omitted in `0.3.20` release).
+- **Version mismatch (Patch)** — Bump internal `__version__` string in `__init__.py` to correctly report version (was omitted in `0.3.20` release).
 
 ## [0.3.20] - 2026-03-04
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "notebooklm-mcp-cli"
-version = "0.3.20"
+version = "0.4.0"
 description = "Unified CLI and MCP server for Google NotebookLM"
 readme = "README.md"
 license = "MIT"

src/notebooklm_tools/__init__.py

@@ -1,6 +1,6 @@
 """NotebookLM Tools - Unified CLI and MCP server for Google NotebookLM."""
 
-__version__ = "0.3.20"
+__version__ = "0.4.0"
 
 from notebooklm_tools.core.client import NotebookLMClient
 

src/notebooklm_tools/cli/commands/share.py

@@ -138,3 +138,50 @@ def share_invite(
         if e.hint:
             console.print(f"\n[dim]Hint: {e.hint}[/dim]")
         raise typer.Exit(1)
+
+
+@app.command("batch")
+def share_batch(
+    notebook: str = typer.Argument(..., help="Notebook ID or alias"),
+    emails: str = typer.Argument(..., help="Comma-separated email addresses"),
+    role: str = typer.Option("viewer", "--role", "-r", help="Role for all: viewer or editor"),
+    profile: Optional[str] = typer.Option(None, "--profile", "-p", help="Profile to use"),
+) -> None:
+    """Invite multiple collaborators at once.
+
+    Example: nlm share batch <notebook> "a@gmail.com,b@gmail.com" --role viewer
+    """
+    try:
+        notebook_id = get_alias_manager().resolve(notebook)
+
+        # Parse comma-separated emails into recipients list
+        email_list = [e.strip() for e in emails.split(",") if e.strip()]
+        if not email_list:
+            console.print("[red]Error:[/red] No valid email addresses provided.")
+            raise typer.Exit(1)
+
+        recipients = [{"email": e, "role": role} for e in email_list]
+
+        with get_client(profile) as client:
+            result = sharing_service.invite_collaborators_bulk(client, notebook_id, recipients)
+
+        console.print(f"[green]✓[/green] {result['message']}")
+
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("Email")
+        table.add_column("Role")
+
+        for r in result["recipients"]:
+            role_color = "cyan" if r["role"] == "editor" else "dim"
+            table.add_row(r["email"], f"[{role_color}]{r['role']}[/{role_color}]")
+
+        console.print(table)
+
+    except ServiceError as e:
+        console.print(f"[red]Error:[/red] {e.user_message}")
+        raise typer.Exit(1)
+    except NLMError as e:
+        console.print(f"[red]Error:[/red] {e.message}")
+        if e.hint:
+            console.print(f"\n[dim]Hint: {e.hint}[/dim]")
+        raise typer.Exit(1)

src/notebooklm_tools/core/sharing.py

@@ -4,6 +4,7 @@
 - get_share_status: Get current collaborators and public access
 - set_public_access: Toggle public link access
 - add_collaborator: Add a collaborator by email
+- add_collaborators_bulk: Add multiple collaborators in a single API call
 """
 
 from .base import BaseClient
@@ -150,3 +151,51 @@ def add_collaborator(
 
         # Success if result is not None (no error thrown)
         return result is not None
+
+    def add_collaborators_bulk(
+        self,
+        notebook_id: str,
+        recipients: list[dict],
+        notify: bool = True,
+        message: str = "",
+    ) -> bool:
+        """Add multiple collaborators to a notebook in a single API call.
+
+        Args:
+            notebook_id: The notebook UUID
+            recipients: List of dicts, each with 'email' (str) and 'role' (str).
+                        Role must be 'viewer' or 'editor'.
+            notify: Send email notification (default: True)
+            message: Optional welcome message
+
+        Returns:
+            True if successful
+
+        Raises:
+            ValueError: If any role is invalid or recipients list is empty
+        """
+        if not recipients:
+            raise ValueError("Recipients list cannot be empty")
+
+        # Build the multi-email array: [[email1, None, role_code1], [email2, None, role_code2], ...]
+        email_items = []
+        for recipient in recipients:
+            email = recipient["email"]
+            role = recipient.get("role", "viewer")
+            role_code = constants.SHARE_ROLES.get_code(role)
+            if role_code == constants.SHARE_ROLE_OWNER:
+                raise ValueError(f"Cannot add collaborator '{email}' as owner")
+            email_items.append([email, None, role_code])
+
+        notify_flag = 0 if notify else 1  # 0 = notify, 1 = don't notify
+
+        params = [
+            [[notebook_id, email_items, None, [notify_flag, message]]],
+            1,
+            None,
+            [2]
+        ]
+
+        result = self._call_rpc(self.RPC_SHARE_NOTEBOOK, params)
+
+        return result is not None

src/notebooklm_tools/mcp/tools/__init__.py

@@ -23,6 +23,7 @@
     notebook_share_status,
     notebook_share_public,
     notebook_share_invite,
+    notebook_share_batch,
 )
 from .research import (
     research_start,
@@ -65,10 +66,11 @@
     "source_delete",
     "source_describe",
     "source_get_content",
-    # Sharing (3)
+    # Sharing (4)
     "notebook_share_status",
     "notebook_share_public",
     "notebook_share_invite",
+    "notebook_share_batch",
     # Research (3)
     "research_start",
     "research_status",

src/notebooklm_tools/mcp/tools/sharing.py

@@ -71,3 +71,35 @@ def notebook_share_invite(
         return {"status": "error", "error": e.user_message}
     except Exception as e:
         return {"status": "error", "error": str(e)}
+
+
+@logged_tool()
+def notebook_share_batch(
+    notebook_id: str,
+    recipients: list[dict],
+    confirm: bool = False,
+) -> dict[str, Any]:
+    """Invite multiple collaborators in a single request.
+
+    Args:
+        notebook_id: Notebook UUID
+        recipients: List of dicts, each with 'email' (str) and optional 'role' (str).
+                    Role defaults to 'viewer'. Example: [{"email": "a@b.com", "role": "editor"}]
+        confirm: Must be True after user approval
+
+    Returns: invited_count, recipients list, and message
+    """
+    if not confirm:
+        return {
+            "status": "confirmation_required",
+            "message": f"About to invite {len(recipients)} collaborators. Set confirm=True to proceed.",
+            "recipients": recipients,
+        }
+    try:
+        client = get_client()
+        result = sharing_service.invite_collaborators_bulk(client, notebook_id, recipients)
+        return {"status": "success", **result}
+    except ServiceError as e:
+        return {"status": "error", "error": e.user_message}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}

src/notebooklm_tools/services/sharing.py

@@ -41,6 +41,20 @@ class InviteResult(TypedDict):
     message: str
 
 
+class RecipientInfo(TypedDict):
+    """Individual recipient in a bulk invite."""
+    email: str
+    role: str
+
+
+class BulkInviteResult(TypedDict):
+    """Result of a bulk collaborator invitation."""
+    notebook_id: str
+    invited_count: int
+    recipients: list[RecipientInfo]
+    message: str
+
+
 def _collaborator_to_dict(c: Collaborator) -> CollaboratorInfo:
     """Convert a Collaborator dataclass to a dict."""
     return {
@@ -162,3 +176,66 @@ def invite_collaborator(
         raise
     except Exception as e:
         raise ServiceError(f"Failed to invite collaborator: {e}")
+
+
+def invite_collaborators_bulk(
+    client: NotebookLMClient,
+    notebook_id: str,
+    recipients: list[dict],
+) -> BulkInviteResult:
+    """Invite multiple collaborators in a single API call.
+
+    Args:
+        client: Authenticated NotebookLM client
+        notebook_id: Notebook UUID
+        recipients: List of dicts, each with 'email' (str) and optional 'role' (str).
+                    Role defaults to 'viewer' if not specified.
+
+    Returns:
+        BulkInviteResult with invitation summary
+
+    Raises:
+        ValidationError: If recipients list is empty or any role is invalid
+        ServiceError: If the API call fails
+    """
+    if not recipients:
+        raise ValidationError(
+            "Recipients list is empty.",
+            user_message="You must provide at least one email address.",
+        )
+
+    # Validate all roles upfront before making the API call
+    cleaned_recipients: list[RecipientInfo] = []
+    for recipient in recipients:
+        email = recipient.get("email", "").strip()
+        if not email:
+            raise ValidationError(
+                "Empty email in recipients list.",
+                user_message="Each recipient must have a non-empty email address.",
+            )
+        role = recipient.get("role", "viewer").lower()
+        if role not in ("viewer", "editor"):
+            raise ValidationError(
+                f"Invalid role '{role}' for {email}. Must be 'viewer' or 'editor'.",
+                user_message=f"Role must be 'viewer' or 'editor' (got '{role}' for {email})",
+            )
+        cleaned_recipients.append({"email": email, "role": role})
+
+    try:
+        result = client.add_collaborators_bulk(notebook_id, cleaned_recipients)
+        if result:
+            emails_str = ", ".join(r["email"] for r in cleaned_recipients)
+            return {
+                "notebook_id": notebook_id,
+                "invited_count": len(cleaned_recipients),
+                "recipients": cleaned_recipients,
+                "message": f"Invited {len(cleaned_recipients)} collaborators: {emails_str}",
+            }
+        raise ServiceError(
+            "Bulk invitation returned falsy result",
+            user_message="Bulk invitation may have failed — no confirmation from API.",
+        )
+    except ServiceError:
+        raise
+    except Exception as e:
+        raise ServiceError(f"Failed to invite collaborators: {e}")

tests/core/test_sharing.py

@@ -25,6 +25,7 @@ def test_sharing_mixin_has_methods():
         'get_share_status',
         'set_public_access',
         'add_collaborator',
+        'add_collaborators_bulk',
     ]
 
     for method_name in expected_methods:
@@ -79,3 +80,53 @@ def test_add_collaborator_uses_correct_rpc():
             call_args = mock_rpc.call_args
             assert call_args[0][0] == "QDyure"  # RPC_SHARE_NOTEBOOK
             assert result is True
+
+
+def test_add_collaborators_bulk_uses_correct_rpc():
+    """Test that add_collaborators_bulk calls the correct RPC with multi-email payload."""
+    from notebooklm_tools.core.sharing import SharingMixin
+    
+    with patch.object(SharingMixin, '_refresh_auth_tokens'):
+        with patch.object(SharingMixin, '_call_rpc') as mock_rpc:
+            mock_rpc.return_value = []
+            
+            mixin = SharingMixin(cookies={"test": "cookie"}, csrf_token="test")
+            recipients = [
+                {"email": "alice@example.com", "role": "viewer"},
+                {"email": "bob@example.com", "role": "editor"},
+            ]
+            result = mixin.add_collaborators_bulk("notebook_id_123", recipients)
+            
+            mock_rpc.assert_called_once()
+            call_args = mock_rpc.call_args
+            assert call_args[0][0] == "QDyure"  # RPC_SHARE_NOTEBOOK
+            
+            # Verify the multi-email array structure
+            params = call_args[0][1]
+            email_items = params[0][0][1]  # [[email, None, role_code], ...]
+            assert len(email_items) == 2
+            assert email_items[0][0] == "alice@example.com"
+            assert email_items[0][2] == 3  # SHARE_ROLE_VIEWER
+            assert email_items[1][0] == "bob@example.com"
+            assert email_items[1][2] == 2  # SHARE_ROLE_EDITOR
+            assert result is True
+
+
+def test_add_collaborators_bulk_empty_recipients():
+    """Test that add_collaborators_bulk raises ValueError for empty list."""
+    from notebooklm_tools.core.sharing import SharingMixin
+    
+    with patch.object(SharingMixin, '_refresh_auth_tokens'):
+        mixin = SharingMixin(cookies={"test": "cookie"}, csrf_token="test")
+        with pytest.raises(ValueError, match="Recipients list cannot be empty"):
+            mixin.add_collaborators_bulk("notebook_id_123", [])
+
+
+def test_add_collaborators_bulk_rejects_owner_role():
+    """Test that add_collaborators_bulk raises ValueError for owner role."""
+    from notebooklm_tools.core.sharing import SharingMixin
+    
+    with patch.object(SharingMixin, '_refresh_auth_tokens'):
+        mixin = SharingMixin(cookies={"test": "cookie"}, csrf_token="test")
+        with pytest.raises(ValueError, match="Cannot add collaborator"):
+            mixin.add_collaborators_bulk("notebook_id_123", [{"email": "a@b.com", "role": "owner"}])