fix: NDV UX polish — Create billing hint, deduped notices, Validate country dropdown (#24)

Follow-up to the cognitive-load and UX audits:
- Add node-level output-pane warning hint for Create so the billing caution
  shows even when params are collapsed or the node runs via usableAsTool
- Fold the credential-fit reminder into createCostNotice and gate
  shippingCredentialNotice to Get Rates + Validate, so Create shows one yellow block
- Give phone + dimension fields distinct inline hint text vs. hover description
- Swap Validate's Country to the COUNTRY_OPTIONS dropdown (matches Get Rates)
- Add harness pnpm scripts (harness, harness:reset, harness:login)

Co-authored-by: Kyle Tully <kytully@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

nodes/Fedex/Fedex.node.ts

@@ -19,6 +19,18 @@ export class Fedex implements INodeType {
 		// configured account, so gate it behind human approval in agentic workflows; the
 		// credential defaults to sandbox to keep an unattended agent off a live account.
 		usableAsTool: true,
+		// Node-level warning surfaced in the output pane before execution (in addition to the
+		// field-level createCostNotice) so the billing caution is visible even when the user —
+		// or an AI agent on the usableAsTool path — runs Create without expanding its parameters.
+		hints: [
+			{
+				message: 'Create books a real, billable FedEx shipment (free in Sandbox).',
+				type: 'warning',
+				location: 'outputPane',
+				whenToDisplay: 'beforeExecution',
+				displayCondition: '={{ $parameter["operation"] === "create" }}',
+			},
+		],
 		inputs: [NodeConnectionTypes.Main],
 		outputs: [NodeConnectionTypes.Main],
 		// Each resource mirrors a FedEx dev-portal project and binds that project's credential:
@@ -82,13 +94,16 @@ export class Fedex implements INodeType {
 				default: '',
 				displayOptions: { show: { resource: ['tracking'] } },
 			},
+			// Shown for Get Rates + Validate only. Create gets the same credential-fit reminder
+			// folded into its cost notice (createCostNotice) so its panel carries a single yellow
+			// block instead of two stacked notices (UX audit, Recommended #1).
 			{
 				displayName:
 					'These operations use a <b>FedEx Shipping OAuth2 API</b> credential. If the credential field above is empty or shows a red mark, create or select one of that type — Shipping and Track require separate FedEx project keys, so a Track credential cannot be used here.',
 				name: 'shippingCredentialNotice',
 				type: 'notice',
 				default: '',
-				displayOptions: { show: { resource: ['shipping'] } },
+				displayOptions: { show: { resource: ['shipping'], operation: ['getRates', 'validate'] } },
 			},
 			...trackingDescription,
 			...shippingDescription,

nodes/Fedex/fields.ts

@@ -102,7 +102,11 @@ export function contactFields(role: Role, show: Show): INodeProperties[] {
 			default: '',
 			required: true,
 			displayOptions: { show },
-			description: 'FedEx requires a phone number for the shipment contact',
+			// description = hover tooltip (longer, explains why); hint = persistent inline text
+			// (terse). Kept distinct so the two layers don't render identical copy (UX audit, Minor #2).
+			description:
+				'FedEx requires a phone number for the shipment contact. It is used by FedEx and the delivering carrier to reach the sender or recipient about delivery exceptions, and for customs contact on international shipments.',
+			hint: 'FedEx requires a phone number for the shipment contact',
 		},
 	];
 }
