Add destinations api client

docs/cli/cli-destinations.md

@@ -0,0 +1,151 @@
+---
+title: CLI for Destinations API Tutorial
+---
+
+## Introduction
+The `planet destinations` command provides an interface for creating, listing, and modifying destinations in the [Planet Destinations API](https://docs.planet.com/develop/apis/destinations/). This tutorial takes you through the main commands available in the CLI.
+
+## Core Workflows
+
+### Create a Destination
+To discover 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 --bucket my-bucket --region us-west-2 --access-key-id AKIA... --secret-access-key SECRET... --name my-s3-destination
+```
+
+The newly created destination will be printed to stdout, 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
+List all destinations within your organization with command `planet destinations list`.
+
+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`: Set to true to include only archived destinations,
+                false to exclude them.
+* `--is-owner`: Set to true to include only destinations owned by the
+                requesting user, false to exclude them.
+* `--can-write`: Set to true to include only destinations the user can
+                 modify, false to exclude them.
+
+For example, issue the following command to list destinations that are not archived and you as the user have permission to modify:
+```sh
+planet destinations list --archived false --can-write true
+```
+
+### Modify Destinations
+The CLI conveniently moves all modify actions to first class commands on the destination. The supported actions are archive, unarchive, rename, and update 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 s3 my-destination-id --access-key-id NEW_ACCESS_KEY --secret-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