Add destinations api client

docs/cli/cli-destinations.md

@@ -0,0 +1,148 @@
+---
+title: CLI for Destinations API Tutorial
+---
+
+## Introduction
+The `planet destinations` command enables interaction with the [Destinations API](https://docs.planet.com/develop/apis/destinations/), which enables the creation, listing, and modifying of destinations as well as using destinations in other services to streamline data delivery. This tutorial takes you through the main commands available in the CLI.
+
+## Core Workflows
+
+### Create a Destination
+To discover the supported cloud destinations, run the command `planet destinations create --help`. Once you have chosen your target cloud destination type, run the command `planet destinations create <type> --help` to discover the required and supported parameters (eg: `planet destinations create s3 --help`).
+
+Finally, submit the full request:
+```sh
+planet destinations create s3 my-bucket us-west-2 AKIA... SECRET... --name my-s3-destination
+```
+
+The newly created destination will be printed to standard out, with the destination reference under the key `pl:ref`, which can subsequently be used in Orders API and Subscriptions API requests as the delivery destination.
+
+### List Destinations
+Listing destinations can be accomplished with the command `planet destinations list`. This will return all destinations within your organization.
+
+You can get nicer formatting with `--pretty` or pipe it into `jq`, just like the other Planet CLIs.
+
+#### Filtering
+The `list` command supports filtering on a variety of fields. You can discover all filterable fields by running the command `planet destinations list --help`.
+
+* `--archived / --is-not-archived`: Filter by archive status. Use --archived to include only archived destinations, or --is-not-archived to list only active (not archived) destinations.
+* `--is-owner / --is-not-owner`: Filter by ownership. Use --is-owner to include only destinations owned by the requesting user, or --is-not-owner to include destinations not owned by the user.
+* `--can-write / --can-not-write`: Filter by write access. Use --can-write to include only destinations the user can modify, or --can-not-write to list destinations with read-only access for the user.
+
+For example, to list destinations that are not archived and you can modify you would issue the following command:
+```sh
+planet destinations list --not-archived --can-write
+```
+
+### Update Destinations
+The CLI conveniently moves all update actions to first class commands on the destination. The allowed update actions are archiving, unarchiving, renaming, and updating credentials. To discover all update actions run `planet destinations --help`.
+
+To discover more information about a specific update action, use the `--help` flag (eg: `planet destinations rename --help`, `planet destinations update --help`).
+
+Credential updating might be done if credentials expire or need to be rotated. For example, this is how s3 credentials would be updated.
+```sh
+planet destinations update parameters s3 my-destination-id NEW_ACCESS_KEY NEW_SECRET_KEY
+```
+
+## Using destinations in Subscriptions API
+After creating a destination, it can be used as the delivery location for subscriptions. Use the destination reference in the delivery block instead of credentials.
+
+The subsequent examples will use the destination ref `pl:destinations/my-s3-destination-6HRjBcW74jeH9SC4VElKqX`.
+```json
+{
+  "name": "Subscription using a destination",
+  "source": {
+    "parameters": {
+      "asset_types": [
+        "ortho_analytic_8b"
+      ],
+      "end_time": "2023-11-01T00:00:00Z",
+      "geometry": {
+        "coordinates": [
+          [
+            [
+              139.5648193359375,
+              35.42374884923695
+            ],
+            [
+              140.1031494140625,
+              35.42374884923695
+            ],
+            [
+              140.1031494140625,
+              35.77102915686019
+            ],
+            [
+              139.5648193359375,
+              35.77102915686019
+            ],
+            [
+              139.5648193359375,
+              35.42374884923695
+            ]
+          ]
+        ],
+        "type": "Polygon"
+      },
+      "item_types": [
+        "PSScene"
+      ],
+      "start_time": "2023-03-17T04:08:00.0Z"
+    }
+  },
+  "delivery": {
+    "type": "destination",
+    "parameters": {
+      "ref": "pl:destinations/my-s3-destination-6HRjBcW74jeH9SC4VElKqX",
+    }
+  }
+}
+```
+
+Then create the subscription, with the json above saved to a file.
+```sh
+planet subscriptions create my-subscription.json
+```
+
+The results of the created subscription will be delivered to the destination provided.
+
+To retrieve all subscriptions created with a specific destination, issue the following command:
+```sh
+planet subscriptions list --destination-ref pl:destinations/my-s3-destination-6HRjBcW74jeH9SC4VElKqX
+```
+
+## Using destinations in Orders API
+After creating a destination, it can be used as the delivery location for orders. Use the destination reference in the delivery block instead of credentials.
+
+The subsequent examples will use the destination ref `pl:destinations/my-s3-destination-6HRjBcW74jeH9SC4VElKqX`.
+```json
+{
+  "name": "Order using a destination",
+  "products": [
+    {
+      "item_ids": [
+        "20220605_124027_64_242b"
+      ],
+      "item_type": "PSScene",
+      "product_bundle": "analytic_sr_udm2"
+    }
+  ],
+  "delivery": {
+    "destination": {
+      "ref": "pl:destinations/cp-gcs-6HRjBcW74jeH9SC4VElKqX"
+    }
+  }
+}
+```
+
+Then create the order, with the json above saved to a file.
+```sh
+planet orders create my-order.json
+```
+
+The results of the created order will be delivered to the destination provided.
+
+To retrieve all orders created with a specific destination, issue the following command:
+```sh
+planet orders list --destination-ref pl:destinations/my-s3-destination-6HRjBcW74jeH9SC4VElKqX
+```

docs/cli/cli-orders.md

@@ -83,6 +83,7 @@ The `list` command supports filtering on a variety of fields:
 * `--created-on`: Filter on the order creation time or an interval of creation times.
 * `--last-modified`: Filter on the order's last modified time or an interval of last modified times.
 * `--hosting`: Filter on orders containing a hosting location (e.g. SentinelHub). Accepted values are `true` or `false`.
+* `--destination-ref`: Filter on orders created with the provided destination reference.
 
 Datetime args (`--created-on` and `--last-modified`) can either be a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.
 * A date-time: `2018-02-12T23:20:50Z`

docs/cli/cli-subscriptions.md

@@ -130,7 +130,7 @@ outputs the JSON for your first 100 subscriptions. If you'd like more you can se
 parameter higher, or you can set it to 0 and there will be no limit.  By default the `list` command will request Subscriptions API with a page size of 500 subscriptions, and can be set lower or higher with the `--page-size` parameter.
 
 You can get nicer formatting with `--pretty` or pipe it into `jq`, just like the other Planet
-CLI’s.
+CLIs.
 
 #### Filtering
 
@@ -139,11 +139,12 @@ The `list` command supports filtering on a variety of fields:
 * `--end-time`: Filter on the subscription end time or an interval of end times.
 * `--hosting`: Filter on subscriptions containing a hosting location (e.g. SentinelHub). Accepted values are `true` or `false`.
 * `--name-contains`: Filter on subscriptions with a name that contains the provided string.
-* `--name`: Filter on subscriptions with a specific name
+* `--name`: Filter on subscriptions with a specific name.
 * `--source-type`: Filter by the source type of the subscription. For the full list of available source types, see [Subscription Source Types](https://docs.planet.com/develop/apis/subscriptions/sources/#catalog-source-type). Multiple source type args are allowed.
 * `--start-time`: Filter on the subscription start time or an interval of start times.
 * `--status`: Filter on the status of the subscription. Status options include `running`, `cancelled`, `preparing`, `pending`, `completed`, `suspended`, and `failed`. Multiple status args are allowed.
 * `--updated`: Filter on the subscription update time or an interval of updated times.
+* `--destination-ref`: Filter on subscriptions created with the provided destination reference.
 
 Datetime args (`--created`, `end-time`, `--start-time`, and `--updated`) can either be a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.
 * A date-time: `2018-02-12T23:20:50Z`

planet/__init__.py

@@ -16,7 +16,7 @@
 from . import data_filter, order_request, reporting, subscription_request
 from .__version__ import __version__  # NOQA
 from .auth import Auth
-from .clients import DataClient, FeaturesClient, OrdersClient, SubscriptionsClient  # NOQA
+from .clients import DataClient, DestinationsClient, FeaturesClient, OrdersClient, SubscriptionsClient  # NOQA
 from .io import collect
 from .sync import Planet
 
@@ -25,6 +25,7 @@
     'collect',
     'DataClient',
     'data_filter',
+    'DestinationsClient',
     'FeaturesClient',
     'OrdersClient',
     'order_request',

planet/cli/cli.py

@@ -20,7 +20,7 @@
 
 import planet
 
-from . import auth, collect, data, orders, subscriptions, features
+from . import auth, collect, data, destinations, orders, subscriptions, features
 
 LOGGER = logging.getLogger(__name__)
 
@@ -78,4 +78,5 @@ def _configure_logging(verbosity):
 main.add_command(orders.orders)  # type: ignore
 main.add_command(subscriptions.subscriptions)  # type: ignore
 main.add_command(collect.collect)  # type: ignore
-main.add_command(features.features)
+main.add_command(features.features)  # type: ignore
+main.add_command(destinations.destinations)  # type: ignore