[LC-1423] X-API Scoped by Contract

[TaylorBeeston]

Overview

🎟 Relevant Jira Issues

[LC-1423] Port xAPI activity logs to the new ConsentFlow design

📚 What is the context and goal of this PR?

In order to query X-API statements scoped by contract, we need to tag them!

🥴 TL; RL:

Tags X-API statements with a contract URI by adding the contract URI to the VP JWT

💡 Feature Breakdown (screenshots & videos encouraged!)

• Adds contract URI to VP JWT in LCA
• Reads contract URI from JWT in X-API Wrapper and adds to the X-API statement

🛠 Important tradeoffs made:

🔍 Types of Changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Chore (refactor, documentation update, etc)

💳 Does This Create Any New Technical Debt? ( If yes, please describe and add JIRA TODOs )

• No
• Yes

Testing

🔬 How Can Someone QA This?

Easiest way is to just run the tests! =) The E2E tests will check the new JWT format and test correctly
tag statements

📱 🖥 Which devices would you like help testing on?

🧪 Code Coverage

Wrote E2E tests

Documentation

I had Claude update the docs =)

📝 Documentation Checklist

User-Facing Docs (docs/ → docs.learncard.com)

• Tutorial — New capability that users need to learn (docs/tutorials/)
• How-To Guide — New workflow or integration (docs/how-to-guides/)
• Reference — New/changed API, config, or SDK method (docs/sdks/)
• Concept — New mental model or architecture explanation (docs/core-concepts/)
• App Flows — Changes to LearnCard App or ScoutPass user flows (docs/apps/)

Internal/AI Docs

• CLAUDE.md — New pattern, flow, or context that AI assistants need
• Code comments/JSDoc — Complex logic that needs inline explanation

Visual Documentation

• Mermaid diagram — Complex flow, state machine, or architecture

B[LearnCard] --> C[Network]

-->

#### 💭 Documentation Notes
<!-- If no docs needed, briefly explain why (e.g., "Internal refactor, no API changes") -->


