@getargvio/argvio 0.1.0 → 0.5.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Histogram, Counter } from '@opentelemetry/api';
+import { Tracer, Histogram, Counter } from '@opentelemetry/api';
 import { Logger } from '@opentelemetry/api-logs';
 import { LoggerProvider } from '@opentelemetry/sdk-logs';
 import { MeterProvider } from '@opentelemetry/sdk-metrics';
@@ -15,17 +15,20 @@ import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
  * allowed at the tier below it. Compare with plain `<`/`<=`/`>=` — the
  * numeric values are significant, not just distinct enum tags.
  *
- * TODO(schema): the wire string values in {@link tierToString} are
- * provisional pending the server-side allowlist file being confirmed.
- * They MUST match the `public` server's semantic allowlist exactly, or
- * the server will reject/strip the resource attribute.
+ * The wire string values in {@link tierToString} MUST match the
+ * consent_tiers names in the `public` server's allowlist
+ * (schema/allowlist/v1.yaml in getargvio/argvio) exactly, or the server
+ * rejects the record.
  */
 declare const 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.
+     */
     readonly 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. */
     readonly 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`. */
     readonly Full: 2;
     /**
      * The explicit opt-in tier: raw error detail (stack traces, messages)
@@ -77,6 +80,18 @@ declare const ErrorCategory: {
 };
 type ErrorCategory = (typeof ErrorCategory)[keyof typeof ErrorCategory];
 declare function isValidErrorCategory(value: string): value is ErrorCategory;
+/**
+ * What a vendor's classifier returns for an error: the {@link ErrorCategory}
+ * plus, optionally, a fixed-vocabulary `reason` that says more precisely
+ * what failed (e.g. `"no-token"`, `"invalid-url"`). The reason must be an
+ * identifier chosen in code (`^[a-z0-9][a-z0-9._-]*$`, at most 64 bytes),
+ * never error text or anything derived from user input; one that doesn't
+ * match is dropped, not rewritten. Sent at `Tier.Basic`+.
+ */
+interface ErrorClassification {
+    category: ErrorCategory;
+    reason?: string;
+}
 
 /**
  * Resolves the consent tier that should be used for the current
@@ -186,6 +201,19 @@ interface ClientOptions {
      * build itself rather than any individual invocation.
      */
     resourceAttributes?: Record<string, string>;
+    /**
+     * Where the install ID (`cli.install_id`, `Tier.Basic`+) is persisted.
+     * Defaults to `argvio-install-id` in the same per-CLI config directory
+     * as `FileConsentProvider`'s consent file. `''` turns install IDs off.
+     */
+    installIdPath?: string;
+    /**
+     * How this CLI was installed (for example `'brew'`, `'npm'`, `'curl'` or
+     * `'binary'`), reported on the session start event at every consent tier.
+     * The SDK can't tell on its own, so the vendor supplies it, typically from
+     * a value stamped in at build time. Omit to send nothing.
+     */
+    installMethod?: string;
 }
 
 /** A snapshot of in-process telemetry-about-telemetry: never sent over the network. */
@@ -198,7 +226,32 @@ interface Stats {
     recoveredErrors: number;
 }
 
+/** Options for {@link Client.recordCounter}. */
+interface CounterOptions {
+    /**
+     * Splits the counter into series (e.g. a tool or HTTP verb). A fixed
+     * identifier chosen in code, subject to the same rules as the counter name.
+     */
+    label?: string;
+}
+/** One completed command, for {@link Client.recordCommand}. */
+interface CommandResult {
+    /** The full command path, as for {@link Client.recordCommandInvocation}. */
+    path: string;
+    /** Names (never values) of the flags the user set. Only sent at `Tier.Basic`+. */
+    flagNames?: readonly string[];
+    /** When the command began, in epoch milliseconds. Defaults to `durationMs` before now. */
+    startMs?: number;
+    /** How long the command ran, in milliseconds. */
+    durationMs: number;
+    /** The command's exit code; non-zero counts as an error. */
+    exitCode: number;
+}
 interface ClientParams {
+    cliName?: string;
+    installIdPath?: string | undefined;
+    installMethod?: string | undefined;
+    tracer?: Tracer;
     disabled: boolean;
     initError: Error | null;
     tier: Tier;
@@ -210,8 +263,8 @@ interface ClientParams {
     logger?: Logger;
     latencyHist?: Histogram;
     invocationsCounter?: Counter;
-    sessionsCounter?: Counter;
     errorEventsCounter?: Counter;
+    productCounter?: Counter;
 }
 /**
  * The entry point for emitting telemetry. Every method is safe to call
@@ -232,14 +285,21 @@ declare class Client {
     private shuttingDown;
     private shutdownStarted;
     private sessionId;
+    private sessionStarted;
+    private readonly cliName;
+    private readonly installIdPath;
+    private readonly installMethod;
+    private installId;
+    private readonly activatedFeatures;
+    private readonly tracer;
     private readonly tracerProvider;
     private readonly meterProvider;
     private readonly loggerProvider;
     private readonly logger;
     private readonly latencyHist;
     private readonly invocationsCounter;
-    private readonly sessionsCounter;
     private readonly errorEventsCounter;
+    private readonly productCounter;
     /** @internal use {@link createClient} */
     constructor(params: ClientParams);
     private enabled;
@@ -248,46 +308,83 @@ declare class Client {
     private gate;
     private tierAttr;
     private emitEvent;
+    private emitEventNow;
+    private name;
     /**
-     * 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.
      */
     private ensureSessionId;
     /**
-     * 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.
+     */
+    private identityAttrs;
+    /**
+     * 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(): void;
-    /** Records the end of a CLI process session. Call once, symmetric with {@link recordSessionStart}. */
-    recordSessionEnd(): void;
     /**
      * 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: string, flagNames?: readonly string[]): void;
     /**
-     * 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: string, code: number): void;
+    recordCommand(result: CommandResult): void;
     /**
-     * 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: string, durationMs: number): void;
+    recordFeatureActivated(feature: string, commandPath?: string): void;
     /** Records that a command's help output was requested (`-h`/`--help` or an explicit help command). */
     recordHelpFlagUsage(commandPath: string): void;
     /**
@@ -296,10 +393,43 @@ declare class Client {
      * 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: string, category?: ErrorCategory): void;
+    recordError(commandPath: string, category?: ErrorCategory, reason?: string): void;
+    /**
+     * 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: string, n: number, options?: CounterOptions): void;
     /**
      * Returns an {@link OptInScope} if, and only if, this Client's resolved
      * consent tier is `Tier.OptIn`; otherwise returns `undefined`. There is
@@ -359,6 +489,11 @@ declare function createClient(apiKey: string, cliName: string, cliVersion: strin
 
 /** Reports whether the current process appears to be running inside a CI system. */
 declare function isCI(): boolean;
+/**
+ * Returns which CI provider the process runs in, `'unknown'` for an
+ * unrecognized CI system, or `undefined` outside CI.
+ */
+declare function detectCIProvider(): string | undefined;
 /**
  * Reports whether the `DO_NOT_TRACK` environment variable
  * (https://do-not-track.dev) requests telemetry be disabled. Any value
@@ -435,20 +570,86 @@ declare class FileConsentProvider implements ConsentProvider {
  * can assert on them without relying on string literals staying in
  * sync.
  *
- * TODO(schema): these keys are provisional and must be checked against
- * the authoritative server-side allowlist before v0.1.0 ships.
+ * Every event, span, metric and attribute name in this file is taken from
+ * the `public` server's allowlist (schema/allowlist/v1.yaml in
+ * getargvio/argvio), which rejects anything else. Change them only
+ * together with a server-side schema version.
  */
-declare const AttrCommandPath = "cli.command.path";
-declare const AttrCommandFlags = "cli.command.flags";
+declare const AttrCommandName = "cli.command.name";
 declare const AttrExitCode = "cli.command.exit_code";
-declare const AttrHelpUsed = "cli.command.help_used";
-declare const AttrSessionId = "cli.session.id";
-declare const AttrErrorCategory = "cli.error.category";
-/** TierOptIn only. */
+declare const AttrDurationMs = "cli.command.duration_ms";
+/** `Tier.Basic`+. Peak resident set size of the process, in bytes. */
+declare const AttrPeakRssBytes = "cli.process.peak_rss_bytes";
+/** `Tier.Basic`+. User plus system CPU time of the process, in milliseconds. */
+declare const AttrCpuTimeMs = "cli.process.cpu_time_ms";
+/**
+ * `Tier.Basic`+. Size of the CLI's binary, in bytes. Only on
+ * `cli.session.started`, and only for a Node single executable application.
+ */
+declare const AttrBinarySizeBytes = "cli.binary.size_bytes";
+/**
+ * `Tier.Basic`+. Time from process start to the point the command begins
+ * running, in milliseconds. Only on `cli.session.started`.
+ */
+declare const AttrStartupDurationMs = "cli.startup.duration_ms";
+/** `Tier.Basic`+. */
+declare const AttrFlagNames = "cli.flag.names";
+/** `Tier.Basic`+. */
+declare const AttrSessionId = "cli.session_id";
+/** `Tier.Basic`+. */
+declare const AttrInstallId = "cli.install_id";
+declare const AttrHelpFlag = "cli.help.flag";
+/** How the CLI was installed; supplied by the vendor via the `installMethod` option. */
+declare const AttrInstallMethod = "cli.install.method";
+/** `Tier.Basic`+. A fixed feature identifier supplied by the vendor. */
+declare const AttrActivationFeature = "cli.activation.feature";
+/** `Tier.Basic`+. */
+declare const AttrErrorType = "cli.error.type";
+/**
+ * `Tier.Basic`+. A vendor-assigned reason from a fixed vocabulary, alongside
+ * the error type. Never error text.
+ */
+declare const AttrErrorReason = "cli.error.reason";
+/** `Tier.OptIn` only. */
 declare const AttrErrorMessage = "cli.error.message";
-/** TierOptIn only. */
-declare const AttrErrorStack = "cli.error.stack";
-/** The name of the histogram instrument `recordLatency` records to (unit: milliseconds). */
+/** `Tier.OptIn` only. */
+declare const AttrErrorStack = "cli.error.stacktrace";
+/**
+ * Every tier. The name of a vendor-defined counter, a fixed identifier
+ * chosen in code. Sent on `cli.counter`.
+ */
+declare const AttrCounterName = "cli.counter.name";
+/**
+ * Every tier. An optional fixed identifier that splits one counter into
+ * series, chosen in code. Sent on `cli.counter`.
+ */
+declare const AttrCounterLabel = "cli.counter.label";
+/** Log event names. */
+declare const EventSessionStarted = "cli.session.started";
+declare const EventCommandInvoked = "cli.command.invoked";
+declare const EventCommandCompleted = "cli.command.completed";
+declare const EventFeatureActivated = "cli.feature.activated";
+declare const EventHelpViewed = "cli.help.viewed";
+declare const EventErrorRaised = "cli.error.raised";
+/**
+ * Prefixes the name of the span `recordCommand` emits for each command
+ * (e.g. `cli.command.deploy.push`). The server's command dashboards
+ * (frequency, latency, error rate, exit codes) are built from these spans.
+ */
+declare const SpanCommandPrefix = "cli.command.";
+/** Metric instrument names. */
+declare const MetricCommandInvocations = "cli.command.invocations";
+/** Unit: milliseconds. */
 declare const MetricCommandDuration = "cli.command.duration";
+declare const MetricErrors = "cli.errors";
+/** Unit: 1. A vendor-defined counter, see {@link Client.recordCounter}. */
+declare const MetricCounter = "cli.counter";
+
+/** Resource attribute keys describing the CLI build and host, promoted by the server into filterable columns. */
+declare const ResourceAttrCLIVersion = "cli.version";
+declare const ResourceAttrOS = "cli.os";
+declare const ResourceAttrArch = "cli.arch";
+declare const ResourceAttrIsCI = "cli.is_ci";
+declare const ResourceAttrCIProvider = "cli.ci_provider";
 
-export { AttrCommandFlags, AttrCommandPath, AttrErrorCategory, AttrErrorMessage, AttrErrorStack, AttrExitCode, AttrHelpUsed, AttrSessionId, Client, type ClientOptions, type ConsentProvider, DEFAULT_AUTH_HEADER, DEFAULT_ENDPOINT_GRPC, DEFAULT_ENDPOINT_HTTP, DEFAULT_EXPORT_TIMEOUT_MS, DEFAULT_QUEUE_SIZE, DEFAULT_SHUTDOWN_TIMEOUT_MS, DisabledProvider, EnvConsentProvider, ErrorCategory, FileConsentProvider, type FileConsentProviderOptions, MetricCommandDuration, OptInScope, RESOURCE_ATTR_TIER, StaticProvider, type Stats, Tier, type Transport, 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, type ClientOptions, type CommandResult, type ConsentProvider, type CounterOptions, DEFAULT_AUTH_HEADER, DEFAULT_ENDPOINT_GRPC, DEFAULT_ENDPOINT_HTTP, DEFAULT_EXPORT_TIMEOUT_MS, DEFAULT_QUEUE_SIZE, DEFAULT_SHUTDOWN_TIMEOUT_MS, DisabledProvider, EnvConsentProvider, ErrorCategory, type ErrorClassification, EventCommandCompleted, EventCommandInvoked, EventErrorRaised, EventFeatureActivated, EventHelpViewed, EventSessionStarted, FileConsentProvider, type FileConsentProviderOptions, MetricCommandDuration, MetricCommandInvocations, MetricCounter, MetricErrors, OptInScope, RESOURCE_ATTR_TIER, ResourceAttrArch, ResourceAttrCIProvider, ResourceAttrCLIVersion, ResourceAttrIsCI, ResourceAttrOS, SpanCommandPrefix, StaticProvider, type Stats, Tier, type Transport, chainProviders, clampTier, createClient, detectCIProvider, isCI, isDoNotTrackRequested, isValidErrorCategory, isValidTier, parseTier, tierAllows, tierToString };