@suaveplan/clipboard - Enterprise Clipboard API abstraction: typed errors, OTel metrics, async queue serializer, secure-context guard, image/blob copy + read, paste-event read fallback, permission change subscription, focus-aware retry, sanitizer hook. Browser-tier, zero @suaveplan/* runtime deps beyond error + opentelemetry + types.

Enterprise Clipboard API abstraction for browser-tier consumers. Wraps the async Clipboard API with a textarea + execCommand fallback, a paste-event read fallback, image / blob copy + read via ClipboardItem, FIFO serialization, secure-context guard, permission change subscription, focus-aware retry, optional HTML sanitizer, structured errors via @suaveplan/error, and OpenTelemetry instrumentation.

Documentation tree

errors — Stable error code registry, per-code metadata, and the concrete ClipboardError class for the @suaveplan/clipboard p…
- errors — Stable error code registry, per-code metadata, and the concrete ClipboardError class for the @suaveplan/clipboard p…
fallback — Legacy clipboard fallback paths used when navigator.clipboard is unavailable or rejects. Provides a hidden-textarea +…
- fallback — Legacy clipboard fallback paths used when navigator.clipboard is unavailable or rejects. Provides a hidden-textarea +…
manager — ClipboardManager is the orchestrator class for @suaveplan/clipboard. It composes the navigator + window seams, the…
- helpers — Pure helpers shared between manager.ts and operations.ts. Keeps both files under the line budget by housing the nav…
- manager — ClipboardManager is the orchestrator class for @suaveplan/clipboard. It composes the navigator + window seams, the…
- operations — Pure operation functions invoked by ClipboardManager. Each function takes an OperationContext (navigator, window, o…
observability — OpenTelemetry instrumentation bundle for @suaveplan/clipboard. Wires four counters and one histogram on a single `Met…
- observability — OpenTelemetry instrumentation bundle for @suaveplan/clipboard. Wires four counters and one histogram on a single `Met…
permissions — Probe and subscribe to clipboard permission state via the browser's Permissions API. checkPermissions returns a snaps…
- permissions — Probe and subscribe to clipboard permission state via the browser's Permissions API. checkPermissions returns a snaps…
queue — AsyncQueue is a minimal FIFO asynchronous queue that serializes operations on a single tail promise. The `ClipboardMa…
- queue — AsyncQueue is a minimal FIFO asynchronous queue that serializes operations on a single tail promise. The `ClipboardMa…
sanitizer — Sanitizer hooks applied to inbound text/html clipboard payloads. The package ships an identity sanitizer (pass-throug…
- sanitizer — Sanitizer hooks applied to inbound text/html clipboard payloads. The package ships an identity sanitizer (pass-throug…
security — Browser-side security helpers that guard clipboard operations against insecure contexts and orchestrate the focus-aware…
- security — Browser-side security helpers that guard clipboard operations against insecure contexts and orchestrate the focus-aware…

Install

bun add @suaveplan/clipboard

Quick start

import { ClipboardManager } from "@suaveplan/clipboard";

const clipboard = new ClipboardManager({
    useFallback: true,
    requireSecureContext: false,
    serialize: true,
});

const result = await clipboard.copyText("hello");
if (!result.success) {
    console.error("copy failed:", result.code, result.error);
}

Modules

manager/manager.md — ClipboardManager, the orchestrator.
manager/helpers.md — internal helpers used by the manager.
manager/operations.md — pure operation functions.
errors/errors.md — CLIPBOARD_CODES, ClipboardError, metadata.
fallback/fallback.md — textarea + paste-event fallback paths.
observability/observability.md — OpenTelemetry counters + histogram.
permissions/permissions.md — permission probe + change subscription.
queue/queue.md — AsyncQueue FIFO serializer.
sanitizer/sanitizer.md — sanitizer interface + helpers.
security/security.md — secure-context guards + focus utilities.

Features

Copy plain text, HTML, images, and arbitrary MIME blobs.
Read plain text and rich content with optional HTML sanitization.
Paste-event fallback when navigator.clipboard.readText is unavailable.
Permission probe + live subscription (onPermissionChange).
Async FIFO queue so concurrent calls execute in arrival order.
Secure-context guard with typed error code (CLIPBOARD.INSECURE_CONTEXT).
Focus-aware retry on NotAllowedError: Document is not focused.
Eight stable error codes under the CLIPBOARD.* namespace.
Five OpenTelemetry instruments wired into every public method.
SSR-safe — graceful degradation when document / navigator / window are undefined.

Error codes

CLIPBOARD.API_UNAVAILABLE, CLIPBOARD.PERMISSION_DENIED, CLIPBOARD.FALLBACK_FAILED, CLIPBOARD.INSECURE_CONTEXT, CLIPBOARD.NO_CONTENT, CLIPBOARD.READ_FAILED, CLIPBOARD.DOCUMENT_UNAVAILABLE, CLIPBOARD.QUEUE_DRAINED.

License

MIT

6.1 KiB Raw Blame History