Merge pull request #11 from grid-x/feat/replace-topic-content

feat: Allow for replacing a single post's content

Author: wwerner

README.md

@@ -1,7 +1,8 @@
 # Post a string or the contents of a file to a Discourse topic
 
 This repository provides a GitHub Action to post a string or the contents of a
-given file to a specific Discourse topic.
+given file to a specific Discourse topic, either adding a new reply or replacing
+a single post's content.
 
 We use it as part of our API documentation management suite:
 [Rapidoc](https://rapidocweb.com/) as a [Discourse](https://discourse.org/)
@@ -17,10 +18,17 @@ finally upload the changelogs with the action from this repository.
 
 - `discourse_url` - your discourse instance domain, e.g.
   "community.developer.gridx.de
-- `discourse_topic_id` - the ID of the Discourse post to reply to. You can find
-  the ID, e.g., by inspecting your post in the browser and looking for
-  `data-topic-id="<n>"` in the `article` element. (XPath `//h1/@data-topic-id`)
-  ![Discourse Topic ID](doc-topic-id.png)
+- `discourse_topic_id` - Use this to reply to a topic: the ID of the Discourse
+  topic to reply to. You can find the ID, e.g., by inspecting your post in the
+  browser and looking for `data-topic-id="<n>"` in the `article` element. (XPath
+  `//h1/@data-topic-id`). **If both topic and post ID are given, topic ID takes
+  precedence and a new reply is added**. ![Discourse Topic ID](doc-topic-id.png)
+- `discourse_post_id` - Use this to replace the contents of a post: the ID of
+  the Discourse post to reply to. You can find the ID, e.g., by inspecting your
+  post in the browser and looking for `data-post-id="<n>"` in the `article`
+  element. (XPath `//article/@data-post-id`). If there are multiple posts in the
+  topic, make sure to find the correct one to replace. **If both topic and post
+  ID are given, topic ID takes precedence and a new reply is added**.
 - `discourse_api_key` - your discourse API key. It needs `topics:write`
   permissions. ![Discourse API Key](doc-discourse-api-key.png)
 - `discourse_user` - the discourse user on whose behalf the action should be
@@ -29,9 +37,11 @@ finally upload the changelogs with the action from this repository.
   obtained using `$GITHUB_SHA` when running in an action or with
   `git rev-parse --short HEAD`
 - `content_file` - the (text) file containing the contents to be posted,
-  relative to the repositories root. Use either this or `content` directly.
+  relative to the repositories root. Use either this or `content` directly. **If
+  both are present, content file takes precedence.**
 - `content` - the contents to be posted. Use either this or `content_file` to
-  load the content from a file. D'uh.
+  load the content from a file. D'uh. **If both are present, content file takes
+  precedence.**
 
 ## Instructions
 
@@ -40,19 +50,36 @@ finally upload the changelogs with the action from this repository.
 1. Get the required parameters as described above
 1. Configure the action in your GH workflow, preferably on release
 
+Example: Adding a reply from a file
+
 ```yaml
 - name: Test Action against gridX community example post
   uses: ./
   with:
     discourse_url: ${{secrets.DISCOURSE_URL}}
     discourse_topic_id: <n>
+    # OR discourse_post_id: <n>
     discourse_api_key: ${{secrets.DISCOURSE_API_KEY}}
     discourse_user: ${{secrets.DISCOURSE_USER}}
     github_sha: ${{env.SHORT_SHA}}
     content_file: ./changelog.md
     # OR content: "content as string"
 ```
 
+Example: Replacing a single post with a fixed string
+
+```yaml
+- name: Test Action against gridX community example post
+  uses: ./
+  with:
+    discourse_url: ${{secrets.DISCOURSE_URL}}
+    discourse_post_id: <n>
+    discourse_api_key: ${{secrets.DISCOURSE_API_KEY}}
+    discourse_user: ${{secrets.DISCOURSE_USER}}
+    github_sha: ${{env.SHORT_SHA}}
+    content: 'Post <n> will be replaced by this'
+```
+
 ## Development
 
 - You can run the action locally using `npm run test:run`, providing the

action.yml

@@ -10,26 +10,33 @@ branding:
 # Define your inputs here.
 inputs:
   discourse_url:
-    description: 'your discourse instance domain, e.g. "community.acme.com'
+    description: 'Your discourse instance domain, e.g. "community.acme.com'
     required: true
   discourse_topic_id:
-    description: 'the ID of the Discourse topic to reply to'
-    required: true
+    description:
+      'The ID of the Discourse topic to reply to. Leave empty and set
+      `discourse_post_id` to update the original post.'
+    required: false
+  discourse_post_id:
+    description:
+      'The ID of the Discourse post to replace with the content given. Leave
+      empty and set `discourse_topic_id` to add a new reply to the topic.'
+    required: false
   discourse_api_key:
-    description: 'your discourse API key. It needs `topics:write`` permissions'
+    description: 'Your discourse API key. It needs `topics:write` permissions'
     required: true
   discourse_user:
     description:
-      'the discourse user on whose behalf the action should be executed'
+      'The discourse user on whose behalf the action should be executed'
     required: true
   content_file:
-    description: 'the file to load the content to post from'
+    description: 'The file to load the content to post from'
     required: false
   content:
-    description: 'the string to post'
+    description: 'The string to post'
     required: false
   github_sha:
-    description: 'short commit hash to be put into to post for traceability'
+    description: 'Short commit hash to be put into to post for traceability'
     required: true
 
 runs:

src/index.ts

@@ -7,6 +7,7 @@ import * as core from '@actions/core'
 // eslint-disable-next-line @typescript-eslint/no-floating-promises
 const discourseUrl: string = core.getInput('discourse_url')
 const discourseTopicId: string = core.getInput('discourse_topic_id')
+const discoursePostId: string = core.getInput('discourse_post_id')
 const discourseApiKey: string = core.getInput('discourse_api_key')
 const discourseUser: string = core.getInput('discourse_user')
 const commit: string = core.getInput('github_sha')
@@ -17,6 +18,7 @@ const contentFile: string = core.getInput('content_file')
 run(
   discourseUrl,
   discourseTopicId,
+  discoursePostId,
   discourseApiKey,
   discourseUser,
   commit,

src/main.ts

@@ -10,6 +10,7 @@ import { title } from 'process'
 export async function run(
   discourseUrl: string,
   discourseTopicId: string,
+  discoursePostId: string,
   discourseApiKey: string,
   discourseUser: string,
   commit: string,
@@ -38,29 +39,37 @@ export async function run(
           Accept: 'application/json'
         }
       })
-      return http
-        .post('/posts.json', {
-          raw: postBody,
-          topic_id: discourseTopicId,
-          reply_to_post_number: discourseTopicId,
-          skip_validations: true
-        })
-        .then(({ data }) => {
-          core.debug(JSON.stringify(data, null, 2))
-        })
-        .catch(e => {
-          console.error(
-            'Error uploading file to Discourse',
-            JSON.stringify(e, null, 2)
-          )
-          throw e
-        })
+      const commonProps = {
+        raw: postBody,
+        skip_validations: true
+      }
+
+      return discourseTopicId
+        ? http // topic ID given, post reply
+            .post('/posts.json', {
+              ...commonProps,
+              topic_id: discourseTopicId,
+              reply_to_post_number: discourseTopicId
+            })
+        : http // post ID given, update this post
+            .put(`/posts/${discoursePostId}.json`, {
+              ...commonProps
+            })
+            .then(({ data }) => {
+              core.debug(JSON.stringify(data, null, 2))
+            })
+            .catch(e => {
+              console.error(
+                'Error uploading file to Discourse',
+                JSON.stringify(e, null, 2)
+              )
+              throw e
+            })
     }
 
     const postBody = (content: string, commit: string): string =>
       content
