@newrelic/preflight 0.0.1-pre.1 → 1.0.1

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/shared/__test-utils__/log-output.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Test-only helper for asserting on captured stderr output
+ * (CODE_REVIEW §9.20).
+ *
+ * Across the test suite, the structured logger writes to stderr (which
+ * tests stub via `jest.spyOn(console, 'error').mockImplementation(...)`)
+ * and assertions then need to materialize the captured frames into a
+ * single concatenated string for `.toContain(...)` checks. The pattern
+ * `stderrSpy.mock.calls.map(c => c[0]).join('')` was repeated in
+ * `pricing.test.ts`, `config.test.ts`, `tokens.test.ts`, and
+ * `harvest-scheduler.test.ts` — 25 sites total. This helper exists so
+ * each site collapses to `getLogOutput(stderrSpy)`.
+ *
+ * Lives under `src/__test-utils__/` (Jest's conventional double-underscore
+ * directory for test-only support code) so the build-time tsconfig
+ * exclude can keep it out of `dist/` — see `tsconfig.json`'s `exclude`
+ * list. The file is not a test file (no `.test.ts` suffix) so Jest's
+ * `testMatch` will not try to run it.
+ */
+/**
+ * Minimal shape needed off a `jest.spyOn(console, 'error')` result.
+ * Spelled out as a structural interface rather than `jest.SpyInstance`
+ * so the helper doesn't depend on the (frequently-renamed) Jest type
+ * surface and stays narrow — `mock.calls[i][0]` is the only field we
+ * read.
+ */
+interface StderrSpyShape {
+    readonly mock: {
+        readonly calls: ReadonlyArray<ReadonlyArray<unknown>>;
+    };
+}
+/**
+ * Concatenate every stderr frame captured by `stderrSpy` into a single
+ * string suitable for `.toContain(...)` / `.toMatch(...)` assertions.
+ *
+ * Tests across this package only ever inspect the first argument of
+ * each `console.error` call (the log line itself), which matches the
+ * runtime behavior of the structured logger — it always emits the JSON
+ * payload as the sole call argument.
+ *
+ * The default separator is `''` (concatenated). Pass `'\n'` (or any
+ * other delimiter) when the assertion needs frame boundaries preserved
+ * — e.g. `getLogOutput(spy, '\n').split('\n')` to inspect frames
+ * individually. Both styles existed in the suite pre-helper and both
+ * are kept supported.
+ */
+export declare function getLogOutput(stderrSpy: StderrSpyShape, separator?: string): string;
+export {};
+//# sourceMappingURL=log-output.d.ts.map

package/dist/shared/__test-utils__/log-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-output.d.ts","sourceRoot":"","sources":["../../../src/shared/__test-utils__/log-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;GAMG;AACH,UAAU,cAAc;IACtB,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;CAC1E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,cAAc,EAAE,SAAS,GAAE,MAAW,GAAG,MAAM,CAEtF"}

package/dist/shared/__test-utils__/log-output.js

