Added getResource & list helpers

[PiusKariuki]

Summary

Added 2 helper functions to adaptor.js: list & getResource

Fixes #1742

Details

requestWithPagination helper in util.js

• Cursor-based pagination over API V2.

list operation

• Wraps requestWithPagination

getResource operation

• Get a single or mutiple resources by ID

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.
• If there is a changeset, was pnpm run version used to bump versions (not
  pnpm changeset version directly)? This ensures changelog dates are stamped correctly.
• Have you ticked a box under AI Usage?

[PiusKariuki]

@hunterachieng this now ready to review. See description for summary

[mtuchi]

Hey @PiusKariuki can you rebase from main and make sure your branch is up to date and doesn't contain other packages changes eg: msgprah, fhir-opensrp or surveycto

[PiusKariuki]

@mtuchi
I have made the changes you have requested

• Rebased from main
• Removed files not related to this pr: msgraph/ast.json, fhir-opensrp/ast.json, surveycto/package.json

Note: Notice that the build is now failing in the GIT status check. This was the reason I included the files above in the PR since this step kept failing. Do you have any recommendations on how to fix this in a cleaner way? See error below

Run pnpm run test:git

> adaptors@1.0.0 test:git /home/runner/work/adaptors/adaptors
> pnpm exec scripts/status-check.sh

Checking if git working tree is clean...
❌ Git working tree has uncommitted changes

 M packages/msgraph/ast.json

Note: ast.json changes are often caused by the file not being checked into the build

Please commit or stash these changes before proceeding.
 ELIFECYCLE  Command failed with exit code 1.
Error: Process completed with exit code 1.

[mtuchi]

@PiusKariuki i don't think we should hardcode version /v2, Are you sure all endpoints will be supported ?
what if i want to use v1 ?

[PiusKariuki]

@mtuchi The challenge here is that CommCare v1 and v2 APIs have semantic differences when it comes to pagination.

• V1 uses the common limit and offset
• V2 uses a cursor to paginate.
• The shape of the response is also different depending on what version you are using.
  That is the reason I am using version 2 so I can be able to control what shape the response comes in and how I move on to the next batch.

The docs state on that 2 CommCare resources versioned as v1/v2: the Case Data API and the Location API. On other endpoints V2 is just a superset of V1 so anything you can do in v1 you could also do in v2

[mtuchi]

I don't understand what you mean by V2 uses a cursor to paginate. but my problem is getResource() will always use v2 because it's hard coded regardless if i specify apiVersion in my configuration. Maybe the that's fine and we should document in the function this function uses v2 only.

If we want to support auto pagination then regardless of v1 or v2 getResource() should support auto pagination and not force the function to only use v2.

[mtuchi]

Maybe @josephjclark have different opinion on this

[PiusKariuki]

I think the question here @josephjclark is, how opinionated should the requestWithPagination function be when it comes to the API version ?

The 2 API versions handle pagination very differently and give the response in different shapes so I made the call to use v2.

[mtuchi]

CommCare query parameters is clear i think

[mtuchi]

I think we just need to return nextState no need for { ...nextState, data}, thats what prepareNextState do

[PiusKariuki]

@mtuchi I tried it locally and it returned state without a data object

[mtuchi]

Hey @PiusKariuki , left couple of comments here, please review them. Also see my comments on CommCare url scheme change from the previous pr 👇🏽

• #1753 (comment)
• #1753 (comment)

[PiusKariuki]

@mtuchi please take a quick look at this PR when you can.

[mtuchi]

@PiusKariuki can you check the box in review checklist

[mtuchi]

Hey @PiusKariuki i left you couple, Please address them and ask joe for final review

[PiusKariuki]

Hi @josephjclark could you please have a look at this when you get the time?

[josephjclark]

I can look but I don't see an approve from @mtuchi yet.

There are also conflicts because the version was bumped too earlier.

Please submit a changeset file with all changes, but don't bump versions until we're ready to merge (usually I'll ask when ready for that)

i recommend you revert the package.json and changelog files.

[josephjclark]

I don't know where there are so many changes in the package lock either - you should probably revert those

[mtuchi]

@PiusKariuki

• Extract HTTP gate utility logic - to support pagination for V1 and V2 in the list function.
• Review 404 handling - test removing the 404 protection logic to check if default headers work properly. use parseAs: json