TypeScript .d.ts

[formula1]

So far I'm pretty pleased with everything this module has to offer. I don't think it's reasonable to rewrite the hole thing in typescript but having a definition file is probably a good idea.

I tried downloading @types/greenlock and @types/@root/greenlock but found nothing. If there's something I'm missing, please let me know.

I got started on it but there are a couple of spots that I got hung up.

• In multiple places, errors are thrown if the options argument has a certian key
  • I haven't found a way to implement this in typescript but it seems like it probably is a good idea to at least document
• In at least one place, it seems the code is dynamically requiring a manager
  • _find is used in a few places (Github makes it pretty easy to find it)
  • it returns the value of mega.find
  • mega.find runs mini.find
  • mini.find is created by loadManager
  • loadManager loads a dynamically required module
• Because I don't know the value of mega.find(), I can't implement the definition properly in multiple places
• the create config is used in places it's hard for me to figure out how it's used

For places I don't know the exact value necessary I just put in any or made a note how how the shape is supposed to look like. If you have any insights, I'll gladly accept them. I probably won't be interacting with @root/greenlock directly so I probably could have just exported the class as any but this may help someone else and may help you all internally if you ever plan to make the switch to typescript. I may not be a big fan of microsoft but I'm a fan of typescript

Unfinished greenlock.d.ts

declare module "@root/greenlock" {

  type JSON_Primitives = boolean | number | string;
  type JSON_Array = Array<JSON_Primitives | JSON_Array | JSON_Object>
  type JSON_Object = {
    [key: string]: JSON_Primitives | JSON_Array | JSON_Object
  }
  type JSON_Unknown = JSON_Primitives | JSON_Array | JSON_Object;

  // Note: the get args cannot have a number of options
  // https://github.com/therootcompany/greenlock.js/blob/f01286d5b1dfd73015be9316dd3e5c1cd614d25f/greenlock.js#L262
  type GetArgs = {
    serverName: string
  }

  // I may be missing args related to mega.find
  // https://github.com/therootcompany/greenlock.js/blob/f01286d5b1dfd73015be9316dd3e5c1cd614d25f/lib/manager-wrapper.js#L237
  // Also args related to gconf.find
  // https://github.com/therootcompany/greenlock.js/blob/f01286d5b1dfd73015be9316dd3e5c1cd614d25f/lib/manager-wrapper.js#L237
  export function create(gconf?: {
    maintainerEmail: string,
    notify?: (ev: string, params: any)=>any
    packageRoot?: string
    manager: {
      module: string
    }
    staging?: boolean
    directoryUrl?: string
    renew?: boolean
  }): Greenlock;

  type RenewArgs = {
    servername?: string
    wildname?: string
    servernames?: Array<string>
    altnames?: Array<string>
    subject?: string
    renewBefore?: number
  }

  // Returns the value of mega.find
  // https://github.com/therootcompany/greenlock.js/blob/f01286d5b1dfd73015be9316dd3e5c1cd614d25f/lib/manager-wrapper.js#L237
  // which is mini.find
  // which comes fro loadManager
  // which is loaded from a generic file
  // https://github.com/therootcompany/greenlock.js/blob/f01286d5b1dfd73015be9316dd3e5c1cd614d25f/lib/manager-wrapper.js#L237

  // I'm able to guess what it looks like but no certianty
  // https://github.com/therootcompany/greenlock.js/blob/f01286d5b1dfd73015be9316dd3e5c1cd614d25f/greenlock.js#L341
  type RenewValue = {
    // I don't know what the site is supposed to look like
    site: any
    // I don't know what the pems are supposed to look like
    pems?: any
    error?: any & {
      toJSON(): JSON_Unknown
      context: any | "cert_order"
      subject?: any
      servername?: string
    }
  }

  // Maybe more, since mega then does its own thing
  // https://github.com/therootcompany/greenlock.js/blob/f01286d5b1dfd73015be9316dd3e5c1cd614d25f/lib/manager-wrapper.js#L169
  type SiteArg = {
    renewOffset?: number | string
    renewStagger?: number | string
    subject: string,
    altnames: Array<string>
  }

  type AddSite = (arg: SiteArg)=>any
  type UpdateSite = (arg: SiteArg)=>any
  type RemoveSite = ({ subject: string })=>any

  type SitesUpdater = {
    add: AddSite
    update: UpdateSite
    remove: RemoveSite
  }

  type SitesGetter = {
    get(args: any):  Promise<any>
  }

  type SitesManager = {
    // https://github.com/therootcompany/greenlock.js/blob/f01286d5b1dfd73015be9316dd3e5c1cd614d25f/lib/manager-wrapper.js#L54
    defaults(conf?: any): Promise<any>
    set: UpdateSite
    // https://github.com/therootcompany/greenlock.js/blob/f01286d5b1dfd73015be9316dd3e5c1cd614d25f/lib/manager-wrapper.js#L196
    // https://github.com/therootcompany/greenlock.js/blob/f01286d5b1dfd73015be9316dd3e5c1cd614d25f/lib/manager-wrapper.js#L344
    init(args: any): any
  }

  export type Greenlock = SitesUpdater & {
    notify(ev: string, params: any): void
    renew(args?: RenewArgs): Promise<Array<RenewValue>>
    get(args: GetArgs): Promise<null|RenewValue>
    sites: SitesUpdater & SitesGetter
    manager: SitesUpdater & SitesGetter & SitesManager
    challenges: {
      get(chall: {
        servername?: string,
        altname?: string,
        identifier?: {
          value: string
        }
        // Is type necessary?
        type: string
        token?: string
      }): Promise<(
        null |
        { keyAuthorization: string} |
        { keyAuthorizationDigest: string }
      )>
    }
  }

}

[mmanishh]

Hi Thanks for defining types for greenlock. I am wondering what would be in for manager in create function ? manager: { module: string }