satusehat: add adaptor examples and update docs (#806)

* feat: add adaptor examples and update docs Signed-off-by: Hunter Achieng <[email protected]> * fix: add state and more examples Signed-off-by: Hunter Achieng <[email protected]> * fix post examples Signed-off-by: Hunter Achieng <[email protected]> * fix add data object to param docs Signed-off-by: Hunter Achieng <[email protected]> * tools: fix nested HTML in example captions * fix: add more satusehat examples Signed-off-by: Hunter Achieng <[email protected]> * fix: add backticks to docs urls Signed-off-by: Hunter Achieng <[email protected]> * fix: example formatting Signed-off-by: Hunter Achieng <[email protected]> * fix: update docs Signed-off-by: Hunter Achieng <[email protected]> * version: [email protected] --------- Signed-off-by: Hunter Achieng <[email protected]> Co-authored-by: Joe Clark <[email protected]>
OpenFn · Nov 4, 2024 · edf1592 · edf1592
1 parent f465188
commit edf1592
Show file tree

Hide file tree

Showing 4 changed files with 56 additions and 36 deletions.
diff --git a/packages/satusehat/CHANGELOG.md b/packages/satusehat/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @openfn/language-satusehat
 
+## 2.0.6
+
+### Patch Changes
+
+- 7c528d3: Update docs with examples
+
 ## 2.0.5
 
 ### Patch Changes

diff --git a/packages/satusehat/package.json b/packages/satusehat/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openfn/language-satusehat",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "OpenFn Satusehat adaptor",
   "type": "module",
   "exports": {

diff --git a/packages/satusehat/src/Adaptor.js b/packages/satusehat/src/Adaptor.js
@@ -2,6 +2,14 @@ import { execute as commonExecute } from '@openfn/language-common';
 import { expandReferences } from '@openfn/language-common/util';
 import { request, prepareNextState, authorize } from './Utils';
 
+/**
+ * State object
+ * @typedef {Object} SatusehatHttpState
+ * @property data - The response body (as JSON)
+ * @property response - The HTTP response from the Satusehat server (excluding the body)
+ * @property references - An array of all previous data objects used in the Job
+ */
+
 /**
  * Execute a sequence of operations.
  * Wraps `language-common/execute` to make working with this API easier.
@@ -32,15 +40,22 @@ export function execute(...operations) {
 }
 
 /**
- * Make a GET request to Satusehat
+ * Make a GET request to Satusehat. Use this to fetch resources directly from the Satusehat REST API.
+ * You can pass Satusehat query parameters as an object of key value pairs, which will map to parameters
+ * in the URL.
  * @public
- * @example
- * get("Organization", {"name": "somename"})
+ * @example  <caption>Get a resource by Id. Equivalent to GET `<baseUrl>/Organization/abcde`</caption>
+ * get("Organization/abcde")
+ * @example <caption>Get resources with a query. Equivalent to GET `<baseUrl>/Patient?identifier=https://fhir.kemkes.go.id/id/nik|9271060312000001`</caption>
+ * get('/Patient', {
+ *   identifier:'https://fhir.kemkes.go.id/id/nik|9271060312000001'
+ * });
  * @function
  * @param {string} path - Path to resource
- * @param {object} params - Optional request params such as name.
+ * @param {object} params - Optional object of query parameters to include in the request
  * @param {function} callback - An optional callback to handle the response
  * @returns {Operation}
+ * @state {SatusehatHttpState}
  */
 export function get(path, params = {}, callback = s => s) {
   return async state => {
@@ -63,21 +78,20 @@ export function get(path, params = {}, callback = s => s) {
 }
 
 /**
- * Make a POST request to Satusehat
- * @example
- * post(
- *   "Organization",
- *  { "resourceType": "Organization", "active": true,
- *  }
- * );
+ * Make a POST request to Satusehat. Use this to send resources directly to Satusehat REST API.
+ * You can pass Satusehat body data as a JSON FHIR object.
+ * @example <caption>Create an encounter resource. Equivalent to POST `<baseUrl>/Encounter`</caption>
+ * post('Encounter', { resourceType: 'Encounter', ...state.data });
  * @function
  * @public
  * @param {string} path - Path to resource
- * @param {object} data - Object or JSON which defines data that will be used to create a given instance of resource
- * @param {Object} params - Optional request params.
+ * @param {object} data - JSON FHIR object to create a resource
+ * @param {Object} params - Optional object of query parameters to include in the request
  * @param {function} [callback] - Optional callback to handle the response
  * @returns {Operation}
+ * @state {SatusehatHttpState}
  */
+
 export function post(path, data, params = {}, callback = s => s) {
   return async state => {
     const [resolvedPath, resolvedData, resolvedParams] = expandReferences(
@@ -102,20 +116,19 @@ export function post(path, data, params = {}, callback = s => s) {
 }
 
 /**
- * Make a PUT request to Satusehat
- * @example
- * put(
- *   "Organization/123",
- *  { "resourceType": "Organization", "active": false,
- *  }
- * );
+ * Make a PUT request to Satusehat. Use this to directly update resources on Satusehat REST API.
+ * You can pass Satusehat body data as a JSON FHIR object. You can also pass Satusehat query parameters as an object of key value pairs, which will map to parameters
+ * in the URL.
+ * @example <caption>Update a resource. Equivalent to PUT `<baseurl>/Organization/abcde`</caption>
+ * put('Organization/abcde', { resourceType: 'Organization', active: false });
  * @function
  * @public
  * @param {string} path - Path to resource and exact item to be updated
- * @param {object} data - Object or JSON which defines data that will be used to update a given instance of resource
- * @param {Object} params - Optional request params.
+ * @param {object} data - JSON FHIR object to update the resource
+ * @param {Object} params - Optional object of query parameters to include in the request
  * @param {function} [callback] - Optional callback to handle the response
  * @returns {Operation}
+ * @state {SatusehatHttpState}
  */
 export function put(path, data, params = {}, callback = s => s) {
   return async state => {
@@ -141,24 +154,25 @@ export function put(path, data, params = {}, callback = s => s) {
 }
 
 /**
- * Make a PATCH request to Satusehat
- * @example
- * patch(
- *   "Organization/123",
- *    [{
- * "op": "replace", // Operation - `replace` is the only one used to change a specific property or element
- *  "path": "/language", // Path - The name of property/element of resource to be replaced
- *  "value": "id" // Value- The value to be replaced
- *}]
- *
- * );
+ * Make a PATCH request to Satusehat. Use this to directly update resources on Satusehat REST API.
+ * You can pass Satusehat an array of objects which contains `op`, `path`, and `value` as the body. You can also pass Satusehat query parameters as an object of key value pairs, which will map to parameters
+ * in the URL.
+ * @example <caption>Update a property of a resource. Equivalent to PATCH `<baseurl>/Organization/abcde`</caption>
+ * patch('Organization/abcde', [
+ * {
+ *  op: 'replace',
+ *  path: '/language', // Name of property/element of resource to be replaced
+ *  value: 'id', // Value to be replaced
+ * },
+ * ]);
  * @function
  * @public
  * @param {string} path - Path to resource and exact item to be partially updated
  * @param {Array} data - An array of objects which defines data that will be used to partially update a given instance of resource
- * @param {Object} params - Optional request params.
+ * @param {Object} params - Optional object of query parameters to include in the request.
  * @param {function} [callback] - Optional callback to handle the response
  * @returns {Operation}
+ * @state {SatusehatHttpState}
  */
 export function patch(path, data, params = {}, callback = s => s) {
   return async state => {

diff --git a/tools/build/src/partials/examples.hbs b/tools/build/src/partials/examples.hbs
@@ -1,4 +1,4 @@
 {{#examples}}
-**Example{{#if caption}}:** {{caption}}{{else}}**{{/if}}
+**Example{{#if caption}}:** {{{caption}}}{{else}}**{{/if}}
 {{{inlineLinks example}}}
 {{/examples}}