Configuration, permissions, and audience policies#

Status: accepted planning decision. This repository copy captures the configuration interview for offline reading and PR review. The canonical resolution is Define configuration, permissions, and audience policies; subsequent changes should keep this document and the tracker aligned.

Established design pattern#

Developer-composed configuration with optional helpers and presets is an established SnagBadger design pattern. Developers can configure individual settings directly, use provided profiles, nest selectors, or compose settings for different consumers. Helpers offer convenience without imposing mandatory structure. The Valibot comparison describes the desired composition experience, not a schema-library choice.

Profiles such as dev and public are customizable starting points. Their names introduce no special runtime modes or permission rules. Every behavior comes from the resulting developer configuration.

Configuration and access#

• Developers explicitly configure enablement, capabilities, enabled harvesters, collection, reporter-adjustable controls, and evidence review.
• Reporter controls are available only where developer configuration permits them. Reporters may narrow allowed collection but cannot expand developer-authorized capabilities.
• Helpers may select configuration by hostname, environment variables, or custom checks. Audience and deployment environment are independent: the host may select different settings for authenticated QA staff and customers on the same production site.
• Configuration resolves at initialization. Changing it requires reinitialization for now.
• The adopting host owns identity, access checks, and environment rules. SnagBadger does not introduce a built-in identity or role system in this scope.
• UI visibility does not grant submission authorization. Destination services enforce their own authorization, and developer settings cannot bypass browser-required capture prompts.

Earlier discussion of fixed public-mode harvester selection and Dev/QA-only controls was superseded by the developer-composed pattern. Those behaviors can be profile defaults, but developers can customize them individually.

History and review#

Developers can enable diagnostic history, choose whether it starts on or off, and decide whether reporters may adjust it. Optional persistence across page reloads is in scope. Retention limits, storage mechanisms, per-harvester behavior, and expiration/cleanup semantics remain implementation-design questions.

Developers can configure evidence review directly or use provided profiles/helpers. Detailed QA review and end-user submission without an evidence-review dialog are both supported through settings. Exact review settings and profile defaults remain implementation choices.

Reuse and consumer-specific configuration#

A project may provide snagBadger.config.ts for its application and reporting skills to reuse. Sharing is optional. Separate configurations and developer-composed splits for the in-app reporter, launcher/button, and test-run reports are supported too.

Reuse project/provider destination settings and submission behavior where useful without requiring identical settings across consumers. Integration configuration owns reusable composition and resolution; individual consumers interpret the resulting settings rather than introducing competing resolution rules.

Privileged credentials remain appropriate to the consuming execution environment and are not copied into exported HTML. The configuration split and credential-loading interface are developer-composable implementation decisions; this decision imposes no mandatory file topology.

Illustrative composition#

These examples express the user's intended composition style. Function names, signatures, selector behavior, and wildcard syntax are illustrative, not implemented or frozen interfaces.

initSnagBadger(defaultSnagBadgerDevProfile());

initSnagBadger(
  pickConfigByHost({
    '*.prod.com': pickConfigByCustomCb({
      dev: {
        check: () => isLoggedInAsDev(),
        config: defaultSnagBadgerDevProfile(),
      },
      publicUser: {
        check: () => !isLoggedInAsDev(),
        config: defaultSnagBadgerPublicProfile(),
      },
    }),
    '*.stage.com': defaultSnagBadgerDevProfile(),
  }),
);

init(splitConfigForReports(buttonConfig, reportConfig));

First-match selection with an optional fallback and no-match disablement was the preferred direction. The user explicitly deferred exact helper semantics to implementation; it is not a finalized function specification.

Roadmap implications and deferred work#

This decision supersedes the original requirement to implement both in-place configuration and a built-in server URL immediately. Built-in remote configuration, live remote enablement, caching/outage behavior, and mid-capture remote revocation are deferred. A future custom configuration function may fetch settings from a server. Define the optional server and hosted-service boundary retains ownership of that service discussion.

The SnagBadger roadmap now indexes this resolution and reflects initialization-time configuration and optional configuration reuse. The rest of the roadmap remains owned by its existing decision threads.

Report/evidence schemas remain with Define the shared bug report and evidence model. Configuration schemas, exact helpers, lifecycle details, storage mechanisms, and server implementation are deferred to the appropriate implementation or decision work. This record does not authorize product implementation.