fix!: improve campaign methods interfaces (#89)

* docs: improve types doc

* fix!: use plural form of grantedAccess for GrantedAccess list

* test: remove unsupported feature workaround

* fix: improve workerpool mismatch error message

* chore: clean type usage


BREAKING CHANGE: `prepareTelegram()` param `grantedAccess` is renamed to `grantedAccesses`

Author: PierreJeanjacquot

src/web3telegram/prepareTelegramCampaign.ts

@@ -39,7 +39,7 @@ export const prepareTelegramCampaign = async ({
   label,
   appMaxPrice = MAX_DESIRED_APP_ORDER_PRICE,
   workerpoolMaxPrice = MAX_DESIRED_WORKERPOOL_ORDER_PRICE,
-  grantedAccess,
+  grantedAccesses,
   maxProtectedDataPerTask,
 }: IExecConsumer &
   DappAddressConsumer &
@@ -122,7 +122,7 @@ export const prepareTelegramCampaign = async ({
         args: vLabel,
         inputFiles: [],
         secrets,
-        bulkAccesses: grantedAccess,
+        bulkAccesses: grantedAccesses,
         maxProtectedDataPerTask: vMaxProtectedDataPerTask,
       });
     return { campaignRequest };

src/web3telegram/sendTelegramCampaign.ts

@@ -7,12 +7,12 @@ import {
 } from '../utils/validators.js';
 import { DataProtectorConsumer } from './internalTypes.js';
 import {
-  BulkRequest,
   ProcessBulkRequestParams,
   ProcessBulkRequestResponse,
 } from '@iexec/dataprotector';
 import { ValidationError } from 'yup';
 import {
+  CampaignRequest,
   SendTelegramCampaignParams,
   SendTelegramCampaignResponse,
 } from './types.js';
@@ -29,7 +29,7 @@ export const sendTelegramCampaign = async ({
     const vCampaignRequest = campaignRequestSchema()
       .required()
       .label('campaignRequest')
-      .validateSync(campaignRequest) as BulkRequest;
+      .validateSync(campaignRequest) as CampaignRequest;
 
     const vWorkerpoolAddressOrEns = addressOrEnsSchema()
       .required()
@@ -41,13 +41,15 @@ export const sendTelegramCampaign = async ({
       vCampaignRequest.workerpool.toLowerCase() !==
         vWorkerpoolAddressOrEns.toLowerCase()
     ) {
-      throw new ValidationError('Workerpool mismatch');
+      throw new ValidationError(
+        "workerpoolAddressOrEns doesn't match campaignRequest workerpool"
+      );
     }
 
     // Process bulk request
     const processBulkRequestResponse: ProcessBulkRequestResponse<ProcessBulkRequestParams> =
       await dataProtector.processBulkRequest({
-        bulkRequest: vCampaignRequest as BulkRequest,
+        bulkRequest: vCampaignRequest,
         workerpool: vWorkerpoolAddressOrEns,
       });
 

src/web3telegram/types.ts

@@ -12,6 +12,22 @@ 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;
@@ -70,11 +86,11 @@ export type SendTelegramResponse = {
 
 export type PrepareTelegramCampaignParams = {
   /**
-   * Granted access to process in bulk.
+   * List of `GrantedAccess` to contacts to send telegrams to in bulk.
+   *
    * use `fetchMyContacts({ bulkOnly: true })` to get granted accesses.
-   * if not provided, the single message will be processed.
    */
-  grantedAccess: GrantedAccess[];
+  grantedAccesses: GrantedAccess[];
   maxProtectedDataPerTask?: number;
   senderName?: string;
   telegramContent: string;
@@ -86,11 +102,22 @@ export type PrepareTelegramCampaignParams = {
 };
 
 export type PrepareTelegramCampaignResponse = {
-  campaignRequest: BulkRequest;
+  /**
+   * The prepared campaign request
+   *
+   * Use this in `sendTelegramCampaign()` to start or continue sending the campaign
+   */
+  campaignRequest: CampaignRequest;
 };
 
 export type SendTelegramCampaignParams = {
-  campaignRequest: BulkRequest;
+  /**
+   * The prepared campaign request from prepareTelegramCampaign
+   */
+  campaignRequest: CampaignRequest;
+  /**
+   * Workerpool address or ENS to use for processing
+   */
   workerpoolAddressOrEns?: string;
 };
 

tests/e2e/prepareTelegramCampaign.test.ts

@@ -101,7 +101,7 @@ describe('web3telegram.prepareTelegramCampaign()', () => {
         telegramContent: 'Bulk test message',
         senderName: 'Bulk test sender',
         // protectedData is optional when grantedAccess is provided
-        grantedAccess: bulkOrders,
+        grantedAccesses: bulkOrders,
         maxProtectedDataPerTask: 3,
         workerpoolMaxPrice: prodWorkerpoolPublicPrice,
       });