@openfn/language-commcare - npm Package Compare versions

Comparing version 3.2.4 to 3.2.5

ast.json

@@ -11,3 +11,3 @@ {
       "docs": {
-        "description": "Make a GET request to any CommCare endpoint. The response body will be returned to `state.data` as JSON.\nPaginated responses will be fully downloaded and returned as a single array, _unless_ an `offset` is passed.",
+        "description": "Make a GET request to CommCare. Use this to fetch resources directly from Commcare REST API.\nYou can pass Commcare query parameters as an object of key value pairs, which will map to parameters\nin the URL.\nThe response body will be returned to `state.data` as JSON.\nPaginated responses will be fully downloaded and returned as a single array, _unless_ an `offset` is passed.",
         "tags": [
@@ -27,3 +27,3 @@ {
             "description": "get(\"/case/12345\")",
-            "caption": "Get a specific case by id"
+            "caption": "Get a resource by Id. Equivalent to GET `<baseUrl>/case/12345`"
           },
@@ -33,15 +33,10 @@ {
             "description": "get(\"/case\", { offset:0, limit: 20 })",
-            "caption": "Get exactly 20 cases"
+            "caption": "Get a resource with exactly 20 items. Equivalent to `<baseUrl>/case?offset=0&limit=20`"
           },
           {
             "title": "example",
-            "description": "get(\"/form\", { app_id: \"02bf50ab803a89ea4963799362874f0c\" })",
-            "caption": "Get forms by app id"
+            "description": "get(\"/case\", {}, (state) => {\n  state.cases.push(...state.data) // adds all cases to the cases array\n  return state;\n})",
+            "caption": "Get all items in a resource, and add them to state. Equivalent to `<baseUrl>/case`"
           },
           {
-            "title": "example",
-            "description": "get(\"/case\", {}, (state) => {\n   state.cases.push(...state.data) // adds 50 cases to the cases array\n   return state;\n})",
-            "caption": "Get all cases, 50 at a time, and add them to state"
-          },
-          {
             "title": "param",
@@ -104,3 +99,3 @@ "description": "Path to resource",
       "docs": {
-        "description": "Make a POST request to any CommCare endpoint.",
+        "description": "Make a POST request to CommCare. Use this to send resources directly to Commcare REST API.\nYou can pass Commcare body data as a JSON object.",
         "tags": [
@@ -110,3 +105,3 @@ {
             "description": "post(\"/user\", { \"username\":\"test\", \"password\":\"somepassword\" })",
-            "caption": "Post a user object to to the /user endpoint"
+            "caption": "Create a user resource.Equivalent to `<baseUrl>/user`"
           },
@@ -134,3 +129,3 @@ {
             "title": "param",
-            "description": "Object or JSON to use as the request body",
+            "description": "Object or JSON to create a resource",
             "type": {
@@ -189,3 +184,3 @@ "type": "NameExpression",
       "docs": {
-        "description": "Bulk upload data to CommCare. Accepts an array of objects, converts them into\nan XLS representation, and uploads.",
+        "description": "Bulk upload data to CommCare. Use this to send multiple items for a single resource at once to Commcare. It accepts an array of objects, converts them into\nan XLS representation, and uploads.",
         "tags": [
@@ -204,4 +199,4 @@ {
             "title": "example",
-            "description": "submitXls(\n   [\n     {name: 'Mamadou', phone: '000000'},\n   ],\n   {\n     case_type: 'student',\n     search_field: 'external_id',\n     create_new_cases: 'on',\n   }\n)",
-            "caption": "Upload a single row of data"
+            "description": "submitXls([{ name: 'Mamadou', phone: '000000' }], {\n  case_type: 'student',\n  search_field: 'external_id',\n  create_new_cases: 'on',\n});",
+            "caption": "Upload a single row of data for a resource."
           },
@@ -228,3 +223,3 @@ {
             "title": "state",
-            "description": "data - the response from the CommCare Server"
+            "description": "{CommcareHttpState}"
           },
@@ -249,3 +244,3 @@ {
       "docs": {
-        "description": "Submit forms to CommCare. Accepts an array of JSON\nobjects, converts them into XML, and submits to CommCare as an x-form.",
+        "description": "Submit forms to CommCare. Use this to send forms directly to Commcare REST API. Accepts an array of JSON\nobjects, converts them into XML, and submits to CommCare as an x-form.",
         "tags": [
@@ -264,4 +259,4 @@ {
             "title": "example",
-            "description": "submit(\n   fields(\n     field(\"@\", (state) => ({\n         \"xmlns\": `http://openrosa.org/formdesigner/${state.formId}`\n     }),\n     field(\"question1\", (state) => state.data.answer1),\n     field(\"question2\", (state) => state.data.answer2),\n   )\n )",
-            "caption": "Submit a form to CommCare"
+            "description": "submit(\n fields(\n   field('@', state => ({\n     xmlns: `http://openrosa.org/formdesigner/${state.formId}`,\n   })),\n   field('question1', state => state.data.answer1),\n   field('question2', state => state.data.answer2)\n )\n);",
+            "caption": "Submit a form resource."
           },
@@ -279,3 +274,3 @@ {
             "title": "state",
-            "description": "data - the response from the CommCare Server"
+            "description": "{CommcareHttpState}"
           },
@@ -311,4 +306,4 @@ {
             "title": "example",
-            "description": "fetchReportData(\n  \"9aab0eeb88555a7b4568676883e7379a\",\n  { limit: 10 },\n  \"https://www.example.com/api/\"\n)",
-            "caption": "Fetch 10 records from a report and post them to example.com"
+            "description": "fetchReportData(\n  \"abcde\",\n  { limit: 10 },\n  \"https://www.example.com/api/\"\n)",
+            "caption": "Get 10 records from a report and post them to example.com. Equivalent to `<baseUrl>/configurablereportdata/abcde?limit=10`"
           },
@@ -348,2 +343,6 @@ {
           {
+            "title": "state",
+            "description": "{CommcareHttpState}"
+          },
+          {
             "title": "returns",
@@ -369,3 +368,3 @@ "description": null,
       "docs": {
-        "description": "Make a general HTTP request against the Commcare server.",
+        "description": "Make a general HTTP request against the Commcare server. Use this to make any request to Commcare REST API.",
         "tags": [
@@ -375,3 +374,3 @@ {
             "description": "request(\"GET\", \"/a/asri/api/v0.5/case\");",
-            "caption": "Make a GET request to get cases"
+            "caption": "Get a resource. Equivalent to `<baseUrl>/a/asri/api/v0.5/case`"
           },
@@ -462,9 +461,9 @@ {
             "title": "example",
-            "description": "bulk(\n'case-data',\n   [\n     {name: 'Mamadou', phone: '000000'},\n   ],\n   {\n     case_type: 'student',\n     search_field: 'external_id',\n     create_new_cases: 'on',\n   }\n)",
-            "caption": "Upload a single row of data for case-data"
+            "description": "bulk('case-data', [{ name: 'Mamadou', phone: '000000' }], {\n  case_type: 'student',\n  search_field: 'external_id',\n  create_new_cases: 'on',\n});",
+            "caption": "Upload a single row of a case-data resource"
           },
           {
             "title": "example",
-            "description": "bulk(\n    'lookup-table',\n {\n   types: [{\n\n  'DELETE(Y/N)':'N',\n  table_id: 'fruit',\n  'is_global?':'yes',\n  'field 1': 'type',\n  'field 2': 'name',\n     }],\n     fruit: [{\n      UID: '',\n       'DELETE(Y/N)':'N',\n      'field:type': 'citrus',\n       'field:name': 'Orange',\n    }],\n  },\n{replace: false}\n)",
-            "caption": "Upload a single row of data for a lookup-table"
+            "description": "bulk(\n  'lookup-table',\n  {\n    types: [\n      {\n        'DELETE(Y/N)': 'N',\n        table_id: 'fruit',\n        'is_global?': 'yes',\n        'field 1': 'type',\n        'field 2': 'name',\n      },\n    ],\n    fruit: [\n      {\n        UID: '',\n        'DELETE(Y/N)': 'N',\n        'field:type': 'citrus',\n        'field:name': 'Orange',\n      },\n    ],\n  },\n  { replace: false }\n);",
+            "caption": "Upload a single row of a lookup-table resource"
           },
@@ -527,3 +526,3 @@ {
             "title": "state",
-            "description": "data - the response from the CommCare Server"
+            "description": "{CommcareHttpState}"
           },
@@ -530,0 +529,0 @@ {

configuration-schema.json

@@ -65,4 +65,5 @@ {
         "hostUrl",
-        "domain"
+        "domain",
+        "appId"
     ]
 }

package.json

 {
   "name": "@openfn/language-commcare",
-  "version": "3.2.4",
+  "version": "3.2.5",
   "description": "Commcare Language Pack for OpenFn",
@@ -5,0 +5,0 @@ "homepage": "https://docs.openfn.org",

types/Adaptor.d.ts

@@ -22,16 +22,17 @@ /**
 /**
- * Make a GET request to any CommCare endpoint. The response body will be returned to `state.data` as JSON.
+ * Make a GET request to CommCare. Use this to fetch resources directly from Commcare REST API.
+ * You can pass Commcare query parameters as an object of key value pairs, which will map to parameters
+ * in the URL.
+ * The response body will be returned to `state.data` as JSON.
  * Paginated responses will be fully downloaded and returned as a single array, _unless_ an `offset` is passed.
  * @public
  * @function
- * @example <caption>Get a specific case by id</caption>
+ * @example <caption>Get a resource by Id. Equivalent to GET `<baseUrl>/case/12345`</caption>
  * get("/case/12345")
- * @example <caption>Get exactly 20 cases</caption>
+ * @example <caption>Get a resource with exactly 20 items. Equivalent to `<baseUrl>/case?offset=0&limit=20`</caption>
  * get("/case", { offset:0, limit: 20 })
- * @example <caption>Get forms by app id</caption>
- * get("/form", { app_id: "02bf50ab803a89ea4963799362874f0c" })
- * @example <caption>Get all cases, 50 at a time, and add them to state</caption>
+ * @example <caption>Get all items in a resource, and add them to state. Equivalent to `<baseUrl>/case`</caption>
  * get("/case", {}, (state) => {
- *    state.cases.push(...state.data) // adds 50 cases to the cases array
- *    return state;
+ *   state.cases.push(...state.data) // adds all cases to the cases array
+ *   return state;
  * })
@@ -46,4 +47,5 @@ * @param {string} path - Path to resource
 /**
- * Make a POST request to any CommCare endpoint.
- * @example <caption>Post a user object to to the /user endpoint</caption>
+ * Make a POST request to CommCare. Use this to send resources directly to Commcare REST API.
+ * You can pass Commcare body data as a JSON object.
+ * @example <caption>Create a user resource.Equivalent to `<baseUrl>/user`</caption>
  * post("/user", { "username":"test", "password":"somepassword" })
@@ -53,3 +55,3 @@ * @function
  * @param {string} path - Path to resource
- * @param {object} data - Object or JSON to use as the request body
+ * @param {object} data - Object or JSON to create a resource
  * @param {Object} [params] - Optional request params
@@ -62,20 +64,15 @@ * @param {function} [callback] - Optional callback to handle the response
 /**
- * Bulk upload data to CommCare. Accepts an array of objects, converts them into
+ * Bulk upload data to CommCare. Use this to send multiple items for a single resource at once to Commcare. It accepts an array of objects, converts them into
  * an XLS representation, and uploads.
  * @public
  * @function
- * @example <caption>Upload a single row of data</caption>
- * submitXls(
- *    [
- *      {name: 'Mamadou', phone: '000000'},
- *    ],
- *    {
- *      case_type: 'student',
- *      search_field: 'external_id',
- *      create_new_cases: 'on',
- *    }
- * )
+ * @example <caption>Upload a single row of data for a resource.</caption>
+ * submitXls([{ name: 'Mamadou', phone: '000000' }], {
+ *   case_type: 'student',
+ *   search_field: 'external_id',
+ *   create_new_cases: 'on',
+ * });
  * @param {array} data - Array of objects to upload
  * @param {Object} params - Input parameters, see {@link https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143946459/Bulk+Upload+Case+Data CommCare docs}.
- * @state data - the response from the CommCare Server
+ * @state {CommcareHttpState}
  * @returns {Operation}
@@ -85,18 +82,18 @@ */
 /**
- * Submit forms to CommCare. Accepts an array of JSON
+ * Submit forms to CommCare. Use this to send forms directly to Commcare REST API. Accepts an array of JSON
  * objects, converts them into XML, and submits to CommCare as an x-form.
  * @public
  * @function
- * @example <caption>Submit a form to CommCare</caption>
- *  submit(
- *    fields(
- *      field("@", (state) => ({
- *          "xmlns": `http://openrosa.org/formdesigner/${state.formId}`
- *      }),
- *      field("question1", (state) => state.data.answer1),
- *      field("question2", (state) => state.data.answer2),
- *    )
+ * @example <caption>Submit a form resource.</caption>
+ * submit(
+ *  fields(
+ *    field('@', state => ({
+ *      xmlns: `http://openrosa.org/formdesigner/${state.formId}`,
+ *    })),
+ *    field('question1', state => state.data.answer1),
+ *    field('question2', state => state.data.answer2)
  *  )
+ * );
  * @param {Object} data - The form as a JSON object
- * @state data - the response from the CommCare Server
+ * @state {CommcareHttpState}
  * @returns {Operation}
@@ -109,5 +106,5 @@ */
  * @public
- * @example <caption>Fetch 10 records from a report and post them to example.com</caption>
+ * @example <caption>Get 10 records from a report and post them to example.com. Equivalent to `<baseUrl>/configurablereportdata/abcde?limit=10`</caption>
  * fetchReportData(
- *   "9aab0eeb88555a7b4568676883e7379a",
+ *   "abcde",
  *   { limit: 10 },
@@ -120,2 +117,3 @@ *   "https://www.example.com/api/"
  * @param {String} postUrl - URL to which the response object will be posted.
+ * @state {CommcareHttpState}
  * @returns {Operation}
@@ -125,4 +123,4 @@ */
 /**
- * Make a general HTTP request against the Commcare server.
- * @example <caption>Make a GET request to get cases</caption>
+ * Make a general HTTP request against the Commcare server. Use this to make any request to Commcare REST API.
+ * @example <caption>Get a resource. Equivalent to `<baseUrl>/a/asri/api/v0.5/case`</caption>
  * request("GET", "/a/asri/api/v0.5/case");
@@ -144,35 +142,32 @@ * @function
  * @function
- * @example <caption>Upload a single row of data for case-data</caption>
+ * @example <caption>Upload a single row of a case-data resource</caption>
+ * bulk('case-data', [{ name: 'Mamadou', phone: '000000' }], {
+ *   case_type: 'student',
+ *   search_field: 'external_id',
+ *   create_new_cases: 'on',
+ * });
+ * @example <caption>Upload a single row of a lookup-table resource</caption>
  * bulk(
- * 'case-data',
- *    [
- *      {name: 'Mamadou', phone: '000000'},
- *    ],
- *    {
- *      case_type: 'student',
- *      search_field: 'external_id',
- *      create_new_cases: 'on',
- *    }
- * )
- * @example <caption>Upload a single row of data for a lookup-table</caption>
- * bulk(
- *     'lookup-table',
- *  {
- *    types: [{
- *
- *   'DELETE(Y/N)':'N',
- *   table_id: 'fruit',
- *   'is_global?':'yes',
- *   'field 1': 'type',
- *   'field 2': 'name',
- *      }],
- *      fruit: [{
- *       UID: '',
- *        'DELETE(Y/N)':'N',
- *       'field:type': 'citrus',
- *        'field:name': 'Orange',
- *     }],
+ *   'lookup-table',
+ *   {
+ *     types: [
+ *       {
+ *         'DELETE(Y/N)': 'N',
+ *         table_id: 'fruit',
+ *         'is_global?': 'yes',
+ *         'field 1': 'type',
+ *         'field 2': 'name',
+ *       },
+ *     ],
+ *     fruit: [
+ *       {
+ *         UID: '',
+ *         'DELETE(Y/N)': 'N',
+ *         'field:type': 'citrus',
+ *         'field:name': 'Orange',
+ *       },
+ *     ],
  *   },
- * {replace: false}
- * )
+ *   { replace: false }
+ * );
  * @param {('case-data'|'lookup-table')} type -  The type of data being processed.
@@ -183,3 +178,3 @@ * @param {(Object|Object[])} data - An object or an array of objects to upload.
  * @param {Object} params - Input parameters, see {@link https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143946459/Bulk+Upload+Case+Data CommCare docs} for case-data and {@link https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143946023/Bulk+upload+Lookup+Tables Commcare Docs} for lookup-table.
- * @state data - the response from the CommCare Server
+ * @state {CommcareHttpState}
  * @returns {Operation}
@@ -186,0 +181,0 @@ */

No alert changes

Improved metrics

Total package byte prevSize

118659

increased by0.82%

Worsened metrics

Lines of code

2208

decreased by-0.18%

No dependency changes