INTEG-2940 - add legal-hold

Author: ceciliastevens

CHANGELOG.md

@@ -10,6 +10,11 @@
  here.
 ## Unreleased
 
+### Added
+
+- The `orgs` and `legal_hold` clients to the SDK.
+- The `orgs` and `legal-hold` command groups to the CLI.
+
 ## 2.4.0 - 2025-05-27
 
 ### Added

docs/cli/cmds/legal_hold.md

@@ -0,0 +1,6 @@
+# Legal Hold Commands
+
+::: mkdocs-click
+    :module: _incydr_cli.cmds.legal_hold
+    :command: legal_hold
+    :list_subcommands:

docs/sdk/clients/legal_hold.md

@@ -0,0 +1,5 @@
+# Legal Hold
+
+::: _incydr_sdk.legal_hold.client.LegalHoldV1
+    :docstring:
+    :members:

mkdocs.yml

@@ -54,6 +54,7 @@ nav:
       - File Events: 'sdk/clients/file_events.md'
       - Files: 'sdk/clients/files.md'
       - File Event Querying: 'sdk/clients/file_event_queries.md'
+      - Legal Hold: 'sdk/clients/legal_hold.md'
       - Orgs: 'sdk/clients/orgs.md'
       - Sessions: 'sdk/clients/sessions.md'
       - Trusted Activites: 'sdk/clients/trusted_activities.md'
@@ -81,6 +82,7 @@ nav:
         - Directory Groups: 'cli/cmds/directory_groups.md'
         - File Events: 'cli/cmds/file_events.md'
         - Files: 'cli/cmds/files.md'
+        - Legal Hold: 'cli/cmds/legal_hold.md'
         - Orgs: 'cli/cmds/orgs.md'
         - Sessions: 'cli/cmds/sessions.md'
         - Trusted Activites: 'cli/cmds/trusted_activities.md'

src/_incydr_cli/cmds/legal_hold.py

