default destinations sdk and cli support

Author: asonnenschein

planet/cli/destinations.py

@@ -65,6 +65,33 @@ async def _create_destination(ctx, data, pretty):
             raise ClickException(f"Failed to create destination: {e}")
 
 
+async def _set_default_destination(ctx, destination_id, pretty):
+    async with destinations_client(ctx) as cl:
+        try:
+            response = await cl.set_default_destination(destination_id)
+            echo_json(response, pretty)
+        except Exception as e:
+            raise ClickException(f"Failed to set default destination: {e}")
+
+
+async def _unset_default_destination(ctx, pretty):
+    async with destinations_client(ctx) as cl:
+        try:
+            response = await cl.unset_default_destination()
+            echo_json(response, pretty)
+        except Exception as e:
+            raise ClickException(f"Failed to unset default destination: {e}")
+
+
+async def _get_default_destination(ctx, pretty):
+    async with destinations_client(ctx) as cl:
+        try:
+            response = await cl.get_default_destination()
+            echo_json(response, pretty)
+        except Exception as e:
+            raise ClickException(f"Failed to get default destination: {e}")
+
+
 @command(destinations, name="list")
 @click.option('--archived',
               type=bool,
@@ -590,3 +617,57 @@ async def update_s3_compatible(ctx,
         data["parameters"]["use_path_style"] = True
 
     await _patch_destination(ctx, destination_id, data, pretty)
+
+
+@destinations.group()
+def default():
+    """Commands for interacting with default destinations."""
+    pass
+
+
+@command(default, name="set")
+@click.argument("destination_id")
+async def set_default_destination(ctx, destination_id, pretty):
+    """
+    Set a default destination.
+
+    This command sets a specified destination as the default for the organization.  Default destinations
+    are globally available to all members of an organization.  An organization can have zero or one default
+    destination at any time.  Ability to set a default destination is restricted to organization
+    administrators and destination owners.
+
+    Example:
+
+        planet destinations default set my-destination-id
+    """
+    await _set_default_destination(ctx, destination_id, pretty)
+
+
+@command(default, name="unset")
+async def unset_default_destination(ctx, pretty):
+    """
+    Unset the current default destination.
+
+    This command unsets the current default destination.  Ability to unset a default destination is restricted
+    to organization administrators and destination owners.  Returns None (HTTP 204, No Content) on success.
+
+    Example:
+
+        planet destinations default unset
+    """
+    await _unset_default_destination(ctx, pretty)
+
+
+@command(default, name="get")
+async def get_default_destination(ctx, pretty):
+    """
+    Get the current default destination.
+
+    This command gets the current default destination for the organization, if one is set.  The default
+    destination is globally available to all members of an organization.
+
+    Example:
+
+        planet destinations default get
+    """
+    await _get_default_destination(ctx, pretty)

planet/clients/destinations.py

@@ -26,6 +26,8 @@
 
 T = TypeVar("T")
 
+DEFAULT_DESTINATION_REF = "pl:destinations/default"
+
 
 class DestinationsClient(_BaseClient):
     """Asynchronous Destinations API client.
@@ -174,3 +176,77 @@ async def create_destination(self, request: Dict[str, Any]) -> Dict:
         else:
             dest = response.json()
             return dest
+
+    async def set_default_destination(self, destination_id: str) -> None:
+        """
+        Set an existing destination as the default destination.  Default destinations are globally available
+        to all members of an organization.  An organization can have zero or one default destination at any time.
+        Ability to set a default destination is restricted to organization administrators and destination owners.
+
+        Args:
+            destination_id (str): The ID of the destination to set as default.
+
+        Returns:
+            dict: A dictionary containing the default destination details.
+
+        Raises:
+            APIError: If the API returns an error response.
+            ClientError: If there is an issue with the client request.
+        """
+        url = f'{self._base_url}/default'
+        request = {
+            "destination_id": destination_id
+        }
+        try:
+            response = await self._session.request(method='PUT',
+                                        url=url,
+                                        json=request)
+        except APIError:
+            raise
+        except ClientError:  # pragma: no cover
+            raise
+        else:
+            return response.json()
+
+    async def unset_default_destination(self) -> None:
+        """
+        Unset the current default destination.  Ability to unset a default destination is restricted to
+        organization administrators and destination owners.  Returns None (HTTP 204, No Content) on success.
+
+        Returns:
+            None
+
+        Raises:
+            APIError: If the API returns an error response.
+            ClientError: If there is an issue with the client request.
+        """
+        url = f'{self._base_url}/default'
+        try:
+            await self._session.request(method='DELETE', url=url)
+        except APIError:
+            raise
+        except ClientError:  # pragma: no cover
+            raise
+
+    async def get_default_destination(self) -> Dict:
+        """
+        Get the current default destination.  The default destination is globally available to all members of an
+        organization.
+
+        Returns:
+            dict: A dictionary containing the default destination details.
+
+        Raises:
+            APIError: If the API returns an error response.
+            ClientError: If there is an issue with the client request.
+        """
+        url = f'{self._base_url}/default'
+        try:
+            response = await self._session.request(method='GET', url=url)
+        except APIError:
+            raise
+        except ClientError:  # pragma: no cover
+            raise
+        else:
+            dest = response.json()
+            return dest

planet/order_request.py

@@ -392,6 +392,35 @@ def s3_compatible(endpoint: str,
     return {'s3_compatible': parameters}
 
 
+def destination(destination_ref: str, path_prefix: Optional[str] = None) -> dict:
+    """Destinations API configuration.
+    Parameters:
+        destination_ref: Reference to an existing Destinations API
+            destination.
+        path_prefix: Path prefix for deliveries.
+    """
+    cloud_details: Dict[str, Any] = {'ref': destination_ref}
+
+    if path_prefix:
+        cloud_details['path_prefix'] = path_prefix
+
+    return {'destination': cloud_details}
+
+
+def default_destination(path_prefix: Optional[str] = None) -> dict:
+    """Default Destinations API configuration.
+
+    Parameters:
+        path_prefix: Path prefix for deliveries.
+    """
+    parameters: Dict[str, Any] = {'ref': 'pl:destinations/default'}
+
+    if path_prefix:
+        parameters['path_prefix'] = path_prefix
+
+    return {'destination': parameters}
+
+
 def _tool(name: str, parameters: dict) -> dict:
     """Create the API spec representation of a tool.
 

planet/subscription_request.py

@@ -19,6 +19,7 @@
 from typing_extensions import Literal
 
 from . import geojson, specs
+from .clients.destinations import DEFAULT_DESTINATION_REF
 from .exceptions import ClientError
 
 NOTIFICATIONS_TOPICS = ('delivery.success',
@@ -528,6 +529,34 @@ def s3_compatible(endpoint: str,
     return _delivery('s3_compatible', parameters)
 
 
+def destination(destination_ref: str, path_prefix: Optional[str] = None) -> dict:
+    """Specify a Destinations API destination by its ref.
+
+    Parameters:
+        destination_id: The ID of the destination to deliver to.
+    """
+    parameters: Dict[str, Any] = {"ref": destination_ref}
+
+    if path_prefix:
+        parameters['path_prefix'] = path_prefix
+
+    return _delivery('destination', parameters)
+
+
+def default_destination(path_prefix: Optional[str] = None) -> dict:
+    """Specify the organization's default Destinations API destination.
+
+    Parameters:
+        path_prefix: Path prefix for deliveries.
+    """
+    parameters: Dict[str, Any] = {"ref": DEFAULT_DESTINATION_REF}
+
+    if path_prefix:
+        parameters['path_prefix'] = path_prefix
+
+    return _delivery('destination', parameters)
+
+
 def notifications(url: str, topics: List[str]) -> dict:
     """Specify a subscriptions API notification.