@getargvio/argvio 0.1.0 → 0.5.0

package/dist/index.js

@@ -1,7 +1,11 @@
+import { SpanStatusCode } from '@opentelemetry/api';
 import { SeverityNumber } from '@opentelemetry/api-logs';
 import { LoggerProvider, BatchLogRecordProcessor } from '@opentelemetry/sdk-logs';
 import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
 import { NodeTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { readFileSync, mkdirSync, writeFileSync, statSync } from 'fs';
 import { Metadata } from '@grpc/grpc-js';
 import { OTLPTraceExporter as OTLPTraceExporter$1 } from '@opentelemetry/exporter-trace-otlp-http';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
@@ -9,22 +13,22 @@ import { OTLPMetricExporter as OTLPMetricExporter$1 } from '@opentelemetry/expor
 import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-grpc';
 import { OTLPLogExporter as OTLPLogExporter$1 } from '@opentelemetry/exporter-logs-otlp-http';
 import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-grpc';
-import { readFileSync, mkdirSync, writeFileSync } from 'fs';
 import { resourceFromAttributes } from '@opentelemetry/resources';
 import { ATTR_SERVICE_VERSION, ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
-import { randomBytes } from 'crypto';
-import { homedir } from 'os';
-import { dirname, join } from 'path';
+import { randomBytes, randomUUID } from 'crypto';
 
 // src/client.ts
 
 // src/tier.ts
 var Tier = {
-  /** No persistent or cross-invocation identifiers; aggregate counts only. */
+  /**
+   * No persistent or cross-invocation identifiers: command name, exit
+   * code, duration, CLI version, OS/arch and CI environment only.
+   */
   Anonymous: 0,
-  /** Adds command path, flag names (not values), exit code, and latency. */
+  /** Adds an opaque per-process session ID, an opaque per-install ID, flag names (never values), and classified (not raw) error types. */
   Basic: 1,
-  /** Adds session correlation and classified (not raw) error signatures. */
+  /** Reserved: the server allowlist permits some fields here, but this SDK sends nothing beyond `Tier.Basic`. */
   Full: 2,
   /**
    * The explicit opt-in tier: raw error detail (stack traces, messages)
@@ -38,7 +42,7 @@ var TIER_STRINGS = {
   [Tier.Anonymous]: "anonymous",
   [Tier.Basic]: "basic",
   [Tier.Full]: "full",
-  [Tier.OptIn]: "opt-in"
+  [Tier.OptIn]: "optin_plus"
 };
 function tierToString(tier) {
   return TIER_STRINGS[tier] ?? "unknown";
@@ -51,6 +55,7 @@ function parseTier(value) {
       return Tier.Basic;
     case "full":
       return Tier.Full;
+    case "optin_plus":
     case "opt-in":
       return Tier.OptIn;
     default:
@@ -82,6 +87,72 @@ function isValidErrorCategory(value) {
   return ERROR_CATEGORY_VALUES.has(value);
 }
 
+// src/errors.ts
+var ArgvioError = class extends Error {
+  constructor(message) {
+    super(`argvio: ${message}`);
+    this.name = "ArgvioError";
+  }
+};
+var errNoProviderResolved = new ArgvioError("no consent provider resolved a tier");
+var errNoConsentFile = new ArgvioError("no consent config file path resolved");
+var errUnknownTierValue = new ArgvioError("unknown tier value in consent config");
+
+// src/consentFile.ts
+function userConfigDir() {
+  switch (process.platform) {
+    case "win32":
+      return process.env["APPDATA"];
+    case "darwin":
+      return join(homedir(), "Library", "Application Support");
+    default:
+      return process.env["XDG_CONFIG_HOME"] || join(homedir(), ".config");
+  }
+}
+function defaultInstallIdPath(cliName) {
+  const consentPath = defaultConsentPath(cliName);
+  return consentPath ? join(dirname(consentPath), "argvio-install-id") : void 0;
+}
+function defaultConsentPath(cliName) {
+  const dir = userConfigDir();
+  if (!dir) return void 0;
+  return join(dir, cliName || "argvio", "argvio-consent.json");
+}
+var FileConsentProvider = class {
+  /** The resolved config file path (after defaults/overrides), primarily for diagnostics and tests. */
+  path;
+  constructor(cliName, options = {}) {
+    this.path = options.path || defaultConsentPath(cliName);
+  }
+  /**
+   * A missing file, unreadable file, or malformed contents all throw
+   * synchronously, so callers should place `FileConsentProvider` inside
+   * `chainProviders` with a sane fallback (e.g.
+   * `new StaticProvider(Tier.Anonymous)`).
+   */
+  resolve() {
+    if (!this.path) throw errNoConsentFile;
+    const data = readFileSync(this.path, "utf8");
+    const parsed = JSON.parse(data);
+    const tier = parseTier(parsed.tier ?? "");
+    if (tier === void 0) throw errUnknownTierValue;
+    return tier;
+  }
+  /**
+   * Persists `tier` as the chosen consent tier, creating the parent
+   * directory if needed. Intended for use by a vendor's first-run
+   * consent prompt. Does not itself enforce any tier ceiling — it's the
+   * vendor's own UX writing the user's explicit choice.
+   */
+  store(tier) {
+    if (!this.path) throw errNoConsentFile;
+    if (!isValidTier(tier)) throw errUnknownTierValue;
+    mkdirSync(dirname(this.path), { recursive: true, mode: 448 });
+    const contents = { tier: tierToString(tier) };
+    writeFileSync(this.path, JSON.stringify(contents), { mode: 384 });
+  }
+};
+
 // src/options.ts
 var DEFAULT_ENDPOINT_HTTP = "https://ingest.argvio.io:4318";
 var DEFAULT_ENDPOINT_GRPC = "ingest.argvio.io:4317";
@@ -89,6 +160,7 @@ var DEFAULT_AUTH_HEADER = "x-argvio-api-key";
 var DEFAULT_EXPORT_TIMEOUT_MS = 1e4;
 var DEFAULT_SHUTDOWN_TIMEOUT_MS = 5e3;
 var DEFAULT_QUEUE_SIZE = 2048;
+var MAX_INSTALL_METHOD_LENGTH = 32;
 function resolveConfig(apiKey, cliName, cliVersion, options = {}) {
   const transport = options.transport ?? "http";
   return {
@@ -105,7 +177,9 @@ function resolveConfig(apiKey, cliName, cliVersion, options = {}) {
     exportTimeoutMs: options.exportTimeoutMs && options.exportTimeoutMs > 0 ? options.exportTimeoutMs : DEFAULT_EXPORT_TIMEOUT_MS,
     shutdownTimeoutMs: options.shutdownTimeoutMs && options.shutdownTimeoutMs > 0 ? options.shutdownTimeoutMs : DEFAULT_SHUTDOWN_TIMEOUT_MS,
     queueSize: options.queueSize && options.queueSize > 0 ? options.queueSize : DEFAULT_QUEUE_SIZE,
-    resourceAttributes: options.resourceAttributes ?? {}
+    resourceAttributes: options.resourceAttributes ?? {},
+    installIdPath: options.installIdPath !== void 0 ? options.installIdPath || void 0 : defaultInstallIdPath(cliName),
+    installMethod: options.installMethod?.slice(0, MAX_INSTALL_METHOD_LENGTH) || void 0
   };
 }
 var SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
@@ -153,37 +227,6 @@ function buildExporters(cfg) {
     })
   };
 }