@@ -0,0 +1,274 @@
+from typing import Optional
+
+import click
+from rich.panel import Panel
+
+from _incydr_cli import console
+from _incydr_cli import logging_options
+from _incydr_cli import render
+from _incydr_cli.cmds.options.output_options import columns_option
+from _incydr_cli.cmds.options.output_options import single_format_option
+from _incydr_cli.cmds.options.output_options import SingleFormat
+from _incydr_cli.cmds.options.output_options import table_format_option
+from _incydr_cli.cmds.options.output_options import TableFormat
+from _incydr_cli.core import IncydrCommand
+from _incydr_cli.core import IncydrGroup
+from _incydr_sdk.core.client import Client
+from _incydr_sdk.legal_hold.models import Custodian
+from _incydr_sdk.legal_hold.models import CustodianMatter
+from _incydr_sdk.legal_hold.models import LegalHoldPolicy
+from _incydr_sdk.legal_hold.models import Matter
+from _incydr_sdk.utils import model_as_card
+
+
+@click.group(cls=IncydrGroup)
+@logging_options
+def legal_hold():
+    """View and manage legal holds."""
+
+
+@legal_hold.command("list-matters-for-user", cls=IncydrCommand)
+@click.argument("user-id")
+@table_format_option
+@columns_option
+@logging_options
+def list_matters_for_user(user_id: str, format_: TableFormat, columns: Optional[str]):
+    """List the matter memberships for a specific user."""
+    client = Client()
+    memberships_ = client.legal_hold.v1.iter_all_memberships_for_user(user_id=user_id)
+
+    if format_ == TableFormat.csv:
+        render.csv(CustodianMatter, memberships_, columns=columns, flat=True)
+    elif format_ == TableFormat.table:
+        render.table(CustodianMatter, memberships_, columns=columns, flat=False)
+    elif format_ == TableFormat.json_pretty:
+        for item in memberships_:
+            console.print_json(item.json())
+    else:
+        for item in memberships_:
+            click.echo(item.json())
+
+
+@legal_hold.command("list-custodians", cls=IncydrCommand)
+@click.argument("matter-id")
+@table_format_option
+@columns_option
+@logging_options
+def list_custodians(matter_id: str, format_: TableFormat, columns: Optional[str]):
+    """List the matter memberships for a specific user."""
+    client = Client()
+    memberships_ = client.legal_hold.v1.iter_all_custodians(matter_id=matter_id)
+
+    if format_ == TableFormat.csv:
+        render.csv(Custodian, memberships_, columns=columns, flat=True)
+    elif format_ == TableFormat.table:
+        render.table(Custodian, memberships_, columns=columns, flat=False)
+    elif format_ == TableFormat.json_pretty:
+        for item in memberships_:
+            console.print_json(item.json())
+    else:
+        for item in memberships_:
+            click.echo(item.json())
+
+
+@legal_hold.command("add-custodian", cls=IncydrCommand)
+@click.option("--user-id", required=True, default=None, help="The user ID to add.")
+@click.option(
+    "--matter-id",
+    required=True,
+    default=None,
+    help="The matter ID to which the user will be added",
+)
+@single_format_option
+@logging_options
+def add_custodian(user_id: str, matter_id: str, format_: SingleFormat):
+    """Add a custodian to a matter."""
+    client = Client()
+    result = client.legal_hold.v1.add_custodian(user_id=user_id, matter_id=matter_id)
+
+    if format_ == SingleFormat.rich and client.settings.use_rich:
+        console.print(
+            Panel.fit(
+                model_as_card(result), title=f"Membership: {result.custodian.username}"
+            )
+        )
+    elif format_ == SingleFormat.json_pretty:
+        console.print_json(result.json())
+    else:
+        click.echo(result.json())
+
+
+@legal_hold.command("remove-custodian", cls=IncydrCommand)
+@click.option("--user-id", required=True, default=None, help="The user ID to remove.")
+@click.option(
+    "--matter-id",
+    required=True,
+    default=None,
+    help="The matter ID from which the user will be removed",
+)
+@logging_options
+def remove_custodian(
+    user_id: str,
+    matter_id: str,
+):
+    """Remove custodian from a matter."""
+    client = Client()
+    client.legal_hold.v1.remove_custodian(user_id=user_id, matter_id=matter_id)
+    console.log(f"User {user_id} removed successfully from matter {matter_id}.")
+
+
+@legal_hold.command("list-matters", cls=IncydrCommand)
+@click.option(
+    "--creator-user-id",
+    default=None,
+    help="Find legal hold matters that were created by the user with this unique identifier.",
+)
+@click.option(
+    "--active/--inactive",
+    default=None,
+    help="Filter by active or inactive matters. Defaults to returning both when when neither option is passed.",
+)
+@click.option(
+    "--name",
+    default=None,
+    help="Find legal hold matters whose 'name' either equals or partially contains this value.",
+)
+@table_format_option
+@columns_option
+@logging_options
+def list_matters(
+    creator_user_id: Optional[str],
+    active: Optional[bool],
+    name: Optional[str],
+    format_: TableFormat,
+    columns: Optional[str],
+):
+    """List all matters."""
+    client = Client()
+    result = client.legal_hold.v1.iter_all_matters(
+        creator_user_id=creator_user_id, active=active, name=name
+    )
+
+    if format_ == TableFormat.csv:
+        render.csv(Matter, result, columns=columns, flat=True)
+    elif format_ == TableFormat.table:
+        render.table(Matter, result, columns=columns, flat=False)
+    elif format_ == TableFormat.json_pretty:
+        for item in result:
+            console.print_json(item.json())
+    else:
+        for item in result:
+            click.echo(item.json())
+
+
+@legal_hold.command("create-matter", cls=IncydrCommand)
+@click.option(
+    "--policy-id",
+    required=True,
+    default=None,
+    help="The policy ID to be used by the created matter. Required.",
+)
+@click.option(
+    "--name",
+    required=True,
+    default=None,
+    help="The name of the matter to be created. Required.",
+)
+@click.option(
+    "--description", default=None, help="The description of the matter to be created."
+)
+@click.option("--notes", default=None, help="The notes for the matter to be created.")
+@single_format_option
+@logging_options
+def create_matter(
+    policy_id: str,
+    name: str,
+    description: Optional[str],
+    notes: Optional[str],
+    format_: SingleFormat,
+):
+    """Create a matter."""
+    client = Client()
+    result = client.legal_hold.v1.create_matter(
+        policy_id=policy_id, name=name, description=description, notes=notes
+    )
+
+    if format_ == SingleFormat.rich and client.settings.use_rich:
+        console.print(Panel.fit(model_as_card(result), title=f"Matter: {result.name}"))
+    elif format_ == SingleFormat.json_pretty:
+        console.print_json(result.json())
+    else:
+        click.echo(result.json())
+
+
+@legal_hold.command("deactivate-matter", cls=IncydrCommand)
+@click.argument("matter-id")
+@logging_options
+def deactivate_matter(matter_id: str):
+    """Deactivate a matter."""
+    client = Client()
+    client.legal_hold.v1.deactivate_matter(matter_id=matter_id)
+    console.log(f"Successfully deactivated {matter_id}")
+
+
+@legal_hold.command("reactivate-matter", cls=IncydrCommand)
+@click.argument("matter-id")
+@logging_options
+def reactivate_matter(matter_id: str):
+    """Reactivate a matter."""
+    client = Client()
+    client.legal_hold.v1.reactivate_matter(matter_id=matter_id)
+    console.log(f"Successfully reactivated {matter_id}")
+
+
+@legal_hold.command("show-matter", cls=IncydrCommand)
+@click.argument("matter-id")
+@single_format_option
+@logging_options
+def show_matter(matter_id: str, format_: SingleFormat):
+    """Show details for a matter."""
+    client = Client()
+    result = client.legal_hold.v1.get_matter(matter_id=matter_id)
+
+    if format_ == SingleFormat.rich and client.settings.use_rich:
+        console.print(Panel.fit(model_as_card(result), title=f"Matter: {result.name}"))
+    elif format_ == SingleFormat.json_pretty:
+        console.print_json(result.json())
+    else:
+        click.echo(result.json())
+
+
+@legal_hold.command("list-policies", cls=IncydrCommand)
+@table_format_option
+@columns_option
+@logging_options
+def list_policies(format_: TableFormat, columns: Optional[str]):
+    client = Client()
+    result = client.legal_hold.v1.iter_all_policies()
+
+    if format_ == TableFormat.csv:
+        render.csv(LegalHoldPolicy, result, columns=columns, flat=True)
+    elif format_ == TableFormat.table:
+        render.table(LegalHoldPolicy, result, columns=columns, flat=False)
+    elif format_ == TableFormat.json_pretty:
+        for item in result:
+            console.print_json(item.json())
+    else:
+        for item in result:
+            click.echo(item.json())
+
+
+@legal_hold.command("show-policy", cls=IncydrCommand)
+@click.argument("policy-id")
+@single_format_option
+@logging_options
+def show_policy(policy_id: str, format_: SingleFormat):
+    client = Client()
+    result = client.legal_hold.v1.get_policy(policy_id=policy_id)
+
+    if format_ == SingleFormat.rich and client.settings.use_rich:
+        console.print(Panel.fit(model_as_card(result), title=f"Policy: {result.name}"))
+    elif format_ == SingleFormat.json_pretty:
+        console.print_json(result.json())
+    else:
+        click.echo(result.json())

