@iexec/web3mail 1.6.0 → 1.7.1

package/src/web3mail/prepareEmailCampaign.ts

@@ -0,0 +1,170 @@
+import { Buffer } from 'buffer';
+import {
+  DEFAULT_CONTENT_TYPE,
+  MAX_DESIRED_APP_ORDER_PRICE,
+  MAX_DESIRED_WORKERPOOL_ORDER_PRICE,
+} from '../config/config.js';
+import { handleIfProtocolError, WorkflowError } from '../utils/errors.js';
+import * as ipfs from '../utils/ipfs-service.js';
+import {
+  addressOrEnsSchema,
+  contentTypeSchema,
+  emailContentSchema,
+  emailSubjectSchema,
+  labelSchema,
+  positiveNumberSchema,
+  senderNameSchema,
+  throwIfMissing,
+} from '../utils/validators.js';
+import {
+  PrepareEmailCampaignParams,
+  PrepareEmailCampaignResponse,
+} from './types.js';
+import {
+  DappAddressConsumer,
+  DataProtectorConsumer,
+  IExecConsumer,
+  IpfsGatewayConfigConsumer,
+  IpfsNodeConfigConsumer,
+} from './internalTypes.js';
+
+export type PrepareEmailCampaign = typeof prepareEmailCampaign;
+
+export const prepareEmailCampaign = async ({
+  iexec = throwIfMissing(),
+  dataProtector = throwIfMissing(),
+  workerpoolAddressOrEns,
+  dappAddressOrENS,
+  ipfsNode,
+  ipfsGateway,
+  senderName,
+  emailSubject,
+  emailContent,
+  contentType = DEFAULT_CONTENT_TYPE,
+  label,
+  appMaxPrice = MAX_DESIRED_APP_ORDER_PRICE,
+  workerpoolMaxPrice = MAX_DESIRED_WORKERPOOL_ORDER_PRICE,
+  grantedAccesses,
+  maxProtectedDataPerTask,
+}: IExecConsumer &
+  DappAddressConsumer &
+  IpfsNodeConfigConsumer &
+  IpfsGatewayConfigConsumer &
+  DataProtectorConsumer &
+  PrepareEmailCampaignParams): Promise<PrepareEmailCampaignResponse> => {
+  try {
+    const vWorkerpoolAddressOrEns = addressOrEnsSchema()
+      .label('WorkerpoolAddressOrEns')
+      .validateSync(workerpoolAddressOrEns);
+
+    const vSenderName = senderNameSchema()
+      .label('senderName')
+      .validateSync(senderName);
+
+    const vEmailSubject = emailSubjectSchema()
+      .required()
+      .label('emailSubject')
+      .validateSync(emailSubject);
+
+    const vEmailContent = emailContentSchema()
+      .required()
+      .label('emailContent')
+      .validateSync(emailContent);
+
+    const vContentType = contentTypeSchema()
+      .label('contentType')
+      .validateSync(contentType);
+
+    const vLabel = labelSchema().label('label').validateSync(label);
+
+    const vDappAddressOrENS = addressOrEnsSchema()
+      .required()
+      .label('dappAddressOrENS')
+      .validateSync(dappAddressOrENS);
+
+    const vAppMaxPrice = positiveNumberSchema()
+      .label('appMaxPrice')
+      .validateSync(appMaxPrice);
+
+    const vWorkerpoolMaxPrice = positiveNumberSchema()
+      .label('workerpoolMaxPrice')
+      .validateSync(workerpoolMaxPrice);
+
+    const vMaxProtectedDataPerTask = positiveNumberSchema()
+      .label('maxProtectedDataPerTask')
+      .validateSync(maxProtectedDataPerTask);
+
+    // TODO: factor this
+    // Encrypt email content
+    const emailContentEncryptionKey = iexec.dataset.generateEncryptionKey();
+    const encryptedFile = await iexec.dataset
+      .encrypt(Buffer.from(vEmailContent, 'utf8'), emailContentEncryptionKey)
+      .catch((e) => {
+        throw new WorkflowError({
+          message: 'Failed to encrypt email content',
+          errorCause: e,
+        });
+      });
+
+    // Push email content to IPFS
+    const cid = await ipfs
+      .add(encryptedFile, {
+        ipfsNode,
+        ipfsGateway,
+      })
+      .catch((e) => {
+        throw new WorkflowError({
+          message: 'Failed to upload encrypted email content',
+          errorCause: e,
+        });
+      });
+
+    const multiaddr = `/ipfs/${cid}`;
+
+    // Prepare secrets for the requester
+    // Use a positive integer as secret ID (required by iexec)
+    // Using "1" as a fixed ID for the requester secret
+    const requesterSecretId = 1;
+    const secrets = {
+      [requesterSecretId]: JSON.stringify({
+        emailSubject: vEmailSubject,
+        emailContentMultiAddr: multiaddr,
+        contentType: vContentType,
+        senderName: vSenderName,
+        emailContentEncryptionKey,
+        useCallback: true,
+      }),
+    };
+
+    // TODO: end factor this
+    const { bulkRequest: campaignRequest } =
+      await dataProtector.prepareBulkRequest({
+        app: vDappAddressOrENS,
+        appMaxPrice: vAppMaxPrice,
+        workerpoolMaxPrice: vWorkerpoolMaxPrice,
+        workerpool: vWorkerpoolAddressOrEns,
+        args: vLabel,
+        inputFiles: [],
+        secrets,
+        bulkAccesses: grantedAccesses,
+        maxProtectedDataPerTask: vMaxProtectedDataPerTask,
+      });
+
+    return { campaignRequest };
+  } catch (error) {
+    // Protocol error detected, re-throwing as-is
+    if ((error as any)?.isProtocolError === true) {
+      throw error;
+    }
+
+    // Handle protocol errors - this will throw if it's an ApiCallError
+    // handleIfProtocolError transforms ApiCallError into a WorkflowError with isProtocolError=true
+    handleIfProtocolError(error);
+
+    // For all other errors
+    throw new WorkflowError({
+      message: 'Failed to prepareEmailCampaign',
+      errorCause: error,
+    });
+  }
+};

