# Milestone v1.1: SDK & Docs

**Status:** SHIPPED 2026-01-21
**Phases:** 12-16
**Total Plans:** 5

## Overview

SDK supports x402 v2 format with type-safe discrimination; merchants have refund documentation.

## Phases

### Phase 12: SDK Type Definitions

**Goal**: TypeScript consumers can discriminate between v1 and v2 payment payloads with full type narrowing
**Depends on**: Nothing (first phase of v1.1)
**Requirements**: SDK-01, SDK-02, SDK-03, SDK-09
**Success Criteria** (what must be TRUE):
  1. TypeScript recognizes `x402Version: 1` literal as PaymentPayloadV1
  2. TypeScript recognizes `x402Version: 2` literal as PaymentPayloadV2
  3. PaymentPayload union correctly narrows when version is checked
  4. PaymentRequirements types align with both payload versions
**Plans**: 1 plan

Plans:
- [x] 12-01-PLAN.md — Define PaymentPayloadV1/V2 and PaymentRequirementsV1/V2 with discriminated unions

### Phase 13: SDK Type Guards & Utilities

**Goal**: Consumers have runtime utilities to safely handle versioned payloads
**Depends on**: Phase 12
**Requirements**: SDK-04, SDK-05, SDK-06, SDK-08
**Success Criteria** (what must be TRUE):
  1. `isPaymentPayloadV1()` narrows type to PaymentPayloadV1 in TypeScript
  2. `isPaymentPayloadV2()` narrows type to PaymentPayloadV2 in TypeScript
  3. `getSchemeNetwork()` extracts scheme/network from both v1 and v2 payloads
  4. `assertNever` catches unhandled version cases at compile time
**Plans**: 1 plan

Plans:
- [x] 13-01-PLAN.md — Add type guards (isPaymentPayloadV1/V2, isPaymentRequirementsV1/V2) and utilities (getSchemeNetwork, getVersion, assertNever)

### Phase 14: SDK Method Updates

**Goal**: SDK methods handle both v1 and v2 formats; all types exported
**Depends on**: Phase 13
**Requirements**: SDK-07, SDK-10, SDK-11, SDK-12
**Success Criteria** (what must be TRUE):
  1. All new types exported from `@openfacilitator/sdk` package index
  2. `verify()` accepts and correctly processes both v1 and v2 payloads
  3. `settle()` accepts and correctly processes both v1 and v2 payloads
  4. SDK builds successfully with `pnpm --filter=@openfacilitator/sdk build`
**Plans**: 1 plan

Plans:
- [x] 14-01-PLAN.md — Add getVersionSafe utility and version validation to verify/settle methods

### Phase 15: Refund Documentation

**Goal**: Merchants have a comprehensive guide to implement refund protection
**Depends on**: Nothing (independent of SDK phases)
**Requirements**: DOCS-01, DOCS-02, DOCS-03, DOCS-04
**Success Criteria** (what must be TRUE):
  1. Refund guide accessible at `/docs/sdk/refunds/`
  2. Sidebar navigation includes refunds entry under SDK section
  3. `reportFailure` code examples demonstrate complete usage
  4. `withRefundProtection` middleware example shows end-to-end setup
**Plans**: 1 plan

Plans:
- [x] 15-01-PLAN.md — Create refund documentation page and sidebar navigation entry

### Phase 16: Investigate Whitelabel Volume Tracking

**Goal**: Fix missing volume tracking for users with white-labeled facilitators by creating enrollment markers
**Depends on**: Nothing (bug fix, independent)
**Requirements**: FIX-01 (Create missing facilitator markers), FIX-02 (Auto-create on new facilitators)
**Success Criteria** (what must be TRUE):
  1. Root cause identified for missing volume tracking (missing chain_type='facilitator' markers)
  2. White-labeled facilitator volume correctly attributed to owner
  3. Rewards page displays accurate volume for users with multiple facilitators
**Plans**: 1 plan

Plans:
- [x] 16-01-PLAN.md — Create facilitator enrollment markers and integrate into creation flow

---

## Milestone Summary

**Execution Order:** 12 -> 13 -> 14 -> 15 -> 16 (13 depends on 12, 14 depends on 13, 15 and 16 are independent)

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 12. SDK Type Definitions | 1/1 | Complete | 2026-01-20 |
| 13. SDK Type Guards & Utilities | 1/1 | Complete | 2026-01-21 |
| 14. SDK Method Updates | 1/1 | Complete | 2026-01-21 |
| 15. Refund Documentation | 1/1 | Complete | 2026-01-21 |
| 16. Investigate Whitelabel Volume Tracking | 1/1 | Complete | 2026-01-21 |

**Key Decisions:**

- Use literal types (1, 2) for x402Version to enable TypeScript narrowing
- PaymentRequirements discriminated by field presence (maxAmountRequired vs amount)
- getVersionSafe defaults missing x402Version to v1 for backward compatibility
- Refund docs use middleware-first approach with tab navigation (Hono/Express/Manual)
- Enrollment markers use reward_addresses with chain_type='facilitator'

**Issues Resolved:**

- Missing SDK x402 v2 type support (Phases 12-14)
- Missing refund documentation (Phase 15)
- Whitelabel facilitator volume not tracked (Phase 16)

**Technical Debt Incurred:**

None - all implementations are complete and production-ready.

---

*For current project status, see .planning/ROADMAP.md*
