skills/plugins/document-navigator/docs/money/payment/payment-provider-square/README.md

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

Documentation tree

• payment — Translates between Square's Payment envelope (as returned by POST /v2/payments, POST /v2/payments/{id}/complete,…
• refund — Translates Square's Refund envelope (as returned by POST /v2/refunds) into @suaveplan/payment's Refund shape. T…
• square — SquareProvider is the Square Payments API adapter for @suaveplan/payment. It implements the structural `PaymentProv…
  • square — SquareProvider is the Square Payments API adapter for @suaveplan/payment. It implements the structural `PaymentProv…
• types — Defines the configuration shape SquareProvider accepts and the three default constants the provider falls back to whe…
  • config — Defines the configuration shape SquareProvider accepts and the three default constants the provider falls back to whe…

Install

bun add @suaveplan/payment-provider-square @suaveplan/payment-providers @suaveplan/payment

Quick start

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 — SquareProvider class and lifecycle methods.
• src/types/config.md — SquareConfig, SQUARE_DEFAULT_BASE_URL, SQUARE_SANDBOX_BASE_URL, SQUARE_DEFAULT_API_VERSION.
• src/mapping/payment.md — mapPayment, mapPaymentStatus, SquarePaymentDto, SquareMoney, SquareCard.
• 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