-var SDK_NAME = "@getargvio/argvio";
-function sdkVersion() {
-  try {
-    const pkgUrl = new URL("../package.json", import.meta.url);
-    const pkg = JSON.parse(readFileSync(pkgUrl, "utf8"));
-    return pkg.version ?? "unknown";
-  } catch {
-    return "unknown";
-  }
-}
-function buildResource(cfg) {
-  return resourceFromAttributes({
-    [ATTR_SERVICE_NAME]: cfg.cliName,
-    [ATTR_SERVICE_VERSION]: cfg.cliVersion,
-    "telemetry.sdk.name": SDK_NAME,
-    "telemetry.sdk.version": sdkVersion(),
-    "telemetry.sdk.language": "nodejs",
-    ...cfg.resourceAttributes
-  });
-}
-
-// src/errors.ts
-var ArgvioError = class extends Error {
-  constructor(message) {
-    super(`argvio: ${message}`);
-    this.name = "ArgvioError";
-  }
-};
-var errNoProviderResolved = new ArgvioError("no consent provider resolved a tier");
-var errNoConsentFile = new ArgvioError("no consent config file path resolved");
-var errUnknownTierValue = new ArgvioError("unknown tier value in consent config");
 
 // src/consentEnv.ts
 var CI_ENV_VARS = [
@@ -210,6 +253,21 @@ function isCI() {
     return value !== void 0 && value !== "" && value !== "false" && value !== "0";
   });
 }
+var CI_PROVIDERS = [
+  ["GITHUB_ACTIONS", "github_actions"],
+  ["GITLAB_CI", "gitlab_ci"],
+  ["CIRCLECI", "circleci"],
+  ["BUILDKITE", "buildkite"],
+  ["JENKINS_URL", "jenkins"],
+  ["TRAVIS", "travis"]
+];
+function detectCIProvider() {
+  for (const [envVar, provider] of CI_PROVIDERS) {
+    const value = process.env[envVar];
+    if (value && value !== "false" && value !== "0") return provider;
+  }
+  return isCI() ? "unknown" : void 0;
+}
 function isDoNotTrackRequested() {
   const value = process.env["DO_NOT_TRACK"];
   if (value === void 0) return false;
@@ -221,15 +279,139 @@ var EnvConsentProvider = class {
     throw errNoProviderResolved;
   }
 };
