93 lines
6.1 KiB
Markdown
93 lines
6.1 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [errors](./src/errors/errors.md) — Stable error code registry, per-code metadata, and the concrete `ClipboardError` class for the `@suaveplan/clipboard` p…
|
|
- [errors](./src/errors/errors.md) — Stable error code registry, per-code metadata, and the concrete `ClipboardError` class for the `@suaveplan/clipboard` p…
|
|
- [fallback](./src/fallback/fallback.md) — Legacy clipboard fallback paths used when `navigator.clipboard` is unavailable or rejects. Provides a hidden-textarea +…
|
|
- [fallback](./src/fallback/fallback.md) — Legacy clipboard fallback paths used when `navigator.clipboard` is unavailable or rejects. Provides a hidden-textarea +…
|
|
- [manager](./src/manager/manager.md) — `ClipboardManager` is the orchestrator class for `@suaveplan/clipboard`. It composes the navigator + window seams, the…
|
|
- [helpers](./src/manager/helpers.md) — Pure helpers shared between `manager.ts` and `operations.ts`. Keeps both files under the line budget by housing the nav…
|
|
- [manager](./src/manager/manager.md) — `ClipboardManager` is the orchestrator class for `@suaveplan/clipboard`. It composes the navigator + window seams, the…
|
|
- [operations](./src/manager/operations.md) — Pure operation functions invoked by `ClipboardManager`. Each function takes an `OperationContext` (navigator, window, o…
|
|
- [observability](./src/observability/observability.md) — OpenTelemetry instrumentation bundle for `@suaveplan/clipboard`. Wires four counters and one histogram on a single `Met…
|
|
- [observability](./src/observability/observability.md) — OpenTelemetry instrumentation bundle for `@suaveplan/clipboard`. Wires four counters and one histogram on a single `Met…
|
|
- [permissions](./src/permissions/permissions.md) — Probe and subscribe to clipboard permission state via the browser's Permissions API. `checkPermissions` returns a snaps…
|
|
- [permissions](./src/permissions/permissions.md) — Probe and subscribe to clipboard permission state via the browser's Permissions API. `checkPermissions` returns a snaps…
|
|
- [queue](./src/queue/queue.md) — `AsyncQueue` is a minimal FIFO asynchronous queue that serializes operations on a single tail promise. The `ClipboardMa…
|
|
- [queue](./src/queue/queue.md) — `AsyncQueue` is a minimal FIFO asynchronous queue that serializes operations on a single tail promise. The `ClipboardMa…
|
|
- [sanitizer](./src/sanitizer/sanitizer.md) — Sanitizer hooks applied to inbound `text/html` clipboard payloads. The package ships an identity sanitizer (pass-throug…
|
|
- [sanitizer](./src/sanitizer/sanitizer.md) — Sanitizer hooks applied to inbound `text/html` clipboard payloads. The package ships an identity sanitizer (pass-throug…
|
|
- [security](./src/security/security.md) — Browser-side security helpers that guard clipboard operations against insecure contexts and orchestrate the focus-aware…
|
|
- [security](./src/security/security.md) — Browser-side security helpers that guard clipboard operations against insecure contexts and orchestrate the focus-aware…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/clipboard
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```ts
|
|
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`](./src/manager/manager.md) — `ClipboardManager`, the orchestrator.
|
|
- [`manager/helpers.md`](./src/manager/helpers.md) — internal helpers used by the manager.
|
|
- [`manager/operations.md`](./src/manager/operations.md) — pure operation functions.
|
|
- [`errors/errors.md`](./src/errors/errors.md) — `CLIPBOARD_CODES`, `ClipboardError`, metadata.
|
|
- [`fallback/fallback.md`](./src/fallback/fallback.md) — textarea + paste-event fallback paths.
|
|
- [`observability/observability.md`](./src/observability/observability.md) — OpenTelemetry counters + histogram.
|
|
- [`permissions/permissions.md`](./src/permissions/permissions.md) — permission probe + change subscription.
|
|
- [`queue/queue.md`](./src/queue/queue.md) — `AsyncQueue` FIFO serializer.
|
|
- [`sanitizer/sanitizer.md`](./src/sanitizer/sanitizer.md) — sanitizer interface + helpers.
|
|
- [`security/security.md`](./src/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
|
|
|