improve exported symbols and docs

deno.json

@@ -1,9 +1,10 @@
 {
   "name": "@fishballpkg/acme",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "exports": {
     ".": "./src/mod.ts",
-    "./Dns01ChallengeUtils": "./src/Dns01ChallengeUtils.ts"
+    "./Dns01ChallengeUtils": "./src/Dns01ChallengeUtils.ts",
+    "./generateCSR": "./src/utils/generateCSR.ts"
   },
   "compilerOptions": {
     "strict": true,

src/AcmeClient.ts

@@ -4,8 +4,12 @@ import { AcmeAccount } from "./AcmeAccount.ts";
 import { generateKeyPair } from "./utils/crypto.ts";
 import { jwsFetch } from "./utils/jws.ts";
 
-export const REPLAY_NONCE_HEADER_KEY = "Replay-Nonce";
+const REPLAY_NONCE_HEADER_KEY = "Replay-Nonce";
 
+/**
+ * The directory object.
+ * @see https://datatracker.ietf.org/doc/html/rfc8555#section-7.1.1
+ */
 export type AcmeDirectory = {
   keyChange: string;
   newAccount: string;

src/AcmeOrder.ts

@@ -80,13 +80,6 @@ export type AcmeOrderStatus =
   | "valid"
   | "invalid";
 
-export type AcmeOrderInit = {
-  account: AcmeAccount;
-  url: string;
-  domains?: string[];
-  authorizationUrls?: string[];
-};
-
 /**
  * Represents your request for a certificate.
  */
@@ -151,7 +144,12 @@ export class AcmeOrder {
       domains,
       url,
       authorizationUrls,
-    }: AcmeOrderInit,
+    }: {
+      account: AcmeAccount;
+      url: string;
+      domains?: string[];
+      authorizationUrls?: string[];
+    },
   ): Promise<AcmeOrder> {
     const order = new AcmeOrder({
       account,

src/Dns01ChallengeUtils.ts

@@ -1,18 +1,7 @@
-/**
- * @module Dns01ChallengeUtils
- *
- * Some utility functions to help you with dns-01 challenge.
- */
-
 /**
  * Lookup the DNS `TXT` record for `domain` every `interval`
  * (in ms, default: 5000) until the record matches `pollUntil`.
  *
- * @example
- * ```ts
- * import { pollDnsTxtRecord } from "@fishballpkg/acme/Dns01ChallengeUtils"
- * ```
- *
  * The lookups are done with the Authoritative Name Server of the `domain`.
  *
  * - `onBeforeAttempt` is called before *each* DNS lookup happens.
@@ -22,6 +11,26 @@
  *
  * Note: To avoid issues with DNS-01 challenges, consider waiting an additional
  * 15-30 seconds after this succeeds before submitting the challenge.
+ *
+ * @example
+ * ```ts
+ * import { pollDnsTxtRecord } from "@fishballpkg/acme/Dns01ChallengeUtils";
+ *
+ * pollDnsTxtRecord({
+ *  domain: "sub.example.com",
+ *  pollUntil: "some-secret-text",
+ *  onBeforeAttempt: () => {
+ *    console.log(`Looking up DNS records...`);
+ *  },
+ *  onAfterFailAttempt: (recordss) => {
+ *    for (const [i, records] of recordss.entries()) {
+ *      console.log(`Record in Authoritative Name Server ${i}`);
+ *      console.log(records);
+ *    }
+ *    console.log("Retrying later...");
+ *  },
+ * });
+ * ```
  */
 export const pollDnsTxtRecord: (payload: {
   domain: string;

src/mod.ts

@@ -3,8 +3,8 @@ export * from "./AcmeAuthorization.ts";
 export * from "./AcmeChallenge.ts";
 export * from "./AcmeClient.ts";
 export * from "./AcmeOrder.ts";
+
+/** Utility functions to help you with `dns-01` challenge */
 export * as Dns01ChallengeUtils from "./Dns01ChallengeUtils.ts";
 
 export * from "./ACME_DIRECTORY_URLS.ts";
-
-export * from "./utils/generateCSR.ts";

src/utils/generateCSR.ts

@@ -25,6 +25,11 @@ const ECDSA_WITH_SHA256_SIGNATURE_ALGOTRITHM_SEQUENCE = encodeSequence(
   encodeOID(OIDS.ECDSA_WITH_SHA256),
 );
 
+/**
+ * Generate a Certificate Signing Request (CSR) in DER format.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc2986
+ */
 export async function generateCSR(
   { domains, keyPair }: { domains: readonly string[]; keyPair: CryptoKeyPair },
 ): Promise<Uint8Array> {