@@ -0,0 +1,38 @@
+/**
+ * Test-only helper for asserting on captured stderr output
+ * (CODE_REVIEW §9.20).
+ *
+ * Across the test suite, the structured logger writes to stderr (which
+ * tests stub via `jest.spyOn(console, 'error').mockImplementation(...)`)
+ * and assertions then need to materialize the captured frames into a
+ * single concatenated string for `.toContain(...)` checks. The pattern
+ * `stderrSpy.mock.calls.map(c => c[0]).join('')` was repeated in
+ * `pricing.test.ts`, `config.test.ts`, `tokens.test.ts`, and
+ * `harvest-scheduler.test.ts` — 25 sites total. This helper exists so
+ * each site collapses to `getLogOutput(stderrSpy)`.
+ *
+ * Lives under `src/__test-utils__/` (Jest's conventional double-underscore
+ * directory for test-only support code) so the build-time tsconfig
+ * exclude can keep it out of `dist/` — see `tsconfig.json`'s `exclude`
+ * list. The file is not a test file (no `.test.ts` suffix) so Jest's
+ * `testMatch` will not try to run it.
+ */
+/**
+ * Concatenate every stderr frame captured by `stderrSpy` into a single
+ * string suitable for `.toContain(...)` / `.toMatch(...)` assertions.
+ *
+ * Tests across this package only ever inspect the first argument of
+ * each `console.error` call (the log line itself), which matches the
+ * runtime behavior of the structured logger — it always emits the JSON
+ * payload as the sole call argument.
+ *
+ * The default separator is `''` (concatenated). Pass `'\n'` (or any
+ * other delimiter) when the assertion needs frame boundaries preserved
+ * — e.g. `getLogOutput(spy, '\n').split('\n')` to inspect frames
+ * individually. Both styles existed in the suite pre-helper and both
+ * are kept supported.
+ */
+export function getLogOutput(stderrSpy, separator = '') {
+    return stderrSpy.mock.calls.map((c) => String(c[0])).join(separator);
+}
+//# sourceMappingURL=log-output.js.map

package/dist/shared/__test-utils__/log-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-output.js","sourceRoot":"","sources":["../../../src/shared/__test-utils__/log-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAaH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,SAAyB,EAAE,YAAoB,EAAE;IAC5E,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACvE,CAAC"}

package/dist/shared/config.d.ts

@@ -0,0 +1,56 @@
+import type { LogLevel } from './logger.js';
+import type { TransportMode } from './transport/types.js';
+export interface AgentConfig {
+    readonly licenseKey: string;
+    readonly appName: string;
+    readonly enabled: boolean;
+    readonly recordContent: boolean;
+    readonly costTrackingEnabled: boolean;
+    readonly qualityTrackingEnabled: boolean;
+    readonly conversationTrackingEnabled: boolean;
+    readonly thinkingTrackingEnabled: boolean;
+    readonly customPricingFile: string | null;
+    readonly contentMaxLength: number;
+    readonly highSecurity: boolean;
+    readonly logLevel: LogLevel;
+    readonly collectorHost: string | null;
+    readonly accountId: string | null;
+    readonly attributionDefaults: Record<string, string> | null;
+    readonly otlpEndpoint: string | null;
+    readonly otlpHeaders: Readonly<Record<string, string>>;
+    readonly transport: TransportMode;
+    /**
+     * Identifies the consuming client in telemetry identifiers: HTTP
+     * `User-Agent` headers and OTel instrumentation scope / logger names.
+     * Defaults to `'ai-telemetry'` when not set.
+     *
+     * Pass `'preflight'` from the Preflight MCP server or `'my-agent'`
+     * from the TypeScript agent so telemetry from each consumer is
+     * distinguishable in the NR UI.
+     */
+    readonly clientName: string;
+}
+/**
+ * Load and validate agent config from `process.env`, with optional `overrides`
+ * winning over the env values. Returns a deep-frozen `AgentConfig` so the
+ * result cannot be mutated by accident or by a buggy consumer that holds a
+ * shared reference.
+ *
+ * Precedence: `overrides` (when present per key) > env vars > defaults. The
+ * function is stateless from the library's perspective — call it again to
+ * pick up env-var changes (12 documents the SIGHUP pattern).
+ *
+ * License-key validation enforces a printable-ASCII regex (20–128 chars,
+ * no whitespace) — strict enough to catch trailing newlines from `cat` pipes
+ * and empty strings, lenient enough to accept older keys without an `NRAL`
+ * suffix. Never logs the key value.
+ *
+ * @param overrides Optional partial config that wins over env vars.
+ * @returns Deep-frozen `AgentConfig`.
+ * @throws If `licenseKey` is missing or malformed.
+ */
+export type AgentConfigInput = Omit<Partial<AgentConfig>, 'attributionDefaults'> & {
+    attributionDefaults?: Record<string, string | undefined> | null;
+};
+export declare function loadConfig(overrides?: AgentConfigInput): Readonly<AgentConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/shared/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/shared/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAmB1D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,2BAA2B,EAAE,OAAO,CAAC;IAC9C,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC5D,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAmMD;;;;;;;;;;;;;;;;;;GAkBG;AAMH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,qBAAqB,CAAC,GAAG;IACjF,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;CACjE,CAAC;AAEF,wBAAgB,UAAU,CAAC,SAAS,CAAC,EAAE,gBAAgB,GAAG,QAAQ,CAAC,WAAW,CAAC,CA+G9E"}