# ✅ PR Checklist
- [x] Related to a Jira issue ([create one if not](https://welibrary.atlassian.net/jira/software/projects/WE/boards/2))
- [x] My code follows **style guidelines** (eslint / prettier)
- [x] I have **manually tested** common end-2-end cases
- [x] I have **reviewed** my code
- [x] I have **commented** my code, particularly where ambiguous
- [x] New and existing **unit tests pass** locally with my changes
- [x] I have completed the **Documentation Checklist** above (or explained why N/A)

### 🚀 Ready to squash-and-merge?:
- [x] Code is backwards compatible
- [x] There is **not** a "Do Not Merge" label on this PR
- [x] I have thoughtfully considered the security implications of this change.
- [x] This change does not expose new public facing endpoints that do not have authentication


[LC-1423]: https://welibrary.atlassian.net/browse/LC-1423?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

[changeset-bot]

🦋 Changeset detected

Latest commit: 7be34ed

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 16 packages

Name	Type
@learncard/learn-cloud-service	Patch
learn-card-app	Patch
@learncard/learn-cloud-client	Patch
@learncard/learn-cloud-plugin	Patch
@learncard/cli	Patch
@learncard/init	Patch
@learncard/chapi-example	Patch
@learncard/create-http-bridge	Patch
@learncard/react	Patch
learn-card-discord-bot	Patch
@learncard/lca-api-service	Patch
scoutpass-app	Patch
@learncard/snap-chapi-example	Patch
@learncard/lca-api-client	Patch
@learncard/lca-api-plugin	Patch
learn-card-base	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for learncarddocs canceled.

Name	Link
🔨 Latest commit	7be34ed
🔍 Latest deploy log	https://app.netlify.com/projects/learncarddocs/deploys/6945d09a03cc79000851c227

[netlify]

✅ Deploy Preview for staging-learncardapp canceled.

Name	Link
🔨 Latest commit	7be34ed
🔍 Latest deploy log	https://app.netlify.com/projects/staging-learncardapp/deploys/6945d09ad5391b0008b61a17

[gitstream-cm]

🥷 Code experts: Custard7

Custard7, TaylorBeeston have most 👩‍💻 activity in the files.
Custard7, TaylorBeeston have most 🧠 knowledge in the files.

See details

apps/learn-card-app/src/pages/consentFlow/ExternalConsentFlowDoor.tsx

Activity based on git-commit:

	Custard7	TaylorBeeston
DEC
NOV		340 additions & 0 deletions
OCT
SEP
AUG
JUL

Knowledge based on git-blame:
TaylorBeeston: 100%

apps/learn-card-app/src/pages/consentFlow/FullScreenConsentFlow.tsx

Activity based on git-commit:

	Custard7	TaylorBeeston
DEC		107 additions & 43 deletions
NOV		220 additions & 0 deletions
OCT
SEP
AUG
JUL

Knowledge based on git-blame:
TaylorBeeston: 100%

docs/core-concepts/consent-and-permissions/writing-consented-data.md

Activity based on git-commit:

	Custard7	TaylorBeeston
DEC	77 additions & 0 deletions	29 additions & 2 deletions
NOV
OCT
SEP
AUG
JUL

Knowledge based on git-blame:
Custard7: 72%
TaylorBeeston: 28%

docs/sdks/learncloud-storage-api/xapi-reference.md

Activity based on git-commit:

	Custard7	TaylorBeeston
DEC	528 additions & 0 deletions
NOV
OCT
SEP
AUG
JUL

Knowledge based on git-blame:
Custard7: 100%

docs/tutorials/sending-xapi-statements.md

Activity based on git-commit:

	Custard7	TaylorBeeston
DEC	295 additions & 0 deletions
NOV
OCT
SEP
AUG
JUL

Knowledge based on git-blame:
Custard7: 100%

services/learn-card-network/learn-cloud-service/src/constants/xapi.ts

Activity based on git-commit:

	Custard7	TaylorBeeston
DEC
NOV
OCT
SEP
AUG
JUL	1 additions & 0 deletions

Knowledge based on git-blame:
Custard7: 100%

services/learn-card-network/learn-cloud-service/src/helpers/request.helpers.ts

Activity based on git-commit:

	Custard7	TaylorBeeston
DEC
NOV
OCT
SEP
AUG
JUL

Knowledge based on git-blame:
Custard7: 100%

services/learn-card-network/learn-cloud-service/src/helpers/xapi.helpers.ts

Activity based on git-commit:

	Custard7	TaylorBeeston
DEC
NOV
OCT
SEP
AUG
JUL

Knowledge based on git-blame:
Custard7: 100%

services/learn-card-network/learn-cloud-service/src/types/vp.ts

Activity based on git-commit:

	Custard7	TaylorBeeston
DEC
NOV
OCT
SEP
AUG
JUL

Knowledge based on git-blame:
Custard7: 100%

services/learn-card-network/learn-cloud-service/src/xapi.ts

Activity based on git-commit:

	Custard7	TaylorBeeston
DEC
NOV
OCT
SEP
AUG
JUL

Knowledge based on git-blame:
Custard7: 100%

tests/e2e/tests/dids.spec.ts

Activity based on git-commit:

	Custard7	TaylorBeeston
DEC
NOV
OCT
SEP
AUG
JUL

Knowledge based on git-blame:
Custard7: 100%

tests/e2e/tests/xapi.spec.ts

Activity based on git-commit:

	Custard7	TaylorBeeston
DEC
NOV
OCT
SEP
AUG
JUL

Knowledge based on git-blame:
Custard7: 100%

✨ Comment /gs review for LinearB AI review. Learn how to automate it here.

[Custard7]

@claude please review and provide a recomendation on merging

[claude]

Claude finished @Custard7's task —— View job

---

Code Review Complete ✅

I've reviewed this PR for X-API contract scoping and here's my comprehensive assessment:

Review Tasks

• Read and understand the VP type modifications
• Review X-API statement tagging implementation
• Analyze test coverage and E2E tests
• Check documentation updates
• Address the existing review comment about VP context
• Provide comprehensive feedback and merge recommendation

Code Review Findings

✅ Strong Points

1. Clear Architecture: The implementation properly separates concerns - contract URI is added to VP at creation, extracted in the xAPI service, and injected into statements
2. Excellent Test Coverage: Comprehensive E2E tests in tests/e2e/tests/xapi.spec.ts covering:
   • Contract-scoped statement creation and querying
   • Multiple contract scenarios
   • Proper filtering by contract extension
3. Backward Compatibility: The implementation supports both VP-level and JWT payload-level contract URIs (services/learn-card-network/learn-cloud-service/src/xapi.ts:44)
4. Documentation: Well-documented in both tutorial and reference docs with clear examples

🔍 Addressing the Review Comment

@TaylorBeeston regarding the VP context question:

The implementation doesn't modify the VP context - it's much cleaner than that! Here's what actually happens:

1. VP Level: contractUri is added as a top-level property to the VP object before signing (ExternalConsentFlowDoor.tsx:235-236)
2. JWT Payload: This gets embedded in the signed JWT as part of the decoded payload
3. X-API Service: The service extracts it from either decodedJwt.vp.contractUri or decodedJwt.contractUri (xapi.ts:44)
4. Statement Injection: Only then is it added to the xAPI statement's context.extensions

Why use DidAuthVP type? The DidAuthVP type represents the decoded JWT payload structure. Adding contractUri?: string here is correct because:

• It matches the actual data structure being decoded from the JWT
• It maintains type safety for the contract URI extraction logic
• It's optional, maintaining backward compatibility

🚦 Minor Considerations

1. Type Safety: The cast to any when adding contractUri to VP (ExternalConsentFlowDoor.tsx:235) works but could be more type-safe
2. Consistency: Contract URI extraction logic handles both locations gracefully for backward compatibility

📊 Security & Best Practices

• ✅ Proper authentication flow maintained
• ✅ Contract URI is signed within the VP, preventing tampering
• ✅ No exposure of sensitive data
• ✅ Follows existing LearnCard patterns

Merge Recommendation: ✅ APPROVE

This PR is ready to merge based on:

1. Functional Correctness: Implementation works as designed and tested
2. Code Quality: Clean, well-documented, follows existing patterns
3. Test Coverage: Comprehensive E2E tests validate the feature
4. Documentation: Updated with clear examples and use cases
5. Backward Compatibility: Maintains compatibility while adding new functionality
6. Security: No security concerns identified

The approach is sound - embedding the contract URI in the VP before signing ensures it's cryptographically protected and enables proper statement scoping for ConsentFlow workflows.

---

[smurflo2]

LGTM!