feat: register, change and verify email addresses

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@safe-global/safe-gateway-typescript-sdk",
-  "version": "3.15.0",
+  "version": "3.17.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [

src/endpoint.ts

@@ -1,5 +1,5 @@
 import { deleteData, fetchData, insertParams, stringifyQuery } from './utils'
-import type { DeleteEndpoint, GetEndpoint, paths, PostEndpoint, Primitive } from './types/api'
+import type { DeleteEndpoint, GetEndpoint, paths, PostEndpoint, Primitive, PutEndpoint } from './types/api'
 
 function makeUrl(
   baseUrl: string,
@@ -18,7 +18,16 @@ export function postEndpoint<T extends keyof paths>(
   params?: paths[T] extends PostEndpoint ? paths[T]['post']['parameters'] : never,
 ): Promise<paths[T] extends PostEndpoint ? paths[T]['post']['responses'][200]['schema'] : never> {
   const url = makeUrl(baseUrl, path as string, params?.path, params?.query)
-  return fetchData(url, params?.body)
+  return fetchData(url, 'POST', params?.body, params?.headers)
+}
+
+export function putEndpoint<T extends keyof paths>(
+  baseUrl: string,
+  path: T,
+  params?: paths[T] extends PutEndpoint ? paths[T]['put']['parameters'] : never,
+): Promise<paths[T] extends PutEndpoint ? paths[T]['put']['responses'][200]['schema'] : never> {
+  const url = makeUrl(baseUrl, path as string, params?.path, params?.query)
+  return fetchData(url, 'PUT', params?.body, params?.headers)
 }
 
 export function getEndpoint<T extends keyof paths>(
@@ -31,7 +40,7 @@ export function getEndpoint<T extends keyof paths>(
     return fetchData(rawUrl)
   }
   const url = makeUrl(baseUrl, path as string, params?.path, params?.query)
-  return fetchData(url)
+  return fetchData(url, undefined, undefined, params?.headers)
 }
 
 export function deleteEndpoint<T extends keyof paths>(

src/index.ts

@@ -1,4 +1,4 @@
-import { deleteEndpoint, getEndpoint, postEndpoint } from './endpoint'
+import { deleteEndpoint, getEndpoint, postEndpoint, putEndpoint } from './endpoint'
 import type { operations } from './types/api'
 import type {
   SafeTransactionEstimation,
@@ -25,6 +25,7 @@ import type { DecodedDataResponse } from './types/decoded-data'
 import type { SafeMessage, SafeMessageListPage } from './types/safe-messages'
 import { DEFAULT_BASE_URL } from './config'
 import type { DelegateResponse, DelegatesRequest } from './types/delegates'
+import type { GetEmailResponse } from './types/emails'
 
 export * from './types/safe-info'
 export * from './types/safe-apps'
@@ -413,4 +414,137 @@ export function unregisterDevice(chainId: string, uuid: string): Promise<void> {
   })
 }
 
+/**
+ * Registers a email address for a safe signer.
+ *
+ * The signer wallet has to sign a message of format: `email-register-{chainId}-{safeAddress}-{emailAddress}-{signer}-{timestamp}`
+ * The signature is valid for 5 minutes.
+ *
+ * @param chainId
+ * @param safeAddress
+ * @param body Signer address and email address
+ * @param headers Signature and Signature timestamp
+ * @returns 200 if signature matches the data
+ */
+export function registerEmail(
+  chainId: string,
+  safeAddress: string,
+  body: operations['register_email']['parameters']['body'],
+  headers: operations['register_email']['parameters']['headers'],
+): Promise<void> {
+  return postEndpoint(baseUrl, '/v1/chains/{chainId}/safes/{safe_address}/emails', {
+    path: { chainId, safe_address: safeAddress },
+    body,
+    headers,
+  })
+}
+
+/**
+ * Changes an already registered email address for a safe signer. The new email address still needs to be verified.
+ *
+ * The signer wallet has to sign a message of format: `email-edit-{chainId}-{safeAddress}-{emailAddress}-{signer}-{timestamp}`
+ * The signature is valid for 5 minutes.
+ *
+ * @param chainId
+ * @param safeAddress
+ * @param signerAddress
+ * @param body New email address
+ * @param headers Signature and Signature timestamp
+ * @returns 202 if signature matches the data
+ */
+export function changeEmail(
+  chainId: string,
+  safeAddress: string,
+  signerAddress: string,
+  body: operations['change_email']['parameters']['body'],
+  headers: operations['change_email']['parameters']['headers'],
+): Promise<void> {
+  return putEndpoint(baseUrl, '/v1/chains/{chainId}/safes/{safe_address}/emails/{signer}', {
+    path: { chainId, safe_address: safeAddress, signer: signerAddress },
+    body,
+    headers,
+  })
+}
+
+/**
+ * Resends an email verification code.
+ */
+export function resendEmailVerificationCode(
+  chainId: string,
+  safeAddress: string,
+  signerAddress: string,
+): Promise<void> {
+  return postEndpoint(baseUrl, '/v1/chains/{chainId}/safes/{safe_address}/emails/{signer}/verify-resend', {
+    path: { chainId, safe_address: safeAddress, signer: signerAddress },
+    body: '',
+  })
+}
+
+/**
+ * Verifies a pending email address registration.
+ *
+ * @param chainId
+ * @param safeAddress
+ * @param signerAddress address who signed the email registration
+ * @param body Verification code
+ */
+export function verifyEmail(
+  chainId: string,
+  safeAddress: string,
+  signerAddress: string,
+  body: operations['verify_email']['parameters']['body'],
+): Promise<void> {
+  return putEndpoint(baseUrl, '/v1/chains/{chainId}/safes/{safe_address}/emails/{signer}/verify', {
+    path: { chainId, safe_address: safeAddress, signer: signerAddress },
+    body,
+  })
+}
+
+/**
+ * Gets the registered email address of the signer
+ *
+ * The signer wallet will have to sign a message of format: `email-retrieval-{chainId}-{safe}-{signer}-{timestamp}`
+ * The signature is valid for 5 minutes.
+ *
+ * @param chainId
+ * @param safeAddress
+ * @param signerAddress address of the owner of the Safe
+ *
+ * @returns email address and verified flag
+ */
+export function getRegisteredEmail(
+  chainId: string,
+  safeAddress: string,
+  signerAddress: string,
+  headers: operations['get_email']['parameters']['headers'],
+): Promise<GetEmailResponse> {
+  return getEndpoint(baseUrl, '/v1/chains/{chainId}/safes/{safe_address}/emails/{signer}', {
+    path: { chainId, safe_address: safeAddress, signer: signerAddress },
+    headers,
+  })
+}
+
+/**
+ * Delete a registered email address for the signer
+ *
+ * The signer wallet will have to sign a message of format: `email-delete-{chainId}-{safe}-{signer}-{timestamp}`
+ * The signature is valid for 5 minutes.
+ *
+ * @param chainId
+ * @param safeAddress
+ * @param signerAddress
+ * @param headers
+ */
+export function deleteRegisteredEmail(
+  chainId: string,
+  safeAddress: string,
+  signerAddress: string,
+  headers: operations['delete_email']['parameters']['headers'],
+): Promise<void> {
+  return deleteEndpoint(baseUrl, '/v1/chains/{chainId}/safes/{safe_address}/emails/{signer}', {
+    path: { chainId, safe_address: safeAddress, signer: signerAddress },
+    headers,
+  })
+}
+
 /* eslint-enable @typescript-eslint/explicit-module-boundary-types */

src/types/api.ts

@@ -30,11 +30,19 @@ import type {
 } from './safe-messages'
 import type { DelegateResponse, DelegatesRequest } from './delegates'
 import type { RegisterNotificationsRequest } from './notifications'
+import type {
+  ChangeEmailRequestBody,
+  GetEmailResponse,
+  RegisterEmailRequestBody,
+  AuthorizationEmailRequestHeader,
+  VerifyEmailRequestBody,
+} from './emails'
 
 export type Primitive = string | number | boolean | null
 
 interface Params {
   path?: { [key: string]: Primitive }
+  headers?: Record<string, string>
 }
 
 interface GetParams extends Params {
@@ -70,6 +78,13 @@ export interface PostEndpoint extends Endpoint {
   }
 }
 
+export interface PutEndpoint extends Endpoint {
+  put: {
+    parameters: PostParams | null
+    responses: Responses
+  }
+}
+
 export interface DeleteEndpoint extends Endpoint {
   delete: {
     parameters: Params | null
@@ -78,7 +93,7 @@ export interface DeleteEndpoint extends Endpoint {
 }
 
 interface PathRegistry {
-  [key: string]: GetEndpoint | PostEndpoint | (GetEndpoint & PostEndpoint) | DeleteEndpoint
+  [key: string]: GetEndpoint | PostEndpoint | PutEndpoint | DeleteEndpoint
 }
 
 export interface paths extends PathRegistry {
@@ -332,6 +347,47 @@ export interface paths extends PathRegistry {
       }
     }
   }
+  '/v1/chains/{chainId}/safes/{safe_address}/emails': {
+    post: operations['register_email']
+    parameters: {
+      path: {
+        chainId: string
+        safe_address: string
+      }
+    }
+  }
+  '/v1/chains/{chainId}/safes/{safe_address}/emails/{signer}': {
+    put: operations['change_email']
+    get: operations['get_email']
+    delete: operations['delete_email']
+    parameters: {
+      path: {
+        chainId: string
+        safe_address: string
+        signer: string
+      }
+    }
+  }
+  '/v1/chains/{chainId}/safes/{safe_address}/emails/{signer}/verify-resend': {
+    post: operations['verify_resend']
+    parameters: {
+      path: {
+        chainId: string
+        safe_address: string
+        signer: string
+      }
+    }
+  }
+  '/v1/chains/{chainId}/safes/{safe_address}/emails/{signer}/verify': {
+    put: operations['verify_email']
+    parameters: {
+      path: {
+        chainId: string
+        safe_address: string
+        signer: string
+      }
+    }
+  }
 }
 
 export interface operations {
@@ -833,4 +889,114 @@ export interface operations {
       }
     }
   }