src/_incydr_cli/cmds/orgs.py

@@ -93,7 +93,7 @@ def create(
     external_reference: Optional[str],
     notes: Optional[str],
     parent_org_guid: Optional[str],
-    format_: TableFormat,
+    format_: SingleFormat,
     columns: Optional[str],
 ):
     """
@@ -134,7 +134,7 @@ def deactivate_org(org_guid: str):
 @logging_options
 def show(
     org_guid: str,
-    format_: TableFormat,
+    format_: SingleFormat,
     columns: Optional[str],
 ):
     """
@@ -174,7 +174,7 @@ def update(
     name: str,
     external_reference: Optional[str],
     notes: Optional[str],
-    format_: TableFormat,
+    format_: SingleFormat,
     columns: Optional[str],
 ):
     """

src/_incydr_cli/main.py

@@ -19,6 +19,7 @@
 from _incydr_cli.cmds.directory_groups import directory_groups
 from _incydr_cli.cmds.file_events import file_events
 from _incydr_cli.cmds.files import files as files_client
+from _incydr_cli.cmds.legal_hold import legal_hold
 from _incydr_cli.cmds.orgs import orgs
 from _incydr_cli.cmds.risk_profiles import risk_profiles
 from _incydr_cli.cmds.sessions import sessions
@@ -90,6 +91,7 @@ def incydr(version, python, script_dir):
 incydr.add_command(trusted_activities)
 incydr.add_command(users)
 incydr.add_command(orgs)
+incydr.add_command(legal_hold)
 incydr.add_command(watchlists)
 
 if __name__ == "__main__":

src/_incydr_sdk/core/client.py

@@ -23,6 +23,7 @@
 from _incydr_sdk.exceptions import AuthMissingError
 from _incydr_sdk.file_events.client import FileEventsClient
 from _incydr_sdk.files.client import FilesClient
+from _incydr_sdk.legal_hold.client import LegalHoldClient
 from _incydr_sdk.orgs.client import OrgsClient
 from _incydr_sdk.risk_profiles.client import RiskProfiles
 from _incydr_sdk.sessions.client import SessionsClient
@@ -109,6 +110,7 @@ def response_hook(response, *args, **kwargs):
         self._directory_groups = DirectoryGroupsClient(self)
         self._file_events = FileEventsClient(self)
         self._files = FilesClient(self)
+        self._legal_hold = LegalHoldClient(self)
         self._orgs = OrgsClient(self)
         self._sessions = SessionsClient(self)
         self._trusted_activities = TrustedActivitiesClient(self)
@@ -297,6 +299,17 @@ def files(self):
         """
         return self._files
 
+    @property
+    def legal_hold(self):
+        """
+        Property returning a [`LegalHoldClient`](../legal_hold) for interacting with `/v1/legal-hold` API endpoints.
+
+        Usage:
+
+            >>> client.legal_hold.v1.iter_all_matters()
+        """
+        return self._legal_hold
+
     @property
     def orgs(self):
         """