package/dist/shared/config.js

@@ -0,0 +1,290 @@
+import { createLogger } from './logger.js';
+import { DEFAULT_CLIENT_NAME } from './transport/otlp-shared.js';
+/**
+ * Strings that count as `true`. The lowercased env
+ * value is checked against these literal sets — any other value falls
+ * through to the default.
+ */
+const ENV_TRUTHY = new Set(['true', '1', 'yes', 'on']);
+const ENV_FALSY = new Set(['false', '0', 'no', 'off']);
+/**
+ * Module-level config logger. Per 5 the underlying
+ * `createLogger` now resolves the minimum log level per-call via the cached
+ * `getMinLevel()`, so a runtime env mutation followed by `__resetLogLevelCache()`
+ * propagates here without re-constructing this logger.
+ */
+const configLogger = createLogger('config');
+/**
+ * Parse a boolean environment variable. Accepts `true|1|yes|on` as truthy
+ * and `false|0|no|off` as falsy (case-insensitive, 8). Any
+ * other value (or missing env var) returns the default. Unknown values emit
+ * a debug log so misconfigurations are diagnosable.
+ */
+function envBool(key, defaultValue) {
+    const raw = process.env[key];
+    if (raw === undefined)
+        return defaultValue;
+    const val = raw.toLowerCase().trim();
+    if (ENV_TRUTHY.has(val))
+        return true;
+    if (ENV_FALSY.has(val))
+        return false;
+    configLogger.debug(`${key}: unrecognized boolean value, falling back to default. Accepted: true|1|yes|on or false|0|no|off`, { value: raw, defaultValue });
+    return defaultValue;
+}
+/**
+ * Parse an integer environment variable. Out-of-bound values are clamped to
+ * the bound and emit a debug log so the override is observable
+ *.
+ */
+function envInt(key, defaultValue, bounds) {
+    const val = process.env[key];
+    if (val === undefined)
+        return defaultValue;
+    // Reject values with trailing garbage (e.g. '4kb', '1e3') that parseInt
+    // would accept silently; fall back to the default with a diagnostic log (§C2).
+    if (!/^-?\d+$/.test(val.trim())) {
+        configLogger.debug(`${key}: not a valid integer, using default`, { value: val, defaultValue });
+        return defaultValue;
+    }
+    const parsed = parseInt(val, 10);
+    if (Number.isNaN(parsed))
+        return defaultValue;
+    if (bounds?.min !== undefined && parsed < bounds.min) {
+        configLogger.debug(`${key}: value clamped to min`, { requested: parsed, min: bounds.min });
+        return bounds.min;
+    }
+    if (bounds?.max !== undefined && parsed > bounds.max) {
+        configLogger.debug(`${key}: value clamped to max`, { requested: parsed, max: bounds.max });
+        return bounds.max;
+    }
+    return parsed;
+}
+function envLogLevel(key, defaultValue) {
+    const val = process.env[key]?.toLowerCase().trim();
+    if (val === 'debug' || val === 'info' || val === 'warn' || val === 'error')
+        return val;
+    if (val !== undefined) {
+        // Use warn (not debug) so the diagnostic is visible even at the fallback
+        // 'info' log level — an invalid log level is always worth surfacing.
+        configLogger.warn(`${key}: unrecognized log level, using default`, {
+            value: val,
+            defaultValue,
+        });
+    }
+    return defaultValue;
+}
+// Returns the env var value, or null if the var is absent or empty string.
+// `export VAR=` in a shell produces '' — treat that the same as unset (§C3).
+function envOrNull(key) {
+    const v = process.env[key];
+    return v === undefined || v === '' ? null : v;
+}
+// Normalize a string override value: undefined passes through (fall back to
+// env); empty string coerces to null; any other value (including null) wins
+// over the env var. Mirrors envOrNull for the override path (§CFG3).
+function overrideString(v, envFn) {
+    if (v === undefined)
+        return envFn();
+    return v === '' ? null : v;
+}
+/**
+ * Parse the transport-mode env var. Accepts the same
+ * values as the `transport` field on `AgentConfig`. Unrecognized values
+ * fall back to the default and emit a debug log so misconfigurations are
+ * diagnosable.
+ */
+function envTransport(key, defaultValue) {
+    const raw = process.env[key];
+    if (raw === undefined)
+        return defaultValue;
+    const val = raw.toLowerCase().trim();
+    if (val === 'nr-events-api' || val === 'otlp' || val === 'both')
+        return val;
+    configLogger.debug(`${key}: unrecognized transport, falling back to default. Accepted: nr-events-api | otlp | both`, { value: raw, defaultValue });
+    return defaultValue;
+}
+function buildAttributionDefaults(overrideDefaults) {
+    const result = {};
+    // Env-var defaults for the four standard attribution fields.
+    //
+    // 11: empty-string env values are intentionally treated as
+    // "not set" via the truthiness check below. NR's events API rejects empty
+    // string attribute values, so a deliberately-empty env var (e.g. to "clear"
+    // a higher-precedence default) would only produce a 400 at ingest time —
+    // not the desired clear semantics. Consumers wanting to clear a default
+    // should pass `attributionDefaults: { feature: undefined }` (or omit the
+    // key entirely from overrides), not set the env var to "".
+    const envFeature = process.env.NEW_RELIC_AI_ATTRIBUTION_FEATURE;
+    const envTeam = process.env.NEW_RELIC_AI_ATTRIBUTION_TEAM;
+    const envUser = process.env.NEW_RELIC_AI_ATTRIBUTION_USER;
+    const envEnvironment = process.env.NEW_RELIC_AI_ATTRIBUTION_ENVIRONMENT;
+    // Truthiness check: exclude undefined (not set) and '' (empty — NR Events
+    // API rejects empty-string attributes, §3.3.11). Do NOT exclude '0' or
+    // 'false' — those are valid attribution tag values (§CFG4).
+    if (envFeature !== undefined && envFeature !== '')
+        result.feature = envFeature;
+    if (envTeam !== undefined && envTeam !== '')
+        result.team = envTeam;
+    if (envUser !== undefined && envUser !== '')
+        result.user = envUser;
+    if (envEnvironment !== undefined && envEnvironment !== '')
+        result.environment = envEnvironment;
+    // Merge override defaults (they win over env vars).
+    // Passing `undefined` as a value explicitly removes the key so that
+    // `attributionDefaults: { feature: undefined }` clears a prior env-set
+    // default, matching the documented "clear" pattern (§C1).
+    if (overrideDefaults) {
+        for (const [k, v] of Object.entries(overrideDefaults)) {
+            if (v === undefined) {
+                delete result[k];
+            }
+            else {
+                result[k] = v;
+            }
+        }
+    }
+    return Object.keys(result).length > 0 ? result : null;
+}
+// Per OTel spec for OTEL_EXPORTER_OTLP_HEADERS:
+//   - Comma-separated list of `key=value` pairs.
+//   - `=` and `,` inside a key OR value must be percent-encoded as `%3D` and `%2C`.
+//   - Whitespace around the `=` is stripped.
+//   - Only the FIRST `=` separates key from value (so a value can legitimately
+//     contain `=` if it appears later in the substring after percent-decoding).
+//   - Keys and values are percent-decoded after splitting.
+function parseOtlpHeaders(headerString) {
+    if (!headerString)
+        return {};
+    const result = {};
+    for (const pair of headerString.split(',')) {
+        const eqIdx = pair.indexOf('=');
+        if (eqIdx <= 0)
+            continue; // missing '=' or empty key — skip
+        // OTel spec: trim key whitespace; do NOT trim value (§CF1).
+        const rawKey = pair.slice(0, eqIdx).trim();
+        const rawValue = pair.slice(eqIdx + 1);
+        if (!rawKey)
+            continue;
+        let key;
+        let value;
+        try {
+            key = decodeURIComponent(rawKey);
+        }
+        catch {
+            // §11.4: warn so operators can diagnose a misconfigured auth header that
+            // will be forwarded malformed and likely rejected by the OTLP collector.
+            configLogger.warn('OTEL_EXPORTER_OTLP_HEADERS: malformed percent-encoding in key — using raw string', { rawKey });
+            key = rawKey;
+        }
+        try {
+            value = decodeURIComponent(rawValue);
+        }
+        catch {
+            // §11.4: same as key path — warn so a broken Authorization value is visible.
+            configLogger.warn('OTEL_EXPORTER_OTLP_HEADERS: malformed percent-encoding in value — using raw string', { rawKey });
+            value = rawValue;
+        }
+        result[key] = value;
+    }
+    return result;
+}
+// License keys must be printable ASCII (no whitespace, no control chars)
+// and a plausible length. We're deliberately lenient on the exact format
+// (no NRAL-suffix enforcement) to avoid false-rejecting older keys, but
+// strict enough to catch common mistakes: trailing newlines from `cat`
+// pipes, embedded CR/LF (would inject HTTP headers), or empty strings.
+const LICENSE_KEY_RE = /^[\x21-\x7E]{20,128}$/;
+export function loadConfig(overrides) {
+    const rawLicenseKey = overrides?.licenseKey ?? process.env.NEW_RELIC_LICENSE_KEY;
+    if (!rawLicenseKey) {
+        throw new Error('Missing required configuration: NEW_RELIC_LICENSE_KEY. ' +
+            'Set the NEW_RELIC_LICENSE_KEY environment variable or pass licenseKey in options.');
+    }
+    // Strip leading/trailing whitespace before validating — guards against
+    // accidental newlines from `cat key.txt`-style sourcing.
+    const licenseKey = rawLicenseKey.trim();
+    if (!LICENSE_KEY_RE.test(licenseKey)) {
+        throw new Error('Invalid configuration: NEW_RELIC_LICENSE_KEY must be 20-128 printable ASCII ' +
+            'characters with no whitespace. (Note: never log the key value.)');
+    }
+    const appName = overrides?.appName ?? process.env.NEW_RELIC_APP_NAME;
+    if (!appName) {
+        throw new Error('Missing required configuration: NEW_RELIC_APP_NAME. ' +
+            'Set the NEW_RELIC_APP_NAME environment variable or pass appName in options.');
+    }
+    // Reject control characters (CR/LF etc.) to prevent header injection if
+    // appName is ever used in an HTTP context, and cap length at 255 chars (§CF2).
+    if (/[\r\n\x00-\x1f]/.test(appName) || appName.length > 255) {
+        throw new Error('Invalid configuration: NEW_RELIC_APP_NAME must be 1-255 characters with no control characters.');
+    }
+    // Use explicit undefined-check so `accountId: null` in overrides wins over the
+    // env var — `??` would treat null as "not provided" and fall through to the
+    // env var, silently ignoring an explicit null override (§CFG1).
+    const accountId = overrides?.accountId !== undefined
+        ? overrides.accountId
+        : (process.env.NEW_RELIC_ACCOUNT_ID ?? null);
+    if (accountId !== null && !/^[1-9]\d*$/.test(accountId)) {
+        // 6: positive-integer-only, no leading zeros, any length.
+        // - Removes the prior 12-digit cap so consumers don't have to release a
+        //   new version when NR issues 13+ digit account IDs server-side.
+        // - Rejects '0' / leading-zero strings (e.g. '07' would have passed the
+        //   old `/^\d{1,12}$/` regex even though no NR account uses leading zeros).
+        // The upper bound is enforced server-side by the ingest API.
+        throw new Error('Invalid configuration: NEW_RELIC_ACCOUNT_ID must be a positive decimal integer (no leading zeros). ' +
+            `Received: "${accountId}"`);
+    }
+    // F3: hoist `transport` resolution so we can fail fast when
+    // accountId is missing for transports that need it. Without this check, the
+    // NR Events API URL becomes ".../accounts/null/events", which NR returns 404
+    // on; the harvest scheduler then silently retry-loops every batch until the
+    // retry buffer overflows. Surface the misconfiguration at startup instead.
+    const transport = overrides?.transport ?? envTransport('NEW_RELIC_AI_TRANSPORT', 'nr-events-api');
+    if ((transport === 'nr-events-api' || transport === 'both') && accountId === null) {
+        throw new Error(`Missing required configuration: NEW_RELIC_ACCOUNT_ID. ` +
+            `Required when transport is "${transport}" (NR Events API URLs include the account ID in the path). ` +
+            `Set the NEW_RELIC_ACCOUNT_ID environment variable or pass accountId in options. ` +
+            `Only the "otlp" transport mode can omit accountId.`);
+    }
+    const highSecurity = overrides?.highSecurity ?? envBool('NEW_RELIC_AI_HIGH_SECURITY', false);
+    const recordContent = highSecurity
+        ? false
+        : (overrides?.recordContent ?? envBool('NEW_RELIC_AI_RECORD_CONTENT', false));
+    // Build global attribution defaults from env vars and/or overrides
+    const attributionDefaults = buildAttributionDefaults(overrides?.attributionDefaults);
+    const config = {
+        licenseKey,
+        appName,
+        enabled: overrides?.enabled ?? envBool('NEW_RELIC_AI_ENABLED', true),
+        recordContent,
+        costTrackingEnabled: overrides?.costTrackingEnabled ?? envBool('NEW_RELIC_AI_COST_TRACKING', true),
+        qualityTrackingEnabled: overrides?.qualityTrackingEnabled ?? envBool('NEW_RELIC_AI_QUALITY_TRACKING', true),
+        conversationTrackingEnabled: overrides?.conversationTrackingEnabled ?? envBool('NEW_RELIC_AI_CONVERSATION_TRACKING', true),
+        thinkingTrackingEnabled: overrides?.thinkingTrackingEnabled ?? envBool('NEW_RELIC_AI_THINKING_TRACKING', true),
+        customPricingFile: overrideString(overrides?.customPricingFile, () => envOrNull('NEW_RELIC_AI_CUSTOM_PRICING_FILE')),
+        contentMaxLength: overrides?.contentMaxLength ??
+            envInt('NEW_RELIC_AI_CONTENT_MAX_LENGTH', 4096, { min: 1, max: 1_048_576 }),
+        highSecurity,
+        logLevel: overrides?.logLevel ?? envLogLevel('NEW_RELIC_AI_LOG_LEVEL', 'info'),
+        collectorHost: overrideString(overrides?.collectorHost, () => envOrNull('NEW_RELIC_HOST')),
+        accountId,
+        attributionDefaults,
+        otlpEndpoint: overrideString(overrides?.otlpEndpoint, () => envOrNull('OTEL_EXPORTER_OTLP_ENDPOINT')),
+        otlpHeaders: overrides?.otlpHeaders ?? parseOtlpHeaders(process.env.OTEL_EXPORTER_OTLP_HEADERS),
+        transport,
+        clientName: overrides?.clientName || process.env.NEW_RELIC_AI_CLIENT_NAME || DEFAULT_CLIENT_NAME,
+    };
+    return deepFreeze(config);
+}
+function deepFreeze(obj) {
+    if (obj && typeof obj === 'object' && !Object.isFrozen(obj)) {
+        for (const value of Object.values(obj)) {
+            if (value && typeof value === 'object') {
+                deepFreeze(value);
+            }
+        }
+        Object.freeze(obj);
+    }
+    return obj;
+}
+//# sourceMappingURL=config.js.map

