@getargvio/argvio 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,454 @@
+import { Histogram, Counter } from '@opentelemetry/api';
+import { Logger } from '@opentelemetry/api-logs';
+import { LoggerProvider } from '@opentelemetry/sdk-logs';
+import { MeterProvider } from '@opentelemetry/sdk-metrics';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+
+/**
+ * The consent tier a CLI user (or their organization) has granted for
+ * telemetry collection. Gates both which `record*` calls are allowed to
+ * emit which fields, and the value sent on the `cli.analytics.tier`
+ * resource attribute, which the public ingest server re-validates and
+ * enforces as a backstop.
+ *
+ * Tiers are strictly ordered: each tier is a superset of the fields
+ * 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.
+ */
+declare const Tier: {
+    /** No persistent or cross-invocation identifiers; aggregate counts only. */
+    readonly Anonymous: 0;
+    /** Adds command path, flag names (not values), exit code, and latency. */
+    readonly Basic: 1;
+    /** Adds session correlation and classified (not raw) error signatures. */
+    readonly Full: 2;
+    /**
+     * The explicit opt-in tier: raw error detail (stack traces, messages)
+     * and any other field the allowlist marks opt-in-only. Never the
+     * default; a vendor or user must positively select it.
+     */
+    readonly OptIn: 3;
+};
+type Tier = (typeof Tier)[keyof typeof Tier];
+/** The OTel resource attribute key the tier is reported under. */
+declare const RESOURCE_ATTR_TIER = "cli.analytics.tier";
+/** Returns the wire value sent on the `cli.analytics.tier` resource attribute. */
+declare function tierToString(tier: Tier): string;
+/**
+ * Parses a wire tier string (as produced by {@link tierToString}) back
+ * into a {@link Tier}. Returns `undefined` if `value` does not match a
+ * known tier — callers should fail closed to `Tier.Anonymous` in that
+ * case, never assume the highest tier.
+ */
+declare function parseTier(value: string): Tier | undefined;
+/** Reports whether `value` is a known {@link Tier}. */
+declare function isValidTier(value: number): value is Tier;
+/**
+ * Reports whether `tier` permits emitting a field scoped to `required`.
+ * A session resolved to `Tier.Full`, for example, `tierAllows(Tier.Full,
+ * Tier.Basic)` and `tierAllows(Tier.Full, Tier.Full)` but not
+ * `tierAllows(Tier.Full, Tier.OptIn)`.
+ */
+declare function tierAllows(tier: Tier, required: Tier): boolean;
+/** Returns the lower of `tier` and `ceiling`. */
+declare function clampTier(tier: Tier, ceiling: Tier): Tier;
+/**
+ * A coarse, vendor-assigned classification of an error — deliberately
+ * not the error's message or type name, both of which can carry
+ * arbitrary (and potentially sensitive) free-form text. This SDK does
+ * not attempt to infer a category from an error value itself; the
+ * vendor's own error handling already knows which of these applies.
+ */
+declare const ErrorCategory: {
+    readonly Unknown: "unknown";
+    /** Bad input, invalid flags/args. */
+    readonly User: "user";
+    readonly Validation: "validation";
+    readonly Network: "network";
+    readonly Auth: "auth";
+    readonly Internal: "internal";
+    readonly Timeout: "timeout";
+    readonly Canceled: "canceled";
+};
+type ErrorCategory = (typeof ErrorCategory)[keyof typeof ErrorCategory];
+declare function isValidErrorCategory(value: string): value is ErrorCategory;
+
+/**
+ * Resolves the consent tier that should be used for the current
+ * process. Consulted once per {@link Client}, synchronously, at
+ * construction time (cached for the process lifetime — consent is not
+ * expected to change mid-invocation of a short-lived CLI command).
+ *
+ * `resolve` here is **synchronous**: Node's single-threaded event loop
+ * has no way to synchronously await a Promise, and `createClient` must
+ * return a fully
+ * resolved, usable Client without an async round-trip (see the "why
+ * createClient is synchronous" note in client.ts). Implementations must
+ * therefore be fast and local only — env vars, an already-loaded config
+ * object, a synchronous local file read — never network I/O. A provider
+ * that throws is treated identically to `Tier.Anonymous` (fail closed).
+ */
+interface ConsentProvider {
+    resolve(): Tier;
+}
+/**
+ * A {@link ConsentProvider} that always resolves to a fixed tier. Useful
+ * for tests, for vendors who resolve consent themselves before
+ * constructing the Client, or as a fallback wrapped by
+ * {@link chainProviders}.
+ */
+declare class StaticProvider implements ConsentProvider {
+    private readonly tier;
+    constructor(tier: Tier);
+    resolve(): Tier;
+}
+/**
+ * A {@link ConsentProvider} that always resolves to `Tier.Anonymous`. It
+ * exists as an explicit, self-documenting choice distinct from "a
+ * provider that happens to return anonymous".
+ */
+declare class DisabledProvider implements ConsentProvider {
+    resolve(): Tier;
+}
+/**
+ * Returns a {@link ConsentProvider} that tries each provider in order
+ * and returns the first successful (non-throwing) result. If all
+ * providers throw, it throws {@link errNoProviderResolved} (the caller
+ * treats that as `Tier.Anonymous`, same as any other thrown error). Lets
+ * a vendor compose, e.g., "env override, then config file, then
+ * anonymous default" without writing that logic themselves.
+ */
+declare function chainProviders(...providers: ReadonlyArray<ConsentProvider | null | undefined>): ConsentProvider;
+
+type Transport = 'http' | 'grpc';
+/**
+ * The hosted public ingest endpoint for OTLP/HTTP. Overridden by
+ * `options.endpoint` for self-hosted/on-prem deployments.
+ *
+ * TODO(schema): confirm the production hostname; this is a placeholder.
+ */
+declare const DEFAULT_ENDPOINT_HTTP = "https://ingest.argvio.io:4318";
+/** The hosted public ingest endpoint for OTLP/gRPC. Same TODO(schema) status as above. */
+declare const DEFAULT_ENDPOINT_GRPC = "ingest.argvio.io:4317";
+/**
+ * The metadata/header key the API key is sent under.
+ *
+ * TODO(schema): confirm against the public server's actual auth
+ * contract; placeholder pending that being pasted into this repo.
+ */
+declare const DEFAULT_AUTH_HEADER = "x-argvio-api-key";
+declare const DEFAULT_EXPORT_TIMEOUT_MS = 10000;
+declare const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5000;
+declare const DEFAULT_QUEUE_SIZE = 2048;
+/** Configures a {@link Client} constructed by `createClient`. */
+interface ClientOptions {
+    /**
+     * Overrides the OTLP collector endpoint. Defaults to the hosted
+     * public endpoint appropriate for `transport`.
+     */
+    endpoint?: string;
+    /**
+     * Selects the OTLP wire transport. Defaults to `'http'` so a CLI that
+     * embeds it doesn't pull in a gRPC client stack by default. Pass
+     * `'grpc'` if you need gRPC.
+     */
+    transport?: Transport;
+    /** Disables transport security. Only intended for local development against a self-hosted collector without TLS. */
+    insecure?: boolean;
+    /** Overrides the header the API key is sent under. Rarely needed. */
+    authHeader?: string;
+    /** The consent tier used when no `consentProvider` is supplied, or if it rejects/times out. Defaults to `Tier.Anonymous`. */
+    defaultTier?: Tier;
+    /** Resolves the session's consent tier at construction time. If unset, `defaultTier` is used directly. */
+    consentProvider?: ConsentProvider;
+    /**
+     * Fully disables the client: `createClient` returns a Client that
+     * performs zero network calls and whose `record*` methods are no-ops
+     * with negligible overhead. Equivalent to setting `ARGVIO_DISABLED=1`,
+     * and also engaged automatically when `DO_NOT_TRACK` requests it.
+     */
+    disabled?: boolean;
+    /** Bounds how long a single export attempt may take. */
+    exportTimeoutMs?: number;
+    /** Bounds how long `flush`/`shutdown` may block waiting for in-flight data to be exported. */
+    shutdownTimeoutMs?: number;
+    /** Bounds the number of pending records buffered before new records are dropped (counted, never blocking). */
+    queueSize?: number;
+    /**
+     * Additional static OTel resource attributes (e.g. a build channel or
+     * distribution identifier). Not tier-gated and not part of the
+     * taxonomy — use sparingly, for attributes that describe the CLI
+     * build itself rather than any individual invocation.
+     */
+    resourceAttributes?: Record<string, string>;
+}
+
+/** A snapshot of in-process telemetry-about-telemetry: never sent over the network. */
+interface Stats {
+    /** Records dropped because a batch queue was full rather than blocking the host CLI. */
+    queueOverflowDropped: number;
+    /** Records/fields dropped because the resolved consent tier didn't permit them. */
+    belowTierDropped: number;
+    /** Internal errors recovered from; should always be zero. */
+    recoveredErrors: number;
+}
+
+interface ClientParams {
+    disabled: boolean;
+    initError: Error | null;
+    tier: Tier;
+    queueSize: number;
+    shutdownTimeoutMs: number;
+    tracerProvider?: NodeTracerProvider;
+    meterProvider?: MeterProvider;
+    loggerProvider?: LoggerProvider;
+    logger?: Logger;
+    latencyHist?: Histogram;
+    invocationsCounter?: Counter;
+    sessionsCounter?: Counter;
+    errorEventsCounter?: Counter;
+}
+/**
+ * The entry point for emitting telemetry. Every method is safe to call
+ * on a disabled Client (explicitly disabled, `DO_NOT_TRACK`/`ARGVIO_DISABLED`,
+ * or degraded due to a construction error) — vendors never need to
+ * check `disabled` before using a Client.
+ *
+ * Construct via {@link createClient}, never directly.
+ */
+declare class Client {
+    readonly tier: Tier;
+    readonly disabled: boolean;
+    /** Set if construction encountered a problem; the Client still degrades to a safe disabled no-op. */
+    readonly initError: Error | null;
+    private readonly counters;
+    private readonly queue;
+    private readonly shutdownTimeoutMs;
+    private shuttingDown;
+    private shutdownStarted;
+    private sessionId;
+    private readonly tracerProvider;
+    private readonly meterProvider;
+    private readonly loggerProvider;
+    private readonly logger;
+    private readonly latencyHist;
+    private readonly invocationsCounter;
+    private readonly sessionsCounter;
+    private readonly errorEventsCounter;
+    /** @internal use {@link createClient} */
+    constructor(params: ClientParams);
+    private enabled;
+    /** A snapshot of in-process counters about dropped records. Never sent over the network. */
+    stats(): Stats;
+    private gate;
+    private tierAttr;
+    private emitEvent;
+    /**
+     * Lazily generates a session correlation ID at `Tier.Full`+. 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.
+     */
+    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.
+     *
+     * 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.
+     */
+    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.
+     */
+    recordExitCode(commandPath: string, code: number): void;
+    /**
+     * Records how long a command took to execute, in milliseconds, on a
+     * histogram (`cli.command.duration`). Available at every tier.
+     */
+    recordLatency(commandPath: string, durationMs: number): void;
+    /** Records that a command's help output was requested (`-h`/`--help` or an explicit help command). */
+    recordHelpFlagUsage(commandPath: string): void;
+    /**
+     * Records that a command failed with an error, classified by
+     * `category` rather than its raw message or stack trace — this is
+     * 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`).
+     */
+    recordError(commandPath: string, category?: ErrorCategory): void;
+    /**
+     * Returns an {@link OptInScope} if, and only if, this Client's resolved
+     * consent tier is `Tier.OptIn`; otherwise returns `undefined`. There is
+     * no other way to reach raw error detail (message, stack trace)
+     * anywhere in this package — it's structurally impossible to pass that
+     * data through {@link recordError}'s signature.
+     */
+    optIn(): OptInScope | undefined;
+    /** @internal called only by {@link OptInScope}. */
+    _recordErrorDetail(commandPath: string, err: Error, stack?: string): void;
+    /**
+     * Blocks until all telemetry queued so far has been handed to the
+     * exporters and an export attempt has completed, or `timeoutMs`
+     * elapses, whichever comes first. Safe to call on a disabled Client
+     * (a no-op).
+     */
+    flush(timeoutMs?: number): Promise<void>;
+    /**
+     * Flushes any queued telemetry (best-effort, bounded by `timeoutMs`)
+     * and releases all background resources. After `shutdown`, the Client
+     * permanently behaves as a disabled no-op. Safe to call on a disabled
+     * Client, and safe to call more than once.
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
+}
+/**
+ * Exposes telemetry capabilities that require the user's explicit
+ * `Tier.OptIn` consent, structurally separated from {@link Client} so
+ * that raw error content (messages, stack traces) can never be passed
+ * through a lower-tier code path by mistake or misuse.
+ */
+declare class OptInScope {
+    private readonly client;
+    constructor(client: Client);
+    /** Records an error's message at full fidelity. */
+    recordErrorDetail(commandPath: string, err: Error): void;
+    /** Identical to {@link recordErrorDetail} but also attaches a raw stack trace. */
+    recordErrorDetailWithStack(commandPath: string, err: Error, stack: string): void;
+}
+/**
+ * Constructs a {@link Client}. `apiKey`, `cliName`, and `cliVersion` are
+ * always required; everything else has a sane default and is set via
+ * `options`.
+ *
+ * `createClient` is synchronous and **never throws**: if construction
+ * encounters a problem (e.g. the exporter transport can't be built, or a
+ * `ConsentProvider` throws), it returns a Client already degraded to a
+ * disabled no-op, with `client.initError` describing why. Callers may
+ * inspect `initError` but are not required to before using the returned
+ * Client safely.
+ *
+ * `createClient` resolves consent through a synchronous
+ * {@link ConsentProvider} — see that interface's doc comment for why
+ * resolution has to be synchronous on Node's single-threaded event loop.
+ */
+declare function createClient(apiKey: string, cliName: string, cliVersion: string, options?: ClientOptions): Client;
+
+/** Reports whether the current process appears to be running inside a CI system. */
+declare function isCI(): boolean;
+/**
+ * Reports whether the `DO_NOT_TRACK` environment variable
+ * (https://do-not-track.dev) requests telemetry be disabled. Any value
+ * other than unset, empty, "0", or "false" is treated as a request.
+ */
+declare function isDoNotTrackRequested(): boolean;
+/**
+ * A {@link ConsentProvider} that caps the resolved tier at
+ * `Tier.Anonymous` when the process appears to be running in a CI
+ * environment. It resolves `Tier.Anonymous` in that case and rejects
+ * otherwise, so it's meant to be placed ahead of other providers in a
+ * {@link chainProviders} call — it "wins" only when CI is detected,
+ * deferring to the next provider otherwise.
+ *
+ * Reasoning: CI runs are usually unattended, share no single human
+ * user's stored consent preference, and can run at high volume (every
+ * commit, every matrix leg). We still allow anonymous-tier telemetry
+ * (e.g. install/build counts) by default rather than fully disabling,
+ * because that data has real product value and carries no identifying
+ * fields at `Tier.Anonymous` by construction. Vendors who want CI runs
+ * fully silent can pass `disabled: true` or check `isCI()` themselves.
+ *
+ * `DO_NOT_TRACK` is handled separately (see {@link isDoNotTrackRequested})
+ * and is enforced by the Client as a full disable, not a tier cap: it's
+ * a standing, cross-tool opt-out signal a user or environment sets
+ * deliberately, so it's honored as "no telemetry" rather than "least
+ * telemetry".
+ */
+declare class EnvConsentProvider implements ConsentProvider {
+    resolve(): Tier;
+}
+
+interface FileConsentProviderOptions {
+    /** Overrides the default config file location entirely. */
+    path?: string;
+}
+/**
+ * The reference {@link ConsentProvider} implementation: reads a small
+ * JSON file at a conventional per-CLI config location, namespaced under
+ * the vendor's own CLI name to avoid collisions between unrelated CLIs
+ * that both embed this SDK.
+ *
+ * Reads/writes are synchronous (see {@link ConsentProvider}'s doc
+ * comment for why) — a small local JSON file read is cheap enough that
+ * this doesn't meaningfully block startup.
+ *
+ * Use `options.path` to override the location entirely (e.g. a vendor
+ * that already has its own config file and wants to store the tier
+ * alongside it under a different mechanism should implement their own
+ * {@link ConsentProvider} instead).
+ */
+declare class FileConsentProvider implements ConsentProvider {
+    /** The resolved config file path (after defaults/overrides), primarily for diagnostics and tests. */
+    readonly path: string | undefined;
+    constructor(cliName: string, options?: FileConsentProviderOptions);
+    /**
+     * 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(): 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: Tier): void;
+}
+
+/**
+ * Attribute keys used on emitted signals. Exported so vendors and tests
+ * 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.
+ */
+declare const AttrCommandPath = "cli.command.path";
+declare const AttrCommandFlags = "cli.command.flags";
+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 AttrErrorMessage = "cli.error.message";
+/** TierOptIn only. */
+declare const AttrErrorStack = "cli.error.stack";
+/** The name of the histogram instrument `recordLatency` records to (unit: milliseconds). */
+declare const MetricCommandDuration = "cli.command.duration";
+
+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 };