Add header field support

htunnicliff · Mar 25, 2024 · ff61eb4 · ff61eb4
1 parent 7e21ffa
commit ff61eb4
Show file tree

Hide file tree

Showing 4 changed files with 78 additions and 15 deletions.
diff --git a/src/index.ts b/src/index.ts
@@ -2,6 +2,9 @@
 export * from "./client";
 export { JamClient as default } from "./client";
 
+// Utils
+export * from "./utils";
+
 // -------------------------------------------------
 // Types
 // -------------------------------------------------

diff --git a/src/types/contracts.ts b/src/types/contracts.ts
@@ -29,7 +29,8 @@ import type {
   EmailImport,
   EmailSubmission,
   EmailSubmissionFilterCondition,
-  EmailWithoutHeaderKeys,
+  GetValueFromHeaderKey,
+  HeaderFieldKey,
   Identity,
   Mailbox,
   MailboxFilterCondition,
@@ -67,13 +68,7 @@ export type Requests = {
   "Thread/get": GetArguments<Thread>;
   "Thread/changes": ChangesArguments;
   // Email ----------------------------------
-  "Email/get": GetArguments<EmailWithoutHeaderKeys> & {
-    bodyProperties?: Array<keyof EmailWithoutHeaderKeys>;
-    fetchTextBodyValues?: boolean;
-    fetchHTMLBodyValues?: boolean;
-    fetchAllBodyValues?: boolean;
-    maxBodyValueBytes?: number;
-  };
+  "Email/get": GetEmailArguments;
   "Email/changes": ChangesArguments;
   "Email/query": QueryArguments<Email, EmailFilterCondition> & {
     collapseThreads?: boolean;
@@ -163,7 +158,7 @@ export type Responses<A> = HasAllKeysOfRelated<
     "Thread/get": GetResponse<Thread, A>;
     "Thread/changes": ChangesResponse;
     // Email ----------------------------------
-    "Email/get": GetResponse<Email, A>;
+    "Email/get": GetEmailResponse<A>;
     "Email/changes": ChangesResponse;
     "Email/query": QueryResponse;
     "Email/queryChanges": QueryChangesResponse;
@@ -280,3 +275,33 @@ export type ProxyAPI = {
     ) => Promise<[Responses<A>[Method], Meta]>;
   };
 };
+
+export type GetEmailArguments = {
+  accountId: ID;
+  ids?: ReadonlyArray<ID> | null;
+  properties?: ReadonlyArray<keyof Email | HeaderFieldKey> | null;
+  bodyProperties?: Array<keyof Email>;
+  fetchTextBodyValues?: boolean;
+  fetchHTMLBodyValues?: boolean;
+  fetchAllBodyValues?: boolean;
+  maxBodyValueBytes?: number;
+};
+
+export type GetEmailResponse<Args> = Args extends GetEmailArguments
+  ? {
+      accountId: ID;
+      state: string;
+      list: ReadonlyArray<
+        Args["properties"] extends Array<infer P extends string>
+          ? {
+              [Key in P]: Key extends HeaderFieldKey
+                ? GetValueFromHeaderKey<Key>
+                : Key extends keyof Email
+                ? Email[Key]
+                : never;
+            }
+          : Email
+      >;
+      notFound: ReadonlyArray<ID>;
+    }
+  : never;
diff --git a/src/types/jmap-mail.ts b/src/types/jmap-mail.ts
@@ -92,12 +92,7 @@ export type Thread = {
  */
 export type Email = EmailMetadataFields &
   EmailHeaderFields &
-  EmailBodyPartFields & {
-    // TODO: Support header parsed forms
-    [K in HeaderFieldKey]: any;
-  };
-
-export type EmailWithoutHeaderKeys = Omit<Email, HeaderFieldKey>;
+  EmailBodyPartFields;
 
 /**
  * [rfc8621 § 4.1.1](https://datatracker.ietf.org/doc/html/rfc8621#section-4.1.1)
@@ -160,6 +155,21 @@ export type HeaderFieldKey =
   | `header:${string}:all`
   | `header:${string}`;
 
+export type GetValueFromHeaderKey<K extends HeaderFieldKey> =
+  K extends `header:${string}:as${infer Form extends keyof HeaderParsedForm}:all`
+    ? HeaderParsedForm[Form] extends Array<infer _>
+      ? HeaderParsedForm[Form]
+      : Array<HeaderParsedForm[Form]>
+    : K extends `header:${string}:as${infer Form extends keyof HeaderParsedForm}`
+    ? HeaderParsedForm[Form]
+    : K extends `header:${string}:all`
+    ? string[]
+    : K extends `header:${infer Name extends string}`
+    ? Name extends `:${string}` | `${string}:` | `:${string}:`
+      ? never
+      : string
+    : never;
+
 export type EmailHeader = {
   name: string;
   value: string;

diff --git a/src/utils.ts b/src/utils.ts
@@ -0,0 +1,25 @@
+import type { HeaderParsedForm } from "./types/jmap-mail";
+
+/**
+ * Generate a key to retrieve a header field
+ *
+ * @example
+ * ```ts
+ * headerField("Some-Header", "Addresses") // "header:Some-Header:asAddresses"
+ * ```
+ */
+export function headerField<
+  Name extends string,
+  Form extends keyof HeaderParsedForm
+>(name: Name, form: Form) {
+  return `header:${name}:as${form}` as const;
+}
+
+export function allHeaderFields<
+  Name extends string,
+  Form extends keyof HeaderParsedForm
+>(name: Name, form: Form) {
+  const header = headerField(name, form);
+
+  return `${header}:all` as const;
+}