Week 1: check and award API implementation

[sruju333]

Summary

Adds checkAndAward to the badges API client and a new completeActivity function to the activities API client - the two endpoints with the clearest existing server support. Also traces the PUT /activities/:username/activity call against the ?taskId= deep link emitted in ActivitiesModal.tsx:129, to identify where client-side wiring will need to go.

Type of Change

• New feature

Key Changes

• core/services/badgesApi.ts: Added checkAndAward(userId, token), calling POST /badges/:userId/check-and-award. Confirmed signature and response shape ({ awarded: [...] }) against the live server route (requireAuth + requireSelf, no body, server-authoritative recompute).
• core/services/activitiesApi.ts (new file): Added completeActivity(username, token, activityName), calling PUT /activities/:username/activity. Confirmed request body shape ({ activityName }) against the live server route.
• Trace/investigation: Followed the ?taskId= deep link ActivitiesModal.tsx:129 emits when navigating to a puzzle/lesson. Confirmed it's currently read nowhere. Identified the puzzle-completion block in Puzzles.tsx (moveListRef.current.length === 0) as the right insertion point for the client-side PUT call. Found a mismatch worth flagging below.

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed (partial - see note below)
• All tests pass

Bugs Fixed (if applicable)

N/A

TODO (Follow-up Work)

• Wire completeActivity and checkAndAward into Puzzles.tsx's puzzle-completion block
• Wire the same into the lesson-completion flow
• Mismatch found: ?taskId= (from the backend activity catalog's taskId field) doesn't match what PUT /activities/:username/activity expects (activities.name) - will need a lookup step client-side, or a server-side change, before the deep link can actually drive the PUT call
• Server-side: add completedDates write on last-daily-activity completion in routes/activities.js

Additional Notes

Per Week 1 scope, this PR covers the two client functions plus tracing/identifying the wiring point - actual wiring is intentionally deferred to Week 2+/follow-up, per the plan.

Manual end-to-end testing was blocked locally by a middlewarenode startup error (Configuration property "indexKey" is not defined) - appears to be a missing local .env value, unrelated to this change. Function signatures and request/response shapes were verified by reading the confirmed server route handlers directly. Will complete manual testing once local env is sorted.

[karthikeya1976]

Verified both client functions against the real, live server routes (not just the PR's own description) — everything checks out:

• checkAndAward(userId, token) — confirmed POST /:userId/check-and-award in routes/badges.js: requireAuth + requireSelf("userId"), no body, response is { awarded }. Also traced requireSelf itself — despite the param being named userId, it actually compares against req.user.username, so passing a username here (as the JSDoc says) is correct, not a bug.
• completeActivity(username, token, activityName) (new activitiesApi.ts) — confirmed PUT /:username/activity in routes/activities.js expects exactly { activityName } in the body, matched by requireActivityWriteAccess (self-or-admin, same pattern as requireSelf). Correct as written.
• npx tsc --noEmit on this branch: clean, no type errors.

One small, non-blocking nit: completeActivity's JSDoc still says @param {string} activityId but the actual parameter (and the body key) is activityName — just the comment is stale, the code itself is right.

No unit tests yet (matches the PR's own honest checklist) — worth adding before this lane goes much further, but not a reason to hold this specific PR, since the signatures are independently verified against the real routes.

Approving — this unblocks Week 2/3 wiring as planned.

🤖 Generated with Claude Code