[codex] implement MyPayTag SDK sprint 7 contracts

agent-context/2026-06-28-mypaytag-mvp-realignment.md

@@ -0,0 +1,85 @@
+# MyPayTag MVP Realignment Instruction
+
+Date: 2026-06-28
+Repo: `mypaytag-sdk`
+Status: implementation instruction
+
+## Cross-Repo Instruction Set
+
+This is one of five coordinated instruction docs:
+
+- `mypaytag-backend`: `/Users/botmaster/src/myPayTag/mypaytag-backend/agent-context/2026-06-28-mypaytag-mvp-realignment.md`
+- `mypaytag-sdk`: `/Users/botmaster/src/myPayTag/mypaytag-sdk/agent-context/2026-06-28-mypaytag-mvp-realignment.md`
+- `mypaytag-site`: `/Users/botmaster/src/myPayTag/mypaytag-site/agent-context/2026-06-28-mypaytag-mvp-realignment.md`
+- `cubid-monorepo`: `/Users/botmaster/src/cubid/cubid-monorepo/agent-context/2026-06-28-mypaytag-mvp-realignment.md`
+- `cubid-sdk-v2`: `/Users/botmaster/src/cubid/cubid-sdk-v2/agent-context/2026-06-28-mypaytag-mvp-realignment.md`
+
+When touching this repo, read the other four docs first and preserve the ownership split.
+
+## Naming Requirement
+
+Request and implement the rename from `GlobalPayTo` / `globalpayto` / `gptr` language to `MyPayTag` / `mypaytag` / `mpt` where that text is public package metadata, schemas, generated types, examples, docs, OpenAPI, Postman collections, fixtures, tests, and published-contract names. Keep backwards-compatible aliases only when needed for package consumers or staged migrations, and mark them explicitly as compatibility.
+
+## Product Boundary
+
+Do not remove public docs or helper material about future solver/execution adapters solely because it is beyond MVP. Instead, ensure the MVP contract is correct and future execution helpers are clearly not required for MVP resolution.
+
+`mypaytag-sdk` owns the public MyPayTag contract for:
+
+- PayingDapp resolve requests and responses.
+- PayToDapp route registration requests and responses.
+- Provider callback request/response contracts.
+- Hosted route-selection action contracts that MyPayTag owns.
+- MyPayTag intent schema and fixtures.
+
+It must not define Cubid-owned user stamp elevation, opaque paytag creation, Cubid grant management, or Cubid authenticated user-session APIs. Those belong in `cubid-monorepo` and `cubid-sdk-v2`.
+
+## Product Decisions To Preserve
+
+- A paytag is a MyPayTag-branded payment identity powered by Cubid identity and consent primitives.
+- Paytags are universal global identifiers for PayingDapps at the public protocol layer.
+- Implementation may default to PayToDapp-scoped identifiers behind the scenes until global availability and non-Cubid identity provider support are ready.
+- Opaque Cubid-backed paytags such as `abd123@cubid.mypaytag` are the default. Raw stamp-based paytags such as `+1234569999@phone.cubid.mypaytag` require explicit user choice.
+- MyPayTag validates paytag uniqueness and availability before issuance, in preparation for future identity providers beyond Cubid.
+- MyPayTag stores Cubid-issued opaque aliases or stable references where possible, plus hashes for lookup and audit. Raw paytags are avoided unless explicitly user-chosen.
+- MVP supports multiple paytags per user, with each paytag initially mapped to one Cubid stamp or one opaque Cubid-backed alias.
+- Launch readiness requires local tests first, then hosted staging smoke across Cubid, MyPayTag, one test PayingDapp, and one test PayToDapp.
+
+## SDK Work Required
+
+1. Make OpenAPI match the canonical MyPayTag intent schema.
+   - `api/openapi.yaml` must require the same intent fields as `packages/protocol/schemas/mypaytag-intent.schema.json`.
+   - Require `provider_json` payload fields: provider intent id, chain, network, asset, destination, amount, reference, and expiry.
+   - Remove weaker examples that only require `destination`.
+
+2. Keep Cubid out of the MyPayTag API contract except as an external identity/consent dependency.
+   - MyPayTag public contracts should accept a paytag/opaque paytag reference and rely on backend validation against Cubid.
+   - Do not expose Cubid internal ids, raw Cubid user ids, Cubid grant internals, or Cubid stamp management APIs in this SDK.
+   - PayingDapps integrate with MyPayTag, not Cubid. Do not add public examples where a PayingDapp directly probes Cubid for paytag state.
+
+3. Separate MVP helpers from future execution helpers.
+   - Resolve and provider callback helpers are MVP.
+   - Solver quote helpers, preferred solver ids, bridge/swap/cross-chain quote previews, and execution fanout are future/extension helpers.
+   - Keep future helpers if useful, but label them as non-MVP and ensure examples do not imply they are required for the core resolve flow.
+
+4. Align terminology.
+   - Use `PayingDapp`, `PayToDapp`, `paytag`, `opaque paytag`, `route`, and `MyPayTag intent` consistently.
+   - Avoid saying Cubid resolves payments or routes.
+   - Avoid saying Cubid owns wallets or payment destinations.
+   - Present paytags as universal for PayingDapps while noting the implementation may use PayToDapp-scoped aliases internally.
+
+5. Add contract tests.
+   - OpenAPI examples, JSON Schemas, generated TypeScript types, and SDK fixtures must agree.
+   - Add tests that reject route registration with wallet addresses or payment instructions.
+   - Add tests that reject provider responses missing required `provider_json` fields.
+   - Add negative-disclosure fixture coverage for `no_route`, `authorization_required`, and `user_action_required`.
+   - Add fixtures for opaque and raw-explicit paytag examples and for paytag uniqueness/availability checks.
+
+6. Validation target.
+   - Run the repo validation command after changes.
+   - Regenerate derived OpenAPI/Postman/generated schema artifacts only through repo scripts.
+   - Include a staged smoke checklist that pairs this SDK with Cubid SDK and one test PayingDapp/PayToDapp integration.
+
+## Done Means
+
+This repo is realigned when integrators can build against an accurate MVP MyPayTag protocol without learning or depending on Cubid internals, and without needing any solver/execution helper to complete the MVP resolve flow.