-var AttrCommandPath = "cli.command.path";
-var AttrCommandFlags = "cli.command.flags";
+
+// src/resource.ts
+var ResourceAttrCLIVersion = "cli.version";
+var ResourceAttrOS = "cli.os";
+var ResourceAttrArch = "cli.arch";
+var ResourceAttrIsCI = "cli.is_ci";
+var ResourceAttrCIProvider = "cli.ci_provider";
+function normalizeOS(platform) {
+  switch (platform) {
+    case "linux":
+    case "darwin":
+      return platform;
+    case "win32":
+      return "windows";
+    default:
+      return "other";
+  }
+}
+function normalizeArch(arch) {
+  switch (arch) {
+    case "x64":
+      return "amd64";
+    case "arm64":
+    case "arm":
+      return arch;
+    case "ia32":
+      return "386";
+    default:
+      return "other";
+  }
+}
+var SDK_NAME = "@getargvio/argvio";
+function sdkVersion() {
+  try {
+    const pkgUrl = new URL("../package.json", import.meta.url);
+    const pkg = JSON.parse(readFileSync(pkgUrl, "utf8"));
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function buildResource(cfg) {
+  const ciProvider = detectCIProvider();
+  return resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: cfg.cliName,
+    [ATTR_SERVICE_VERSION]: cfg.cliVersion,
+    "telemetry.sdk.name": SDK_NAME,
+    "telemetry.sdk.version": sdkVersion(),
+    "telemetry.sdk.language": "nodejs",
+    [ResourceAttrCLIVersion]: cfg.cliVersion,
+    [ResourceAttrOS]: normalizeOS(process.platform),
+    [ResourceAttrArch]: normalizeArch(process.arch),
+    [ResourceAttrIsCI]: ciProvider !== void 0,
+    ...ciProvider ? { [ResourceAttrCIProvider]: ciProvider } : {},
+    ...cfg.resourceAttributes
+  });
+}
+var AttrCommandName = "cli.command.name";
 var AttrExitCode = "cli.command.exit_code";
-var AttrHelpUsed = "cli.command.help_used";
-var AttrSessionId = "cli.session.id";
-var AttrErrorCategory = "cli.error.category";
+var AttrDurationMs = "cli.command.duration_ms";
+var AttrPeakRssBytes = "cli.process.peak_rss_bytes";
+var AttrCpuTimeMs = "cli.process.cpu_time_ms";
+var AttrBinarySizeBytes = "cli.binary.size_bytes";
+var AttrStartupDurationMs = "cli.startup.duration_ms";
+var AttrFlagNames = "cli.flag.names";
+var AttrSessionId = "cli.session_id";
+var AttrInstallId = "cli.install_id";
+var AttrHelpFlag = "cli.help.flag";
+var AttrInstallMethod = "cli.install.method";
+var AttrActivationFeature = "cli.activation.feature";
+var AttrErrorType = "cli.error.type";
+var AttrErrorReason = "cli.error.reason";
 var AttrErrorMessage = "cli.error.message";
-var AttrErrorStack = "cli.error.stack";
+var AttrErrorStack = "cli.error.stacktrace";
+var AttrCounterName = "cli.counter.name";
+var AttrCounterLabel = "cli.counter.label";
+var EventSessionStarted = "cli.session.started";
+var EventCommandInvoked = "cli.command.invoked";
+var EventCommandCompleted = "cli.command.completed";
+var EventFeatureActivated = "cli.feature.activated";
+var EventHelpViewed = "cli.help.viewed";
+var EventErrorRaised = "cli.error.raised";
+var SpanCommandPrefix = "cli.command.";
+var MetricCommandInvocations = "cli.command.invocations";
 var MetricCommandDuration = "cli.command.duration";