package/dist/shared/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/shared/config.ts"],"names":[],"mappings":"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"}

package/dist/shared/errors.d.ts

@@ -0,0 +1,139 @@
+import type { AiProvider } from './events/types.js';
+/**
+ * Canonical error classifications produced by {@link classifyError} and
+ * {@link classifyErrorDetailed}.
+ *
+ * Implemented as a `const` object plus derived string-literal union
+ * rather than a TypeScript `enum`, so that:
+ *   - runtime usage (`AiErrorClassification.RATE_LIMIT`) keeps working
+ *     identically for existing call sites;
+ *   - the type is a string-literal union, matching every other
+ *     enum-like type in this package (`AiProvider`, `AiRequestMethod`,
+ *     `LogLevel`, `TransportMode`, etc.) — one consistent style;
+ *   - bundlers can tree-shake unused members (TS enums emit a runtime
+ *     object even when none of its members are referenced);
+ *   - the wire-format strings (`'RATE_LIMIT'`, `'OVERLOADED'`, …) are
+ *     usable directly as values without going through an enum lookup,
+ *     which simplifies serialization paths.
+ */
+export declare const AiErrorClassification: {
+    readonly RATE_LIMIT: "RATE_LIMIT";
+    readonly OVERLOADED: "OVERLOADED";
+    readonly CONTENT_POLICY: "CONTENT_POLICY";
+    readonly CONTEXT_LENGTH_EXCEEDED: "CONTEXT_LENGTH_EXCEEDED";
+    readonly AUTHENTICATION: "AUTHENTICATION";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly SERVER_ERROR: "SERVER_ERROR";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly UNKNOWN: "UNKNOWN";
+};
+export type AiErrorClassification = (typeof AiErrorClassification)[keyof typeof AiErrorClassification];
+/**
+ * Classifications that `isRetryable()` reports as retryable. Exported as a
+ * `ReadonlySet` so consumers can build their own retry policy on top of the
+ * canonical list (e.g. layered backoff per category, custom routing) without
+ * having to re-derive it. Mutation is rejected at the type level.
+ */
+export declare const RETRYABLE: ReadonlySet<AiErrorClassification>;
+/**
+ * Classify an arbitrary `unknown` error from a provider SDK or `fetch` into
+ * one of the canonical {@link AiErrorClassification} categories. The
+ * decision routes through HTTP status (when present), Node `code` for
+ * network/timeout cases, and provider-specific 400 disambiguation
+ * — content policy vs. context length vs. generic.
+ *
+ * Designed for retry-loop consumption — see {@link isRetryable} and
+ * {@link RETRYABLE} for the policy applied downstream. For UI / logging
+ * surfaces that need the original message + status alongside the
+ * classification, use {@link classifyErrorDetailed} instead.
+ *
+ * @param error The thrown value (Error, plain object, or anything else).
+ * @param provider The provider that produced the error — affects 400
+ *   disambiguation and Anthropic-specific 529 (OVERLOADED) handling.
+ */
+export declare function classifyError(error: unknown, provider: AiProvider): AiErrorClassification;
+/**
+ * Whether `classification` is one of the categories the library's retry
+ * loop will re-attempt: `RATE_LIMIT`, `OVERLOADED`, `TIMEOUT`,
+ * `SERVER_ERROR`, `NETWORK_ERROR`. Backed by the {@link RETRYABLE} set.
+ * Use this when implementing a custom retry policy on top of
+ * {@link classifyError}.
+ */
+export declare function isRetryable(classification: AiErrorClassification): boolean;
+export interface RateLimitInfo {
+    readonly tokensRemaining: number | null;
+    readonly requestsRemaining: number | null;
+    readonly tokensReset: string | null;
+    readonly requestsReset: string | null;
+}
+/**
+ * Extract rate-limit metadata from a provider error's `headers` field.
+ *
+ * Returns `null` when the error carries no `headers` at all,
+ * letting callers distinguish "no headers in the response" from "headers
+ * present but no rate-limit headers parsed". When `headers` is present but
+ * none of the recognized rate-limit headers parse, returns a `RateLimitInfo`
+ * with all four fields null.
+ *
+ * Provider coverage: Anthropic, OpenAI, Gemini, Mistral. Bedrock and Cohere
+ * intentionally return all-null — Bedrock exposes throttling in the
+ * ThrottlingException body rather than response headers; Cohere has no
+ * documented rate-limit headers for their Chat v2 API.
+ */
+export declare function extractRateLimitHeaders(error: unknown): RateLimitInfo | null;
+/**
+ * Truncate `message` to `maxLength` chars (default 1024), suffixing `...`
+ * when truncation occurs. Useful for keeping provider error messages within
+ * NR's per-attribute 4096-byte limit before they're logged or attached to
+ * events.
+ *
+ * The minimum effective `maxLength` is 4 — a shorter cap is silently
+ * clamped to 4 so the result is always at least `'X...'` for some single
+ * character of the original message.
+ *
+ * Examples:
+ * ```
+ *   truncateErrorMessage('hello world', 8)  // => 'hello...'
+ *   truncateErrorMessage('hi', 8)           // => 'hi'        (already short)
+ *   truncateErrorMessage('hello', 3)        // => 'h...'      (clamp to 4)
+ *   truncateErrorMessage('hello', 0)        // => 'h...'      (clamp to 4)
+ * ```
+ *
+ * @param message The message to truncate.
+ * @param maxLength Maximum length of the returned string. Values < 4 are
+ *   clamped to 4. Default is 1024.
+ */
+export declare function truncateErrorMessage(message: string, maxLength?: number): string;
+/**
+ * Rich classification result that pairs the {@link AiErrorClassification}
+ * enum value with the original error context — message, HTTP status, and
+ * Node system code (15, §E6).
+ *
+ * `code` is the Node system-level error code (e.g. `'ECONNREFUSED'`,
+ * `'ETIMEDOUT'`), extracted by walking the cause chain. It is NOT the
+ * provider body-level typed code (e.g. `'content_filter'`,
+ * `'context_length_exceeded'`) — those only appear inside the 400-body
+ * handling of `classifyError` and are not currently surfaced here.
+ */
+export interface ClassifiedError {
+    readonly classification: AiErrorClassification;
+    readonly originalMessage: string | null;
+    readonly status: number | null;
+    /** Node system code (e.g. `'ECONNREFUSED'`), or null. Not the provider body error code. */
+    readonly code: string | null;
+}
+/**
+ * Same classification logic as {@link classifyError}, but returns a
+ * {@link ClassifiedError} carrying the original message, HTTP status, and
+ * provider error code alongside the enum value. Useful when the caller
+ * wants to log a richer line ("Rate limit hit: ...message...") or
+ * propagate the original message to a UI surface.
+ *
+ * The retry path in `http-client.ts` does not currently consume this —
+ * its decision is purely "is this retryable?". This is exposed as a
+ * separate function so existing callers of `classifyError` continue to
+ * work unchanged.
+ */
+export declare function classifyErrorDetailed(error: unknown, provider: AiProvider): ClassifiedError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/shared/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;CAWxB,CAAC;AACX,MAAM,MAAM,qBAAqB,GAC/B,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,OAAO,qBAAqB,CAAC,CAAC;AAkBrE;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,qBAAqB,CAMvD,CAAC;AAsBH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,GAAG,qBAAqB,CAsFzF;AA4DD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,cAAc,EAAE,qBAAqB,GAAG,OAAO,CAE1E;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AA8ED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CA8B5E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,MAAM,CAS9E;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,cAAc,EAAE,qBAAqB,CAAC;IAC/C,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,GAAG,eAAe,CAc3F"}