package/src/web3mail/sendEmail.ts

@@ -67,43 +67,55 @@ export const sendEmail = async ({
     .required()
     .label('protectedData')
     .validateSync(protectedData);
+
   const vEmailSubject = emailSubjectSchema()
     .required()
     .label('emailSubject')
     .validateSync(emailSubject);
+
   const vEmailContent = emailContentSchema()
     .required()
     .label('emailContent')
     .validateSync(emailContent);
+
   const vContentType = contentTypeSchema()
     .required()
     .label('contentType')
     .validateSync(contentType);
+
   const vSenderName = senderNameSchema()
     .label('senderName')
     .validateSync(senderName);
+
   const vLabel = labelSchema().label('label').validateSync(label);
+
   const vWorkerpoolAddressOrEns = addressOrEnsSchema()
     .required()
     .label('WorkerpoolAddressOrEns')
     .validateSync(workerpoolAddressOrEns);
+
   const vDappAddressOrENS = addressOrEnsSchema()
     .required()
     .label('dappAddressOrENS')
     .validateSync(dappAddressOrENS);
+
   const vDappWhitelistAddress = addressSchema()
     .required()
     .label('dappWhitelistAddress')
     .validateSync(dappWhitelistAddress);
+
   const vDataMaxPrice = positiveNumberSchema()
     .label('dataMaxPrice')
     .validateSync(dataMaxPrice);
+
   const vAppMaxPrice = positiveNumberSchema()
     .label('appMaxPrice')
     .validateSync(appMaxPrice);
+
   const vWorkerpoolMaxPrice = positiveNumberSchema()
     .label('workerpoolMaxPrice')
     .validateSync(workerpoolMaxPrice);
+
   const vUseVoucher = booleanSchema()
     .label('useVoucher')
     .validateSync(useVoucher);
@@ -113,6 +125,7 @@ export const sendEmail = async ({
     graphQLClient,
     vDatasetAddress
   );
+
   if (!isValidProtectedData) {
     throw new Error(
       'This protected data does not contain "email:string" in its schema.'
@@ -145,7 +158,8 @@ export const sendEmail = async ({
     ] = await Promise.all([
       // Fetch dataset order for web3mail app
       iexec.orderbook
-        .fetchDatasetOrderbook(vDatasetAddress, {
+        .fetchDatasetOrderbook({
+          dataset: vDatasetAddress,
           app: dappAddressOrENS,
           requester: requesterAddress,
         })
@@ -155,9 +169,11 @@ export const sendEmail = async ({
           );
           return desiredPriceDataOrderbook[0]?.order; // may be undefined
         }),
+
       // Fetch dataset order for web3mail whitelist
       iexec.orderbook
-        .fetchDatasetOrderbook(vDatasetAddress, {
+        .fetchDatasetOrderbook({
+          dataset: vDatasetAddress,
           app: vDappWhitelistAddress,
           requester: requesterAddress,
         })
@@ -167,9 +183,11 @@ export const sendEmail = async ({
           );
           return desiredPriceDataOrderbook[0]?.order; // may be undefined
         }),
+
       // Fetch app order
       iexec.orderbook
-        .fetchAppOrderbook(dappAddressOrENS, {
+        .fetchAppOrderbook({
+          app: dappAddressOrENS,
           minTag: ['tee', 'scone'],
           maxTag: ['tee', 'scone'],
           workerpool: workerpoolAddressOrEns,
@@ -184,6 +202,7 @@ export const sendEmail = async ({
           }
           return desiredPriceAppOrder;
         }),
+
       // Fetch workerpool order for App or AppWhitelist
       Promise.all([
         // for app
@@ -219,9 +238,11 @@ export const sendEmail = async ({
             useVoucher: vUseVoucher,
             userVoucher,
           });
+
           if (!desiredPriceWorkerpoolOrder) {
             throw new Error('No Workerpool order found for the desired price');
           }
+
           return desiredPriceWorkerpoolOrder;
         }
       ),
@@ -247,6 +268,7 @@ export const sendEmail = async ({
           errorCause: e,
         });
       });
+
     const cid = await ipfs
       .add(encryptedFile, {
         ipfsNode: ipfsNode,
@@ -258,6 +280,7 @@ export const sendEmail = async ({
           errorCause: e,
         });
       });
+
     const multiaddr = `/ipfs/${cid}`;
 
     await iexec.secrets.pushRequesterSecret(
@@ -289,10 +312,11 @@ export const sendEmail = async ({
         iexec_args: vLabel,
       },
     });
+
     const requestorder = await iexec.order.signRequestorder(requestorderToSign);
 
     // Match orders and compute task ID
-    const { dealid } = await iexec.order.matchOrders(
+    const { dealid: dealId } = await iexec.order.matchOrders(
       {
         apporder: apporder,
         datasetorder: datasetorder,
@@ -301,10 +325,12 @@ export const sendEmail = async ({
       },
       { useVoucher: vUseVoucher }
     );
-    const taskId = await iexec.deal.computeTaskId(dealid, 0);
+
+    const taskId = await iexec.deal.computeTaskId(dealId, 0);
 
     return {
       taskId,
+      dealId,
     };
   } catch (error) {
     handleIfProtocolError(error);

package/src/web3mail/sendEmailCampaign.ts

@@ -0,0 +1,69 @@
+import { NULL_ADDRESS } from 'iexec/utils';
+import { ValidationError } from 'yup';
+import { handleIfProtocolError, WorkflowError } from '../utils/errors.js';
+import {
+  addressOrEnsSchema,
+  campaignRequestSchema,
+  throwIfMissing,
+} from '../utils/validators.js';
+import {
+  CampaignRequest,
+  SendEmailCampaignParams,
+  SendEmailCampaignResponse,
+} from './types.js';
+import { DataProtectorConsumer } from './internalTypes.js';
+
+export type SendEmailCampaign = typeof sendEmailCampaign;
+
+export const sendEmailCampaign = async ({
+  dataProtector = throwIfMissing(),
+  workerpoolAddressOrEns = throwIfMissing(),
+  campaignRequest,
+}: DataProtectorConsumer &
+  SendEmailCampaignParams): Promise<SendEmailCampaignResponse> => {
+  const vCampaignRequest = campaignRequestSchema()
+    .required()
+    .label('campaignRequest')
+    .validateSync(campaignRequest) as CampaignRequest;
+
+  const vWorkerpoolAddressOrEns = addressOrEnsSchema()
+    .required()
+    .label('workerpoolAddressOrEns')
+    .validateSync(workerpoolAddressOrEns);
+
+  if (
+    vCampaignRequest.workerpool !== NULL_ADDRESS &&
+    vCampaignRequest.workerpool.toLowerCase() !==
+      vWorkerpoolAddressOrEns.toLowerCase()
+  ) {
+    throw new ValidationError(
+      "workerpoolAddressOrEns doesn't match campaignRequest workerpool"
+    );
+  }
+
+  try {
+    // Process the prepared bulk request
+    const processBulkRequestResponse = await dataProtector.processBulkRequest({
+      bulkRequest: vCampaignRequest,
+      workerpool: vWorkerpoolAddressOrEns,
+      waitForResult: false,
+    });
+
+    return processBulkRequestResponse;
+  } catch (error) {
+    // Protocol error detected, re-throwing as-is
+    if ((error as any)?.isProtocolError === true) {
+      throw error;
+    }
+
+    // Handle protocol errors - this will throw if it's an ApiCallError
+    // handleIfProtocolError transforms ApiCallError into a WorkflowError with isProtocolError=true
+    handleIfProtocolError(error);
+
+    // For all other errors
+    throw new WorkflowError({
+      message: 'Failed to sendEmailCampaign',
+      errorCause: error,
+    });
+  }
+};

package/src/web3mail/types.ts

@@ -1,5 +1,6 @@
 import { EnhancedWallet } from 'iexec';
 import { IExecConfigOptions } from 'iexec/IExecConfig';
+import type { BulkRequest } from '@iexec/dataprotector';
 
 export type Web3SignerProvider = EnhancedWallet;
 
@@ -11,14 +12,44 @@ export type Address = string;
 
 export type TimeStamp = string;
 
+/**
+ * request to send email in bulk
+ *
+ * use `prepareEmailCampaign()` to create a `CampaignRequest`
+ *
+ * then use `sendEmailCampaign()` to send the campaign
+ */
+export type CampaignRequest = BulkRequest;
+
+/**
+ * authorization signed by the data owner granting access to this contact
+ *
+ * `GrantedAccess` are obtained by fetching contacts (e.g. `fetchMyContacts()` or `fetchUserContacts()`)
+ *
+ * `GrantedAccess` can be consumed for email campaigns (e.g. `prepareEmailCampaign()` then `sendEmailCampaign()`)
+ */
+export type GrantedAccess = {
+  dataset: string;
+  datasetprice: string;
+  volume: string;
+  tag: string;
+  apprestrict: string;
+  workerpoolrestrict: string;
+  requesterrestrict: string;
+  salt: string;
+  sign: string;
+  remainingAccess: number;
+};
+
 export type Contact = {
   address: Address;
   owner: Address;
   accessGrantTimestamp: TimeStamp;
   isUserStrict: boolean;
-  name: string;
+  name?: string;
   remainingAccess: number;
   accessPrice: number;
+  grantedAccess: GrantedAccess;
 };
 
 export type SendEmailParams = {
@@ -40,6 +71,10 @@ export type FetchMyContactsParams = {
    * Get contacts for this specific user only
    */
   isUserStrict?: boolean;
+  /**
+   * If true, returns only contacts with bulk processing access grants
+   */
+  bulkOnly?: boolean;
 };
 
 export type FetchUserContactsParams = {
@@ -50,7 +85,14 @@ export type FetchUserContactsParams = {
 } & FetchMyContactsParams;
 
 export type SendEmailResponse = {
+  /**
+   * ID of the task
+   */
   taskId: string;
+  /**
+   * ID of the deal containing the task
+   */
+  dealId: string;
 };
 
 /**
@@ -100,3 +142,62 @@ export type Web3MailConfigOptions = {
    */
   allowExperimentalNetworks?: boolean;
 };
+
+export type PrepareEmailCampaignParams = {
+  /**
+   * List of `GrantedAccess` to contacts to send emails to in bulk.
+   *
+   * use `fetchMyContacts({ bulkOnly: true })` to get granted accesses.
+   */
+  grantedAccesses: GrantedAccess[];
+  maxProtectedDataPerTask?: number;
+  senderName?: string;
+  emailSubject: string;
+  emailContent: string;
+  contentType?: string;
+  label?: string;
+  workerpoolAddressOrEns?: AddressOrENS;
+  dataMaxPrice?: number;
+  appMaxPrice?: number;
+  workerpoolMaxPrice?: number;
+};
+
+export type PrepareEmailCampaignResponse = {
+  /**
+   * The prepared campaign request
+   *
+   * Use this in `sendEmailCampaign()` to start or continue sending the campaign
+   */
+  campaignRequest: CampaignRequest;
+};
+
+export type SendEmailCampaignParams = {
+  /**
+   * The prepared campaign request from `prepareEmailCampaign()`
+   */
+  campaignRequest: CampaignRequest;
+  /**
+   * Workerpool address or ENS to use for processing
+   */
+  workerpoolAddressOrEns?: AddressOrENS;
+};
+
+export type SendEmailCampaignResponse = {
+  /**
+   * List of tasks created for the campaign
+   */
+  tasks: Array<{
+    /**
+     * ID of the task
+     */
+    taskId: string;
+    /**
+     * ID of the deal containing the task
+     */
+    dealId: string;
+    /**
+     * Index of the task in the bulk request
+     */
+    bulkIndex: number;
+  }>;
+};