easypost-mcp 2.1.0 → 3.1.0

package/src/services/AddressService.js

@@ -1,8 +1,10 @@
 import { mapAddress } from "../adapters/easypost/responseMappers.js";
+import { createFallbackResponse } from "../elicitation/fallback.js";
 
 class AddressService {
-  constructor(easypostClient) {
+  constructor(easypostClient, { confirmations } = {}) {
     this.easypost = easypostClient;
+    this.confirmations = confirmations;
   }
 
   async verifyAddress(input, context) {
@@ -14,9 +16,32 @@ class AddressService {
       context
     );
 
+    const mapped = mapAddress(address);
+    if (hasAddressCorrection(input.address, mapped) && input.confirm !== true) {
+      try {
+        await this.confirmations?.requireConfirmed(input, {
+          action: "confirm_normalized_address",
+          message: "EasyPost returned a normalized address. Did you mean this corrected address?",
+          details: { original_address: input.address, normalized_address: mapped },
+        }, context);
+      } catch {
+        return createFallbackResponse({
+          errorCode: "ADDRESS_CONFIRMATION_REQUIRED",
+          message: "EasyPost returned a normalized address. Confirm before using it.",
+          availableOptions: [{ value: "normalized_address", address: mapped }],
+          examples: { confirm: [true] },
+          nextAction: "Retry with confirm=true if the normalized address is correct.",
+          metadata: {
+            original_address: input.address,
+            normalized_address: mapped,
+          },
+        });
+      }
+    }
+
     return {
       ok: true,
-      address: mapAddress(address),
+      address: mapped,
       verification_status: address.verifications?.delivery?.success === true ? "verified" : "review_required",
       messages: address.verifications?.delivery?.errors || [],
     };
@@ -29,8 +54,33 @@ class AddressService {
       context
     );
 
-    return { ok: true, address: mapAddress(address) };
+    const mapped = mapAddress(address);
+    if (input.verify && hasAddressCorrection(input.address, mapped) && input.confirm !== true) {
+      return createFallbackResponse({
+        errorCode: "ADDRESS_CONFIRMATION_REQUIRED",
+        message: "EasyPost returned a normalized address. Confirm before using it.",
+        availableOptions: [{ value: "normalized_address", address: mapped }],
+        examples: { confirm: [true] },
+        nextAction: "Retry with confirm=true if the normalized address is correct.",
+        metadata: {
+          original_address: input.address,
+          normalized_address: mapped,
+        },
+      });
+    }
+
+    return { ok: true, address: mapped };
+  }
+}
+
+function hasAddressCorrection(original, normalized) {
+  if (!original || !normalized) return false;
+  for (const field of ["street1", "street2", "city", "state", "zip", "country"]) {
+    const before = String(original[field] || "").trim().toUpperCase();
+    const after = String(normalized[field] || "").trim().toUpperCase();
+    if (before && after && before !== after) return true;
   }
+  return false;
 }
 
 export { AddressService };

package/src/services/BatchService.js

@@ -1,6 +1,7 @@
 class BatchService {
-  constructor(easypostClient) {
+  constructor(easypostClient, { confirmations } = {}) {
     this.easypost = easypostClient;
+    this.confirmations = confirmations;
   }
 
   async createBatch(input, context) {
@@ -17,6 +18,12 @@ class BatchService {
   }
 
   async buyBatch(input, context) {
+    await this.confirmations?.requireConfirmed(input, {
+      action: "buy_batch",
+      message: `You are about to buy labels for batch ${input.batch_id}. Proceed?`,
+      details: { batch_id: input.batch_id },
+    }, context);
+
     const batch = await this.easypost.execute(
       "batch.buy",
       (client) => client.Batch.buy(input.batch_id),

package/src/services/ConfirmationService.js

@@ -0,0 +1,45 @@
+import { AppError } from "../errors/AppError.js";
+
+class ConfirmationRequiredError extends AppError {
+  constructor({ action, message, details }) {
+    super(message, {
+      code: "CONFIRMATION_REQUIRED",
+      statusCode: 409,
+      details: {
+        action,
+        confirmation_required: true,
+        confirmation_field: "confirm",
+        expected_value: true,
+        ...details,
+      },
+      safeMessage: message,
+    });
+  }
+}
+
+class ConfirmationService {
+  async requireConfirmed(input, { action, message, details = {}, typedConfirmation }, context = {}) {
+    if (input.confirm === true) return;
+
+    const elicited = await context.elicitation?.confirm({
+      server: context.server,
+      message,
+      title: "Confirm operation",
+      description: "Required before this high-risk operation can continue.",
+      typedConfirmation,
+    });
+
+    if (elicited?.confirmed) {
+      input.confirm = true;
+      context.audit?.record("confirmation_elicited", {
+        correlationId: context.correlationId,
+        action,
+      });
+      return;
+    }
+
+    throw new ConfirmationRequiredError({ action, message, details });
+  }
+}
+
+export { ConfirmationService, ConfirmationRequiredError };

package/src/services/ElicitationService.js

@@ -0,0 +1,230 @@
+import { schemaForField } from "../elicitation/fields/catalog.js";
+
+class ElicitationService {
+  supportsForm(server) {
+    return Boolean(server?.getClientCapabilities?.()?.elicitation?.form);
+  }
+
+  async requestForm({ server, message, properties, required = [], timeoutMs = 120000 }) {
+    if (!this.supportsForm(server)) {
+      return { accepted: false, reason: "FORM_ELICITATION_UNAVAILABLE" };
+    }
+
+    try {
+      const result = await server.elicitInput(
+        {
+          mode: "form",
+          message,
+          requestedSchema: {
+            type: "object",
+            properties,
+            required,
+          },
+        },
+        { timeout: timeoutMs }
+      );
+
+      if (result.action !== "accept") {
+        return {
+          accepted: false,
+          reason: `ELICITATION_${String(result.action || "UNKNOWN").toUpperCase()}`,
+        };
+      }
+
+      return { accepted: true, content: result.content || {} };
+    } catch (error) {
+      return {
+        accepted: false,
+        reason: "ELICITATION_FAILED",
+        error: { name: error.name, message: error.message },
+      };
+    }
+  }
+
+  async singleSelect({ server, message, field = "selection", title = "Selection", description, options, required = true, timeoutMs }) {
+    const result = await this.requestForm({
+      server,
+      message,
+      timeoutMs,
+      properties: {
+        [field]: {
+          type: "string",
+          title,
+          description,
+          oneOf: options.map((option) => ({
+            const: String(option.value),
+            title: option.label,
+          })),
+        },
+      },
+      required: required ? [field] : [],
+    });
+
+    if (!result.accepted) return { selected: false, ...result };
+    return {
+      selected: true,
+      value: result.content[field],
+      content: result.content,
+    };
+  }
+
+  async multiSelect({ server, message, field = "selections", title = "Selections", description, options, timeoutMs }) {
+    const result = await this.requestForm({
+      server,
+      message,
+      timeoutMs,
+      properties: {
+        [field]: {
+          type: "array",
+          title,
+          description,
+          items: {
+            type: "string",
+            enum: options.map((option) => String(option.value)),
+          },
+        },
+      },
+      required: [field],
+    });
+
+    if (!result.accepted) return { selected: false, ...result };
+    return {
+      selected: true,
+      values: Array.isArray(result.content[field]) ? result.content[field] : [],
+      content: result.content,
+    };
+  }
+
+  async confirm({ server, message, field = "confirm", title = "Confirm", description, typedConfirmation, timeoutMs }) {
+    const properties = {
+      [field]: {
+        type: "boolean",
+        title,
+        description,
+        default: false,
+      },
+    };
+    const required = [field];
+
+    if (typedConfirmation) {
+      properties.confirmation_text = {
+        type: "string",
+        title: `Type ${typedConfirmation}`,
+        description: `Type ${typedConfirmation} to confirm.`,
+        minLength: typedConfirmation.length,
+        maxLength: typedConfirmation.length,
+      };
+      required.push("confirmation_text");
+    }
+
+    const result = await this.requestForm({ server, message, properties, required, timeoutMs });
+    if (!result.accepted) return { confirmed: false, ...result };
+
+    const typedOk = typedConfirmation
+      ? result.content.confirmation_text === typedConfirmation
+      : true;
+
+    return {
+      confirmed: result.content[field] === true && typedOk,
+      content: result.content,
+    };
+  }
+
+  async requestMissingFields({ server, toolName, missingFields, partialInput, timeoutMs }) {
+    const properties = Object.fromEntries(
+      missingFields.map((path) => [path, schemaForField(path)])
+    );
+
+    const result = await this.requestForm({
+      server,
+      timeoutMs,
+      message: `Provide the missing fields for ${toolName}. Already supplied values will be preserved.`,
+      properties,
+      required: missingFields,
+    });
+
+    if (!result.accepted) return { completed: false, ...result };
+    return {
+      completed: true,
+      input: applyFlatPaths(partialInput, result.content),
+    };
+  }
+
+  async clarify({ server, message, field, suggestions, timeoutMs }) {
+    return this.singleSelect({
+      server,
+      message,
+      field,
+      title: "Clarification",
+      description: "Choose one exact suggested value, or cancel and provide a different exact value.",
+      options: suggestions.map((suggestion) => ({
+        value: suggestion.code || suggestion.value || suggestion.id || suggestion.name,
+        label: suggestionLabel(suggestion),
+      })),
+      timeoutMs,
+    });
+  }
+
+  async selectRateForLabel({ server, shipmentId, rates, confirmDefault = false, timeoutMs = 120000 }) {
+    if (!this.supportsForm(server) || !rates.length) {
+      return { selected: false, reason: "FORM_ELICITATION_UNAVAILABLE" };
+    }
+
+    const result = await this.requestForm({
+      server,
+      timeoutMs,
+      message: `Select the rate to buy for shipment ${shipmentId}. This will purchase a shipping label only if you also confirm.`,
+      properties: {
+        rate_option: {
+          type: "string",
+          title: "Rate",
+          description: "Choose one exact returned shipment rate.",
+          oneOf: rates.map((rate, index) => ({
+            const: String(index + 1),
+            title: `${index + 1}. ${rate.carrier} ${rate.service} - ${rate.rate} ${rate.currency || "USD"}`,
+          })),
+        },
+        confirm: {
+          type: "boolean",
+          title: "Confirm label purchase",
+          description: "Required to buy the selected label.",
+          default: confirmDefault,
+        },
+      },
+      required: ["rate_option", "confirm"],
+    });
+
+    if (!result.accepted) {
+      return { selected: false, reason: result.reason, error: result.error };
+    }
+
+    const option = Number(result.content.rate_option);
+    return {
+      selected: Number.isInteger(option),
+      rate_option: option,
+      confirm: result.content.confirm === true,
+    };
+  }
+}
+
+function suggestionLabel(suggestion) {
+  const primary = suggestion.name || suggestion.code || suggestion.value || suggestion.id;
+  const score = suggestion.score !== undefined ? ` (${suggestion.score})` : "";
+  return `${primary}${score}`;
+}
+
+function applyFlatPaths(base, flatValues) {
+  const output = structuredClone(base || {});
+  for (const [path, value] of Object.entries(flatValues || {})) {
+    const parts = path.split(".");
+    let target = output;
+    for (const part of parts.slice(0, -1)) {
+      target[part] = target[part] && typeof target[part] === "object" ? target[part] : {};
+      target = target[part];
+    }
+    target[parts.at(-1)] = value;
+  }
+  return output;
+}
+
+export { ElicitationService, applyFlatPaths };

package/src/services/IdempotencyStore.js

@@ -0,0 +1,40 @@
+class IdempotencyStore {
+  constructor({ ttlMs = 10 * 60 * 1000 } = {}) {
+    this.ttlMs = ttlMs;
+    this.entries = new Map();
+  }
+
+  _purgeExpired() {
+    const now = Date.now();
+    for (const [key, entry] of this.entries.entries()) {
+      if (entry.expiresAt <= now) this.entries.delete(key);
+    }
+  }
+
+  get(key) {
+    if (!key) return null;
+    this._purgeExpired();
+    const entry = this.entries.get(key);
+    return entry?.result || null;
+  }
+
+  set(key, result) {
+    if (!key) return result;
+    this._purgeExpired();
+    this.entries.set(key, {
+      result,
+      expiresAt: Date.now() + this.ttlMs,
+    });
+    return result;
+  }
+
+  async run(key, operation) {
+    const existing = this.get(key);
+    if (existing) return { reused: true, result: existing };
+    const result = await operation();
+    this.set(key, result);
+    return { reused: false, result };
+  }
+}
+
+export { IdempotencyStore };

package/src/services/PickupService.js

@@ -1,35 +1,62 @@
 class PickupService {
-  constructor(easypostClient) {
+  constructor(easypostClient, { confirmations, idempotency } = {}) {
     this.easypost = easypostClient;
+    this.confirmations = confirmations;
+    this.idempotency = idempotency;
   }
 
   async schedulePickup(input, context) {
-    const pickup = await this.easypost.execute(
-      "pickup.create",
-      (client) => client.Pickup.create({
-        shipment: { id: input.shipment_ids[0] },
-        address: input.address,
+    await this.confirmations?.requireConfirmed(input, {
+      action: "schedule_pickup",
+      message: `You are about to create a pickup window from ${input.min_datetime} to ${input.max_datetime} for ${input.shipment_ids.length} shipment(s). Proceed?`,
+      details: {
+        shipment_ids: input.shipment_ids,
         min_datetime: input.min_datetime,
         max_datetime: input.max_datetime,
-        instructions: input.instructions,
-        carrier_accounts: input.carrier_accounts,
-      }),
-      context
-    );
+      },
+    }, context);
 
-    const pickupRate = pickup.lowestRate?.() || pickup.pickup_rates?.[0];
-    const scheduled = pickupRate
-      ? await this.easypost.execute(
-          "pickup.buy",
-          (client) => client.Pickup.buy(pickup.id, pickupRate.carrier, pickupRate.service),
-          context
-        )
-      : pickup;
+    const operation = async () => {
+      const pickup = await this.easypost.execute(
+        "pickup.create",
+        (client) => client.Pickup.create({
+          shipment: { id: input.shipment_ids[0] },
+          address: input.address,
+          min_datetime: input.min_datetime,
+          max_datetime: input.max_datetime,
+          instructions: input.instructions,
+          carrier_accounts: input.carrier_accounts,
+        }),
+        context
+      );
 
-    return { ok: true, pickup: scheduled, pickup_rate: pickupRate || null };
+      context.audit?.record("pickup_created", {
+        correlationId: context.correlationId,
+        pickup_id: pickup.id,
+        pickup_rate_count: Array.isArray(pickup.pickup_rates) ? pickup.pickup_rates.length : 0,
+      });
+
+      return {
+        ok: true,
+        pickup,
+        pickup_rates: pickup.pickup_rates || [],
+        next_step: "Review returned pickup_rates. This tool does not auto-buy a pickup rate.",
+      };
+    };
+
+    if (!this.idempotency || !input.idempotency_key) return operation();
+    const { reused, result } = await this.idempotency.run(`schedule_pickup:${input.idempotency_key}`, operation);
+    return reused ? { ...result, idempotent_replay: true } : result;
   }
 
   async cancelPickup(input, context) {
+    await this.confirmations?.requireConfirmed(input, {
+      action: "cancel_pickup",
+      message: `You are about to cancel pickup ${input.pickup_id}. Proceed?`,
+      details: { pickup_id: input.pickup_id },
+      typedConfirmation: "CANCEL",
+    }, context);
+
     const pickup = await this.easypost.execute(
       "pickup.cancel",
       (client) => client.Pickup.cancel(input.pickup_id),

package/src/services/ReturnService.js

@@ -1,8 +1,10 @@
 import { mapShipment, mapRate } from "../adapters/easypost/responseMappers.js";
 
 class ReturnService {
-  constructor(easypostClient) {
+  constructor(easypostClient, { confirmations, elicitation } = {}) {
     this.easypost = easypostClient;
+    this.confirmations = confirmations;
+    this.elicitation = elicitation;
   }
 
   async createReturnLabel(input, context) {
@@ -18,13 +20,41 @@ class ReturnService {
       context
     );
 
-    const rate = input.carrier && input.service
-      ? (shipment.rates || []).find((candidate) => candidate.carrier === input.carrier && candidate.service === input.service)
-      : shipment.lowestRate?.();
+    const rates = shipment.rates || [];
+    if (!input.rate_id && !input.rate_option) {
+      return {
+        ok: true,
+        shipment: mapShipment(shipment),
+        rates: rates.map((rate, index) => ({ option: index + 1, ...mapRate(rate) })),
+        next_step: "Choose a numbered rate_option or exact rate_id to buy the return label. The server will not auto-select a return rate.",
+      };
+    }
 
-    const bought = rate
-      ? await this.easypost.execute("return.buy", (client) => client.Shipment.buy(shipment.id, rate), context)
-      : shipment;
+    const rate = input.rate_id
+      ? rates.find((candidate) => candidate.id === input.rate_id)
+      : rates[input.rate_option - 1];
+
+    if (!rate) {
+      return {
+        ok: false,
+        success: false,
+        error_code: "RETURN_RATE_SELECTION_REQUIRED",
+        message: "The requested return rate selection is unavailable. Select one returned option.",
+        missing_fields: [],
+        ambiguous_fields: [],
+        available_options: rates.map((candidate, index) => ({ option: index + 1, ...mapRate(candidate) })),
+        examples: { rate_option: [1] },
+        next_action: "Retry with a valid rate_option or rate_id from available_options.",
+      };
+    }
+
+    await this.confirmations?.requireConfirmed(input, {
+      action: "create_return_label",
+      message: `You are about to buy a return label using ${rate.carrier} ${rate.service} for ${rate.rate} ${rate.currency || "USD"}. Proceed?`,
+      details: { rate: mapRate(rate), shipment_id: shipment.id },
+    }, context);
+
+    const bought = await this.easypost.execute("return.buy", (client) => client.Shipment.buy(shipment.id, rate), context);
 
     return { ok: true, shipment: mapShipment(bought), purchased_rate: mapRate(rate) };
   }