+  register_email: {
+    parameters: {
+      path: {
+        chainId: string
+        safe_address: string
+      }
+      body: RegisterEmailRequestBody
+      headers: AuthorizationEmailRequestHeader
+    }
+    responses: {
+      200: {
+        schema: void
+      }
+      201: {
+        schema: void
+      }
+    }
+  }
+  change_email: {
+    parameters: {
+      path: {
+        chainId: string
+        safe_address: string
+        signer: string
+      }
+      body: ChangeEmailRequestBody
+      headers: AuthorizationEmailRequestHeader
+    }
+    responses: {
+      200: {
+        schema: void
+      }
+      202: {
+        schema: void
+      }
+    }
+  }
+  get_email: {
+    parameters: {
+      path: {
+        chainId: string
+        safe_address: string
+        signer: string
+      }
+      headers: AuthorizationEmailRequestHeader
+    }
+    responses: {
+      200: {
+        schema: GetEmailResponse
+      }
+    }
+  }
+  verify_resend: {
+    parameters: {
+      path: {
+        chainId: string
+        safe_address: string
+        signer: string
+      }
+      body: ''
+    }
+    responses: {
+      202: {
+        schema: void
+      }
+      200: {
+        schema: void
+      }
+    }
+  }
+  verify_email: {
+    parameters: {
+      path: {
+        chainId: string
+        safe_address: string
+        signer: string
+      }
+      body: VerifyEmailRequestBody
+    }
+
+    responses: {
+      204: {
+        schema: void
+      }
+      200: {
+        schema: void
+      }
+      400: unknown
+    }
+  }
+  delete_email: {
+    parameters: {
+      path: {
+        chainId: string
+        safe_address: string
+        signer: string
+      }
+      headers: AuthorizationEmailRequestHeader
+    }
+
+    responses: {
+      204: {
+        schema: void
+      }
+      200: {
+        schema: void
+      }
+      403: unknown
+    }
+  }
 }