Final merge from dev (#38)

* fix: Blank buttons no longer appear for players who have not selected a token/character
* Adds an API, Hooks, and better translations (#37)
Fixes #32

.eslintignore

@@ -1,2 +1,3 @@
 deploy/
-dist/
+dist/
+gulpfile.mjs

.eslintrc.json

@@ -13,9 +13,10 @@
       // "eslint:recommended",
       "@typhonjs-fvtt/eslint-config-foundry.js/0.8.0",
       "plugin:jest/recommended",
-      "plugin:prettier/recommended"
+      "plugin:prettier/recommended",
+      "plugin:jsdoc/recommended"
     ],
-    "plugins": ["jest","unicorn","prettier"],
+    "plugins": ["jest","unicorn","prettier", "jsdoc"],
     "parserOptions": {
       "ecmaVersion": 2020,
       "extraFileExtensions": [".cjs", ".mjs"],
@@ -33,17 +34,18 @@
     //
     // Note: if you are using Typescript you must use `@typescript-eslint/no-shadow`
     "rules": {
+      "linebreak-style": ["error", "unix"],
       // "no-shadow": ["error", { "builtinGlobals": true, "hoist": "all", "allow": ["event"] }],
       // "brace-style": ["error", "1tbs"],
-      // "require-jsdoc": "off",
+      "require-jsdoc": 2
       // "quotes": ["error", "double", { "avoidEscape": true }],
       // "no-unused-vars": [2, {"args": "all", "argsIgnorePattern": "^_"}],
       //"unicorn/better-regex": "error"
     },
 
     "overrides": [
       {
-        "files": ["./*.js", "./*.cjs", "./*.mjs"],
+        "files": ["./src/**/*.js", "./*.cjs", "./*.mjs"],
         "env": {
           "node": true
         }

.prettierrc.json

@@ -5,5 +5,5 @@
   "singleQuote": false,
   "printWidth": 120,
   "tabWidth": 2,
-  "endOfLine": "lf"
+  "endOfLine": "auto"
 }

API.md

@@ -0,0 +1,168 @@
+# API functions
+
+Access functions via `game["fvtt-player-achievements"].api`.
+
+All functions return the following object:
+
+  ```javascript
+  {
+    errorMessage: 'Error message',
+    payload: object
+  }
+  ```
+
+## Current API Functions:
+
+### getAchievements - Returns the achievements array
+
+
+
+     **Returns:**
+
+&nbsp;&nbsp;&nbsp;&nbsp;  - `"PlayerAchievementReturn.<Array.<Achievement>>"`: Achievements List
+
+<hr/>
+
+
+### doesAchievementExist - Does the achievement exist?
+
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Parameters:**
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `achievementId` (string): The achievement id
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Returns:**
+
+&nbsp;&nbsp;&nbsp;&nbsp;  - `"PlayerAchievementReturn.<boolean>"`: Does the achievement exist?
+
+<hr/>
+
+
+### doesCharacterHaveAchievement - Does the character have the achievement?
+
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Parameters:**
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `characterUUID` (string): The character uuid
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `achievementId` (string): The achievement id
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Returns:**
+
+&nbsp;&nbsp;&nbsp;&nbsp;  - `"PlayerAchievementReturn.<boolean>"`: Does the character have the achievement?
+
+<hr/>
+
+
+### awardAchievementToCharacter - Award the achievement to the character
+
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Parameters:**
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `achievementId` (string): The achievement id
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `characterUUID` (string): The character uuid
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Returns:**
+
+&nbsp;&nbsp;&nbsp;&nbsp;  - `"PlayerAchievementReturn.<boolean>"`: Was the achievement awarded?
+
+<hr/>
+
+
+### getAchievementsByCharacter - Get the achievements for the character
+
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Parameters:**
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `characterUUID` (string): The character uuid
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Returns:**
+
+&nbsp;&nbsp;&nbsp;&nbsp;  - `"PlayerAchievementReturn.<Array.<Achievement>>"`: achievements for the character
+
+<hr/>
+
+
+### createAchievement - Create an achievement
+
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Parameters:**
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `id` (string): The achievement id
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `title` (string): The achievement title
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `description` (string): The achievement description
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `showTitleCloaked` (boolean) [**Optional**]: Show the title cloaked? (Default: false)
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `image` (string) [**Optional**]: The achievement image (Default: &quot;/modules/fvtt-player-achievements/images/default.webp&quot;)
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `cloakedImage` (string) [**Optional**]: The achievement cloaked image (Default: &quot;/modules/fvtt-player-achievements/images/default.webp&quot;)
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `sound` (string) [**Optional**]: The achievement sound effect (Default: &quot;/modules/fvtt-player-achievements/sounds/notification.ogg&quot;)
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Returns:**
+
+&nbsp;&nbsp;&nbsp;&nbsp;  - `"PlayerAchievementReturn.<boolean>"`: Was the achievement created?
+
+<hr/>
+
+
+### editAchievement - Edit an achievement
+
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Parameters:**
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `id` (string): The achievement id
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `title` (string): The achievement title
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `description` (string): The achievement description
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `showTitleCloaked` (boolean) [**Optional**]: Show the title cloaked? (Default: false)
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `image` (string) [**Optional**]: The achievement image (Default: &quot;/modules/fvtt-player-achievements/images/default.webp&quot;)
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `cloakedImage` (string) [**Optional**]: The achievement cloaked image (Default: &quot;/modules/fvtt-player-achievements/images/default.webp&quot;)
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `sound` (string) [**Optional**]: The achievement sound effect (Default: &quot;/modules/fvtt-player-achievements/sounds/notification.ogg&quot;)
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Returns:**
+
+&nbsp;&nbsp;&nbsp;&nbsp;  - `"PlayerAchievementReturn.<boolean>"`: Was the achievement edited?
+
+<hr/>
+
+
+### removeAchievementFromCharacter - Remove an achievement from the character
+
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Parameters:**
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `achievementId` (string): The achievement id
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `characterUUID` (string): The character uuid
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Returns:**
+
+&nbsp;&nbsp;&nbsp;&nbsp;  - `"PlayerAchievementReturn.<boolean>"`: Was the achievement removed?
+
+<hr/>
+
+
+### deleteAchievement - Delete an achievement
+
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Parameters:**
+
+  &nbsp;&nbsp;&nbsp;&nbsp;  - `id` (string): 
+
+&nbsp;&nbsp;&nbsp;&nbsp; **Returns:**
+
+&nbsp;&nbsp;&nbsp;&nbsp;  - `"PlayerAchievementReturn.<boolean>"`: Was the achievement deleted?
+
+<hr/>
+
+

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.2.0 (2024-01-29)
+
+##### New Features
+
+*  Translated into Brazilian Portuguese, credits to Daniel Norberto ([f6293dc3](https://github.com/EddieDover/fvtt-player-achievements/commit/f6293dc3c09123311797f3cfb80556c6bb48598f))
+*  Added award/unward hooks. ([7d5c7edb](https://github.com/EddieDover/fvtt-player-achievements/commit/7d5c7edbaba7d5991cbe51a08a0a9c914a593173))
+*  Added API for external access to the plugin ([adb681dc](https://github.com/EddieDover/fvtt-player-achievements/commit/adb681dcaba3fad8331372729f80a8387ec4245e))
+
 ## 1.1.0 (2023-12-04)
 
 #### New Features

README.md

@@ -8,6 +8,9 @@ This module provides GMs with a way to award players with achievements.
 [![Foundry Hub Comments](https://img.shields.io/endpoint?logoColor=white&url=https%3A%2F%2Fwww.foundryvtt-hub.com%2Fwp-json%2Fhubapi%2Fv1%2Fpackage%2Ffvtt-player-achievements%2Fshield%2Fcomments)](https://www.foundryvtt-hub.com/package/fvtt-player-achievements/)
 
 ## Features
+  ### Developers
+  - Provides an API documented in [API.md](./API.md)
+  - Provides hooks for after achievement award/unaward.
   ### GMs
   - Create your own achievements.
   - Assign/Unassign achievements to/from players.
@@ -39,7 +42,10 @@ Feel free to file a Bug Report / Feature Request under the Issues tab of Github.
 
 Or you can join my **Discord** server here: https://discord.gg/XuGx7zNMKZ
 
-## How to Use
+## How to Use - DMs & Players
+
+    Note: Players will see achievements that they are allowed to see based on the DMs options.
+    Players will also not see the add-achievement/export/import/award/unaward/etc buttons.
 
 ### First, click the Icon on your side panel: <img src="./previews/achievementsIcon.png" title="Foundry Achievements Button"></img>
 
@@ -49,6 +55,28 @@ Or you can join my **Discord** server here: https://discord.gg/XuGx7zNMKZ
 
 <img src="./previews/achievementScreenDMInstructions2.png" title="DM Instructions for awarding achievements" />
 
+
+## How to Use - Developers
+
+### Hooks for Achievement Events
+
+The module provides two hooks, "**fvtt-player-achievements.awardAchievement**" and "**fvtt-player-achievements.unAwardAchievement**", allowing developers to integrate custom functionality after an achievement is granted or removed to/from a character.
+
+***Both hooks grant two parameters, the Achievement ID and the Character UUID, in that order.***
+
+#### Example Usage:
+
+```javascript
+// Triggered after an achievement is granted to a character
+Hooks.on("fvtt-player-achievements.awardAchievement", (achievementId, characterUUID) => {
+  console.log(`Character ${characterUUID} has gained the achievement: ${achievementId}`);
+});
+```
+
+### API
+
+An API is also provided that allows direct control of this module. See [API.md](./API.md)
+
 ## Screenshots
 
 ### Achievements Icon

api_doc_generation/apidoctemplate.hbs

@@ -0,0 +1,39 @@
+# API functions
+
+Access functions via `game["fvtt-player-achievements"].api`.
+
+All functions return the following object:
+
+  ```javascript
+  {
+    errorMessage: 'Error message',
+    payload: object
+  }
+  ```
+
+## Current API Functions:
+{{#functions}}
+
+### {{name}} - {{description}}
+
+
+{{#if params}}
+     **Parameters:**
+  {{#each params}}
+
+        - `{{name}}` ({{ type.names.[0] }}){{#if optional}} [**Optional**]{{/if}}: {{description}}{{#if optional}} (Default: {{defaultvalue}}){{/if}}
+  {{/each}}
+{{/if}}
+
+{{#if returns}}
+     **Returns:**
+  {{#each returns}}
+
+      - `{{stringify type.names.[0]}}`: {{description}}
+  {{/each}}
+{{/if}}
+
+<hr/>
+
+{{/functions}}
+

api_doc_generation/apihelpers.js

@@ -0,0 +1,8 @@
+/* eslint-disable unicorn/prefer-module */
+const Handlebars = require("handlebars");
+
+Handlebars.registerHelper("stringify", function (objectToStringify) {
+  return new Handlebars.SafeString(JSON.stringify(objectToStringify));
+});
+
+module.exports = Handlebars.helpers;