Instrument CLI & SDK “First Run / First Use” Events and Attribute from Awareness → Activation Conversion

[timfong888]

Why

Current metrics of npm downloads is in accurate; this impedes accurate tracking of early activation.

Proposal

We want to instrument two packages (a CLI and an SDK) so we can measure conversion from awareness (docs/blog/tweets) → installation intent → actual activation/usage. Because npm download counts are not reliable proxies for unique installations or usage (per npm’s blog), we need to build our own event-tracking funnel.

Note: NOT intended for the filecoin-pin eng, it's intended as part of DevRel to review and scope.

BEFORE implementation, let me know if this takes more than X hours to see if it's worth it.

Reference from npm: https://blog.npmjs.org/post/92574016600/numeric-precision-matters-how-npm-download-counts-work.html

Key Requirements

Privacy Clarity

•	Track only anonymized IDs or hashes.
•	Document telemetry in README + privacy policy.
•	Provide explicit opt-out.

Types of information:

CLI first run
CLI entrypoint detects first run
Send a POST to /api/event with name=cli_first_run and relevant properties

SDK first use
SDK init or first API call
Same as above: name=sdk_first_use, include version, environment, etc.

await fetch('https://plausible.io/api/event', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${PLAUSIBLE_API_KEY}`
  },
  body: JSON.stringify({
    name: 'cli_first_run',
    url: 'https://yourdomain.dev/cli',
    domain: 'yourdomain.dev',
    props: {
      version: pkg.version,
      source: storedSource,
      os: process.platform
    }
  })
});