+var MetricErrors = "cli.errors";
+var MetricCounter = "cli.counter";
+var MAX_COMMAND_NAME_LENGTH = 128;
+var MAX_ACTIVATION_FEATURE_LENGTH = 64;
+var MAX_IDENTIFIER_LENGTH = 64;
+var IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+function isValidIdentifier(value) {
+  return typeof value === "string" && value.length <= MAX_IDENTIFIER_LENGTH && IDENTIFIER_PATTERN.test(value);
+}
+function commandName(cliName, commandPath) {
+  let parts = commandPath.split(/\s+/).filter(Boolean);
+  if (parts.length > 1 && parts[0] === cliName) parts = parts.slice(1);
+  const name = parts.join(".") || cliName || "root";
+  return name.slice(0, MAX_COMMAND_NAME_LENGTH);
+}
+function readProcessResourceUsage() {
+  const usage = {};
+  try {
+    const rssBytes = Math.round(process.resourceUsage().maxRSS * 1024);
+    if (Number.isFinite(rssBytes) && rssBytes > 0) usage.peakRssBytes = rssBytes;
+  } catch {
+  }
+  try {
+    const { user, system } = process.cpuUsage();
+    const cpuMs = Math.round((user + system) / 1e3);
+    if (Number.isFinite(cpuMs) && cpuMs > 0) usage.cpuTimeMs = cpuMs;
+  } catch {
+  }
+  return usage;
+}
+function readStartupDurationMs() {
+  try {
+    const ms = Math.round(process.uptime() * 1e3);
+    return Number.isFinite(ms) && ms > 0 ? ms : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readBinarySizeBytes() {
+  try {
+    const sea = process.getBuiltinModule?.("node:sea");
+    if (!sea?.isSea()) return void 0;
+    const size = statSync(process.execPath).size;
+    return Number.isFinite(size) && size > 0 ? size : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function newSessionId() {
   try {
     return randomBytes(16).toString("hex");
@@ -237,6 +419,24 @@ function newSessionId() {
     return "";
   }
 }
+var INSTALL_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function loadOrCreateInstallId(path) {
+  if (!path) return "";
+  try {
+    const existing = readFileSync(path, "utf8").trim();
+    if (INSTALL_ID_PATTERN.test(existing)) return existing;
+  } catch {
+  }
+  try {
+    const id = randomUUID();
+    mkdirSync(dirname(path), { recursive: true, mode: 448 });
+    writeFileSync(path, `${id}
+`, { mode: 384 });
+    return id;
+  } catch {
+    return "";
+  }
+}
 
 // src/safety.ts
 var ARGVIO_DEBUG = process.env["ARGVIO_DEBUG"] === "1";
@@ -354,14 +554,21 @@ var Client = class {
   shuttingDown = false;
   shutdownStarted = false;
   sessionId;
+  sessionStarted = false;
+  cliName;
+  installIdPath;
+  installMethod;
+  installId;
+  activatedFeatures = /* @__PURE__ */ new Set();
+  tracer;
   tracerProvider;
   meterProvider;
   loggerProvider;
   logger;
   latencyHist;
   invocationsCounter;
-  sessionsCounter;
   errorEventsCounter;
+  productCounter;
   /** @internal use {@link createClient} */
   constructor(params) {
     this.disabled = params.disabled;
@@ -375,8 +582,12 @@ var Client = class {
     this.logger = params.logger;
     this.latencyHist = params.latencyHist;
     this.invocationsCounter = params.invocationsCounter;
-    this.sessionsCounter = params.sessionsCounter;
     this.errorEventsCounter = params.errorEventsCounter;
+    this.productCounter = params.productCounter;
+    this.cliName = params.cliName ?? "";
+    this.installIdPath = params.installIdPath;
+    this.installMethod = params.installMethod;
+    this.tracer = params.tracer;
   }
   enabled() {
     return !this.disabled && !this.shuttingDown;
@@ -398,109 +609,193 @@ var Client = class {
   }
   emitEvent(name, severity, attributes = {}) {
     this.queue.push(() => {
-      this.logger?.emit({
-        eventName: name,
-        timestamp: Date.now(),
-        severityNumber: severity,
-        attributes: { ...this.tierAttr(), ...attributes }
-      });
+      this.emitEventNow(name, severity, attributes);
+    });
+  }
+  emitEventNow(name, severity, attributes = {}) {
+    this.logger?.emit({
+      eventName: name,
+      timestamp: Date.now(),
+      severityNumber: severity,
+      attributes: { ...this.tierAttr(), ...attributes }
     });
   }
+  name(commandPath) {
+    return commandName(this.cliName, commandPath);
+  }
   /**
-   * Lazily generates a session correlation ID at `Tier.Full`+. A random,
+   * Lazily generates a session correlation ID at `Tier.Basic`+. A random,
    * non-persistent identifier scoped to a single process invocation —
    * not a user or device identifier.
    */
   ensureSessionId() {
-    if (!tierAllows(this.tier, Tier.Full)) return "";
+    if (!tierAllows(this.tier, Tier.Basic)) return "";
     if (this.sessionId === void 0) {
       this.sessionId = newSessionId();
     }
     return this.sessionId;
   }
   /**
-   * Records the start of a CLI process session. Call once, as early as
-   * possible. At `Tier.Anonymous` this only increments an aggregate
-   * session counter. At `Tier.Basic`+ it also emits a `cli.session_start`
-   * event. At `Tier.Full`+ the event carries a per-process session
-   * correlation ID.
+   * The session and install ID attributes for a record, empty below
+   * `Tier.Basic`. May read or create the install ID file, so call it from
+   * inside a queued job rather than on the caller's stack.
+   */
+  identityAttrs(sessionId) {
+    const attrs = {};
+    if (sessionId) attrs[AttrSessionId] = sessionId;
+    if (tierAllows(this.tier, Tier.Basic)) {
+      this.installId ??= loadOrCreateInstallId(this.installIdPath);
+      if (this.installId) attrs[AttrInstallId] = this.installId;
+    }
+    return attrs;
+  }
+  /**
+   * Records the start of a CLI process session, which is what the server
+   * counts sessions, active installs and retention from. Call it as early
+   * as possible (the yargs/commander integrations do it for you); only the
+   * first call per Client emits anything.
+   *
+   * At `Tier.Anonymous` the event carries no identifiers. At `Tier.Basic`+
+   * it also carries the per-process session ID and the install ID, a
+   * random UUID persisted in the CLI's config directory the first time it
+   * is needed — never derived from the user or machine.
+   *
+   * At `Tier.Basic`+ it also carries startup overhead
+   * (`cli.startup.duration_ms`): the time from process start to this call,
+   * so it covers module loading and framework setup. Call it just before
+   * the command runs, as the integrations do. And when running as a Node
+   * single executable application, it carries the binary's size
+   * (`cli.binary.size_bytes`). Either is omitted if unavailable, never 0.
    */
   recordSessionStart() {
     safeRun(() => {
-      if (!this.enabled()) return;
+      if (!this.enabled() || this.sessionStarted) return;
+      this.sessionStarted = true;
+      const sessionId = this.ensureSessionId();
+      const basic = tierAllows(this.tier, Tier.Basic);
+      const startupMs = basic ? readStartupDurationMs() : void 0;
       this.queue.push(() => {
-        this.sessionsCounter?.add(1, this.tierAttr());
+        const attrs = this.identityAttrs(sessionId);
+        if (startupMs !== void 0) attrs[AttrStartupDurationMs] = startupMs;
+        if (basic) {
+          const sizeBytes = readBinarySizeBytes();
+          if (sizeBytes !== void 0) attrs[AttrBinarySizeBytes] = sizeBytes;
+        }
+        if (this.installMethod) attrs[AttrInstallMethod] = this.installMethod;
+        this.emitEventNow(EventSessionStarted, SeverityNumber.INFO, attrs);
       });
-      if (!tierAllows(this.tier, Tier.Basic)) return;
-      const attrs = {};
-      const id = this.ensureSessionId();
-      if (id) attrs[AttrSessionId] = id;
-      this.emitEvent("cli.session_start", SeverityNumber.INFO, attrs);
-    }, this.counters);
-  }
-  /** Records the end of a CLI process session. Call once, symmetric with {@link recordSessionStart}. */
-  recordSessionEnd() {
-    safeRun(() => {
-      if (!this.enabled() || !tierAllows(this.tier, Tier.Basic)) return;
-      const attrs = {};
-      const id = this.ensureSessionId();
-      if (id) attrs[AttrSessionId] = id;
-      this.emitEvent("cli.session_end", SeverityNumber.INFO, attrs);
     }, this.counters);
   }
   /**
    * Records that a command began executing. `commandPath` should be the
-   * full command path (e.g. `"mycli sub subsub"`), not just the leaf
-   * command name. `flagNames` is the list of flag *names* the user set —
-   * never flag values, which this SDK never accepts anywhere in the
-   * taxonomy.
+   * full command path (e.g. `"mycli sub subsub"`); it is reported as the
+   * dotted command name (`"sub.subsub"`). `flagNames` is the list of flag
+   * *names* the user set — never flag values, which this SDK never
+   * accepts anywhere in the taxonomy.
    *
-   * At `Tier.Anonymous` this only increments an aggregate invocation
-   * counter with no path/flag detail. At `Tier.Basic`+ the full command
-   * path and flag names are included.
+   * The command name is recorded at every tier; flag names and the
+   * session ID at `Tier.Basic`+.
    */
   recordCommandInvocation(commandPath, flagNames = []) {
     safeRun(() => {
       if (!this.enabled()) return;
+      const attrs = { [AttrCommandName]: this.name(commandPath) };
+      if (tierAllows(this.tier, Tier.Basic) && flagNames.length > 0) {
+        attrs[AttrFlagNames] = [...flagNames];
+      }
+      const sessionId = this.ensureSessionId();
       this.queue.push(() => {
-        this.invocationsCounter?.add(1, this.tierAttr());
+        this.emitEventNow(EventCommandInvoked, SeverityNumber.INFO, {
+          ...attrs,
+          ...this.identityAttrs(sessionId)
+        });
       });
-      if (!tierAllows(this.tier, Tier.Basic)) return;
-      const attrs = { [AttrCommandPath]: commandPath };
-      if (flagNames.length > 0) attrs[AttrCommandFlags] = [...flagNames];
-      this.emitEvent("cli.command_invocation", SeverityNumber.INFO, attrs);
     }, this.counters);
   }
   /**
-   * Records the exit code a command finished with. Pass `""` for
-   * `commandPath` if unknown (e.g. a single-command CLI). At
-   * `Tier.Anonymous` the exit code is recorded without a command path.
-   * At `Tier.Basic`+ the command path is included.
+   * Records a completed command: a `cli.command.<name>` span covering its
+   * execution, plus the `cli.command.invocations` and
+   * `cli.command.duration` metrics. This is what the server's command
+   * frequency, latency, error-rate and exit-code dashboards are built
+   * from, so call it once for every command that ran (the integrations
+   * do). Available at every tier; flag names, peak memory and CPU time
+   * only at `Tier.Basic`+.
+   *
+   * Peak memory (`cli.process.peak_rss_bytes`) and CPU time
+   * (`cli.process.cpu_time_ms`) are read once from the process, so they are
+   * process-wide and cumulative: right for a CLI that runs one command per
+   * process, but in a long-lived or multi-command process each call
+   * reports totals since the process started. A measure the platform can't
+   * provide is omitted.
    */
-  recordExitCode(commandPath, code) {
+  recordCommand(result) {
     safeRun(() => {
-      if (!this.gate(Tier.Anonymous)) return;
-      const attrs = { [AttrExitCode]: code };
-      if (tierAllows(this.tier, Tier.Basic) && commandPath) {
-        attrs[AttrCommandPath] = commandPath;
+      if (!this.enabled()) return;
+      const durationMs = Math.max(0, result.durationMs);
+      const startMs = result.startMs ?? Date.now() - durationMs;
+      const name = this.name(result.path);
+      const attrs = {
+        ...this.tierAttr(),
+        [AttrCommandName]: name,
+        [AttrExitCode]: result.exitCode
+      };
+      const spanAttrs = { ...attrs, [AttrDurationMs]: Math.round(durationMs) };
+      if (tierAllows(this.tier, Tier.Basic) && result.flagNames && result.flagNames.length > 0) {
+        spanAttrs[AttrFlagNames] = [...result.flagNames];
+      }
+      if (tierAllows(this.tier, Tier.Basic)) {
+        const { peakRssBytes, cpuTimeMs } = readProcessResourceUsage();
+        if (peakRssBytes !== void 0) spanAttrs[AttrPeakRssBytes] = peakRssBytes;
+        if (cpuTimeMs !== void 0) spanAttrs[AttrCpuTimeMs] = cpuTimeMs;
       }
-      const severity = code !== 0 ? SeverityNumber.WARN : SeverityNumber.INFO;
-      this.emitEvent("cli.exit_code", severity, attrs);
+      const sessionId = this.ensureSessionId();
+      this.queue.push(() => {
+        const span = this.tracer?.startSpan(SpanCommandPrefix + name, {
+          startTime: startMs,
+          attributes: spanAttrs
+        });
+        if (result.exitCode !== 0) span?.setStatus({ code: SpanStatusCode.ERROR });
+        span?.end(startMs + durationMs);
+        this.invocationsCounter?.add(1, attrs);
+        this.latencyHist?.record(durationMs, attrs);
+        this.emitEventNow(EventCommandCompleted, SeverityNumber.INFO, {
+          [AttrCommandName]: name,
+          [AttrExitCode]: result.exitCode,
+          [AttrDurationMs]: Math.round(durationMs),
+          ...this.identityAttrs(sessionId)
+        });
+      });
     }, this.counters);
   }
   /**
-   * Records how long a command took to execute, in milliseconds, on a
-   * histogram (`cli.command.duration`). Available at every tier.
+   * Records that the user used one of the vendor's features, so the server
+   * can tell which features an install has adopted and how soon after
+   * installing. Emitted at `Tier.Basic`+ only; nothing is sent at
+   * `Tier.Anonymous`. The event carries the feature name, the command name
+   * when `commandPath` is given, and the session and install IDs.
+   *
+   * `feature` must be a fixed identifier chosen by the vendor in code
+   * (e.g. `"export-csv"`), **never user input** such as a flag value, path
+   * or argument. It is truncated to the server's 64 character limit.
+   *
+   * Each feature is reported at most once per process, however often this
+   * is called, to keep volume down. The server derives "first use" per
+   * install itself, so repeat reports within a run add nothing.
    */
-  recordLatency(commandPath, durationMs) {
+  recordFeatureActivated(feature, commandPath) {
     safeRun(() => {
-      if (!this.gate(Tier.Anonymous)) return;
-      const attrs = { ...this.tierAttr() };
-      if (tierAllows(this.tier, Tier.Basic) && commandPath) {
-        attrs[AttrCommandPath] = commandPath;
-      }
+      if (!this.gate(Tier.Basic)) return;
+      const name = feature.slice(0, MAX_ACTIVATION_FEATURE_LENGTH);
+      if (!name || this.activatedFeatures.has(name)) return;
+      this.activatedFeatures.add(name);
+      const attrs = { [AttrActivationFeature]: name };
+      if (commandPath) attrs[AttrCommandName] = this.name(commandPath);
+      const sessionId = this.ensureSessionId();
       this.queue.push(() => {
-        this.latencyHist?.record(durationMs, attrs);
+        this.emitEventNow(EventFeatureActivated, SeverityNumber.INFO, {
+          ...attrs,
+          ...this.identityAttrs(sessionId)
+        });
       });
     }, this.counters);
   }
@@ -508,11 +803,10 @@ var Client = class {
   recordHelpFlagUsage(commandPath) {
     safeRun(() => {
       if (!this.gate(Tier.Anonymous)) return;
-      const attrs = { [AttrHelpUsed]: true };
-      if (tierAllows(this.tier, Tier.Basic) && commandPath) {
-        attrs[AttrCommandPath] = commandPath;
-      }
-      this.emitEvent("cli.help_flag_used", SeverityNumber.INFO, attrs);
+      this.emitEvent(EventHelpViewed, SeverityNumber.INFO, {
+        [AttrCommandName]: this.name(commandPath),
+        [AttrHelpFlag]: "help"
+      });
     }, this.counters);
   }
   /**
@@ -521,19 +815,73 @@ var Client = class {
    * deliberately the only error-recording capability available below
    * `Tier.OptIn`. Raw error detail is only reachable via {@link optIn}.
    *
-   * Requires `Tier.Full`+; at lower tiers this is a no-op (counted in
-   * `stats().belowTierDropped`).
+   * At every tier this counts the error on the `cli.errors` metric by
+   * command. At `Tier.Basic`+ the category is attached as the error type
+   * and a `cli.error.raised` event is emitted too, tied to the session and
+   * install.
+   *
+   * `reason` is an optional, finer classification from a fixed vocabulary
+   * you define (e.g. `"no-token"`, `"invalid-url"`), sent at `Tier.Basic`+
+   * as `cli.error.reason` on both of those. It must be an identifier chosen
+   * in code, **never error text or user input**: this SDK does not scrub it.
+   * It must match `^[a-z0-9][a-z0-9._-]*$` and be at most 64 bytes; one that
+   * doesn't is dropped (the error is still recorded, without a reason).
    */
-  recordError(commandPath, category = ErrorCategory.Unknown) {
+  recordError(commandPath, category = ErrorCategory.Unknown, reason) {
     safeRun(() => {
-      if (!this.gate(Tier.Full)) return;
+      if (!this.enabled()) return;
       const cat = isValidErrorCategory(category) ? category : ErrorCategory.Unknown;
-      const attrs = { [AttrErrorCategory]: cat };
-      if (commandPath) attrs[AttrCommandPath] = commandPath;
+      const basic = tierAllows(this.tier, Tier.Basic);
+      const attrs = { [AttrCommandName]: this.name(commandPath) };
+      if (basic) {
+        attrs[AttrErrorType] = cat;
+        if (isValidIdentifier(reason)) attrs[AttrErrorReason] = reason;
+      }
+      const sessionId = this.ensureSessionId();
       this.queue.push(() => {
-        this.errorEventsCounter?.add(1, { ...this.tierAttr(), [AttrErrorCategory]: cat });
+        this.errorEventsCounter?.add(1, { ...this.tierAttr(), ...attrs });
+        if (basic) {
+          this.emitEventNow(EventErrorRaised, SeverityNumber.ERROR, {
+            ...attrs,
+            ...this.identityAttrs(sessionId)
+          });
+        }
       });
-      this.emitEvent("cli.error", SeverityNumber.ERROR, attrs);
+    }, this.counters);
+  }
+  /**
+   * Adds `n` to a vendor-defined counter, sent as the `cli.counter` metric
+   * with the `cli.counter.name` and, if given, `cli.counter.label`
+   * attributes. Increments are summed in memory: one data point per name
+   * and label is sent at each export, however often this is called, so it
+   * is cheap in a hot loop.
+   *
+   * **Counters are accepted at the anonymous tier.** They are sent at every
+   * tier, including `Tier.Anonymous` and in CI, even when the user has made
+   * no consent choice. Nothing identifies the user, but `name` and `label`
+   * are strings you choose, so a mistake here puts text into anonymous
+   * data. They must be fixed identifiers chosen in code, **never user
+   * input, file paths, host names, URLs, tokens or anything derived from
+   * them**. This SDK does not scrub them.
+   *
+   * `name` and `label` must match `^[a-z0-9][a-z0-9._-]*$` and be at most
+   * 64 bytes. If either does not, nothing is recorded: the increment is
+   * dropped, not trimmed or sent without its label. `n` must be a positive
+   * integer; anything else is ignored. The server caps the number of
+   * distinct names and labels per tenant and folds the rest into `other`.
+   *
+   * Never throws, and does nothing on a disabled Client.
+   */
+  recordCounter(name, n, options = {}) {
+    safeRun(() => {
+      if (!this.gate(Tier.Anonymous)) return;
+      if (!isValidIdentifier(name)) return;
+      if (typeof n !== "number" || !Number.isSafeInteger(n) || n <= 0) return;
+      const label = options?.label;
+      if (label !== void 0 && !isValidIdentifier(label)) return;
+      const attrs = { ...this.tierAttr(), [AttrCounterName]: name };
+      if (label !== void 0) attrs[AttrCounterLabel] = label;
+      this.productCounter?.add(n, attrs);
     }, this.counters);
   }
   /**
@@ -551,10 +899,12 @@ var Client = class {
   _recordErrorDetail(commandPath, err, stack) {
     safeRun(() => {
       if (!this.gate(Tier.OptIn)) return;
-      const attrs = { [AttrErrorMessage]: err.message };
-      if (commandPath) attrs[AttrCommandPath] = commandPath;
+      const attrs = {
+        [AttrCommandName]: this.name(commandPath),
+        [AttrErrorMessage]: err.message
+      };
       if (stack) attrs[AttrErrorStack] = stack;
-      this.emitEvent("cli.error_detail", SeverityNumber.ERROR, attrs);
+      this.emitEvent(EventErrorRaised, SeverityNumber.ERROR, attrs);
     }, this.counters);
   }
   /**
@@ -567,13 +917,11 @@ var Client = class {
     if (!this.enabled()) return;
     await this.queue.waitForDrain(timeoutMs);
     await withTimeout(
-      Promise.all(
-        [
-          this.tracerProvider?.forceFlush(),
-          this.meterProvider?.forceFlush(),
-          this.loggerProvider?.forceFlush()
-        ].filter((p) => Boolean(p))
-      ).then(() => void 0),
+      Promise.allSettled([
+        this.tracerProvider?.forceFlush(),
+        this.meterProvider?.forceFlush(),
+        this.loggerProvider?.forceFlush()
+      ]).then(() => void 0),
       timeoutMs
     );
   }
@@ -589,13 +937,11 @@ var Client = class {
     this.shuttingDown = true;
     await this.queue.waitForDrain(timeoutMs);
     await withTimeout(
-      Promise.all(
-        [
-          this.tracerProvider?.shutdown(),
-          this.meterProvider?.shutdown(),
-          this.loggerProvider?.shutdown()
-        ].filter((p) => Boolean(p))
-      ).then(() => void 0),
+      Promise.allSettled([
+        this.tracerProvider?.shutdown(),
+        this.meterProvider?.shutdown(),
+        this.loggerProvider?.shutdown()
+      ]).then(() => void 0),
       timeoutMs
     );
   }
@@ -672,6 +1018,10 @@ function createClient(apiKey, cliName, cliVersion, options = {}) {
     const meter = meterProvider.getMeter(INSTRUMENTATION_NAME);
     const logger = loggerProvider.getLogger(INSTRUMENTATION_NAME);
     return new Client({
+      cliName,
+      installIdPath: cfg.installIdPath,
+      installMethod: cfg.installMethod,
+      tracer: tracerProvider.getTracer(INSTRUMENTATION_NAME),
       disabled: false,
       initError: null,
       tier,
@@ -685,14 +1035,17 @@ function createClient(apiKey, cliName, cliVersion, options = {}) {
         unit: "ms",
         description: "Duration of a CLI command invocation."
       }),
-      invocationsCounter: meter.createCounter("cli.invocations", {
-        description: "Count of CLI command invocations."
+      invocationsCounter: meter.createCounter(MetricCommandInvocations, {
+        unit: "1",
+        description: "Count of completed CLI command invocations."
       }),
-      sessionsCounter: meter.createCounter("cli.sessions", {
-        description: "Count of CLI process sessions."
-      }),
-      errorEventsCounter: meter.createCounter("cli.errors", {
+      errorEventsCounter: meter.createCounter(MetricErrors, {
+        unit: "1",
         description: "Count of recorded CLI errors."
+      }),
+      productCounter: meter.createCounter(MetricCounter, {
+        unit: "1",
+        description: "Vendor-defined counters, by fixed name and optional label."
       })
     });
   } catch (err) {
@@ -730,56 +1083,7 @@ function chainProviders(...providers) {
     }
   };
 }
-function userConfigDir() {
-  switch (process.platform) {
-    case "win32":
-      return process.env["APPDATA"];
-    case "darwin":
-      return join(homedir(), "Library", "Application Support");
-    default:
-      return process.env["XDG_CONFIG_HOME"] || join(homedir(), ".config");
-  }
-}
-function defaultConsentPath(cliName) {
-  const dir = userConfigDir();
-  if (!dir) return void 0;
-  return join(dir, cliName || "argvio", "argvio-consent.json");
-}
-var FileConsentProvider = class {
-  /** The resolved config file path (after defaults/overrides), primarily for diagnostics and tests. */
-  path;
-  constructor(cliName, options = {}) {
-    this.path = options.path || defaultConsentPath(cliName);
-  }
-  /**
-   * A missing file, unreadable file, or malformed contents all throw
-   * synchronously, so callers should place `FileConsentProvider` inside
-   * `chainProviders` with a sane fallback (e.g.
-   * `new StaticProvider(Tier.Anonymous)`).
-   */
-  resolve() {
-    if (!this.path) throw errNoConsentFile;
-    const data = readFileSync(this.path, "utf8");
-    const parsed = JSON.parse(data);
-    const tier = parseTier(parsed.tier ?? "");
-    if (tier === void 0) throw errUnknownTierValue;
-    return tier;
-  }
-  /**
-   * Persists `tier` as the chosen consent tier, creating the parent
-   * directory if needed. Intended for use by a vendor's first-run
-   * consent prompt. Does not itself enforce any tier ceiling — it's the
-   * vendor's own UX writing the user's explicit choice.
-   */
-  store(tier) {
-    if (!this.path) throw errNoConsentFile;
-    if (!isValidTier(tier)) throw errUnknownTierValue;
-    mkdirSync(dirname(this.path), { recursive: true, mode: 448 });
-    const contents = { tier: tierToString(tier) };
-    writeFileSync(this.path, JSON.stringify(contents), { mode: 384 });
-  }
-};
 
-export { AttrCommandFlags, AttrCommandPath, AttrErrorCategory, AttrErrorMessage, AttrErrorStack, AttrExitCode, AttrHelpUsed, AttrSessionId, Client, DEFAULT_AUTH_HEADER, DEFAULT_ENDPOINT_GRPC, DEFAULT_ENDPOINT_HTTP, DEFAULT_EXPORT_TIMEOUT_MS, DEFAULT_QUEUE_SIZE, DEFAULT_SHUTDOWN_TIMEOUT_MS, DisabledProvider, EnvConsentProvider, ErrorCategory, FileConsentProvider, MetricCommandDuration, OptInScope, RESOURCE_ATTR_TIER, StaticProvider, Tier, chainProviders, clampTier, createClient, isCI, isDoNotTrackRequested, isValidErrorCategory, isValidTier, parseTier, tierAllows, tierToString };
+export { AttrActivationFeature, AttrBinarySizeBytes, AttrCommandName, AttrCounterLabel, AttrCounterName, AttrCpuTimeMs, AttrDurationMs, AttrErrorMessage, AttrErrorReason, AttrErrorStack, AttrErrorType, AttrExitCode, AttrFlagNames, AttrHelpFlag, AttrInstallId, AttrInstallMethod, AttrPeakRssBytes, AttrSessionId, AttrStartupDurationMs, Client, DEFAULT_AUTH_HEADER, DEFAULT_ENDPOINT_GRPC, DEFAULT_ENDPOINT_HTTP, DEFAULT_EXPORT_TIMEOUT_MS, DEFAULT_QUEUE_SIZE, DEFAULT_SHUTDOWN_TIMEOUT_MS, DisabledProvider, EnvConsentProvider, ErrorCategory, EventCommandCompleted, EventCommandInvoked, EventErrorRaised, EventFeatureActivated, EventHelpViewed, EventSessionStarted, FileConsentProvider, MetricCommandDuration, MetricCommandInvocations, MetricCounter, MetricErrors, OptInScope, RESOURCE_ATTR_TIER, ResourceAttrArch, ResourceAttrCIProvider, ResourceAttrCLIVersion, ResourceAttrIsCI, ResourceAttrOS, SpanCommandPrefix, StaticProvider, Tier, chainProviders, clampTier, createClient, detectCIProvider, isCI, isDoNotTrackRequested, isValidErrorCategory, isValidTier, parseTier, tierAllows, tierToString };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map