105 lines
5.0 KiB
Markdown
105 lines
5.0 KiB
Markdown
# @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
|
|
|