@@ -180,6 +184,7 @@ const dimensionEntries: INodeProperties[] = [
 		typeOptions: { minValue: 0 },
 		description:
 			'Dimensions are sent only when length, width, and height are all greater than zero',
+		hint: 'All three dimensions must be > 0 or none are sent',
 	},
 	{
 		displayName: 'Length',
@@ -189,6 +194,7 @@ const dimensionEntries: INodeProperties[] = [
 		typeOptions: { minValue: 0 },
 		description:
 			'Dimensions are sent only when length, width, and height are all greater than zero',
+		hint: 'All three dimensions must be > 0 or none are sent',
 	},
 	{
 		displayName: 'Width',
@@ -198,6 +204,7 @@ const dimensionEntries: INodeProperties[] = [
 		typeOptions: { minValue: 0 },
 		description:
 			'Dimensions are sent only when length, width, and height are all greater than zero',
+		hint: 'All three dimensions must be > 0 or none are sent',
 	},
 ];
 

nodes/Fedex/resources/shipping/create.ts

@@ -34,9 +34,14 @@ export const createFields: INodeProperties[] = [
 	// Honest friction (cognitive-load audit, "What NOT to touch" #2): Create buys a real
 	// shipment and bills the configured account, and the node is usableAsTool, so an AI agent
 	// can invoke it. Surface the cost up front rather than burying it in docs.
+	//
+	// The credential-fit reminder is merged in here (rather than rendered as a second standalone
+	// notice like shippingCredentialNotice on the other shipping ops) so the Create panel shows a
+	// single yellow block, keeping the high-stakes billing message from being diluted by a stacked
+	// callout (UX audit, Recommended #1).
 	{
 		displayName:
-			'Running this operation books a real FedEx shipment and bills the Shipping Account below. In Sandbox it is free; in Production it incurs charges.',
+			'Running this operation books a real FedEx shipment and bills the Shipping Account below — free in Sandbox, charged in Production. It needs a <b>FedEx Shipping OAuth2 API</b> credential; a Track credential will not work here.',
 		name: 'createCostNotice',
 		type: 'notice',
 		default: '',

nodes/Fedex/resources/shipping/validate.ts

@@ -1,5 +1,11 @@
-import type { IDataObject, IExecuteSingleFunctions, IHttpRequestOptions, INodeProperties } from 'n8n-workflow';
+import type {
+	IDataObject,
+	IExecuteSingleFunctions,
+	IHttpRequestOptions,
+	INodeProperties,
+} from 'n8n-workflow';
 import { toFedexAddress } from '../../cores/toFedexAddress';
+import { COUNTRY_OPTIONS } from '../../countries';
 
 const show = { resource: ['shipping'], operation: ['validate'] };
 
@@ -15,7 +21,13 @@ export const validateFields: INodeProperties[] = [
 		displayOptions: { show },
 		description: 'Street address. Put each additional line on its own line; up to three are sent.',
 	},
-	{ displayName: 'City', name: 'addressCity', type: 'string', default: '', displayOptions: { show } },
+	{
+		displayName: 'City',
+		name: 'addressCity',
+		type: 'string',
+		default: '',
+		displayOptions: { show },
+	},
 	{
 		displayName: 'State/Province Code',
 		name: 'addressStateOrProvinceCode',
@@ -24,13 +36,20 @@ export const validateFields: INodeProperties[] = [
 		placeholder: 'TN',
 		displayOptions: { show },
 	},
-	{ displayName: 'Postal Code', name: 'addressPostalCode', type: 'string', default: '', displayOptions: { show } },
 	{
-		displayName: 'Country Code',
-		name: 'addressCountryCode',
+		displayName: 'Postal Code',
+		name: 'addressPostalCode',
 		type: 'string',
+		default: '',
+		displayOptions: { show },
+	},
+	{
+		displayName: 'Country',
+		name: 'addressCountryCode',
+		type: 'options',
+		options: COUNTRY_OPTIONS,
 		default: 'US',
-		description: 'Two-letter ISO country code',
+		description: 'Country of the address; the two-letter ISO code is what gets sent to FedEx',
 		displayOptions: { show },
 	},
 ];

package.json

@@ -26,6 +26,9 @@
     "lint:fix": "n8n-node lint --fix",
     "test": "vitest run",
     "test:watch": "vitest",
+    "harness": "./scripts/fedex-test-harness.sh up",
+    "harness:reset": "./scripts/fedex-test-harness.sh reset",
+    "harness:login": "./scripts/fedex-test-harness.sh login",
     "release": "n8n-node release",
     "prepublishOnly": "n8n-node prerelease"
   },