CorrelAid / CorrelAid/formtransform
[survey2ddi 3/6] Kobo pull adapter + formtransform kobo command
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
Step 3 of 6 for the survey2ddi retirement. Plan: HANDOVER_SURVEY2DDI.md. Best done after the xlsform2ddi --data issue, since kobo transform composes it.
Why
kobo2ddi in CorrelAid/survey2ddi is the only way to go from a Kobo asset UID to a codebook in one step. Its converter half is now duplicated here; its fetch half has no equivalent. Porting the fetch half is what lets that package stop shipping a second DDI implementation.
What to port
kobo2ddi/client.py — 98 lines of httpx, all straightforwardly fetch:
| Python | Endpoint | Notes |
|---|---|---|
list_assets() |
GET /api/v2/assets/ |
paginated (next) |
get_asset(uid) |
GET /api/v2/assets/<uid>/ |
title/metadata |
get_submissions(uid) |
GET /api/v2/assets/<uid>/data/ |
paginated; returns JSON records |
download_xlsform(uid, dest) |
GET /api/v2/assets/<uid>.xls |
serves xlsx despite the .xls path — SheetJS reads it, no legacy-BIFF work needed |
pull(uid, out) |
— | writes submissions.json + form.xlsx into <out>/<uid>/ |
CLI surface mirroring the Python one:
formtransform kobo list
formtransform kobo pull <uid> -o output/
formtransform kobo transform <uid> -o output/ # pull + xlsform2ddi + data CSV
- Auth:
--token, elseKOBO_API_TOKEN. Server:--server-url, elseKOBO_SERVER_URL, elsehttps://eu.kobotoolbox.org. Keep the env var names identical so existing.envfiles keep working;node --env-filereplacespython-dotenv, no dependency needed. - Kobo submission records are keyed
group/namewith space-joinedselect_multiplevalues — exactly whatbuildDataCsv'sreadCellalready handles, sotransformispull+ the existing emitters with no adapter.
Constraints
- Node-only, like
src/cli.tsandsrc/fileChoices.ts. Do not re-export the client fromsrc/index.ts. The app must not start shipping an HTTP client, and anode:fs/ network import surfacing in the browser bundle is a regression. - Fail loudly on a missing token rather than issuing an unauthenticated request.
- Do not print the token in error messages or verbose output.
Acceptance criteria
-
list/pull/transformbehave as the Python CLI does, same env var names - Pagination handled for assets and submissions (a >1-page asset is the test that matters)
-
transformproduces XML + CSV with a correctcaseQnty - Browser entry unchanged — nothing new reachable from
src/index.ts -
--helpfor the command group and each subcommand
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with HANDOVER_SURVEY2DDI.md and the Node-only entry points src/cli.ts and src/fileChoices.ts, then compare the requested behavior with survey2ddi's kobo2ddi/client.py. Verify list, pull, and transform help output, pagination, environment variables, XML and CSV output including caseQnty, and that src/index.ts and the browser entry remain unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, typescript
- Domain
- api, cli, data
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100