agent-context/2026-06-28-mypaytag-sdk-mvp-gap-review.md

@@ -0,0 +1,121 @@
+# MyPayTag SDK MVP Gap Review
+
+Date: 2026-06-28
+Repo: `mypaytag-sdk`
+Branch reviewed: `codex/mypaytag-mvp-realignment-20260628`
+Status: implementation gap note
+
+## Scope
+
+This note evaluates the SDK implementation against:
+
+- `agent-context/2026-06-28-mypaytag-mvp-realignment.md`
+- the updated MyPayTag backend PRD scope that promotes NEAR Intents / 1Click into Phase 1/MVP
+- the MyPayTag happy-path use cases for paytag issuance, route CRUD, resolve, NEAR 1Click quotes, quote selection, and SmarTrust swap/bridge
+
+The branch is mechanically healthy and `pnpm validate` passes, but several public contract gaps remain against the revised MVP scope.
+
+## Summary
+
+The SDK now correctly moves most public contract language from GlobalPayTo to MyPayTag, uses `paytag` terminology, keeps Cubid internals out of public request shapes, validates the canonical MyPayTag intent envelope, and rejects wallet/address fields during route registration.
+
+However, the SDK still treats all execution quoting as a future generic solver extension. That is no longer aligned with the MVP: NEAR Intents / 1Click is now the only Phase 1 swap/bridge execution adapter, while LI.FI, Squid, 0x, Across, LayerZero/Stargate, broad solver fanout, and generic external adapter support are Phase 2.
+
+## Current Strengths
+
+- `ResolveRequest` and `ResolveResponse` use `identifierType: "paytag"` and keep Cubid internals out of public response shapes.
+- `MyPayTagIntent` requires `schema`, `status`, `modality`, `recipient`, `selectedRoute`, `amount`, `expiresAt`, `singleUse`, `paymentInstruction`, and `references`.
+- `provider_json.payload` requires provider intent id, chain, network, asset, destination, amount, reference, and expiry.
+- Route registration schemas reject top-level account/address/payment-instruction fields.
+- Provider SDK helpers validate provider callback and provider response payloads.
+- Testing fixtures include opaque paytags, explicit raw paytag examples, safe negative responses, and provider fixtures.
+- `pnpm validate` passes on the reviewed branch.
+
+## Gaps Against MVP Scope
+
+### 1. NEAR Intents / 1Click Is Not An MVP Contract
+
+The SDK still labels all crypto-native execution helpers as future extension helpers and includes generic solver ids plus fanout behavior. The revised MVP requires a concrete NEAR Intents / 1Click contract for SmarTrust swap/bridge use cases.
+
+Required change:
+
+- Add explicit Phase 1 NEAR Intents / 1Click quote and selected-payable-instruction contracts.
+- Keep LI.FI, Squid, 0x, Across, LayerZero/Stargate, broad fanout, and generic external adapter support as Phase 2 only.
+- Update SDK helpers and tests so the MVP path does not rely on generic quote fanout.
+
+### 2. Quote Selection And Payable Instruction Handoff Are Missing
+
+The happy path needs:
+
+1. PayingDapp resolves a paytag and receives one or more NEAR 1Click quotes.
+2. PayingDapp selects a quote.
+3. MyPayTag validates the selected quote and returns a payable instruction.
+
+Current schemas expose `RouteQuotePreview` and generic `ExecutionQuote`, but they do not define the public request/response shapes for quote option return, quote selection, or selected payable instruction.
+
+Required change:
+
+- Add schemas/types for NEAR 1Click quote options returned by MyPayTag.
+- Add schemas/types for selected quote confirmation.
+- Add schemas/types for the payable instruction returned after quote selection.
+- Add fixtures and validators for quote expiry, route reference, resolver reference, selected PayToDapp route reference, and payable instruction consistency.
+
+### 3. Provider Callback Binding Is Incomplete
+
+The protocol schema requires resolver request id, recipient, PayingDapp id, selected path, amount, purpose, and expiry. The revised MVP also requires PayingDapp reference binding. OpenAPI is currently weaker than the JSON Schema and omits purpose and expiry in the provider callback component.
+
+Required change:
+
+- Add `payingDappReference` to `ProviderCallbackRequest`.
+- Align OpenAPI `ProviderCallbackRequest` with JSON Schema and generated TypeScript.
+- Ensure provider SDK conformance tests verify purpose, expiry, resolver request id, selected route, amount, PayingDapp id, and PayingDapp reference matching.
+
+### 4. OpenAPI And JSON Schemas Drift
+
+OpenAPI differs from the JSON Schemas for `NotificationEvent` and provider callbacks. This creates integration risk because OpenAPI consumers and TypeScript consumers will build against different payloads.
+
+Required change:
+
+- Make OpenAPI consume or mirror the canonical JSON Schema shapes.
+- Align `NotificationEvent` around `eventType`, `schema`, `recipient`, `amount`, `references`, and `action`.
+- Add tests that compare OpenAPI examples/components against protocol fixtures, not only string snippets.
+
+### 5. Route CRUD And Hosted Action Contracts Are Incomplete In Protocol Package
+
+OpenAPI documents route CRUD and hosted action endpoints, but the protocol package only exports route registration request/response validators. There are no canonical protocol schemas for PayToRoute reads, route update requests, delete/revoke responses, hosted action view models, hosted action decisions, or hosted action completion.
+
+Required change:
+
+- Add protocol schemas, generated types, validators, and fixtures for route CRUD and hosted route-selection actions.
+- Ensure route CRUD types expose only PayToDapp-owned scoped data.
+- Ensure hosted action types do not expose route graph, raw identifiers, wallet addresses, unrelated PayToDapps, route preferences, or private diagnostics.
+
+### 6. Paytag Availability Is Fixture-Only
+
+Happy path paytag issuance needs Cubid to check availability with MyPayTag before issuing an opaque paytag. The SDK currently has testing fixtures for availability, but no public or service-facing contract.
+
+Required change:
+
+- Add paytag availability request/response schemas for the MyPayTag/Cubid boundary if this contract belongs in the public SDK.
+- If the contract is private service-to-service only, document that explicitly and keep only fixtures/test vectors here.
+- Add availability states for available, unavailable, reserved, idempotent retry, raw-explicit, and opaque-default issuance cases.
+
+## Required Change Order
+
+1. Add explicit NEAR Intents / 1Click MVP quote and selected-instruction contracts.
+2. Move generic solver fanout docs/tests to Phase 2 language.
+3. Fix provider callback binding and OpenAPI/schema drift.
+4. Add protocol schemas and validators for route CRUD and hosted action surfaces.
+5. Decide and document whether paytag availability is public SDK or private service contract; add schemas if public.
+6. Expand fixtures, examples, and conformance tests around the revised MVP happy paths.
+7. Run `pnpm validate` after generated artifacts are refreshed through repo scripts.
+
+## Validation Target
+
+The SDK is MVP-ready when:
+
+- `pnpm validate` passes.
+- OpenAPI, JSON Schemas, generated TypeScript, fixtures, SDK helpers, provider SDK helpers, and Postman examples agree.
+- PayingDapp examples can build same-chain resolve requests and NEAR 1Click swap/bridge quote flows without direct Cubid probing.
+- PayToDapp examples can register routes and handle provider callbacks with complete binding fields.
+- Testing fixtures cover the MVP happy paths: paytag availability, route registration, route deregistration, resolve, route selection, NEAR 1Click quote options, selected quote payable instruction, and safe negative statuses.