TypeScript types - Githubissues

Is your feature request related to a problem? Please describe.

Currently, it's hard to know what properties are available on the result object and there is no type safety when using TypeScript.

Describe the solution you'd like

I'd love to have TypeScript types either shipped with the package or published under @types/

Describe alternatives you've considered

Typing everything as any :)

Additional context

I tried writing types with some AI help from the example JSON: https://gist.githubusercontent.com/andris9/6514b5e7c59154a5b08636f99052ce37/raw/a6fa78c400fd7068de502e878f0da1eb9334cd7b/mailauth.json

It seems that is currently the only documentation of what properties are available? Unfortunately I don't know nearly enough about the internals of the library and all the email specs to know which properties should be optional/required etc so some help would be greatly appreciated — even if in the form of written API documentation (list of fields and types) or JSDoc. It would also be nice to add descriptions for the fields. I'd be happy to help writing types from that.

Here's what I got with AI help (which unfortunately still has some type errors with the result JSON):

export interface EmailAuthenticationResult {
  dkim: DKIM
  spf: SPF
  dmarc: DMARC
  arc: ARC
  bimi: BIMI
  headers: string
}

export interface DKIM {
  headerFrom: string[]
  envelopeFrom: string
  results: DKIMResult[]
}

export interface DKIMResult {
  signingDomain: string
  selector: string
  signature: string
  algo: string
  format: string
  bodyHash: string
  bodyHashExpecting: string
  status: DKIMStatus
  publicKey: string
  info: string
}

export interface DKIMStatus {
  result: string
  comment?: boolean
  header: DKIMHeader
  policy?: Record<string, unknown>
  aligned: string | boolean
}

export interface DKIMHeader {
  i: string
  s: string
  a: string
  b: string
}

export interface SPF {
  domain: string
  "client-ip": string
  helo: string
  "envelope-from": string
  status: SPFStatus
  header: string
  info: string
}

export interface SPFStatus {
  result: string
  comment: string
  smtp: SPFSMTP
}

export interface SPFSMTP {
  mailfrom: string
  helo: string
}

export interface DMARC {
  status: DMARCStatus
  domain: string
  policy: string
  p: string
  sp: string
  info: string
}

export interface DMARCStatus {
  result: string
  comment: string
  header: DMARCHeader
}

export interface DMARCHeader {
  from: string
}

export interface ARC {
  status: ARCStatus
  i: number
  signature: ARCSignature
  authenticationResults: ARCResults
  info: string
  authResults: string
}

export interface ARCStatus {
  result: string
  comment: string | boolean
}

export interface ARCSignature {
  signingDomain: string
  selector: string
  signature: string
  algo: string
  format: string
  bodyHash: string
  bodyHashExpecting: string
  status: ARCStatus // Reusing ARCStatus as it matches the structure
  publicKey: string
}

export interface ARCResults {
  [key: string]: ARCResult | ARCDKIM[] | SPF // key is the domain, e.g., "mx.google.com"
}

export interface ARCResult {
  value: string
}

export interface ARCDKIM {
  header: DKIMHeader
  result: string
}

export interface BIMI {
  status: BIMIStatus
  location: string
  info: string
}

export interface BIMIStatus {
  header: BIMIHeader
  result: string
}

export interface BIMIHeader {
  selector: string
  d: string
}

postalsys / mailauth

TypeScript types #51