New template using HTTP utils

README.md

@@ -133,23 +133,22 @@ export function yourFunctionName(arguments) {
 ```
 
 The logic is where you will prepare your API request. Build the URL, passing in
-any arguments if needed. Next, return the fetch request, making sure you set the
-Authorization, passing in any secrets from `state.configuration`.
+any arguments if needed. Then, using a helper function in common, return the
+fetch request, making sure you set the Authorization, passing in any secrets
+from `state.configuration`.
 
 ```js
+import { get } from '@openfn/language-common/util';
+
 export function getTodaysWeather(latitude = 25.52, longitude = 13.41) {
   return state => {
     const url = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current_weather=true&hourly=temperature_2m,relativehumidity_2m,windspeed_10m`;
 
-    return (
-      fetch(url, {
-        headers: {
-          Authorization: `${state.configuration.username}:${state.configuration.password}`,
-        },
-      })
-        .then(response => response.json())
-        .then(data => ({ ...state, data }));
-    );
+    const headers = {
+      Authorization: `${state.configuration.username}:${state.configuration.password}`,
+    };
+    const result = await get(url, { headers });
+    return { ...state, data: result.body };
   };
 }
 ```
@@ -185,7 +184,7 @@ export function getTodaysWeather(latitude = 25.52, longitude = 13.41) {
 
 Import your newly defined function
 
-```
+```js
 import { functionName } from '../src/Adaptor.js';
 ```
 
@@ -194,7 +193,7 @@ to see how state should be passed to it).
 
 Make an assertion to check the result.
 
-```
+```js
 it('should xyz', async () => {
 const state = {
   configuration: {},

packages/common/src/util/http.js

@@ -4,6 +4,17 @@ import { Readable } from 'node:stream';
 
 const clients = new Map();
 
+export const makeBasicAuthHeader = (username, password) => {
+  const buff = Buffer.from(`${username}:${password}`);
+  const credentials = buff.toString('base64');
+  return { Authorization: `Basic ${credentials}` };
+};
+
+export const logResponse = response => {
+  const { method, url, statusCode, duration } = response;
+  console.log(`${method} ${url} - ${statusCode} in ${duration}ms`);
+};
+
 const getClient = (baseUrl, options) => {
   const { tls, timeout } = options;
   if (!clients.has(baseUrl)) {

packages/http/ast.json

@@ -1,5 +1,78 @@
 {
   "operations": [
+    {
+      "name": "request",
+      "params": [
+        "method",
+        "path",
+        "params",
+        "callback"
+      ],
+      "docs": {
+        "description": "Make a HTTP request",
+        "tags": [
+          {
+            "title": "public",
+            "description": null,
+            "type": null
+          },
+          {
+            "title": "example",
+            "description": "get('/myEndpoint', {\n  query: {foo: 'bar', a: 1},\n  headers: {'content-type': 'application/json'},\n})"
+          },
+          {
+            "title": "function",
+            "description": null,
+            "name": null
+          },
+          {
+            "title": "param",
+            "description": "The HTTP method to use",
+            "type": {
+              "type": "NameExpression",
+              "name": "string"
+            },
+            "name": "method"
+          },
+          {
+            "title": "param",
+            "description": "Path to resource",
+            "type": {
+              "type": "NameExpression",
+              "name": "string"
+            },
+            "name": "path"
+          },
+          {
+            "title": "param",
+            "description": "Query, Headers and Authentication parameters",
+            "type": {
+              "type": "NameExpression",
+              "name": "RequestOptions"
+            },
+            "name": "params"
+          },
+          {
+            "title": "param",
+            "description": "(Optional) Callback function",
+            "type": {
+              "type": "NameExpression",
+              "name": "function"
+            },
+            "name": "callback"
+          },
+          {
+            "title": "returns",
+            "description": null,
+            "type": {
+              "type": "NameExpression",
+              "name": "Operation"
+            }
+          }
+        ]
+      },
+      "valid": true
+    },
     {
       "name": "get",
       "params": [
@@ -38,7 +111,7 @@
             "description": "Query, Headers and Authentication parameters",
             "type": {
               "type": "NameExpression",
-              "name": "object"
+              "name": "RequestOptions"
             },
             "name": "params"
           },
@@ -101,7 +174,7 @@
             "description": "Body, Query, Headers and Authentication parameters",
             "type": {
               "type": "NameExpression",
-              "name": "object"
+              "name": "RequestOptions"
             },
             "name": "params"
           },
@@ -164,7 +237,7 @@
             "description": "Body, Query, Headers and Auth parameters",
             "type": {
               "type": "NameExpression",
-              "name": "object"
+              "name": "RequestOptions"
             },
             "name": "params"
           },
@@ -227,7 +300,7 @@
             "description": "Body, Query, Headers and Auth parameters",
             "type": {
               "type": "NameExpression",
-              "name": "object"
+              "name": "RequestOptions"
             },
             "name": "params"
           },
@@ -290,7 +363,7 @@
             "description": "Body, Query, Headers and Auth parameters",
             "type": {
               "type": "NameExpression",
-              "name": "object"
+              "name": "RequestOptions"
             },
             "name": "params"
           },

packages/http/src/Utils.js

@@ -2,13 +2,14 @@ import { composeNextState } from '@openfn/language-common';
 import {
   request as commonRequest,
   expandReferences,
+  logResponse,
+  makeBasicAuthHeader,
 } from '@openfn/language-common/util';
 
 export function addBasicAuth(configuration = {}, headers) {
   const { username, password } = configuration;
   if (username && password) {
-    const base64Encode = btoa(`${username}:${password}`);
-    headers['Authorization'] = `Basic ${base64Encode}`;
+    Object.assign(headers, makeBasicAuthHeader(username, password));
   }
 }
 
@@ -20,11 +21,6 @@ function encodeFormBody(data) {
   return form;
 }
 
-export function generateResponseLog(response) {
-  const { method, url, statusCode, duration } = response;
-  return `${method} ${url} - ${statusCode} in ${duration}ms`;
-}
-
 export function request(method, path, params, callback = s => s) {
   return state => {
     const [resolvedPath, resolvedParams = {}] = expandReferences(
@@ -73,8 +69,7 @@ export function request(method, path, params, callback = s => s) {
 
     return commonRequest(method, resolvedPath, options)
       .then(response => {
-        const log = generateResponseLog(response);
-        console.log(log);
+        logResponse(response);
 
         return {
           ...composeNextState(state, response.body),
@@ -83,8 +78,7 @@ export function request(method, path, params, callback = s => s) {
       })
       .then(callback)
       .catch(err => {
-        const log = generateResponseLog(err);
-        console.log(log);
+        logResponse(err);
 
         throw err;
       });

packages/template/ast.json

@@ -35,7 +35,7 @@
           },
           {
             "title": "param",
-            "description": "The data to create the new resource",
+            "description": "The data to create the new resource from",
             "type": {
               "type": "NameExpression",
               "name": "object"

packages/template/src/Adaptor.js

@@ -2,9 +2,12 @@ import {
   execute as commonExecute,
   composeNextState,
 } from '@openfn/language-common';
-import { expandReferences } from '@openfn/language-common/util'
+import { expandReferences } from '@openfn/language-common/util';
 import { request } from './Utils';
 
+// TODO You can override the execute function to run code at the start
+//      and end of job execution. This is useful for initialising and destroying
+//      client objects. In this example we need it to create the references array.
 /**
  * Execute a sequence of operations.
  * Wraps `language-common/execute` to make working with this API easier.
@@ -32,45 +35,52 @@ export function execute(...operations) {
   };
 }
 
+// TODO this is example Opeartions which might create a resource on
+//      on a fictional service. It demonstrates best practice for how
+//      Operations should be written
 /**
  * Create some resource in some system
  * @public
  * @example
  * create("patient", {"name": "Bukayo"})
  * @function
  * @param {string} resource - The type of entity that will be created
- * @param {object} data - The data to create the new resource
+ * @param {object} data - The data to create the new resource from
  * @param {function} callback - An optional callback function
  * @returns {Operation}
  */
-export function create(resource, data, callback) {
-  return state => {
-    const [resolvedResource, resolvedData] = expandReferences(state, resource, data); 
-
-    const { baseUrl, username, password } = state.configuration;
+export function create(resource, data, callback = s => s) {
+  return async state => {
+    // Parameters like resource and data might be passed as functions, which
+    // allow us to lazily evaluate state references
+    // The expand function will either return the provided values back to us,
+    // or evaluate them first
+    const [resolvedResource, resolvedData] = expandReferences(
+      state,
+      resource,
+      data
+    );
 
-    const url = `${baseUrl}/api/${resolvedResource}`;
-    const auth = { username, password };
+    // Make the request to the service
+    // See src/Utils.js for the request implementation
+    const response = await request(
+      state,
+      'POST',
+      resolvedResource,
+      resolvedData
+    );
 
-    const options = {
-      auth,
-      body: resolvedData,
-      method: 'POST',
+    // Write the result to state.data, update the references array,  and save response metadata
+    const nextState = {
+      ...composeNextState(state, response.body),
+      response,
     };
 
-    return request(url, options).then(response => {
-      const nextState = {
-        ...composeNextState(state, response.data),
-        response,
-      };
-      if (callback) return callback(nextState);
-      return nextState;
-    });
+    // Invoke the callback (if passed) before returning
+    return callback(nextState);
   };
 }
 
-export { request } from './Utils';
-
 // TODO: Decide which functions to publish from @openfn/language-common
 export {
   dataPath,