proca 1.4.0 → 1.7.0

package/README.md

@@ -8,53 +8,58 @@ Proca is an open-source campaign toolkit designed to empower activists and organ
 
 One of Proca's standout features is its robust support for coalition campaigns, allowing multiple organisations to collaborate seamlessly on shared initiatives. This coalition functionality enables partners to pool resources, amplify their collective voice, and reach a broader audience whilst maintaining individual branding and supporter relationships. By facilitating data sharing and joint campaign management, Proca helps coalitions to maximise their impact, streamline operations, and present a united front on critical issues, all whilst ensuring compliance with data protection regulations.
 
-
 ## usage
 
 ### global installation
-  <!-- usage -->
+
+if you have or plan to have multiple servers (eg. production and staging) or multiple users, you can setup multiple environments. each proca command support a --env <environment> param (optional, 'default' if not specified.
+
+All the examples are using the default environment, add --env=staging if you need to access another server than your default one. By convention, we keep default for production.
+
 ```sh-session
 $ npm install -g proca
-$ proca COMMAND
-running command...
-$ proca (--version)
-proca/1.4.0 linux-x64 node-v20.12.2
-$ proca --help [COMMAND]
-USAGE
-  $ proca COMMAND
-...
+$# if you don't have your API token, generate one
+$ proca user reset --email <your_email> --passowrd <your password>
+$ proca config init --token=<API-token>
 ```
-<!-- usagestop -->
+you can set up the config folder the widget builder will use to store the caches. skip unless you want a different one than the default (your/widget/folder/config). 
+
 
 ### local development
 
-```sh-session
+````sh-session
    $ git clone https://github.com/fixthestatusquo/proca-cli.git
-   $ git install
    $ cd proca-cli
-   $./proca-cli --help
-...
-```
+   $ npm install
+   $ npm link # let the proca widget and other use the local version
+   $./proca-cli config add --env=local  --url=http://localhost:4000/api
+   $./proca-cli config server --env=local #check if the config is working
+   $./proca-cli config user #check if the config is working
+````
+
+you should also use the local proca-api in your [widget generator](https://github.com/fixthestatusquo/proca)
 
-### TOPICS
--  campaign  Handle campaigns
-- org
--  config    create setting to access the server authentication
-- widget
-- supporters (counter)
+````sh-session
+   $ cd /your/path/to/proca
+   $ npm link proca # use the local proca-cli repo
+````
 
 # Commands
+
 <!-- commands -->
 * [`proca action add`](#proca-action-add)
 * [`proca action count`](#proca-action-count)
 * [`proca action list [TITLE]`](#proca-action-list-title)
 * [`proca action replay`](#proca-action-replay)
 * [`proca campaign add [TITLE]`](#proca-campaign-add-title)
-* [`proca campaign close [TITLE]`](#proca-campaign-close-title)
+* [`proca campaign close`](#proca-campaign-close)
 * [`proca campaign delete`](#proca-campaign-delete)
 * [`proca campaign get`](#proca-campaign-get)
 * [`proca campaign list [TITLE]`](#proca-campaign-list-title)
+* [`proca campaign mtt`](#proca-campaign-mtt)
+* [`proca campaign status`](#proca-campaign-status)
 * [`proca config add [ENV] [HUMAN] [JSON] [CSV] [SIMPLIFY]`](#proca-config-add-env-human-json-csv-simplify)
+* [`proca config folder`](#proca-config-folder)
 * [`proca config init [ENV] [HUMAN] [JSON] [CSV] [SIMPLIFY]`](#proca-config-init-env-human-json-csv-simplify)
 * [`proca config server`](#proca-config-server)
 * [`proca config set [KEY] [VALUE]`](#proca-config-set-key-value)
@@ -78,9 +83,12 @@ USAGE
 * [`proca plugins uninstall [PLUGIN]`](#proca-plugins-uninstall-plugin)
 * [`proca plugins unlink [PLUGIN]`](#proca-plugins-unlink-plugin)
 * [`proca plugins update`](#proca-plugins-update)
+* [`proca target add`](#proca-target-add)
 * [`proca user get`](#proca-user-get)
 * [`proca user leave`](#proca-user-leave)
 * [`proca user list`](#proca-user-list)
+* [`proca user reset [USER]`](#proca-user-reset-user)
+* [`proca user whoami`](#proca-user-whoami)
 * [`proca widget add`](#proca-widget-add)
 * [`proca widget get`](#proca-widget-get)
 * [`proca widget list`](#proca-widget-list)
@@ -92,13 +100,14 @@ USAGE
   $ proca action add [ID_NAME_DXID...] -i <value> --firstname <value> --email <value>
     [--json | --human | --csv] [--env <value>] [--simplify] [-x <value>] [-n <the_short_name>] [--testing] [--optin]
     [--action_type <value>] [--lastname <value>] [--street <value>] [--locality <value>] [--region <value>] [--country
-    <value>] [--utm <value>]
+    <value>] [--utm <value>] [--target <value>] [--subject <value>] [--body <value>]
 
 FLAGS
   -i, --id=<value>             (required) widget's id
   -n, --name=<the_short_name>  name
   -x, --dxid=<value>           dxid
       --action_type=<value>    [default: register]
+      --body=<value>           [mtt] body of the email
       --country=<value>        2-letter country iso code
       --email=<value>          (required) email
       --env=<value>            [default: default] allow to switch between configurations (server or users)
@@ -108,6 +117,8 @@ FLAGS
   --optin
   --region=<value>
   --street=<value>
+      --subject=<value>        [mtt] subject of the email
+      --target=<value>         [mtt] uid of the target
   --testing
       --utm=<value>            utm=campaign.source.medium
 
@@ -121,6 +132,8 @@ EXAMPLES
   $ proca action add -i <widget_id> --firstname=John --email=john@example.org
 
   $ proca action add -i <widget_id> --firstname=John --email=john@example.org --country=FR custom1=A custom2=B
+
+  $ proca action add -i <widget_id> --firstname=John --email=john@example.org target=715a9580-cfe6-4005-9e23-61a62ddecfea --subject='MTT subject' --body='message MTT'
 ```
 
 ## `proca action count`
@@ -234,22 +247,17 @@ EXAMPLES
   $ proca campaign add -n <new_campaign> the full name of the campaign
 ```
 
-## `proca campaign close [TITLE]`
+## `proca campaign close`
 
 ```
 USAGE
-  $ proca campaign close [TITLE] -n <campaign name> -o <org name> --status
-    closed|ignored|live [--json | --human | --csv] [--env <value>] [--simplify]
-
-ARGUMENTS
-  TITLE  title of the campaign
+  $ proca campaign close [ID_NAME_DXID] --status draft|live|closed|ignored [--json |
+    --human | --csv] [--env <value>] [--simplify]
 
 FLAGS
-  -n, --name=<campaign name>  (required) name of the campaign
-  -o, --org=<org name>        (required) name of the coordinator
-      --env=<value>           [default: default] allow to switch between configurations (server or users)
-      --status=<option>       (required) [default: closed] status
-                              <options: closed|ignored|live>
+  --env=<value>      [default: default] allow to switch between configurations (server or users)
+  --status=<option>  (required) Status to set
+                     <options: draft|live|closed|ignored>
 
 OUTPUT FLAGS
   --csv            Format output as csv
@@ -257,8 +265,13 @@ OUTPUT FLAGS
   --json           Format output as json
   --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
 
+ALIASES
+  $ proca campaign close
+
 EXAMPLES
   $ proca campaign close -name <campaign>
+
+  $ proca campaign close -i <campaign_id>
 ```
 
 ## `proca campaign delete`
@@ -350,14 +363,76 @@ EXAMPLES
   $ proca campaign list %pizza%
 ```
 
+## `proca campaign mtt`
+
+set the mail to target (mtt) params
+
+```
+USAGE
+  $ proca campaign mtt [ID_NAME_DXID] --from <value> --to <value> [--json | --human |
+    --csv] [--env <value>] [--simplify] [-i <value> | -n <the_short_name> | -x <value>] [--template <value>] [--period
+    <value>] [--email <value>]
+
+FLAGS
+  -i, --id=<value>
+  -n, --name=<the_short_name>  name
+  -x, --dxid=<value>           dxid
+      --email=<value>          test email address
+      --env=<value>            [default: default] allow to switch between configurations (server or users)
+      --from=<value>           (required) start date (yyyy-mm-dd)
+      --period=<value>         [default: 09:09-18:18] period of the day (HH:HH-HH:HH)
+      --template=<value>       mtt template to use
+      --to=<value>             (required) end date (yyyy-mm-dd)
+
+OUTPUT FLAGS
+  --csv            Format output as csv
+  --human          Format output to be read on screen by a human [default]
+  --json           Format output as json
+  --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
+
+DESCRIPTION
+  set the mail to target (mtt) params
+
+EXAMPLES
+  $ proca campaign mtt -n <test-mtt-campaign>
+```
+
+## `proca campaign status`
+
+```
+USAGE
+  $ proca campaign status [ID_NAME_DXID] --status draft|live|closed|ignored [--json |
+    --human | --csv] [--env <value>] [--simplify]
+
+FLAGS
+  --env=<value>      [default: default] allow to switch between configurations (server or users)
+  --status=<option>  (required) Status to set
+                     <options: draft|live|closed|ignored>
+
+OUTPUT FLAGS
+  --csv            Format output as csv
+  --human          Format output to be read on screen by a human [default]
+  --json           Format output as json
+  --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
+
+ALIASES
+  $ proca campaign close
+
+EXAMPLES
+  $ proca campaign status -name <campaign>
+
+  $ proca campaign status -i <campaign_id>
+```
+
 ## `proca config add [ENV] [HUMAN] [JSON] [CSV] [SIMPLIFY]`
 
-create setting to access the server authentication
+create setting to access to a server
 
 ```
 USAGE
-  $ proca config add [ENV] [HUMAN] [JSON] [CSV] [SIMPLIFY] --token <API-token> [--json
-    | --human | --csv] [--env <value>] [--simplify] [--force] [--url <url>]
+  $ proca config add [ENV] [HUMAN] [JSON] [CSV] [SIMPLIFY] [--json | --human | --csv]
+    [--env <value>] [--simplify] [--url http://localhost:4000] [--token API-token>] [--email you@example.org] [--folder
+    /var/www/proca/config.example]
 
 ARGUMENTS
   ENV       [default: default] allow to switch between configurations (server or users)
@@ -367,10 +442,11 @@ ARGUMENTS
   SIMPLIFY  flatten and filter to output only the most important attributes, mostly relevant for json
 
 FLAGS
-  --env=<value>        [default: default] allow to switch between configurations (server or users)
-  --force              write over an existing configuration
-  --token=<API-token>  (required) user token on proca server
-  --url=<url>          [default: https://api.proca.app/api] url of the proca server api
+  --email=you@example.org                 user email on proca server
+  --env=<value>                           [default: default] allow to switch between configurations (server or users)
+  --folder=/var/www/proca/config.example  config folder (in the proca widget generator)
+  --token=API-token>                      user token on proca server
+  --url=http://localhost:4000             [default: https://api.proca.app/api] url of the proca server api
 
 OUTPUT FLAGS
   --csv            Format output as csv
@@ -379,7 +455,7 @@ OUTPUT FLAGS
   --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
 
 DESCRIPTION
-  create setting to access the server authentication
+  create setting to access to a server
 
 ALIASES
   $ proca config setup
@@ -389,14 +465,38 @@ EXAMPLES
   $ proca config add --user=xavier@example.org --token=API-12345789
 ```
 
+## `proca config folder`
+
+Check and create config folders
+
+```
+USAGE
+  $ proca config folder [--json | --human | --csv] [--env <value>] [--simplify]
+
+FLAGS
+  --env=<value>  [default: default] allow to switch between configurations (server or users)
+
+OUTPUT FLAGS
+  --csv            Format output as csv
+  --human          Format output to be read on screen by a human [default]
+  --json           Format output as json
+  --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
+
+DESCRIPTION
+  Check and create config folders
+
+  Check if the PROCA_CONFIG_FOLDER is set up, if it is, check if the required subfolders exists and create if not
+```
+
 ## `proca config init [ENV] [HUMAN] [JSON] [CSV] [SIMPLIFY]`
 
-create setting to access the server authentication
+create setting to access to a server
 
 ```
 USAGE
-  $ proca config init [ENV] [HUMAN] [JSON] [CSV] [SIMPLIFY] --token <API-token> [--json
-    | --human | --csv] [--env <value>] [--simplify] [--force] [--url <url>]
+  $ proca config init [ENV] [HUMAN] [JSON] [CSV] [SIMPLIFY] [--json | --human | --csv]
+    [--env <value>] [--simplify] [--url http://localhost:4000] [--token API-token>] [--email you@example.org] [--folder
+    /var/www/proca/config.example]
 
 ARGUMENTS
   ENV       [default: default] allow to switch between configurations (server or users)
@@ -406,10 +506,11 @@ ARGUMENTS
   SIMPLIFY  flatten and filter to output only the most important attributes, mostly relevant for json
 
 FLAGS
-  --env=<value>        [default: default] allow to switch between configurations (server or users)
-  --force              write over an existing configuration
-  --token=<API-token>  (required) user token on proca server
-  --url=<url>          [default: https://api.proca.app/api] url of the proca server api
+  --email=you@example.org                 user email on proca server
+  --env=<value>                           [default: default] allow to switch between configurations (server or users)
+  --folder=/var/www/proca/config.example  config folder (in the proca widget generator)
+  --token=API-token>                      user token on proca server
+  --url=http://localhost:4000             [default: https://api.proca.app/api] url of the proca server api
 
 OUTPUT FLAGS
   --csv            Format output as csv
@@ -418,7 +519,7 @@ OUTPUT FLAGS
   --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
 
 DESCRIPTION
-  create setting to access the server authentication
+  create setting to access to a server
 
 ALIASES
   $ proca config setup
@@ -488,12 +589,13 @@ EXAMPLES
 
 ## `proca config setup [ENV] [HUMAN] [JSON] [CSV] [SIMPLIFY]`
 
-create setting to access the server authentication
+create setting to access to a server
 
 ```
 USAGE
-  $ proca config setup [ENV] [HUMAN] [JSON] [CSV] [SIMPLIFY] --token <API-token> [--json
-    | --human | --csv] [--env <value>] [--simplify] [--force] [--url <url>]
+  $ proca config setup [ENV] [HUMAN] [JSON] [CSV] [SIMPLIFY] [--json | --human | --csv]
+    [--env <value>] [--simplify] [--url http://localhost:4000] [--token API-token>] [--email you@example.org] [--folder
+    /var/www/proca/config.example]
 
 ARGUMENTS
   ENV       [default: default] allow to switch between configurations (server or users)
@@ -503,10 +605,11 @@ ARGUMENTS
   SIMPLIFY  flatten and filter to output only the most important attributes, mostly relevant for json
 
 FLAGS
-  --env=<value>        [default: default] allow to switch between configurations (server or users)
-  --force              write over an existing configuration
-  --token=<API-token>  (required) user token on proca server
-  --url=<url>          [default: https://api.proca.app/api] url of the proca server api
+  --email=you@example.org                 user email on proca server
+  --env=<value>                           [default: default] allow to switch between configurations (server or users)
+  --folder=/var/www/proca/config.example  config folder (in the proca widget generator)
+  --token=API-token>                      user token on proca server
+  --url=http://localhost:4000             [default: https://api.proca.app/api] url of the proca server api
 
 OUTPUT FLAGS
   --csv            Format output as csv
@@ -515,7 +618,7 @@ OUTPUT FLAGS
   --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
 
 DESCRIPTION
-  create setting to access the server authentication
+  create setting to access to a server
 
 ALIASES
   $ proca config setup
@@ -545,6 +648,9 @@ OUTPUT FLAGS
 DESCRIPTION
   fetch the information about the current user (based on the token)
 
+ALIASES
+  $ proca user whoami
+
 EXAMPLES
   $ proca config user
 ```
@@ -638,12 +744,13 @@ _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.2
 ```
 USAGE
   $ proca org add [--json | --human | --csv] [--env <value>] [--simplify] [--twitter
-    <screen name>] [-n <org name>]
+    <screen name>] [-n <org acronym/name>] [-t <org full name>]
 
 FLAGS
-  -n, --name=<org name>        name of the org
-      --env=<value>            [default: default] allow to switch between configurations (server or users)
-      --twitter=<screen name>  twitter account
+  -n, --name=<org acronym/name>  short name of the org
+  -t, --title=<org full name>    title/full name of the org
+      --env=<value>              [default: default] allow to switch between configurations (server or users)
+      --twitter=<screen name>    twitter account
 
 OUTPUT FLAGS
   --csv            Format output as csv
@@ -652,6 +759,8 @@ OUTPUT FLAGS
   --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
 
 EXAMPLES
+  $ proca org add --name <twitter of the organisation> --title='this is an organisation'
+
   $ proca org add --twitter <twitter of the organisation>
 ```
 
@@ -709,7 +818,7 @@ view a org
 ```
 USAGE
   $ proca org get [ID_NAME_DXID] [--json | --human | --csv] [--env <value>]
-    [--simplify] [-n <org name>] [--config] [--keys] [--campaigns] [--widgets] [--users]
+    [--simplify] [-n <org name>] [--config] [--keys] [--campaigns] [--users]
 
 FLAGS
   -n, --name=<org name>  name of the org
@@ -718,7 +827,6 @@ FLAGS
       --env=<value>      [default: default] allow to switch between configurations (server or users)
   --[no-]keys
   --[no-]users
-  --[no-]widgets
 
 OUTPUT FLAGS
   --csv            Format output as csv
@@ -1052,6 +1160,27 @@ DESCRIPTION
 
 _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.25/src/commands/plugins/update.ts)_
 
+## `proca target add`
+
+```
+USAGE
+  $ proca target add -c <value> --name <value> --email <value> [--json | --human |
+    --csv] [--env <value>] [--simplify] [--external_id <value>]
+
+FLAGS
+  -c, --campaign=<value>     (required) mtt campaign to add the target
+      --email=<value>        (required) email of the target
+      --env=<value>          [default: default] allow to switch between configurations (server or users)
+      --external_id=<value>  external id of the target
+      --name=<value>         (required) name of the target
+
+OUTPUT FLAGS
+  --csv            Format output as csv
+  --human          Format output to be read on screen by a human [default]
+  --json           Format output as json
+  --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
+```
+
 ## `proca user get`
 
 fetch the information about a user
@@ -1133,6 +1262,60 @@ EXAMPLES
   $ proca user list %pizza%
 ```
 
+## `proca user reset [USER]`
+
+Reset user API token
+
+```
+USAGE
+  $ proca user reset [USER] [--json | --human | --csv] [--env <value>] [--simplify]
+    [--password <value>] [--url <value>]
+
+ARGUMENTS
+  USER  Username (email)
+
+FLAGS
+  --env=<value>       [default: default] allow to switch between configurations (server or users)
+  --password=<value>  Password
+  --url=<value>       URL of the Proca server API
+
+OUTPUT FLAGS
+  --csv            Format output as csv
+  --human          Format output to be read on screen by a human [default]
+  --json           Format output as json
+  --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
+
+DESCRIPTION
+  Reset user API token
+```
+
+## `proca user whoami`
+
+fetch the information about the current user (based on the token)
+
+```
+USAGE
+  $ proca user whoami [--json | --human | --csv] [--env <value>] [--simplify]
+
+FLAGS
+  --env=<value>  [default: default] allow to switch between configurations (server or users)
+
+OUTPUT FLAGS
+  --csv            Format output as csv
+  --human          Format output to be read on screen by a human [default]
+  --json           Format output as json
+  --[no-]simplify  flatten and filter to output only the most important attributes, mostly relevant for json
+
+DESCRIPTION
+  fetch the information about the current user (based on the token)
+
+ALIASES
+  $ proca user whoami
+
+EXAMPLES
+  $ proca user whoami
+```
+
 ## `proca widget add`
 
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proca",
 	"description": "Access the proca api",
-	"version": "1.4.0",
+	"version": "1.7.0",
 	"author": "Xavier",
 	"bin": {
 		"proca": "proca-cli"
@@ -19,7 +19,8 @@
 		"fast-csv": "^5.0.1",
 		"graphql": "^16.10.0",
 		"typescript": "^5.7.3",
-		"urql": "^4.1.0"
+		"urql": "^4.1.0",
+		"prompts": "^2.4.2"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^1.9.3",

package/src/commands/action/add.mjs

@@ -9,6 +9,7 @@ export default class ActionAdd extends Command {
 	static examples = [
 		"<%= config.bin %> <%= command.id %> -i <widget_id> --firstname=John --email=john@example.org",
 		"<%= config.bin %> <%= command.id %> -i <widget_id> --firstname=John --email=john@example.org --country=FR custom1=A custom2=B",
+		"<%= config.bin %> <%= command.id %> -i <widget_id> --firstname=John --email=john@example.org target=715a9580-cfe6-4005-9e23-61a62ddecfea --subject='MTT subject' --body='message MTT'",
 	];
 
 	static args = this.multiid();
@@ -50,6 +51,9 @@ export default class ActionAdd extends Command {
 			description: "email",
 			required: true,
 		}),
+		target: Flags.string({ description: "[mtt] uid of the target" }),
+		subject: Flags.string({ description: "[mtt] subject of the email" }),
+		body: Flags.string({ description: "[mtt] body of the email" }),
 	};
 
 	create = async (flags) => {
@@ -95,6 +99,16 @@ export default class ActionAdd extends Command {
 			},
 		};
 
+		if (flags.target) {
+			values.action.mtt = {
+				targets: [flags.target],
+				subject: flags.subject || "Test MTT",
+				body: flags.body || "Please ignore, this is a test",
+			};
+			values.action.actionType = "mail2target";
+		}
+		console.log(values.action.mtt);
+
 		const query = gql`
  mutation (
   $action: ActionInput!

package/src/commands/campaign/get.mjs

@@ -2,6 +2,7 @@ import { Args, Flags } from "@oclif/core";
 import { error, stdout, ux } from "@oclif/core/ux";
 import Command from "#src/procaCommand.mjs";
 import {
+	FragmentMtt,
 	FragmentOrg,
 	FragmentStats,
 	FragmentSummary,
@@ -43,11 +44,13 @@ export default class CampaignGet extends Command {
           ...Org
           config
           ...Stats @include(if: $withStats)
+          ...Mtt
         }
       }
       ${FragmentStats}
       ${FragmentSummary}
       ${FragmentOrg}
+      ${FragmentMtt}
     `;
 		const result = await query(GetCampaignDocument, {
 			id: id,
@@ -67,6 +70,20 @@ export default class CampaignGet extends Command {
 			locales: d.config.locales && Object.keys(d.config.locales).join(" "),
 			journey: d.config.journey?.join(" → "),
 		};
+		if (d.mtt) {
+			// we have an mtt
+			const hhmm = (date) =>
+				new Date(date).toLocaleTimeString(undefined, {
+					hour: "2-digit",
+					minute: "2-digit",
+					hour12: false,
+				});
+			result.from = d.mtt.startAt.substring(0, 10);
+			result.to = d.mtt.endAt.substring(0, 10);
+			result.period = `${hhmm(d.mtt.startAt)}↔${hhmm(d.mtt.endAt)}`;
+			result["test email"] = d.mtt.testEmail;
+			result["mtt template"] = d.mtt.template;
+		}
 		if (this.flags.stats) {
 			result["#Supporters"] = d.stats.supporterCount;