# @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