gsheets: Update input data format and allow for multiple range updates

[hunterachieng]

Summary

Updated appendValues(), batchUpdateValues(), and getValues() to use positional arguments instead of a single params object.

Callback parameter has been removed from appendValues(), batchUpdateValues(), and getValues() in favor of a promise-based API.

Fixes #1476

AI Usage

Please disclose how you've used AI in this work (it's cool, we just want to
know!):

• I have used Claude Code
• I have used another model
• I have not used AI

You can read more details in our
Responsible AI Policy

Review Checklist

Before merging, the reviewer should check the following items:

• Does the PR do what it claims to do?
• If this is a new adaptor, added the adaptor on marketing website ?
• If this PR includes breaking changes, do we need to update any jobs in
  production? Is it safe to release?
• Are there any unit tests?
• Is there a changeset associated with this PR? Should there be? Note that
  dev only changes don't need a changeset.
• Have you ticked a box under AI Usage?

[mtuchi]

I have asked joe, for his opinion on new signature
batchUpdateValues(sheetId, data = [{range, values}], options = {valueInputOption})

If he agrees i think, we should update appendValues as well and remove support for callback in getValues()

[mtuchi]

@hunterachieng i think the changes are looking good, can you tidy up two things

• Create an issue supporting array of data in appendValues(id, data = [{}], options) to match what we have in batchUpdateValues
• Clean up PR description and title to match the changes and don't forget to update the review checklist as well

[mtuchi]

Hey @hunterachieng sorry for long review, i wanted to confirm few things on appendValues function before approving this pr. Here is my findings

The current implementation does not multiple range when using appendValues(), See issue #1656. And i don't think it's an easy fix you will have to change the entire payload on client.spreadsheets.values.append() to look something like this

{
  "[valueInputOption](https://developers.google.com/workspace/sheets/api/reference/rest/v4/ValueInputOption)": "VALUE_INPUT_OPTION",
  "[data](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values#resource-valuerange)": [
    {
      "range": "Sheet1!A1:A4",
      "[majorDimension](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values#dimension)": "COLUMNS",
      "values": [
        ["Item", "Wheel", "Door", "Engine"]
      ]
    },
    {
      "range": "Sheet1!B1:D2",
      "[majorDimension](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values#dimension)": "ROWS",
      "values": [
        ["Cost", "Stocked", "Ship Date"],
        ["$20.50", "4", "3/1/2016"]
      ]
    }
  ]
}

See writing multiple range docs. I honestly don't think we need to support multiple range in appendValues because batchUpdateValues function already does that. I will edit the pr notes and approve this pr

[mtuchi]

These examples from google are really useful, It's was really hard to find a good documentation on how to use the googleapis sheets api in node

[mtuchi]

@hunterachieng I have update pr notes and remove this issue from the notes #1656, See my comments here.

I am happy to handover this issue to joe for final round of review

[josephjclark]

Re appendValues: yes, appendValues should take a single range/value set, and bulk should take multiple.

As the original issue hints at, I don't understand the difference really between client.spreadsheets.append and client.spreadsheets.batchUpdate()? Can anyone explain that to me? It is just that append only takes a single range and batch accepts multiple ranges? Or is there more going on in batch?

[josephjclark]

It would be nice for the single range API to take a single object, rather than an array of one. Just a little API convenience

[mtuchi]

@josephjclark can you say more 🤔 , values are rows data do you mean we should pass values: [{columnHeader: value, colHeader: value}, {...}]?

[josephjclark]

So multiple ranges is:

batchUpdateValues(id, [set1, set2])

Where a set is { range, values }
And a single range so far is:

batchUpdateValues(id, [set1])

I'm saying allow a single range to be passed like this:

batchUpdateValues(id, set1)

BUT THEN AGAIN

That makes the API the same as the appendValues API, which only confuses the two.

Ok, so we should force data to be an array of ranges. But do not show an example with an array of just 1 range because it's wierd

[mtuchi]

I think function naming is what causing the confusion here. There are singular actions and plural actions
For example:

• If we had appendValue(id, range, data, opt) this is clear, add new row to gsheet
• For appendValues(id, [{set0, set1}], opt), this is clear adding multiple rows

The same could apply for batchUpdateValues()

• batchUpdate(id, range, value,opt)
• batchUpdate(id, [{set0}, {set1}])

Of course adding good docs that explain what append does, and what does batchUpdate do? because their different.

I will remove the single batch update example

[mtuchi]

difference really between client.spreadsheets.append and client.spreadsheets.batchUpdate()

values.append

• Finds the last row with data in the range and adds rows after it — it never overwrites
• The range param is really just a hint to locate which table/sheet to append to
• Designed for "add new rows to a growing list" use cases (logs, form submissions, etc.)
• Single range only, yes

values.batchUpdate

• Writes to exact cell coordinates — it overwrites whatever is there
• The range param means "put data starting at exactly this cell"
• Multiple ranges in one API call (hence "batch")
• Designed for "set these cells to these values" use cases