Code templates for Firebase onRequest and onCall Functions

exports.selectViaOnRequestFunction = functions.region('europe-west2').https.onRequest(async (req, res) => {

    // The 'europe-west2' bit above is where you would declare your own
    // function's location - leave this out completely if you're happy
    // to use the default US location

    // In order to appreciate the next bit of code, you need to
    // understand that, once your function is on the web, anybody who
    // knows its url can access it and feed it with parameters to suit
    // their own ends.  This is because Firestore functions run under
    // project account privileges - where user-base Firestore rules 
    // are bypassed. As a result it now become critically important 
    // to ensure that calls only come from domains that you authorise. 
    // The technology that achieves this is called CORS - (Cross-Origin 
    // Resource Sharing).

    // The CORS mechanism is based on the use of 'headers" - packets of
    // information that the web's architecture enables you to wrap around
    // your transactions. CORS requires a Cloud function to use headers
    // to perform a little dance before accepting a request. On first
    // receipt of a call (the so-called "pre-flight" stage), the function
    // must respond with a header that it can use to tell the caller
    // which domains it's prepared to accept calls from. Unless Fetch
    // find that this matches the caller's domain, it will terminate the
    // dance with a CORS "unauthorised domain" error. You can see the
    // first stage of this below where the function looks for a value of
    // "OPTIONS" in req.method. This tells it that it's got a new caller 
    // and must therefore respond with an authorisation header. 

    if (req.method === 'OPTIONS') {

    // Here's where the function tells Fetch that it's prepared to receive 
    // calls from 'https://approvedSite.org'

        res.set('Access-Control-Allow-Origin', 'https://approvedSite.org');

    // Telling Fetch which domains can be used is only the half of it.
    // Fetch also needs to be told which 'calling methods' (GET, POST
    // etc) and header types (eg 'Content-type') may be used. In the
    // example below, the function authorises use of the POST method and
    // the "content type" header - this will later be used in a Fetch
    // call to send a stringified JSON object using a "'Content-Type':
    // 'application/json'" header

        res.set('Access-Control-Allow-Methods', 'POST');
        res.set('Access-Control-Allow-Headers', 'Content-Type'); 

    // The pre-flight call concludes with a "res.status(204).send('');"
    // that explicitly states that this is an empty response.

        res.status(204).send('');

    } else {

        // Here's the point of entry for a request that has now passed
        // the pre-flight call and so is warranted an authorised source
        // using authorised methods and content-type. Note that this
        // second entry is still required to include an
        // 'Access-Control-Allow-Origin' header in its response

           res.set('Access-Control-Allow-Origin', 'https://approvedSite.org');

        // Tip: make sure you've got your function processing well-logged
        // in this section because processing errors here may still be
        // flagged as CORS errors in your calling code. Check the
        // function logs in the Cloud console to see what's going on 

        // Now get your input from req.body. Although, as you'll see
        // later, you have to "stringy" your parameter object (ie
        // turn it into a character-based string so that it can be
        // transmitted as a POST request), this is converted back into an
        // object automatically by onRequest  - don't try JSON.parse on
        // this - it will error!

        const searchParams = req.body 

        // Now do your processing to construct a 'result' object. If you
        // wanted to apply user-restrictions here, you'd achieve this by
        // including user details in your request body. 

       try {

        // Finally, return your response to the calling program. Note
        // that if you're returning an object there's no need to
        // 'stringify' it - the onRequest function does this for you
        // automatically.  Note also that, although the function obviously
        // needs to return a promise, you don't need to set this explicitly
        // either - the onRequest framework automatically wraps
        // your return inside a "new Promise". 

            res.send(result); 

        } catch (error) {
            res.send({error: error })
        }
    }
});

// Here's the URL for your Cloud function. It takes the following form:
// https://<region>-<project id>.cloudfunctions/net/,function name>

const functionUrl = 'https://europe-west2-yourProject.cloudfunctions.net/selectViaOnRequestFunction';

// Create a search parameter object

const searchParams = {
    surname: "Airey",
    forename: "John",
}

    // Create the required options for your request - in this case a POST
    // method, a content-type header specifying a JSON input and a body
    // containing a character representation of your input data

const requestOptions = {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(searchParams),

try {

    // Make the asynchronous HTTPS request and receive its response 
    // in a local variable

    const response = await fetch(functionUrl, requestOptions)

    // Handle the response from the function. Magically, it comes back as
    // an object

    // Strangely, the JSON payload of "response" is only available as an
    // asynchronous ".json" function property of response - read the W3C
    // Fetch Living Standard if you want to know why

    const responseJSON = await response.json();
    console.log({ responseJSON }); 

} catch (error) {
    // Handle any errors
    console.error('Error calling function:', error);
}

exports.selectViaOnCallFunction = functions.region('europe-west2').https.onCall(async (data, context) => {

    console.log({ data }) // displays properties of original data input object - no need to JSON.parse it

    // That's it - you're in!. Because you're "sandboxed" within your
    // own project domain there's no need for a "pre-flight" check.
    // You'll find that even calls from your local host are accepted.
    // You'll also find that your input data is both transmitted and
    // received as an object - no "stringification" here

    // Wondering what the "context" calling parameter might be? This is
    // an optional field designed to supply a user's "auth" information.
    // Inspection of this then enables you to reject requests that
    // aren't logged in and to access information details such as
    // 'context.auth.email" etc

    // Once comfortably plugged into your function, Firestore
    // collections and Cloud storage buckets are now available.
    // Remember, however, that you are now operating in a Node.js
    // environment so the API interfaces are rather different - see
    // "Working with Cloud Functions" at
    // (https://dev.to/mjoycemilburn/getting-serious-with-firebase-v9-part-4-cloud-storage-uploading-files-3p7c)
    // for background.

    // When you're finally ready to return a response or error object
    // proceed as follows:   

    const response ={
        myResponseProperty:data.myInputProperty + " - yeehaa!"
    }

    try {
        return response; // no need to stringify a JSON response object
    } catch (error) {
        return { error: error}
    }

    // The return is automatically wrapped within a promise.

})

// Here's the initialisation

import { httpsCallable } from 'firebase/functions'; // onCall specific

const firebaseConfig = {
    apiKey: "AIzaSy .. obfuscated ... tYEvb4DRN8",
          .. etc ..
    appId: "1:716624 .. obfuscated ... 542bef254721"
};

const app = initializeApp(firebaseConfig);

const functions = getFunctions(app, 'europe-west2');

// That's the end of the project setup. Now declare your onCall function

const selectViaOnCallFunction = httpsCallable(functions, 'selectViaOnCallFunction'); // onCall specific

// Now here's how you might use your function in an HTML button.  In
// this instance I've not used the optional "context" parameter - the
// function's input is just a simple data object. 

    <button onClick={async () => {

         try {
            const data = {myInputProperty: "yip yip"} // create an input data object
            const responseJSON = await selectViaOnCallFunction(data) // call the onCall function and get its result
            const responseProperty = responseJSON.data.myResponseProperty // the .data method is synchronous
            console.log(response) // logs "yip yip - yeehaa"
            } catch (error)  {
                    console.log("Failure: error details are : " + error); //baa
            }

        } 
    }>Click here to test access to the selectViaOnCallFunction function</button>