fix!: improve campaign methods interfaces

src/web3telegram/prepareTelegramCampaign.ts

@@ -39,7 +39,7 @@
   label,
   appMaxPrice = MAX_DESIRED_APP_ORDER_PRICE,
   workerpoolMaxPrice = MAX_DESIRED_WORKERPOOL_ORDER_PRICE,
-  grantedAccess,
+  grantedAccesses,
   maxProtectedDataPerTask,
 }: IExecConsumer &
   DappAddressConsumer &
@@ -122,13 +122,13 @@
         args: vLabel,
         inputFiles: [],
         secrets,
-        bulkAccesses: grantedAccess,
+        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

src/web3telegram/sendTelegramCampaign.ts

@@ -7,12 +7,12 @@
 } 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 @@
     const vCampaignRequest = campaignRequestSchema()
       .required()
       .label('campaignRequest')
-      .validateSync(campaignRequest) as BulkRequest;
+      .validateSync(campaignRequest) as CampaignRequest;
 
     const vWorkerpoolAddressOrEns = addressOrEnsSchema()
       .required()
@@ -41,19 +41,21 @@
       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,
       });
 
     return processBulkRequestResponse;
   } catch (error) {
     if ((error as any)?.isProtocolError === true) {
       throw error;
     }
     handleIfProtocolError(error);
@@ -61,7 +63,7 @@
       error instanceof Error &&
       error.message === 'Failed to process protected data';
     if (isProcessProtectedDataError) {
       const cause = (error as any)?.cause;
       const unwrappedCause = cause instanceof Error ? cause : error;
       throw new WorkflowError({
         message: 'Failed to sendTelegramCampaign',

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,
       });