chore: prepare OpenAnalytics plugin for 0.1.0 release

[christopherjnelson]

Setup UX

Opening OpenAnalytics after saving valid plugin settings now establishes the connection automatically: one secure server-side /v1/read/site validation, a saved configuration-bound public snapshot, then the existing four analytics reads. A matching snapshot skips site validation on page revisits and range changes. Failed configuration fingerprints show a safe error and Retry connection without automatic retry loops or analytics reads.

Refresh connection lives directly beneath the connection information. The analytics heading and independent Date Range control follow it. Missing credentials direct the administrator to settings without offering a misleading refresh action. Public rendering continues to use only a matching validated snapshot and never calls the read API.

No analytics reports or endpoints were added. This branch starts from merged PR #3 (b143a788e96c39db2914206cf1dcf022b8e84a0b).

Naming

• npm: @blackswampai/emdash-plugin-openanalytics
• Repository: BlackSwampAI/emdash-plugin-openanalytics
• EmDash plugin ID: openanalytics
• Display name: OpenAnalytics

Verified current EmDash conventions and the absence of a generated-settings save callback against upstream 54209bc9bd0b48e12bdefa8ac971da01ced7990f. The repository was renamed after the coherent branch was committed and pushed. The old GitHub API path resolves to the same repository, and old git URLs still reach this release branch. Code, routes, tests, package metadata, docs, demo and artifact checks now use the final identity.

Installation

The private read key is configured after npm installation, through EmDash plugin settings. No OpenAnalytics credential belongs in the install command, astro.config.mjs, or source code.

The README now leads with a short quick start, separate Install/Configure instructions, host encryption-key setup, and the automatic connection flow. oa_sk_... remains private/server-only; the plugin retrieves the public oa_pk_... browser key automatically.

Screenshots

Real EmDash plus synthetic analytics, captured with Playwright. The harness starts with blank settings, fills and saves the native settings form, makes no explicit validation call, verifies automatic connection and analytics, and checks that revisiting does not revalidate. Screenshots and their rendered DOM/HTML, responses and process output are checked for secret exposure.

Desktop overview

Reports

640px responsive view

Security

EmDash encrypts the write-only secret setting using EMDASH_ENCRYPTION_KEY. Private routes retain plugins:manage, authentication and CSRF protection; both plugin POST routes now bound input to 4 KiB. Credential-bearing requests reject redirects, time out after five seconds, and bound upstream JSON to 1 MiB. Errors use safe fixed messages; implausible Retry-After values are ignored. Configuration fingerprints isolate snapshots, including changed API/key and transient-failure cases.

Existing self-hosted HTTP support is retained to avoid an unexpected policy change. Settings, the README and remote-HTTP connection details explicitly warn that HTTP transmits the private key without encryption and recommend HTTPS for production. Tracker script/collector URLs remain administrator-trusted deployment values, validated for permitted HTTP(S) syntax and absence of credentials.

Updated Vitest to patched 4.1.11; both production-only and complete pnpm audit report no known vulnerabilities. Separate Luna Medium security, package/docs, regression, screenshot and independent final reviews completed; meaningful findings were fixed and personally inspected.

Validation

• 138 tests pass across six test files, including automatic setup, matching snapshots, range/revisit reuse, changed key/API isolation, failed validation/retry, transient failures, public tracking, secret suppression and declared/streamed body limits.
• Typecheck, lint, formatting, build, package verification and npm pack dry-run pass locally.
• Node 22, Node 24 and screenshot jobs all passed on final head a493db6cbe068289887cd839d477fee8f4515d18, for both push CI and PR CI.
• Actual EmDash setup from blank settings passes through the native settings form; saving requires no explicit validation call.

Package

0.1.0 is a public scoped ESM package with explicit public access, matching entrypoint/types/exports, emdash >=1.0.1 <2 peer compatibility, Node >=22.16, MIT license and the final repository/homepage/bugs URLs. No production dependencies or publishing workflow were added.

Final local npm tarball: 26,465 bytes compressed, 88,144 bytes unpacked, seven files, manually inspected and scanned:

LICENSE
README.md
package.json
dist/index.mjs
dist/index.d.mts
docs/implementation-footprint.md
docs/upstream-contracts.md

An exact file allowlist prevents demo/test code, screenshots, .env, databases and temporary files from entering the package. Credential, local-path and test-import artifact checks pass. Production output imports only the EmDash runtime. prepublishOnly is a verification guard; it does not publish.

Migration

Pre-release installations using the old emdash-openanalytics plugin ID must re-enter their OpenAnalytics settings once after updating.

The public 0.1.0 starts cleanly with openanalytics; no pre-release settings migration subsystem was added.

Release status

Ready for 0.1.0 publication after merge and final real-site smoke test.

Nothing has been published. This PR is not automatically merged. The configured NPM_TOKEN remains unused; first publication and the later OIDC transition are separate release actions.