@shippo/shippo-mcp 2.0.2 → 2.0.8

package/src/mcp-server/tools/addressesValidateV2.ts

@@ -0,0 +1,105 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { addressesValidateV2 } from "../../funcs/addressesValidateV2.js";
+import { ValidateAddressV2Request$zodSchema } from "../../models/validateaddressv2op.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: ValidateAddressV2Request$zodSchema,
+};
+
+export const tool$addressesValidateV2: ToolDefinition<typeof args> = {
+  name: "addresses-validate-v2",
+  description:
+    `**PRIMARY ADDRESS VALIDATION TOOL** - Use this tool whenever asked to validate an address.
+
+This is the recommended v2 validation endpoint that provides comprehensive results:
+- Original address as submitted
+- Recommended address with corrections
+- Confidence score (high/medium/low)
+- Validation result (valid/invalid/unknown)
+- Address type (residential/commercial/unknown)
+- List of changed attributes
+- Geographic coordinates (latitude/longitude)
+
+**Required Fields:**
+- \`address_line_1\`: The street address (required)
+- \`country_code\`: ISO 3166 country code (required)
+
+**US Address Requirements (one of):**
+- state_province + city_locality + address_line_1
+- OR address_line_1 + postal_code
+
+**International Requirements:**
+- city_locality + address_line_1
+
+**Example Request:**
+\`\`\`
+address_line_1: "731 Market Street"
+address_line_2: "#200"
+city_locality: "San Francisco"
+state_province: "CA"
+postal_code: "94103"
+country_code: "US"
+\`\`\`
+
+**Example Response:**
+\`\`\`json
+{
+  "recommended_address": {
+    "address_line_1": "731 MARKET ST",
+    "city_locality": "SAN FRANCISCO",
+    "state_province": "CA",
+    "postal_code": "94103-2007",
+    "country_code": "US",
+    "confidence_result": {
+      "score": "high",
+      "description": "Address verified"
+    }
+  },
+  "analysis": {
+    "validation_result": {"value": "valid"},
+    "address_type": "commercial",
+    "changed_attributes": ["address_line_1", "postal_code"]
+  },
+  "geo": {"latitude": 37.7879, "longitude": -122.4074}
+}
+\`\`\`
+
+**Use Cases:**
+- Validate customer shipping addresses before label purchase
+- Get corrected/standardized address formatting
+- Determine if address is residential or commercial
+- Get ZIP+4 extended postal codes
+- Geocode addresses for mapping
+`,
+  scopes: ["read", "validation"],
+  annotations: {
+    "title": "",
+    "destructiveHint": false,
+    "idempotentHint": false,
+    "openWorldHint": false,
+    "readOnlyHint": false,
+  },
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await addressesValidateV2(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/ordersList.ts

@@ -14,13 +14,31 @@ export const tool$ordersList: ToolDefinition<typeof args> = {
   name: "orders-list",
   description: `List all orders
 
-Returns a list of all order objects.`,
+Returns a list of all order objects.
+
+**Available Filters:**
+- \`orderStatus\`: Filter by order status. Can pass multiple values as an array.
+  - Values: UNKNOWN, AWAITPAY, PAID, REFUNDED, CANCELLED, PARTIALLY_FULFILLED, SHIPPED
+- \`shop_app\`: Filter by platform/source where order was created
+  - Values: Amazon, Bigcommerce, CSV_Import, eBay, ePages, Etsy, Godaddy, Magento, Shippo, Shopify, Spreecommerce, StripeRelay, Walmart, Weebly, WooCommerce
+- \`start_date\`: Filter orders placed AFTER this date/time (ISO 8601 UTC format, e.g., "2025-01-01T00:00:00Z")
+- \`end_date\`: Filter orders placed BEFORE this date/time (ISO 8601 UTC format)
+- \`page/results\`: Pagination controls
+
+**Example Use Cases:**
+- "Show all paid orders" → filter by \`orderStatus: ["PAID"]\`
+- "Show Shopify orders from last week" → combine \`shop_app: "Shopify"\` with date filters
+- "Show orders ready to ship" → filter by \`orderStatus: ["PAID"]\`
+- "Show cancelled or refunded orders" → filter by \`orderStatus: ["CANCELLED", "REFUNDED"]\`
+
+**Note:** Date filters are based on \`placed_at\` field (when order was placed), not when the order object was created in Shippo.
+`,
   annotations: {
     "title": "",
     "destructiveHint": false,
     "idempotentHint": false,
     "openWorldHint": false,
-    "readOnlyHint": true,
+    "readOnlyHint": false,
   },
   args,
   tool: async (client, args, ctx) => {

package/src/models/addressanalysisv2.ts

@@ -0,0 +1,41 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+import {
+  ValidationResultV2,
+  ValidationResultV2$zodSchema,
+} from "./validationresultv2.js";
+
+export const AddressAnalysisV2AddressType = {
+  Residential: "residential",
+  Commercial: "commercial",
+  Unknown: "unknown",
+} as const;
+export type AddressAnalysisV2AddressType = ClosedEnum<
+  typeof AddressAnalysisV2AddressType
+>;
+
+export const AddressAnalysisV2AddressType$zodSchema = z.enum([
+  "residential",
+  "commercial",
+  "unknown",
+]);
+
+/**
+ * Analysis details for the address validation
+ */
+export type AddressAnalysisV2 = {
+  validation_result?: ValidationResultV2 | undefined;
+  address_type?: AddressAnalysisV2AddressType | null | undefined;
+  changed_attributes?: Array<string> | null | undefined;
+};
+
+export const AddressAnalysisV2$zodSchema: z.ZodType<AddressAnalysisV2> = z
+  .object({
+    address_type: AddressAnalysisV2AddressType$zodSchema.nullable().optional(),
+    changed_attributes: z.array(z.string()).nullable().optional(),
+    validation_result: ValidationResultV2$zodSchema.optional(),
+  }).describe("Analysis details for the address validation");

package/src/models/addresscreaterequestv2.ts

@@ -0,0 +1,64 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+/**
+ * The category of the address. May affect carrier charges.
+ */
+export const AddressCreateRequestV2AddressType = {
+  Unknown: "unknown",
+  Residential: "residential",
+  Commercial: "commercial",
+  PoBox: "po_box",
+  Military: "military",
+} as const;
+/**
+ * The category of the address. May affect carrier charges.
+ */
+export type AddressCreateRequestV2AddressType = ClosedEnum<
+  typeof AddressCreateRequestV2AddressType
+>;
+
+export const AddressCreateRequestV2AddressType$zodSchema = z.enum([
+  "unknown",
+  "residential",
+  "commercial",
+  "po_box",
+  "military",
+]).describe("The category of the address. May affect carrier charges.");
+
+/**
+ * Request body for creating a new address (v2)
+ */
+export type AddressCreateRequestV2 = {
+  name: string;
+  organization?: string | null | undefined;
+  email?: string | null | undefined;
+  phone?: string | null | undefined;
+  address_line_1: string;
+  address_line_2?: string | null | undefined;
+  city_locality?: string | null | undefined;
+  state_province?: string | null | undefined;
+  postal_code?: string | null | undefined;
+  country_code: string;
+  address_type?: AddressCreateRequestV2AddressType | undefined;
+};
+
+export const AddressCreateRequestV2$zodSchema: z.ZodType<
+  AddressCreateRequestV2
+> = z.object({
+  address_line_1: z.string(),
+  address_line_2: z.string().nullable().optional(),
+  address_type: AddressCreateRequestV2AddressType$zodSchema.default("unknown"),
+  city_locality: z.string().nullable().optional(),
+  country_code: z.string(),
+  email: z.string().nullable().optional(),
+  name: z.string(),
+  organization: z.string().nullable().optional(),
+  phone: z.string().nullable().optional(),
+  postal_code: z.string().nullable().optional(),
+  state_province: z.string().nullable().optional(),
+}).describe("Request body for creating a new address (v2)");

package/src/models/addressdatav2.ts

@@ -0,0 +1,56 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+export const AddressDataV2AddressType = {
+  Unknown: "unknown",
+  Residential: "residential",
+  Commercial: "commercial",
+  PoBox: "po_box",
+  Military: "military",
+} as const;
+export type AddressDataV2AddressType = ClosedEnum<
+  typeof AddressDataV2AddressType
+>;
+
+export const AddressDataV2AddressType$zodSchema = z.enum([
+  "unknown",
+  "residential",
+  "commercial",
+  "po_box",
+  "military",
+]);
+
+/**
+ * Address data in v2 format
+ */
+export type AddressDataV2 = {
+  name?: string | null | undefined;
+  email?: string | null | undefined;
+  phone?: string | null | undefined;
+  organization?: string | null | undefined;
+  address_line_1?: string | null | undefined;
+  address_line_2?: string | null | undefined;
+  city_locality?: string | null | undefined;
+  state_province?: string | null | undefined;
+  postal_code?: string | null | undefined;
+  country_code?: string | null | undefined;
+  address_type?: AddressDataV2AddressType | null | undefined;
+};
+
+export const AddressDataV2$zodSchema: z.ZodType<AddressDataV2> = z.object({
+  address_line_1: z.string().nullable().optional(),
+  address_line_2: z.string().nullable().optional(),
+  address_type: AddressDataV2AddressType$zodSchema.nullable().optional(),
+  city_locality: z.string().nullable().optional(),
+  country_code: z.string().nullable().optional(),
+  email: z.string().nullable().optional(),
+  name: z.string().nullable().optional(),
+  organization: z.string().nullable().optional(),
+  phone: z.string().nullable().optional(),
+  postal_code: z.string().nullable().optional(),
+  state_province: z.string().nullable().optional(),
+}).describe("Address data in v2 format");

package/src/models/addressv2.ts

@@ -0,0 +1,34 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+
+/**
+ * Address object in v2 format
+ */
+export type AddressV2 = {
+  address_line_1?: string | null | undefined;
+  address_line_2?: string | null | undefined;
+  city_locality?: string | null | undefined;
+  state_province?: string | null | undefined;
+  postal_code?: string | null | undefined;
+  country_code?: string | null | undefined;
+  name?: string | null | undefined;
+  organization?: string | null | undefined;
+  phone?: string | null | undefined;
+  email?: string | null | undefined;
+};
+
+export const AddressV2$zodSchema: z.ZodType<AddressV2> = z.object({
+  address_line_1: z.string().nullable().optional(),
+  address_line_2: z.string().nullable().optional(),
+  city_locality: z.string().nullable().optional(),
+  country_code: z.string().nullable().optional(),
+  email: z.string().nullable().optional(),
+  name: z.string().nullable().optional(),
+  organization: z.string().nullable().optional(),
+  phone: z.string().nullable().optional(),
+  postal_code: z.string().nullable().optional(),
+  state_province: z.string().nullable().optional(),
+}).describe("Address object in v2 format");

package/src/models/addressvalidationresultv2.ts

@@ -0,0 +1,34 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import {
+  AddressAnalysisV2,
+  AddressAnalysisV2$zodSchema,
+} from "./addressanalysisv2.js";
+import { AddressV2, AddressV2$zodSchema } from "./addressv2.js";
+import { GeoCoordinates, GeoCoordinates$zodSchema } from "./geocoordinates.js";
+import {
+  RecommendedAddressV2,
+  RecommendedAddressV2$zodSchema,
+} from "./recommendedaddressv2.js";
+
+/**
+ * Address validation result from v2 API
+ */
+export type AddressValidationResultV2 = {
+  original_address?: AddressV2 | undefined;
+  recommended_address?: RecommendedAddressV2 | undefined;
+  analysis?: AddressAnalysisV2 | undefined;
+  geo?: GeoCoordinates | undefined;
+};
+
+export const AddressValidationResultV2$zodSchema: z.ZodType<
+  AddressValidationResultV2
+> = z.object({
+  analysis: AddressAnalysisV2$zodSchema.optional(),
+  geo: GeoCoordinates$zodSchema.optional(),
+  original_address: AddressV2$zodSchema.optional(),
+  recommended_address: RecommendedAddressV2$zodSchema.optional(),
+}).describe("Address validation result from v2 API");

package/src/models/addresswithmetadataresponse.ts

@@ -0,0 +1,25 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { AddressDataV2, AddressDataV2$zodSchema } from "./addressdatav2.js";
+
+/**
+ * Response from creating a new address (v2)
+ */
+export type AddressWithMetadataResponse = {
+  id?: string | undefined;
+  address?: AddressDataV2 | undefined;
+  updated_at?: string | undefined;
+  created_at?: string | undefined;
+};
+
+export const AddressWithMetadataResponse$zodSchema: z.ZodType<
+  AddressWithMetadataResponse
+> = z.object({
+  address: AddressDataV2$zodSchema.optional(),
+  created_at: z.iso.datetime({ offset: true }).optional(),
+  id: z.string().optional(),
+  updated_at: z.iso.datetime({ offset: true }).optional(),
+}).describe("Response from creating a new address (v2)");

package/src/models/confidenceresult.ts

@@ -0,0 +1,36 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../types/enums.js";
+
+export const Score = {
+  High: "high",
+  Medium: "medium",
+  Low: "low",
+} as const;
+export type Score = ClosedEnum<typeof Score>;
+
+export const Score$zodSchema = z.enum([
+  "high",
+  "medium",
+  "low",
+]);
+
+/**
+ * Confidence score and details for the address validation
+ */
+export type ConfidenceResult = {
+  score?: Score | null | undefined;
+  code?: string | null | undefined;
+  description?: string | null | undefined;
+};
+
+export const ConfidenceResult$zodSchema: z.ZodType<ConfidenceResult> = z.object(
+  {
+    code: z.string().nullable().optional(),
+    description: z.string().nullable().optional(),
+    score: Score$zodSchema.nullable().optional(),
+  },
+).describe("Confidence score and details for the address validation");

package/src/models/createaddressv2op.ts

@@ -0,0 +1,73 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import {
+  AddressWithMetadataResponse,
+  AddressWithMetadataResponse$zodSchema,
+} from "./addresswithmetadataresponse.js";
+
+export type CreateAddressV2Globals = { shippoApiVersion?: string | undefined };
+
+export const CreateAddressV2Globals$zodSchema: z.ZodType<
+  CreateAddressV2Globals
+> = z.object({
+  shippoApiVersion: z.string().describe(
+    "Optional string used to pick a non-default API version to use. See our <a href=\"https://docs.goshippo.com/docs/api_concepts/apiversioning/\">API version</a> guide.",
+  ).optional(),
+});
+
+export type CreateAddressV2Detail = {};
+
+export const CreateAddressV2Detail$zodSchema: z.ZodType<CreateAddressV2Detail> =
+  z.object({});
+
+/**
+ * Unprocessable Entity
+ */
+export type CreateAddressV2UnprocessableEntityResponseBody = {
+  detail?: Array<CreateAddressV2Detail> | undefined;
+};
+
+export const CreateAddressV2UnprocessableEntityResponseBody$zodSchema:
+  z.ZodType<CreateAddressV2UnprocessableEntityResponseBody> = z.object({
+    detail: z.array(z.lazy(() => CreateAddressV2Detail$zodSchema)).optional(),
+  }).describe("Unprocessable Entity");
+
+/**
+ * Conflict - Address already exists
+ */
+export type CreateAddressV2ConflictResponseBody = {};
+
+export const CreateAddressV2ConflictResponseBody$zodSchema: z.ZodType<
+  CreateAddressV2ConflictResponseBody
+> = z.object({}).describe("Conflict - Address already exists");
+
+export type CreateAddressV2Response = {
+  ContentType: string;
+  StatusCode: number;
+  RawResponse: Response;
+  AddressWithMetadataResponse?: AddressWithMetadataResponse | undefined;
+  fourHundredAndNineApplicationJsonObject?:
+    | CreateAddressV2ConflictResponseBody
+    | undefined;
+  fourHundredAndTwentyTwoApplicationJsonObject?:
+    | CreateAddressV2UnprocessableEntityResponseBody
+    | undefined;
+};
+
+export const CreateAddressV2Response$zodSchema: z.ZodType<
+  CreateAddressV2Response
+> = z.object({
+  AddressWithMetadataResponse: AddressWithMetadataResponse$zodSchema.optional(),
+  ContentType: z.string(),
+  RawResponse: z.custom<Response>(x => x instanceof Response),
+  StatusCode: z.int(),
+  fourHundredAndNineApplicationJsonObject: z.lazy(() =>
+    CreateAddressV2ConflictResponseBody$zodSchema
+  ).optional(),
+  fourHundredAndTwentyTwoApplicationJsonObject: z.lazy(() =>
+    CreateAddressV2UnprocessableEntityResponseBody$zodSchema
+  ).optional(),
+});