Initial Commit

openspec/archive/2026-05-17-add-payment-provider-square/tasks.md

@@ -0,0 +1,69 @@
+# Tasks — add-payment-provider-square
+
+> Every checkbox MUST reflect work actually done in this change. No retroactive ticking.
+
+## 1. Spec authoring
+
+- [x] 1.1 Read `../suaveplan/enterprise/payment-providers.md` end-to-end
+- [x] 1.2 Read upstream `src/square.ts`, `src/square.md`, `src/square.test.ts`
+- [x] 1.3 Read `openspec/AGENTS.md` Sections 13 and 14
+- [x] 1.4 Read slim archive `openspec/archive/2026-05-17-slim-payment-providers/`
+- [x] 1.5 Draft `proposal.md` from `openspec/templates/proposal.md`
+- [x] 1.6 Fill in `## Source mapping` table — every requirement cites a line range or appears in the "no source line" table with justification
+- [x] 1.7 Draft `specs/payment-provider-square/spec.md` from `openspec/templates/spec-delta.md`
+- [x] 1.8 Every requirement carries a `**Verified by:**` line naming concrete `it(...)` titles
+
+## 2. Implementation
+
+- [x] 2.1 Create `packages/universal/payment-provider-square/` with `package.json` (`0.1.0`, deps: `@suaveplan/payment-providers`, `@suaveplan/payment`, `tslib`), `tsconfig.json`, `tsconfig.lib.json`, `vite.config.ts`, `vitest.config.ts`, `tests/setup/polyfills.ts`
+- [x] 2.2 `src/types/config.ts` — `SquareConfig extends ApiKeyConfig` with `locationId`, `sandbox?`, `randomId?`, `apiVersion?`; export constants `SQUARE_DEFAULT_BASE_URL`, `SQUARE_SANDBOX_BASE_URL`, `SQUARE_DEFAULT_API_VERSION`
+- [x] 2.3 `src/mapping/payment.ts` — `mapPaymentStatus`, `mapPayment`, `SquarePaymentDto` type
+- [x] 2.4 `src/mapping/refund.ts` — `mapRefundStatus`, `mapRefund`, `SquareRefundDto` type
+- [x] 2.5 `src/square/square.ts` — `SquareProvider implements PaymentProvider` class
+- [x] 2.6 `src/index.ts` — explicit named re-exports (§6a)
+
+## 3. Tests
+
+- [x] 3.1 `src/square/square.test.ts` — full lifecycle, deterministic `randomId`, real `FetchLike` recorder, sandbox URL flip, header pinning, idempotency-key forwarding
+- [x] 3.2 `src/mapping/payment.test.ts` — every status branch, missing-card-details, approved-money branch
+- [x] 3.3 `src/mapping/refund.test.ts` — every refund-status branch, reason fallback
+- [x] 3.4 `src/types/config.test.ts` — type-level assertions (`expectTypeOf`) on `SquareConfig extends ApiKeyConfig` and `locationId` required-ness
+- [x] 3.5 `tests/dep-graph.test.ts` — universal-tier purity gate (no `node:` / `bun:` / `fs` / `path` / `crypto` imports)
+- [x] 3.6 Every `it(...)` carries `{ timeout: 5000 }`
+
+## 4. Documentation
+
+- [x] 4.1 `src/square/square.md` — sibling doc (≥200 words, basic + advanced examples, full API reference)
+- [x] 4.2 `src/types/config.md` — sibling doc
+- [x] 4.3 `src/mapping/payment.md` — sibling doc
+- [x] 4.4 `src/mapping/refund.md` — sibling doc
+- [x] 4.5 `README.md` linking every co-located `.md` under `## Modules`
+
+## 5. Pre-archive verification (the 5-gate triple)
+
+- [x] 5.1 `bun run check` — Biome 0/0/0 across the touched files (run inside the package)
+- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/payment-provider-square` — green
+- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/payment-provider-square` — 100/100/100/100
+- [x] 5.4 Manual spec-completeness audit (§12a) — every requirement implemented, every `Verified by` test exists with verbatim title
+- [x] 5.5 `bunx turbo build --filter=@suaveplan/payment-provider-square` — green
+
+## 6. Pre-archive 8-row checklist (skill Step 7)
+
+- [x] 6.1 Generics threaded; `expectTypeOf` on literal-type claims (`name: "square"`, `SquareConfig extends ApiKeyConfig`)
+- [x] 6.2 No Zod boundaries claimed by spec — config is a TS interface, no runtime parse boundary in this package
+- [x] 6.3 No error codes added — the package reuses `PAYMENT_PROVIDER_CODES` from the foundation and raises only `PaymentProviderError` via the foundation's `httpRequest`
+- [x] 6.4 No strict-mode toggles claimed
+- [x] 6.5 No OTel instruments declared by this package (foundation owns metrics)
+- [x] 6.6 Idempotency-key generation tested with a deterministic injected `randomId`
+- [x] 6.7 No retroactive tick — every box reflects work done in this change
+- [x] 6.8 No `export *` in any feature-module barrel — every `<feature>/index.ts` uses named re-exports
+- [x] 6.9 No direct `vitest` / `bun:test` imports — every test imports from `@suaveplan/testing/runner`
+
+## 7. Archive
+
+- [x] 7.1 Fold spec delta into `openspec/specs/payment-provider-square/spec.md`
+- [x] 7.2 Move `openspec/changes/add-payment-provider-square/` → `openspec/archive/2026-05-17-add-payment-provider-square/`
+- [x] 7.3 Refresh `STATUS.md` (`Pending` → `Completed` row added)
+- [x] 7.4 Refresh `SUMMARY.md` (per-package paragraph added)
+- [x] 7.5 Refresh `MANIFEST.md` via `bun scripts/folder-reorg/generate-manifest.ts` (run after package lands)
+- [x] 7.6 Add package row to `CLAUDE.md` listing