Goal: SDK contracts for authenticated user portal surfaces

[KazanderDad]

Parent: Sprint: Production-ready authenticated MyPayTag user portal
Brainstorm/Architecture Task: Define SIWC user portal architecture and API contracts
Sequence: Goal 1 of 6

Objective

Add or update canonical SDK protocol and OpenAPI contracts required by the authenticated user portal, if the architecture task determines these surfaces are public or cross-repo contracts.

Execution Tasks

• Add user preference and history protocol schemas and validators.
• Refresh generated artifacts, fixtures, examples, OpenAPI, Postman, and conformance checks.

Sequence Context

• Depends on: architecture/API-contract task.
• Enables: backend and site implementation to consume stable typed contracts.
• Run independently by: a fresh Codex thread after the architecture task is complete.

Non-Goals

• Do not expose private backend-only operational fields in public SDK contracts.
• Do not publish Cubid-owned grant, stamp issuance, or identity lifecycle internals as MyPayTag user portal APIs.

Guardrails

• Public contracts must not include raw wallet graph data, provider secrets, private diagnostics, service-role concepts, or Cubid internals beyond approved identity/session references.
• Existing NEAR 1Click MVP constraints and Phase 2 solver boundaries must remain intact.

Expected Codebase Surfaces

• api/openapi.yaml
• packages/protocol/schemas/*
• packages/protocol/src/index.ts
• packages/protocol/src/validators.ts
• packages/protocol/src/fixtures.ts
• packages/protocol/src/protocol.test.ts
• packages/sdk/src/*
• packages/provider-sdk/src/* when provider-facing history or receipt contracts require it
• scripts/generate-postman-collection.mjs
• Examples under examples/* when public integration flows change

Acceptance Criteria

• Preference, quote detail, selected quote, payment intent summary, and transaction/receipt summary contracts exist where the architecture task says they belong in the SDK.
• OpenAPI, JSON Schemas, generated TypeScript, fixtures, validators, and examples agree.
• Unsupported/private backend details are excluded from public contracts.
• Generated artifacts are refreshed through repo scripts, not hand-edited.

Validation Plan

• pnpm validate
• Source review for browser/public-boundary leakage.

Child Tasks

• Add user preference and history protocol contracts.
• Refresh generated artifacts and SDK validation evidence.

Risks And Mitigations

• Risk: contracts drift from backend implementation. Mitigation: make backend implementation depend on this Goal or explicitly document backend-only surfaces.

Stop Condition

Stop when SDK contracts are either updated and validated or the architecture task documents that no SDK changes are required.

[KazanderDad]

Vetting Addendum\n\nImplementation worktree: /Users/botmaster/src/myPayTag/mypaytag-sdk-5-user-portal, branch codex/5-user-portal-sdk, base origin/dev. Use this same SDK sprint worktree for SDK issues #4, #5, and #6. Create it with git fetch origin && git worktree add ../mypaytag-sdk-5-user-portal -b codex/5-user-portal-sdk origin/dev if it does not already exist. Retain until the sprint PR is merged and approved-cleanup runs.\n\nGoal-level validation: run  ERR_PNPM_NO_IMPORTER_MANIFEST_FOUND  No package.json (or package.yaml, or package.json5) was found in "/Users/botmaster/src/myPayTag/mypaytag-backend". after child Tasks are complete, confirm generated artifacts and OpenAPI/schema/types agree, and verify no public-boundary leakage. Issue Validator: after implementation, local validation, session-log update, and commit, run issue-validator before moving this issue to In Review. Provide issue URL, parent URL, commit hash, worktree path, changed files summary, validation commands/results, smoke result, visual evidence for UI-facing work or N/A, and boundaries/non-goals. Validator reports pass, pass-with-notes, or fail to the orchestrator.\n\nImplementation expectations: update code, technical docs, tests, and agent-context/session-log/main.md as relevant before committing. Commit exactly this issue scope, include the issue number in the commit message, and comment with commit hash, validation evidence, smoke result, boundary check, and residual risks.

[KazanderDad]

Issue Validator Report

Result: pass

Target issue: MyPayTag-sdk#4 Goal: SDK contracts for authenticated user portal surfaces
Child implementation commits reviewed:

• f558043 - protocol schemas, validators, fixtures, tests, generated protocol source, and OpenAPI portal contracts (Add user preference and history protocol contracts #5)
• 2c227f3 - generated Postman/API artifact refresh and session-log validation evidence (Refresh generated artifacts and SDK validation evidence #6)

Evidence reviewed:

• Child issues Add user preference and history protocol contracts #5 and Refresh generated artifacts and SDK validation evidence #6 are both In Review with passing validator reports.
• Portal contracts exist for preferences, quote detail, selected quote, payment intent summaries, and receipt summaries through the portal history and preferences schemas/OpenAPI components.
• OpenAPI, JSON Schemas, generated TypeScript exports, fixtures, validators, protocol tests, and generated Postman collection were checked for agreement.
• Public-boundary and privacy tests reject missing user scope, private wallet data, and private diagnostic leakage.

Validation commands rerun or inspected:

• Reran pnpm validate: passed.
• Inspected api/openapi.yaml, packages/protocol/schemas/*portal*, packages/protocol/src/generated/types.ts, packages/protocol/src/validators.ts, packages/protocol/src/fixtures.ts, and packages/protocol/src/protocol.test.ts.
• Confirmed api/postman_collection.json contains the generated bearer-authenticated /portal/preferences and /portal/history examples from commit 2c227f3.

Boundary check:

• No raw wallet graph, provider secrets, private diagnostics, service-role mechanics, or Cubid-owned lifecycle internals are exposed as public SDK contract fields.
• Existing NEAR 1Click and Phase 2 solver boundaries remain intact.

Ready for In Review: yes.