-        ? `# Changelog ${new Date().toISOString()}
-${content}
+        ? `${content}
 
 (sha ${commit.trim()})
 `

src/test.ts

@@ -4,22 +4,28 @@ import { execSync } from 'node:child_process'
 /*
 export DISCOURSE_URL=community.developer.gridx.de
 export DISCOURSE_TOPIC_ID=<n>
+export DISCOURSE_POST_ID=<n>
 export DISCOURSE_API_KEY=...
 export DISCOURSE_USER=wwerner
 */
 
 const discourseUrl: string = process.env.DISCOURSE_URL ?? ''
 const discourseTopicId: string = process.env.DISCOURSE_TOPIC_ID ?? ''
+const discoursePostId: string = process.env.DISCOURSE_POST_ID ?? ''
 const discourseApiKey: string = process.env.DISCOURSE_API_KEY ?? ''
 const discourseUser: string = process.env.DISCOURSE_USER ?? ''
 const commit: string = execSync('git rev-parse --short HEAD').toString()
 
-const content = ''
+const content = 'I am the replacement!'
 const contentFile = './test-post.md'
 
+// for exploratory testing,
+// replace the topic id w/ "" to update a post and
+// replace contentFile w/ "" to use content over contentFile
 run(
   discourseUrl,
   discourseTopicId,
+  discoursePostId,
   discourseApiKey,
   discourseUser,
   commit,