first commit

2026-05-29 08:20:56 +01:00
commit 949299f58d
6368 changed files with 527176 additions and 0 deletions
--- a/docs/money/payment/payment-provider-square/README.md
+++ b/docs/money/payment/payment-provider-square/README.md
@@ -0,0 +1,104 @@
+# @suaveplan/payment-provider-square - Universal Square Payments API adapter for @suaveplan/payment. Ships SquareProvider (implements PaymentProvider with literal name "square"), SquareConfig (extends ApiKeyConfig with locationId, sandbox, apiVersion, randomId), and the Square-specific payment/refund mappers. Built on the @suaveplan/payment-providers foundation (httpRequest, composeAbortSignal, PAYMENT_PROVIDER_CODES, PaymentProviderError).
+
+Universal Square Payments API adapter for `@suaveplan/payment`.
+Ships the `SquareProvider` class (implements the structural
+`PaymentProvider` contract with literal `name: "square"`), the
+`SquareConfig` interface (extends `ApiKeyConfig` from
+`@suaveplan/payment-providers` with the Square-specific `locationId`,
+`sandbox`, `apiVersion`, and `randomId` fields), and the
+Square-specific payment / refund mappers (`mapPayment`, `mapRefund`,
+`mapPaymentStatus`, `mapRefundStatus`).
+
+Built on the `@suaveplan/payment-providers` foundation — every
+outbound HTTP call goes through `httpRequest`, which handles JSON
+serialisation, the per-call timeout signal, external `AbortSignal`
+composition, and typed `PaymentProviderError` raising.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [payment](./src/mapping/payment.md) — Translates between Square's `Payment` envelope (as returned by `POST /v2/payments`, `POST /v2/payments/{id}/complete`,…
+- [refund](./src/mapping/refund.md) — Translates Square's `Refund` envelope (as returned by `POST /v2/refunds`) into `@suaveplan/payment`'s `Refund` shape. T…
+- [square](./src/square/square.md) — `SquareProvider` is the Square Payments API adapter for `@suaveplan/payment`. It implements the structural `PaymentProv…
+  - [square](./src/square/square.md) — `SquareProvider` is the Square Payments API adapter for `@suaveplan/payment`. It implements the structural `PaymentProv…
+- [types](./src/types/config.md) — Defines the configuration shape `SquareProvider` accepts and the three default constants the provider falls back to whe…
+  - [config](./src/types/config.md) — Defines the configuration shape `SquareProvider` accepts and the three default constants the provider falls back to whe…
+<!-- end:auto-docs -->
+
+## Install
+
+```bash
+bun add @suaveplan/payment-provider-square @suaveplan/payment-providers @suaveplan/payment
+```
+
+## Quick start
+
+```ts
+import { ProviderRegistry } from "@suaveplan/payment-providers";
+import { SquareProvider } from "@suaveplan/payment-provider-square";
+import { PaymentEngine } from "@suaveplan/payment";
+
+const registry = new ProviderRegistry();
+registry.register(
+    new SquareProvider({
+        apiKey: process.env.SQUARE_ACCESS_TOKEN ?? "",
+        locationId: process.env.SQUARE_LOCATION_ID ?? "",
+    })
+);
+
+const engine = new PaymentEngine({ provider: registry.get("square") });
+
+const intent = await engine.createIntent({
+    amount: { amount: 5000n, currency: "USD" },
+});
+```
+
+## Features
+
+- **`SquareProvider`** — full Square Payments API lifecycle
+  (`createIntent`, `confirmIntent`, `captureIntent`, `cancelIntent`,
+  `refund`, `getIntent`) with literal `name: "square"`.
+- **`SquareConfig`** — extends `ApiKeyConfig`; adds required
+  `locationId` plus optional `sandbox`, `apiVersion`, `randomId`.
+- **Sandbox toggle** — `sandbox: true` flips the default base URL to
+  `https://connect.squareupsandbox.com/v2`. Explicit `baseUrl`
+  always wins.
+- **Pinned `Square-Version`** — defaults to `2024-01-18`; override via
+  `apiVersion` to opt into a newer API surface.
+- **Injectable `randomId`** — fills missing `idempotency_key` fields
+  on `CreatePayment` + `RefundPayment` calls. Tests pass a
+  deterministic counter; production defaults to `crypto.randomUUID()`.
+- **Universal** — no `node:`, `bun:`, `fs`, `path`, `crypto`
+  imports; runs on Node, Bun, browsers, and Web Workers.
+- **`PaymentProviderError`-only** — every failure surfaces as a
+  typed `PaymentProviderError` via the foundation's `httpRequest`.
+- **100% test coverage** (Istanbul) + sibling `.md` per
+  implementation file + 5 subpath exports.
+
+## Modules
+
+- [`src/square/square.md`](./src/square/square.md) — `SquareProvider`
+  class and lifecycle methods.
+- [`src/types/config.md`](./src/types/config.md) — `SquareConfig`,
+  `SQUARE_DEFAULT_BASE_URL`, `SQUARE_SANDBOX_BASE_URL`,
+  `SQUARE_DEFAULT_API_VERSION`.
+- [`src/mapping/payment.md`](./src/mapping/payment.md) — `mapPayment`,
+  `mapPaymentStatus`, `SquarePaymentDto`, `SquareMoney`, `SquareCard`.
+- [`src/mapping/refund.md`](./src/mapping/refund.md) — `mapRefund`,
+  `mapRefundStatus`, `SquareRefundDto`.
+
+## Related
+
+- `@suaveplan/payment-providers` — `ProviderRegistry`,
+  `definePaymentProvider`, `httpRequest`, `composeAbortSignal`,
+  `PAYMENT_PROVIDER_CODES`, `PaymentProviderError`,
+  `ApiKeyConfig`/`OAuthConfig`/`MerchantKeyConfig`,
+  `FetchLike`/`RandomIdFn`/`NowFn`/`Base64EncodeFn`.
+- `@suaveplan/payment` — `PaymentEngine`, `WebhookVerifier`,
+  `PaymentProvider` interface, the canonical `PaymentIntent` /
+  `Refund` / `PaymentStatus` / `RefundStatus` shapes.
+
+## License
+
+MIT
+