add comments to everything potentially consumer facing (#3127)

* add comments to everything potentially consumer facing

* rework smtp

---------

Co-authored-by: Aiden McClelland <3732071+dr-bonez@users.noreply.github.com>

sdk/base/lib/actions/input/inputSpecConstants.ts

@@ -5,42 +5,124 @@ import { Value } from './builder/value'
 import { Variants } from './builder/variants'
 
 /**
- * Base SMTP settings, to be used by StartOS for system wide SMTP
+ * Creates an SMTP field spec with provider-specific defaults pre-filled.
  */
-export const customSmtp: InputSpec<SmtpValue> = InputSpec.of<
-  InputSpecOf<SmtpValue>
->({
-  server: Value.text({
-    name: 'SMTP Server',
-    required: true,
-    default: null,
-  }),
-  port: Value.number({
-    name: 'Port',
-    required: true,
-    default: 587,
-    min: 1,
-    max: 65535,
-    integer: true,
-  }),
-  from: Value.text({
-    name: 'From Address',
-    required: true,
-    default: null,
-    placeholder: 'Example Name <test@example.com>',
-    inputmode: 'email',
-    patterns: [Patterns.emailWithName],
-  }),
-  login: Value.text({
-    name: 'Login',
-    required: true,
-    default: null,
-  }),
-  password: Value.text({
-    name: 'Password',
-    required: false,
-    default: null,
-    masked: true,
+function smtpFields(
+  defaults: {
+    host?: string
+    port?: number
+    security?: 'starttls' | 'tls'
+  } = {},
+): InputSpec<SmtpValue> {
+  return InputSpec.of<InputSpecOf<SmtpValue>>({
+    host: Value.text({
+      name: 'Host',
+      required: true,
+      default: defaults.host ?? null,
+      placeholder: 'smtp.example.com',
+    }),
+    port: Value.number({
+      name: 'Port',
+      required: true,
+      default: defaults.port ?? 587,
+      min: 1,
+      max: 65535,
+      integer: true,
+    }),
+    security: Value.select({
+      name: 'Connection Security',
+      default: defaults.security ?? 'starttls',
+      values: {
+        starttls: 'STARTTLS',
+        tls: 'TLS',
+      },
+    }),
+    from: Value.text({
+      name: 'From Address',
+      required: true,
+      default: null,
+      placeholder: 'Example Name <test@example.com>',
+      patterns: [Patterns.emailWithName],
+    }),
+    username: Value.text({
+      name: 'Username',
+      required: true,
+      default: null,
+    }),
+    password: Value.text({
+      name: 'Password',
+      required: false,
+      default: null,
+      masked: true,
+    }),
+  })
+}
+
+/**
+ * Base SMTP settings with no provider-specific defaults.
+ */
+export const customSmtp = smtpFields()
+
+/**
+ * Provider presets for SMTP configuration.
+ * Each variant has SMTP fields pre-filled with the provider's recommended settings.
+ */
+export const smtpProviderVariants = Variants.of({
+  gmail: {
+    name: 'Gmail',
+    spec: smtpFields({
+      host: 'smtp.gmail.com',
+      port: 587,
+      security: 'starttls',
+    }),
+  },
+  ses: {
+    name: 'Amazon SES',
+    spec: smtpFields({
+      host: 'email-smtp.us-east-1.amazonaws.com',
+      port: 587,
+      security: 'starttls',
+    }),
+  },
+  sendgrid: {
+    name: 'SendGrid',
+    spec: smtpFields({
+      host: 'smtp.sendgrid.net',
+      port: 587,
+      security: 'starttls',
+    }),
+  },
+  mailgun: {
+    name: 'Mailgun',
+    spec: smtpFields({
+      host: 'smtp.mailgun.org',
+      port: 587,
+      security: 'starttls',
+    }),
+  },
+  protonmail: {
+    name: 'Proton Mail',
+    spec: smtpFields({
+      host: 'smtp.protonmail.ch',
+      port: 587,
+      security: 'starttls',
+    }),
+  },
+  other: {
+    name: 'Other',
+    spec: customSmtp,
+  },
+})
+
+/**
+ * System SMTP settings with provider presets.
+ * Wraps smtpProviderVariants in a union for use by the system email settings page.
+ */
+export const systemSmtpSpec = InputSpec.of({
+  provider: Value.union({
+    name: 'Provider',
+    default: null as any,
+    variants: smtpProviderVariants,
   }),
 })
 
@@ -55,19 +137,24 @@ const smtpVariants = Variants.of({
           'A custom from address for this service. If not provided, the system from address will be used.',
         required: false,
         default: null,
-        placeholder: '<name>test@example.com',
-        inputmode: 'email',
-        patterns: [Patterns.email],
+        placeholder: 'Name <test@example.com>',
+        patterns: [Patterns.emailWithName],
       }),
     }),
   },
   custom: {
     name: 'Custom Credentials',
-    spec: customSmtp,
+    spec: InputSpec.of({
+      provider: Value.union({
+        name: 'Provider',
+        default: null as any,
+        variants: smtpProviderVariants,
+      }),
+    }),
   },
 })
 /**
- * For service inputSpec. Gives users 3 options for SMTP: (1) disabled, (2) use system SMTP settings, (3) use custom SMTP settings
+ * For service inputSpec. Gives users 3 options for SMTP: (1) disabled, (2) use system SMTP settings, (3) use custom SMTP settings with provider presets
  */
 export const smtpInputSpec = Value.dynamicUnion(async ({ effects }) => {
   const smtp = await new GetSystemSmtp(effects).once()