[21034] add MCP-optimized actions for Returnista

components/returnista/actions/create-draft-return-order/create-draft-return-order.mjs

@@ -0,0 +1,105 @@
+import { ConfigurationError } from "@pipedream/platform";
+import returnista from "../../returnista.app.mjs";
+
+export default {
+  key: "returnista-create-draft-return-order",
+  name: "Create Draft Return Order",
+  description: "Creates a new draft return order for a consumer."
+    + " Draft return orders are pending merchant review before being accepted or rejected."
+    + " Use **Process Draft Return Order** to accept or reject the created draft."
+    + " [See the documentation](https://platform.returnista.com/reference/rest-api/#post-/consumer/-consumerId-/draft-return-order)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  props: {
+    returnista,
+    consumerId: {
+      propDefinition: [
+        returnista,
+        "consumerId",
+      ],
+    },
+    purchaseId: {
+      propDefinition: [
+        returnista,
+        "purchaseId",
+      ],
+    },
+    returnReasonId: {
+      propDefinition: [
+        returnista,
+        "returnReasonId",
+      ],
+    },
+    returnReasonComment: {
+      propDefinition: [
+        returnista,
+        "returnReasonComment",
+      ],
+    },
+    resolutionType: {
+      propDefinition: [
+        returnista,
+        "resolutionType",
+      ],
+    },
+    exchangeProductId: {
+      propDefinition: [
+        returnista,
+        "exchangeProductId",
+      ],
+    },
+    exchangeOptionSku: {
+      propDefinition: [
+        returnista,
+        "exchangeOptionSku",
+      ],
+    },
+    answers: {
+      propDefinition: [
+        returnista,
+        "answers",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const answers = Array.isArray(this.answers)
+      ? this.answers.map((a, index) => {
+        try {
+          return JSON.parse(a);
+        } catch {
+          throw new ConfigurationError(`answers[${index}] must be valid JSON: ${a}`);
+        }
+      })
+      : undefined;
+    const response = await this.returnista.createDraftReturnOrder({
+      $,
+      consumerId: this.consumerId,
+      data: {
+        selectedPurchases: [
+          {
+            purchaseId: this.purchaseId,
+            returnReasonId: this.returnReasonId || null,
+            returnReasonComment: this.returnReasonComment,
+            resolutionType: this.resolutionType,
+            answers,
+            exchangeProductId: this.exchangeProductId,
+            exchangeOptionSku: this.exchangeOptionSku,
+          },
+        ],
+      },
+    });
+    const createdDraftId = response?.id ?? response?.data?.id;
+    $.export(
+      "$summary",
+      createdDraftId
+        ? `Successfully created draft return order ${createdDraftId}`
+        : `Successfully created draft return order for consumer ${this.consumerId}`,
+    );
+    return response;
+  },
+};

components/returnista/actions/create-return-location/create-return-location.mjs

@@ -3,14 +3,19 @@ import returnista from "../../returnista.app.mjs";
 export default {
   key: "returnista-create-return-location",
   name: "Create Return Location",
-  description: "Creates a new return location for the given account. [See the documentation](https://platform.returnista.com/reference/rest-api/#post-/account/-accountId/return-location)",
-  version: "0.0.1",
+  description: "Creates a new return location (warehouse or depot address) for an account."
+    + " Required: `accountId`, `name`, `companyName`, `phoneNumber`, `street`, `houseNumber`, `city`, `postalCode`,"
+    + " `countryCode` (ISO 3166-1 alpha-2, e.g. `NL`, `DE`, `GB`, `US`)."
+    + " Optional: `suffix`, `stateProvinceCode`, `attention`, `contactName`."
+    + " To update a location after creation, use **Update Return Location** with the returned ID."
+    + " [See the documentation](https://platform.returnista.com/reference/rest-api/#post-/account/-accountId/return-location)",
+  version: "1.0.0",
+  type: "action",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
     readOnlyHint: false,
   },
-  type: "action",
   props: {
     returnista,
     accountId: {
@@ -25,6 +30,12 @@ export default {
         "name",
       ],
     },
+    companyName: {
+      propDefinition: [
+        returnista,
+        "companyName",
+      ],
+    },
     street: {
       propDefinition: [
         returnista,
@@ -69,12 +80,6 @@ export default {
       ],
       optional: true,
     },
-    companyName: {
-      propDefinition: [
-        returnista,
-        "companyName",
-      ],
-    },
     attention: {
       propDefinition: [
         returnista,
@@ -117,7 +122,7 @@ export default {
         contactName: this.contactName,
       },
     });
-    $.export("$summary", `Successfully created return location with ID: ${response.id}`);
+    $.export("$summary", `Successfully created return location "${this.name}" with ID: ${response.id}`);
     return response;
   },
 };

components/returnista/actions/get-consumer-purchases/get-consumer-purchases.mjs

@@ -3,14 +3,17 @@ import returnista from "../../returnista.app.mjs";
 export default {
   key: "returnista-get-consumer-purchases",
   name: "Get Consumer Purchases",
-  description: "Get consumer purchases. [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/consumer/-consumerId/purchases)",
-  version: "0.0.1",
+  description: "Gets the purchase history for a consumer by their consumer ID."
+    + " Useful for support workflows to understand what a consumer has purchased before they initiated a return."
+    + " To find a consumer ID, use **Get Return Orders** with `expand: [\"consumer\"]` on a related return order — the consumer object will include the ID."
+    + " [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/consumer/-consumerId/purchases)",
+  version: "0.0.2",
+  type: "action",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
     readOnlyHint: true,
   },
-  type: "action",
   props: {
     returnista,
     consumerId: {
@@ -21,11 +24,14 @@ export default {
     },
   },
   async run({ $ }) {
-    const { data: response } = await this.returnista.getConsumerPurchases({
+    const response = await this.returnista.getConsumerPurchases({
       $,
       consumerId: this.consumerId,
     });
-    $.export("$summary", `Successfully retrieved ${response.length} consumer purchases`);
-    return response;
+    const purchases = response?.data ?? (Array.isArray(response)
+      ? response
+      : []);
+    $.export("$summary", `Retrieved ${purchases.length} purchase(s) for consumer ${this.consumerId}`);
+    return purchases;
   },
 };

components/returnista/actions/get-draft-return-orders/get-draft-return-orders.mjs

@@ -6,7 +6,7 @@ export default {
   key: "returnista-get-draft-return-orders",
   name: "Get Draft Return Orders",
   description: "Gets a list of draft return orders for the given account. [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/account/-accountId-/draft-return-orders)",
-  version: "0.0.1",
+  version: "0.0.2",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

components/returnista/actions/get-return-locations/get-return-locations.mjs

@@ -4,7 +4,7 @@ export default {
   key: "returnista-get-return-locations",
   name: "Get Return Locations",
   description: "Gets a list of return locations for the given account. [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/account/-accountId/return-locations)",
-  version: "0.0.1",
+  version: "0.0.2",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

components/returnista/actions/get-return-order-emails/get-return-order-emails.mjs

@@ -3,14 +3,17 @@ import returnista from "../../returnista.app.mjs";
 export default {
   key: "returnista-get-return-order-emails",
   name: "Get Return Order Emails",
-  description: "Returns emails related to a return order. [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/account/-accountId/return-orders/emails)",
-  version: "0.0.1",
+  description: "Gets all email communications associated with a return order."
+    + " Useful for support and audit workflows to see what emails were sent to the consumer during the return process."
+    + " To find a return order ID, use **Get Return Orders** first."
+    + " [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/account/-accountId/return-order/-id/emails)",
+  version: "0.0.2",
+  type: "action",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
     readOnlyHint: true,
   },
-  type: "action",
   props: {
     returnista,
     accountId: {
@@ -23,20 +26,22 @@ export default {
       propDefinition: [
         returnista,
         "returnOrderId",
-        ({ accountId }) => ({
-          accountId,
+        (c) => ({
+          accountId: c.accountId,
         }),
       ],
     },
   },
   async run({ $ }) {
-    const { data: response } = await this.returnista.getReturnOrderEmails({
+    const response = await this.returnista.getReturnOrderEmails({
       $,
       accountId: this.accountId,
       returnOrderId: this.returnOrderId,
     });
-
-    $.export("$summary", `Successfully retrieved ${response.length} return order emails`);
-    return response;
+    const emails = response?.data ?? (Array.isArray(response)
+      ? response
+      : []);
+    $.export("$summary", `Retrieved ${emails.length} email(s) for return order ${this.returnOrderId}`);
+    return emails;
   },
 };

components/returnista/actions/get-return-order/get-return-order.mjs

@@ -3,14 +3,18 @@ import returnista from "../../returnista.app.mjs";
 export default {
   key: "returnista-get-return-order",
   name: "Get Return Order",
-  description: "Gets a return order by ID. [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/account/-accountId/return-order/-id)",
-  version: "0.0.1",
+  description: "Gets the full details of a single return order by ID."
+    + " Use `expand` to inline related objects (consumer, shipments, returnRequests) in one call instead of making separate requests."
+    + " To find a return order ID, use **Get Return Orders** first."
+    + " To view the email communications for a return order, use **Get Return Order Emails**."
+    + " [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/account/-accountId/return-order/-id)",
+  version: "0.0.2",
+  type: "action",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
     readOnlyHint: true,
   },
-  type: "action",
   props: {
     returnista,
     accountId: {
@@ -23,8 +27,8 @@ export default {
       propDefinition: [
         returnista,
         "returnOrderId",
-        ({ accountId }) => ({
-          accountId,
+        (c) => ({
+          accountId: c.accountId,
         }),
       ],
     },

components/returnista/actions/get-return-orders/get-return-orders.mjs

@@ -4,7 +4,7 @@ export default {
   key: "returnista-get-return-orders",
   name: "Get Return Orders",
   description: "Gets a list of return orders for the given account. [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/account/-accountId/return-orders)",
-  version: "0.0.1",
+  version: "0.0.2",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

components/returnista/actions/get-return-reasons/get-return-reasons.mjs

@@ -4,7 +4,7 @@ export default {
   key: "returnista-get-return-reasons",
   name: "Get Return Reasons",
   description: "Gets a list of return reasons for the given account. [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/return-reasons)",
-  version: "0.0.1",
+  version: "0.0.2",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,

components/returnista/actions/get-return-request/get-return-request.mjs

@@ -3,14 +3,17 @@ import returnista from "../../returnista.app.mjs";
 export default {
   key: "returnista-get-return-request",
   name: "Get Return Request",
-  description: "Gets a return request by ID. [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/account/-accountId-/return-request/-id-)",
-  version: "0.0.1",
+  description: "Gets the full details of a single return request by ID."
+    + " Return requests contain item-level information: purchase order number, return reason, requested resolution (refund, exchange, etc.)."
+    + " To find a return request ID, use **Get Return Requests** first."
+    + " [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/account/-accountId-/return-request/-id-)",
+  version: "0.0.2",
+  type: "action",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
     readOnlyHint: true,
   },
-  type: "action",
   props: {
     returnista,
     accountId: {
@@ -23,8 +26,8 @@ export default {
       propDefinition: [
         returnista,
         "returnRequestId",
-        ({ accountId }) => ({
-          accountId,
+        (c) => ({
+          accountId: c.accountId,
         }),
       ],
     },
@@ -35,7 +38,7 @@ export default {
       accountId: this.accountId,
       returnRequestId: this.returnRequestId,
     });
-    $.export("$summary", `Successfully retrieved return request with ID: ${this.returnRequestId}`);
+    $.export("$summary", `Successfully retrieved return request ${this.returnRequestId}`);
     return response;
   },
 };

components/returnista/actions/get-return-requests/get-return-requests.mjs

@@ -4,7 +4,7 @@ export default {
   key: "returnista-get-return-requests",
   name: "Get Return Requests",
   description: "Gets a list of return requests for the given account. [See the documentation](https://platform.returnista.com/reference/rest-api/#get-/account/-accountId-/return-requests)",
-  version: "0.0.1",
+  version: "0.0.2",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,