@openfn/language-kobotoolbox 2.4.3 → 3.0.0

package/ast.json

@@ -2,12 +2,9 @@
   "operations": [
     {
       "name": "getForms",
-      "params": [
-        "params",
-        "callback"
-      ],
+      "params": [],
       "docs": {
-        "description": "Make a request to get the list of forms",
+        "description": "Make a request to fetch all survey forms accessible to the authorized user. Calls `/api/v2/assets/?asset_type=survey`.",
         "tags": [
           {
             "title": "public",
@@ -16,7 +13,7 @@
           },
           {
             "title": "example",
-            "description": "getForms({}, state => {\n   console.log(state.data);\n   return state;\n});"
+            "description": "getForms();"
           },
           {
             "title": "function",
@@ -24,22 +21,8 @@
             "name": null
           },
           {
-            "title": "param",
-            "description": "Query, Headers and Authentication parameters",
-            "type": {
-              "type": "NameExpression",
-              "name": "object"
-            },
-            "name": "params"
-          },
-          {
-            "title": "param",
-            "description": "(Optional) Callback function to execute after fetching form list",
-            "type": {
-              "type": "NameExpression",
-              "name": "function"
-            },
-            "name": "callback"
+            "title": "state",
+            "description": "data - an array of form objects"
           },
           {
             "title": "returns",
@@ -56,15 +39,21 @@
     {
       "name": "getSubmissions",
       "params": [
-        "params",
-        "callback"
+        "formId",
+        "options"
       ],
       "docs": {
-        "description": "Get submissions for a specific form",
+        "description": "Get submissions for a specific form. Calls `/api/v2/assets/<formId>/data/`.",
         "tags": [
           {
             "title": "example",
-            "description": "getSubmissions({formId: 'aXecHjmbATuF6iGFmvBLBX'}, state => {\n  console.log(state.data);\n  return state;\n});"
+            "description": "getSubmissions('aXecHjmbATuF6iGFmvBLBX');",
+            "caption": "Get all submissions for a specific form"
+          },
+          {
+            "title": "example",
+            "description": "getSubmissions('aXecHjmbATuF6iGFmvBLBX', { query: { _submission_time:{ $gte: \"2022-06-12T21:54:20\" } } });",
+            "caption": "Get form submissions with a query"
           },
           {
             "title": "function",
@@ -78,21 +67,29 @@
           },
           {
             "title": "param",
-            "description": "Form Id and data to make the fetch or filter",
+            "description": "Form Id to get the specific submissions",
             "type": {
               "type": "NameExpression",
-              "name": "object"
+              "name": "string"
             },
-            "name": "params"
+            "name": "formId"
           },
           {
             "title": "param",
-            "description": "(Optional) Callback function to execute after fetching form submissions",
+            "description": "Optional query params for the request",
             "type": {
-              "type": "NameExpression",
-              "name": "function"
+              "type": "OptionalType",
+              "expression": {
+                "type": "NameExpression",
+                "name": "object"
+              }
             },
-            "name": "callback"
+            "name": "options",
+            "default": "{}"
+          },
+          {
+            "title": "state",
+            "description": "data - an array of submission objects"
           },
           {
             "title": "returns",
@@ -109,15 +106,14 @@
     {
       "name": "getDeploymentInfo",
       "params": [
-        "params",
-        "callback"
+        "formId"
       ],
       "docs": {
-        "description": "Get deployment information for a specific form",
+        "description": "Get deployment information for a specific form. Calls `/api/v2/assets/<id>/deployment/`.",
         "tags": [
           {
             "title": "example",
-            "description": "getDeploymentInfo({formId: 'aXecHjmbATuF6iGFmvBLBX'}, state => {\n  console.log(state.data);\n  return state;\n});"
+            "description": "getDeploymentInfo('aXecHjmbATuF6iGFmvBLBX');"
           },
           {
             "title": "function",
@@ -131,21 +127,16 @@
           },
           {
             "title": "param",
-            "description": "Form Id and data to make the fetch or filter",
+            "description": "Form Id to get the deployment information",
             "type": {
               "type": "NameExpression",
-              "name": "object"
+              "name": "string"
             },
-            "name": "params"
+            "name": "formId"
           },
           {
-            "title": "param",
-            "description": "(Optional) Callback function to execute after fetching form deployment information",
-            "type": {
-              "type": "NameExpression",
-              "name": "function"
-            },
-            "name": "callback"
+            "title": "state",
+            "description": "data - an object containing deployment information"
           },
           {
             "title": "returns",
@@ -437,7 +428,7 @@
         "operation"
       ],
       "docs": {
-        "description": "Scopes an array of data based on a JSONPath.\nUseful when the source data has `n` items you would like to map to\nan operation.\nThe operation will receive a slice of the data based of each item\nof the JSONPath provided.\n\nIt also ensures the results of an operation make their way back into\nthe state's references.",
+        "description": "Iterates over an array of items and invokes an operation upon each one, where the state\nobject is _scoped_ so that state.data is the item under iteration.\nThe rest of the state object is untouched and can be referenced as usual.\nYou can pass an array directly, or use lazy state or a JSONPath string to\nreference a slice of state.",
         "tags": [
           {
             "title": "public",
@@ -451,7 +442,18 @@
           },
           {
             "title": "example",
-            "description": "each(\"$.[*]\",\n  create(\"SObject\",\n    field(\"FirstName\", sourceValue(\"$.firstName\"))\n  )\n)"
+            "description": "each(\n  $.data,\n  // Inside the callback operation, `$.data` is scoped to the item under iteration\n  insert(\"patient\", {\n    patient_name: $.data.properties.case_name,\n    patient_id: $.data.case_id,\n  })\n);",
+            "caption": "Using lazy state ($) to iterate over items in state.data and pass each into an \"insert\" operation"
+          },
+          {
+            "title": "example",
+            "description": "each(\n  $.data,\n  insert(\"patient\", (state) => ({\n    patient_id: state.data.case_id,\n    ...state.data\n  }))\n);",
+            "caption": "Iterate over items in state.data and pass each one into an \"insert\" operation"
+          },
+          {
+            "title": "example",
+            "description": "each(\n  \"$.data[*]\",\n  insert(\"patient\", (state) => ({\n    patient_name: state.data.properties.case_name,\n    patient_id: state.data.case_id,\n  }))\n);",
+            "caption": "Using JSON path to iterate over items in state.data and pass each one into an \"insert\" operation"
           },
           {
             "title": "param",

package/configuration-schema.json

@@ -1,8 +1,8 @@
 {
     "$schema": "http://json-schema.org/draft-07/schema#",
     "properties": {
-        "baseURL": {
-            "title": "Base URL",
+        "baseUrl": {
+            "title": "Base Url",
             "type": "string",
             "default": "https://kf.kobotoolbox.org",
             "description": "Kobotoolbox URL",
@@ -46,7 +46,7 @@
     "additionalProperties": true,
     "required": [
         "username",
-        "baseURL",
+        "baseUrl",
         "password",
         "apiVersion"
     ]

package/dist/index.cjs

@@ -19,124 +19,244 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.js
 var src_exports = {};
 __export(src_exports, {
-  alterState: () => import_language_common2.alterState,
-  cursor: () => import_language_common2.cursor,
-  dataPath: () => import_language_common2.dataPath,
-  dataValue: () => import_language_common2.dataValue,
+  alterState: () => import_language_common3.alterState,
+  cursor: () => import_language_common3.cursor,
+  dataPath: () => import_language_common3.dataPath,
+  dataValue: () => import_language_common3.dataValue,
   default: () => src_default,
-  each: () => import_language_common2.each,
+  each: () => import_language_common3.each,
   execute: () => execute,
-  field: () => import_language_common2.field,
-  fields: () => import_language_common2.fields,
-  fn: () => import_language_common2.fn,
-  fnIf: () => import_language_common2.fnIf,
+  field: () => import_language_common3.field,
+  fields: () => import_language_common3.fields,
+  fn: () => import_language_common3.fn,
+  fnIf: () => import_language_common3.fnIf,
   getDeploymentInfo: () => getDeploymentInfo,
   getForms: () => getForms,
   getSubmissions: () => getSubmissions,
-  group: () => import_language_common2.group,
-  http: () => import_language_common2.http,
-  lastReferenceValue: () => import_language_common2.lastReferenceValue,
-  merge: () => import_language_common2.merge,
-  sourceValue: () => import_language_common2.sourceValue
+  group: () => import_language_common3.group,
+  http: () => http_exports,
+  lastReferenceValue: () => import_language_common3.lastReferenceValue,
+  merge: () => import_language_common3.merge,
+  sourceValue: () => import_language_common3.sourceValue
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/Adaptor.js
 var Adaptor_exports = {};
 __export(Adaptor_exports, {
-  alterState: () => import_language_common2.alterState,
-  cursor: () => import_language_common2.cursor,
-  dataPath: () => import_language_common2.dataPath,
-  dataValue: () => import_language_common2.dataValue,
-  each: () => import_language_common2.each,
+  alterState: () => import_language_common3.alterState,
+  cursor: () => import_language_common3.cursor,
+  dataPath: () => import_language_common3.dataPath,
+  dataValue: () => import_language_common3.dataValue,
+  each: () => import_language_common3.each,
   execute: () => execute,
-  field: () => import_language_common2.field,
-  fields: () => import_language_common2.fields,
-  fn: () => import_language_common2.fn,
-  fnIf: () => import_language_common2.fnIf,
+  field: () => import_language_common3.field,
+  fields: () => import_language_common3.fields,
+  fn: () => import_language_common3.fn,
+  fnIf: () => import_language_common3.fnIf,
   getDeploymentInfo: () => getDeploymentInfo,
   getForms: () => getForms,
   getSubmissions: () => getSubmissions,
-  group: () => import_language_common2.group,
-  http: () => import_language_common2.http,
-  lastReferenceValue: () => import_language_common2.lastReferenceValue,
-  merge: () => import_language_common2.merge,
-  sourceValue: () => import_language_common2.sourceValue
+  group: () => import_language_common3.group,
+  http: () => import_language_common3.http,
+  lastReferenceValue: () => import_language_common3.lastReferenceValue,
+  merge: () => import_language_common3.merge,
+  sourceValue: () => import_language_common3.sourceValue
 });
-var import_language_common = require("@openfn/language-common");
 var import_language_common2 = require("@openfn/language-common");
+var import_util2 = require("@openfn/language-common/util");
+
+// src/Utils.js
+var import_language_common = require("@openfn/language-common");
+var import_util = require("@openfn/language-common/util");
+var prepareNextState = (state, response) => {
+  const { body, ...responseWithoutBody } = response;
+  return {
+    ...(0, import_language_common.composeNextState)(state, response.body),
+    response: responseWithoutBody
+  };
+};
+async function request(state, method, path, opts) {
+  const { baseURL, apiVersion, username, password } = state.configuration;
+  let baseUrl;
+  if (!state.configuration.baseUrl && baseURL) {
+    baseUrl = baseURL;
+    console.warn(
+      "No baseUrl found in state.configuration. baseURL will be used instead, but this will be deprecated in the future."
+    );
+  } else {
+    baseUrl = state.configuration.baseUrl;
+  }
+  const {
+    data = {},
+    query = {},
+    headers = {},
+    parseAs = "json",
+    paginate = false
+  } = opts;
+  const authHeaders = (0, import_util.makeBasicAuthHeader)(username, password);
+  let start, limit;
+  const options = {
+    body: data,
+    headers: {
+      "Content-Type": "application/json",
+      ...authHeaders,
+      ...headers
+    },
+    query: {
+      format: "json",
+      ...query
+    },
+    parseAs,
+    baseUrl: `${baseUrl}/api/${apiVersion}`
+  };
+  if (paginate) {
+    const results = [];
+    do {
+      const response = await (0, import_util.request)(method, path, options).then(
+        import_util.logResponse
+      );
+      results.push(...response.body.results);
+      if (response.body.next) {
+        const nextUrl = new URL(response.body.next);
+        const startDigit = nextUrl.searchParams.get("start") !== null ? nextUrl.searchParams.get("start") : 0;
+        start = Number(startDigit);
+        limit = nextUrl.searchParams.get("limit");
+        options.query = {
+          ...options.query,
+          start,
+          limit
+        };
+      } else {
+        break;
+      }
+    } while (true);
+    return { results };
+  } else {
+    return (0, import_util.request)(method, path, options).then(import_util.logResponse);
+  }
+}
+
+// src/Adaptor.js
+var import_language_common3 = require("@openfn/language-common");
 function execute(...operations) {
   const initialState = {
     references: [],
     data: null
   };
   return (state) => {
-    return (0, import_language_common.execute)(...operations)({
+    return (0, import_language_common2.execute)(...operations)({
       ...initialState,
       ...state
     });
   };
 }
-function getForms(params, callback) {
-  return (state) => {
-    const resolvedParams = (0, import_language_common.expandReferences)(params)(state);
-    const { baseURL, apiVersion, username, password } = state.configuration;
-    const url = `${baseURL}/api/${apiVersion}/assets/?format=json`;
-    const auth = { username, password };
-    const config = {
-      url,
-      params: resolvedParams,
-      auth
-    };
-    return import_language_common.http.get(config)(state).then((response) => {
-      console.log("\u2713", response.data.count, "forms fetched.");
-      const nextState = (0, import_language_common.composeNextState)(state, response.data);
-      if (callback)
-        return callback(nextState);
-      return nextState;
+function getForms() {
+  return async (state) => {
+    const url = `/assets/?asset_type=survey`;
+    const response = await request(state, "GET", url, {});
+    console.log("\u2713", response.body.results.length, "forms fetched.");
+    return prepareNextState(state, response);
+  };
+}
+function getSubmissions(formId, options = {}) {
+  return async (state) => {
+    const [resolvedFormId, resolvedOptions] = (0, import_util2.expandReferences)(
+      state,
+      formId,
+      options
+    );
+    const url = `/assets/${resolvedFormId}/data/`;
+    const query = {};
+    if (resolvedOptions.query) {
+      if (typeof resolvedOptions.query == "string") {
+        query.query = resolvedOptions.query;
+      } else {
+        query.query = JSON.stringify(resolvedOptions.query);
+      }
+    }
+    const response = await request(state, "GET", url, {
+      paginate: true,
+      query
     });
+    console.log("\u2713", response.results.length, "submissions fetched.");
+    return prepareNextState(state, response);
   };
 }
-function getSubmissions(params, callback) {
-  return (state) => {
-    const resolvedParams = (0, import_language_common.expandReferences)(params)(state);
-    const { baseURL, apiVersion, username, password } = state.configuration;
-    const { formId } = resolvedParams;
-    const url = `${baseURL}/api/${apiVersion}/assets/${formId}/data/?format=json`;
-    const auth = { username, password };
-    const config = {
-      url,
-      params: resolvedParams.query,
-      auth
+function getDeploymentInfo(formId) {
+  return async (state) => {
+    const [resolvedFormId] = (0, import_util2.expandReferences)(state, formId);
+    const url = `/assets/${resolvedFormId}/deployment/`;
+    const response = await request(state, "GET", url, {});
+    console.log("\u2713", "deployment information fetched.");
+    return prepareNextState(state, response);
+  };
+}
+
+// src/http.js
+var http_exports = {};
+__export(http_exports, {
+  get: () => get,
+  post: () => post,
+  put: () => put
+});
+var import_util3 = require("@openfn/language-common/util");
+function get(path, options = {}) {
+  return async (state) => {
+    const [resolvedPath, resolvedOptions] = (0, import_util3.expandReferences)(
+      state,
+      path,
+      options
+    );
+    const response = await request(
+      state,
+      "GET",
+      resolvedPath,
+      resolvedOptions
+    );
+    return prepareNextState(state, response);
+  };
+}
+function post(path, data, options = {}) {
+  return async (state) => {
+    const [resolvedPath, resolvedData, resolvedOptions] = (0, import_util3.expandReferences)(
+      state,
+      path,
+      data,
+      options
+    );
+    const optionsObject = {
+      data: resolvedData,
+      ...resolvedOptions
     };
-    return import_language_common.http.get(config)(state).then((response) => {
-      console.log("\u2713", response.data.count, "submissions fetched.");
-      const nextState = (0, import_language_common.composeNextState)(state, response.data);
-      if (callback)
-        return callback(nextState);
-      return nextState;
-    });
+    const response = await request(
+      state,
+      "POST",
+      resolvedPath,
+      optionsObject
+    );
+    return prepareNextState(state, response);
   };
 }
-function getDeploymentInfo(params, callback) {
-  return (state) => {
-    const resolvedParams = (0, import_language_common.expandReferences)(params)(state);
-    const { baseURL, apiVersion, username, password } = state.configuration;
-    const { formId } = resolvedParams;
-    const url = `${baseURL}/api/${apiVersion}/assets/${formId}/deployment/?format=json`;
-    const auth = { username, password };
-    const config = {
-      url,
-      params: resolvedParams.query,
-      auth
+function put(path, data, options = {}) {
+  return async (state) => {
+    const [resolvedPath, resolvedData, resolvedOptions] = (0, import_util3.expandReferences)(
+      state,
+      path,
+      data,
+      options
+    );
+    const optionsObject = {
+      data: resolvedData,
+      ...resolvedOptions
     };
-    return import_language_common.http.get(config)(state).then((response) => {
-      console.log("\u2713", "deployment information fetched.");
-      const nextState = (0, import_language_common.composeNextState)(state, response.data);
-      if (callback)
-        return callback(nextState);
-      return nextState;
-    });
+    const response = await request(
+      state,
+      "PUT",
+      resolvedPath,
+      optionsObject
+    );
+    return prepareNextState(state, response);
   };
 }
 

package/dist/index.js

@@ -21,17 +21,90 @@ __export(Adaptor_exports, {
   getForms: () => getForms,
   getSubmissions: () => getSubmissions,
   group: () => group,
-  http: () => http2,
+  http: () => http,
   lastReferenceValue: () => lastReferenceValue,
   merge: () => merge,
   sourceValue: () => sourceValue
 });
+import { execute as commonExecute } from "@openfn/language-common";
+import { expandReferences } from "@openfn/language-common/util";
+
+// src/Utils.js
+import { composeNextState } from "@openfn/language-common";
 import {
-  execute as commonExecute,
-  composeNextState,
-  expandReferences,
-  http
-} from "@openfn/language-common";
+  request as commonRequest,
+  makeBasicAuthHeader,
+  logResponse
+} from "@openfn/language-common/util";
+var prepareNextState = (state, response) => {
+  const { body, ...responseWithoutBody } = response;
+  return {
+    ...composeNextState(state, response.body),
+    response: responseWithoutBody
+  };
+};
+async function request(state, method, path, opts) {
+  const { baseURL, apiVersion, username, password } = state.configuration;
+  let baseUrl;
+  if (!state.configuration.baseUrl && baseURL) {
+    baseUrl = baseURL;
+    console.warn(
+      "No baseUrl found in state.configuration. baseURL will be used instead, but this will be deprecated in the future."
+    );
+  } else {
+    baseUrl = state.configuration.baseUrl;
+  }
+  const {
+    data = {},
+    query = {},
+    headers = {},
+    parseAs = "json",
+    paginate = false
+  } = opts;
+  const authHeaders = makeBasicAuthHeader(username, password);
+  let start, limit;
+  const options = {
+    body: data,
+    headers: {
+      "Content-Type": "application/json",
+      ...authHeaders,
+      ...headers
+    },
+    query: {
+      format: "json",
+      ...query
+    },
+    parseAs,
+    baseUrl: `${baseUrl}/api/${apiVersion}`
+  };
+  if (paginate) {
+    const results = [];
+    do {
+      const response = await commonRequest(method, path, options).then(
+        logResponse
+      );
+      results.push(...response.body.results);
+      if (response.body.next) {
+        const nextUrl = new URL(response.body.next);
+        const startDigit = nextUrl.searchParams.get("start") !== null ? nextUrl.searchParams.get("start") : 0;
+        start = Number(startDigit);
+        limit = nextUrl.searchParams.get("limit");
+        options.query = {
+          ...options.query,
+          start,
+          limit
+        };
+      } else {
+        break;
+      }
+    } while (true);
+    return { results };
+  } else {
+    return commonRequest(method, path, options).then(logResponse);
+  }
+}
+
+// src/Adaptor.js
 import {
   alterState,
   cursor,
@@ -42,7 +115,7 @@ import {
   fields,
   fn,
   fnIf,
-  http as http2,
+  http,
   group,
   lastReferenceValue,
   merge,
@@ -60,66 +133,112 @@ function execute(...operations) {
     });
   };
 }
-function getForms(params, callback) {
-  return (state) => {
-    const resolvedParams = expandReferences(params)(state);
-    const { baseURL, apiVersion, username, password } = state.configuration;
-    const url = `${baseURL}/api/${apiVersion}/assets/?format=json`;
-    const auth = { username, password };
-    const config = {
-      url,
-      params: resolvedParams,
-      auth
-    };
-    return http.get(config)(state).then((response) => {
-      console.log("\u2713", response.data.count, "forms fetched.");
-      const nextState = composeNextState(state, response.data);
-      if (callback)
-        return callback(nextState);
-      return nextState;
+function getForms() {
+  return async (state) => {
+    const url = `/assets/?asset_type=survey`;
+    const response = await request(state, "GET", url, {});
+    console.log("\u2713", response.body.results.length, "forms fetched.");
+    return prepareNextState(state, response);
+  };
+}
+function getSubmissions(formId, options = {}) {
+  return async (state) => {
+    const [resolvedFormId, resolvedOptions] = expandReferences(
+      state,
+      formId,
+      options
+    );
+    const url = `/assets/${resolvedFormId}/data/`;
+    const query = {};
+    if (resolvedOptions.query) {
+      if (typeof resolvedOptions.query == "string") {
+        query.query = resolvedOptions.query;
+      } else {
+        query.query = JSON.stringify(resolvedOptions.query);
+      }
+    }
+    const response = await request(state, "GET", url, {
+      paginate: true,
+      query
     });
+    console.log("\u2713", response.results.length, "submissions fetched.");
+    return prepareNextState(state, response);
   };
 }
-function getSubmissions(params, callback) {
-  return (state) => {
-    const resolvedParams = expandReferences(params)(state);
-    const { baseURL, apiVersion, username, password } = state.configuration;
-    const { formId } = resolvedParams;
-    const url = `${baseURL}/api/${apiVersion}/assets/${formId}/data/?format=json`;
-    const auth = { username, password };
-    const config = {
-      url,
-      params: resolvedParams.query,
-      auth
+function getDeploymentInfo(formId) {
+  return async (state) => {
+    const [resolvedFormId] = expandReferences(state, formId);
+    const url = `/assets/${resolvedFormId}/deployment/`;
+    const response = await request(state, "GET", url, {});
+    console.log("\u2713", "deployment information fetched.");
+    return prepareNextState(state, response);
+  };
+}
+
+// src/http.js
+var http_exports = {};
+__export(http_exports, {
+  get: () => get,
+  post: () => post,
+  put: () => put
+});
+import { expandReferences as expandReferences2 } from "@openfn/language-common/util";
+function get(path, options = {}) {
+  return async (state) => {
+    const [resolvedPath, resolvedOptions] = expandReferences2(
+      state,
+      path,
+      options
+    );
+    const response = await request(
+      state,
+      "GET",
+      resolvedPath,
+      resolvedOptions
+    );
+    return prepareNextState(state, response);
+  };
+}
+function post(path, data, options = {}) {
+  return async (state) => {
+    const [resolvedPath, resolvedData, resolvedOptions] = expandReferences2(
+      state,
+      path,
+      data,
+      options
+    );
+    const optionsObject = {
+      data: resolvedData,
+      ...resolvedOptions
     };
-    return http.get(config)(state).then((response) => {
-      console.log("\u2713", response.data.count, "submissions fetched.");
-      const nextState = composeNextState(state, response.data);
-      if (callback)
-        return callback(nextState);
-      return nextState;
-    });
+    const response = await request(
+      state,
+      "POST",
+      resolvedPath,
+      optionsObject
+    );
+    return prepareNextState(state, response);
   };
 }
-function getDeploymentInfo(params, callback) {
-  return (state) => {
-    const resolvedParams = expandReferences(params)(state);
-    const { baseURL, apiVersion, username, password } = state.configuration;
-    const { formId } = resolvedParams;
-    const url = `${baseURL}/api/${apiVersion}/assets/${formId}/deployment/?format=json`;
-    const auth = { username, password };
-    const config = {
-      url,
-      params: resolvedParams.query,
-      auth
+function put(path, data, options = {}) {
+  return async (state) => {
+    const [resolvedPath, resolvedData, resolvedOptions] = expandReferences2(
+      state,
+      path,
+      data,
+      options
+    );
+    const optionsObject = {
+      data: resolvedData,
+      ...resolvedOptions
     };
-    return http.get(config)(state).then((response) => {
-      console.log("\u2713", "deployment information fetched.");
-      const nextState = composeNextState(state, response.data);
-      if (callback)
-        return callback(nextState);
-      return nextState;
-    });
+    const response = await request(
+      state,
+      "PUT",
+      resolvedPath,
+      optionsObject
+    );
+    return prepareNextState(state, response);
   };
 }
 
@@ -141,7 +260,7 @@ export {
   getForms,
   getSubmissions,
   group,
-  http2 as http,
+  http_exports as http,
   lastReferenceValue,
   merge,
   sourceValue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfn/language-kobotoolbox",
-  "version": "2.4.3",
+  "version": "3.0.0",
   "description": "A Kobo Toolbox Language Pack for OpenFn",
   "homepage": "https://docs.openfn.org",
   "repository": {
@@ -17,15 +17,13 @@
     "configuration-schema.json"
   ],
   "dependencies": {
-    "@openfn/language-common": "1.15.2"
+    "@openfn/language-common": "2.3.0"
   },
   "devDependencies": {
-    "@openfn/simple-ast": "0.4.1",
     "assertion-error": "^1.0.1",
     "chai": "^3.4.0",
     "deep-eql": "^0.1.3",
     "esno": "^0.16.3",
-    "nock": "^12.0.3",
     "rimraf": "^3.0.2"
   },
   "type": "module",

package/types/Adaptor.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Options object
+ * @typedef {Object} RequestOptions
+ * @property {object} query - An object of query parameters to be encoded into the URL
+ * @property {object} headers - An object of all request headers
+ * @property {string} [parseAs='json'] - The response format to parse (e.g., 'json', 'text', or 'stream')
+ */
 /**
  * Execute a sequence of operations.
  * Wraps `language-common/execute`, and prepends initial state for http.
@@ -12,45 +19,55 @@
  */
 export function execute(...operations: Operations): Operation;
 /**
- * Make a request to get the list of forms
+ * Make a request to fetch all survey forms accessible to the authorized user. Calls `/api/v2/assets/?asset_type=survey`.
  * @public
  * @example
- * getForms({}, state => {
- *    console.log(state.data);
- *    return state;
- * });
+ * getForms();
  * @function
- * @param {object} params - Query, Headers and Authentication parameters
- * @param {function} callback - (Optional) Callback function to execute after fetching form list
+ * @state data - an array of form objects
  * @returns {Operation}
  */
-export function getForms(params: object, callback: Function): Operation;
+export function getForms(): Operation;
 /**
- * Get submissions for a specific form
- * @example
- * getSubmissions({formId: 'aXecHjmbATuF6iGFmvBLBX'}, state => {
- *   console.log(state.data);
- *   return state;
- * });
+ * Get submissions for a specific form. Calls `/api/v2/assets/<formId>/data/`.
+ * @example <caption>Get all submissions for a specific form</caption>
+ * getSubmissions('aXecHjmbATuF6iGFmvBLBX');
+ * @example <caption>Get form submissions with a query</caption>
+ * getSubmissions('aXecHjmbATuF6iGFmvBLBX', { query: { _submission_time:{ $gte: "2022-06-12T21:54:20" } } });
  * @function
  * @public
- * @param {object} params - Form Id and data to make the fetch or filter
- * @param {function} callback - (Optional) Callback function to execute after fetching form submissions
+ * @param {string} formId - Form Id to get the specific submissions
+ * @param {object} [options={}] - Optional query params for the request
+ * @state data - an array of submission objects
  * @returns {Operation}
  */
-export function getSubmissions(params: object, callback: Function): Operation;
+export function getSubmissions(formId: string, options?: object): Operation;
 /**
- * Get deployment information for a specific form
+ * Get deployment information for a specific form. Calls `/api/v2/assets/<id>/deployment/`.
  * @example
- * getDeploymentInfo({formId: 'aXecHjmbATuF6iGFmvBLBX'}, state => {
- *   console.log(state.data);
- *   return state;
- * });
+ * getDeploymentInfo('aXecHjmbATuF6iGFmvBLBX');
  * @function
  * @public
- * @param {object} params - Form Id and data to make the fetch or filter
- * @param {function} callback - (Optional) Callback function to execute after fetching form deployment information
+ * @param {string} formId - Form Id to get the deployment information
+ * @state data - an object containing deployment information
  * @returns {Operation}
  */
-export function getDeploymentInfo(params: object, callback: Function): Operation;
+export function getDeploymentInfo(formId: string): Operation;
+/**
+ * Options object
+ */
+export type RequestOptions = {
+    /**
+     * - An object of query parameters to be encoded into the URL
+     */
+    query: object;
+    /**
+     * - An object of all request headers
+     */
+    headers: object;
+    /**
+     * - The response format to parse (e.g., 'json', 'text', or 'stream')
+     */
+    parseAs?: string;
+};
 export { alterState, cursor, dataPath, dataValue, each, field, fields, fn, fnIf, http, group, lastReferenceValue, merge, sourceValue } from "@openfn/language-common";

package/types/Utils.d.ts

@@ -0,0 +1,2 @@
+export function request(state: any, method: any, path: any, opts: any): Promise<any>;
+export function prepareNextState(state: any, response: any): any;

package/types/http.d.ts

@@ -0,0 +1,100 @@
+/**
+ * State object
+ * @typedef {Object} KoboToolboxHttpState
+ * @property data - The response body (as JSON)
+ * @property response - The HTTP response from the KoboToolbox server (excluding the body). Responses will be returned in JSON format
+ * @property references - An array of all previous data objects used in the Job
+ */
+/**
+ * Options object
+ * @typedef {Object} RequestOptions
+ * @property {object} query - An object of query parameters to be encoded into the URL
+ * @property {object} headers - An object of all request headers
+ * @property {string} [parseAs='json'] - The response format to parse (e.g., 'json', 'text', or 'stream')
+ */
+/**
+ * Make a GET request to any KoboToolbox endpoint.
+ * @public
+ * @function
+ * @example <caption>GET assets resource</caption>
+ * http.get(
+ *  "/assets/",
+ *  )
+ * @param {string} path - path to resource
+ * @param {RequestOptions} [options={}] - An object containing query params and headers for the request
+ * @state {KoboToolboxHttpState}
+ * @returns {operation}
+ */
+export function get(path: string, options?: RequestOptions): operation;
+/**
+ * Make a POST request to a KoboToolbox endpoint
+ * @public
+ * @function
+ * @example <caption>Create an asset resource</caption>
+ * http.post(
+ *  '/assets/',
+ *  {
+ *   name: 'Feedback Survey Test',
+ *   asset_type: 'survey',
+ *  },
+ *  );
+ * @param {string} path - path to resource
+ * @param {any} data - the body data in JSON format
+ * @param {RequestOptions} [options={}] - An object containing query params and headers for the request
+ * @state {KoboToolboxHttpState}
+ * @returns {operation}
+ */
+export function post(path: string, data: any, options?: RequestOptions): operation;
+/**
+ * Make a PUT request to a KoboToolbox endpoint
+ * @public
+ * @function
+ * @example <caption>Update an asset resource</caption>
+ * http.put(
+ *  'assets/a4jAWzoa8SZWzZGhx84sB5/deployment/',
+ *  {
+ *   name: 'Feedback Survey Test',
+ *   asset_type: 'survey',
+ *  },
+ *  );
+ * @param {string} path - path to resource
+ * @param {any} data - the body data in JSON format
+ * @param {RequestOptions} [options={}] - An object containing query params and headers for the request
+ * @state {KoboToolboxHttpState}
+ * @returns {operation}
+ */
+export function put(path: string, data: any, options?: RequestOptions): operation;
+/**
+ * State object
+ */
+export type KoboToolboxHttpState = {
+    /**
+     * - The response body (as JSON)
+     */
+    data: any;
+    /**
+     * - The HTTP response from the KoboToolbox server (excluding the body). Responses will be returned in JSON format
+     */
+    response: any;
+    /**
+     * - An array of all previous data objects used in the Job
+     */
+    references: any;
+};
+/**
+ * Options object
+ */
+export type RequestOptions = {
+    /**
+     * - An object of query parameters to be encoded into the URL
+     */
+    query: object;
+    /**
+     * - An object of all request headers
+     */
+    headers: object;
+    /**
+     * - The response format to parse (e.g., 'json', 'text', or 'stream')
+     */
+    parseAs?: string;
+};

package/types/index.d.ts

@@ -1,3 +1,4 @@
 export default Adaptor;
 export * from "./Adaptor";
+export * as http from "./http";
 import * as Adaptor from "./Adaptor";