@atlanai/sdk 0.1.0

package/dist/tracing/client.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Client, init, and lifecycle (SPEC §1, §5, §10).
+ *
+ * Provider stance, adapted for OTel JS 2.x (providers take their processors at
+ * construction; there is no addSpanProcessor): when no global TracerProvider is
+ * registered, the SDK builds one (Atlan resource + sampler + processor) and
+ * registers it — third-party instrumentation then flows in by sharing it.
+ * When the application already registered a provider, a 2.x provider cannot be
+ * attached to, so the SDK runs its own private provider and logs once; the
+ * application can capture foreign spans by passing `client.spanProcessor` into
+ * its own provider's constructor. `isolated: true` forces the private-provider
+ * posture (the dual-run recipe: keeps Atlan spans out of a vendor pipeline that
+ * owns the global, and vendor spans out of ours).
+ */
+import { type Tracer, type TimeInput } from "@opentelemetry/api";
+import { BasicTracerProvider, type SpanExporter } from "@opentelemetry/sdk-trace-base";
+import { type ConfigOptions, type ResolvedConfig } from "./config.js";
+import { type MaskFunction, type MaskOtelSpansFunction } from "./masking.js";
+import { AtlanSpanProcessor } from "./processor.js";
+import { type ShouldExportSpan } from "./span-filter.js";
+import { AtlanSpan, type UpdateFields } from "./spans.js";
+import { type IdentifyVisitorOptions, type Visitor } from "./visitor.js";
+export interface InitOptions extends ConfigOptions {
+    /** Never touch the global provider — run a private pipeline (dual-run). */
+    isolated?: boolean;
+    /** Replace the OTLP exporter (tests, custom transports). */
+    spanExporter?: SpanExporter;
+    /** Fully replaces the default export allowlist decision (SPEC §4.3). */
+    shouldExportSpan?: ShouldExportSpan;
+    /** Data-level mask over input/output/metadata/tool payloads (SPEC §8.2). */
+    mask?: MaskFunction;
+    /** Export-stage batch masking over every exported span (SPEC §8.5). */
+    maskOtelSpans?: MaskOtelSpansFunction;
+    /** Serverless hook: every background flush promise is handed to it. */
+    waitUntil?: (promise: Promise<unknown>) => void;
+    /** "immediate" exports per-span (serverless / short-lived processes);
+     * default "batch". ATLAN_DEBUG=true also forces immediate mode. */
+    exportMode?: "batch" | "immediate";
+}
+/** Explicit remote trace context for a span-creating call (SPEC §7.3). */
+export interface TraceContext {
+    traceId: string;
+    parentSpanId?: string;
+}
+export interface StartSpanOptions {
+    asType?: string;
+    /** Explicit parent (framework integrations tracking their own run trees);
+     * takes precedence over traceContext. */
+    parent?: AtlanSpan;
+    traceContext?: TraceContext;
+    startTime?: TimeInput;
+    fields?: UpdateFields;
+}
+export interface StartAsCurrentSpanOptions {
+    asType?: string;
+    traceContext?: TraceContext;
+    startTime?: TimeInput;
+    endOnExit?: boolean;
+    fields?: UpdateFields;
+}
+export declare class AtlanAI {
+    readonly config: ResolvedConfig;
+    /**
+     * The SDK's span processor, exposed so an application that owns its own
+     * TracerProvider can include it: `new NodeTracerProvider({ spanProcessors:
+     * [client.spanProcessor!, ...] })`.
+     */
+    readonly spanProcessor: AtlanSpanProcessor | null;
+    private readonly provider;
+    private readonly mask;
+    private readonly ownsGlobal;
+    private readonly waitUntil;
+    private shutdownDone;
+    constructor(config: ResolvedConfig, options?: InitOptions);
+    get isEnabled(): boolean;
+    /** The SDK's TracerProvider (null when disabled). Third-party tracers
+     * acquired from it flow through the Atlan pipeline (allowlist + enrichment). */
+    get tracerProvider(): BasicTracerProvider | null;
+    getTracer(): Tracer;
+    /**
+     * Create or refresh a Visitor and return its canonical artifact identity.
+     * This never changes process-global identity; carry visitor.id through
+     * propagateAttributes({ visitorId: visitor.id }, fn) for one request/job.
+     */
+    identify(options: IdentifyVisitorOptions): Promise<Visitor | undefined>;
+    /** Create a span WITHOUT making it current; caller must call .end(). */
+    startSpan(name: string, options?: StartSpanOptions): AtlanSpan;
+    /**
+     * Create a span, make it current while `fn` runs, and end it on exit
+     * (sync return or promise settle). Exceptions are recorded, mark the span
+     * ERROR, and re-throw (SPEC §9.2).
+     */
+    startAsCurrentSpan<T>(name: string, options: StartAsCurrentSpanOptions, fn: (span: AtlanSpan) => T): T;
+    /** Force the processor pipeline to export (SPEC §10.3). */
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Initialize the SDK. Idempotent per API key (SPEC §10.2). Throws
+ * AtlanConfigError only when an Atlan endpoint is configured without a
+ * workspace (SPEC §2.4); all other misconfiguration logs a warning and returns
+ * a disabled, no-op client.
+ */
+export declare function init(options?: InitOptions): AtlanAI;
+/**
+ * The most recently initialized client (or the one for `apiKey`). Returns a
+ * disabled no-op client when init was never called — every public API is safe
+ * to call uninitialized (SPEC §10.1).
+ */
+export declare function getClient(apiKey?: string): AtlanAI;
+/** Test hook: drop all registered clients (does not unregister globals). */
+export declare function _resetForTests(): void;

package/dist/tracing/client.js

@@ -0,0 +1,403 @@
+"use strict";
+/**
+ * Client, init, and lifecycle (SPEC §1, §5, §10).
+ *
+ * Provider stance, adapted for OTel JS 2.x (providers take their processors at
+ * construction; there is no addSpanProcessor): when no global TracerProvider is
+ * registered, the SDK builds one (Atlan resource + sampler + processor) and
+ * registers it — third-party instrumentation then flows in by sharing it.
+ * When the application already registered a provider, a 2.x provider cannot be
+ * attached to, so the SDK runs its own private provider and logs once; the
+ * application can capture foreign spans by passing `client.spanProcessor` into
+ * its own provider's constructor. `isolated: true` forces the private-provider
+ * posture (the dual-run recipe: keeps Atlan spans out of a vendor pipeline that
+ * owns the global, and vendor spans out of ours).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtlanAI = void 0;
+exports.init = init;
+exports.getClient = getClient;
+exports._resetForTests = _resetForTests;
+const api_1 = require("@opentelemetry/api");
+const resources_1 = require("@opentelemetry/resources");
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const config_js_1 = require("./config.js");
+const context_manager_js_1 = require("./context-manager.js");
+const exporter_js_1 = require("./exporter.js");
+const isomorph_js_1 = require("./isomorph.js");
+const logger_js_1 = require("./logger.js");
+const masking_js_1 = require("./masking.js");
+const processor_js_1 = require("./processor.js");
+const span_filter_js_1 = require("./span-filter.js");
+const sc = __importStar(require("./semconv.js"));
+const spans_js_1 = require("./spans.js");
+const ids_js_1 = require("./ids.js");
+const version_js_1 = require("./version.js");
+const visitor_js_1 = require("./visitor.js");
+const REGISTRY_SLOT = Symbol.for("atlanai.registry.v1");
+function registry() {
+    const host = globalThis;
+    let existing = host[REGISTRY_SLOT];
+    if (!existing) {
+        existing = { clients: new Map(), defaultKey: undefined };
+        try {
+            Object.defineProperty(host, REGISTRY_SLOT, {
+                value: existing,
+                writable: false,
+                configurable: false,
+                enumerable: false,
+            });
+        }
+        catch {
+            host[REGISTRY_SLOT] = existing;
+        }
+    }
+    return existing;
+}
+function clientKey(apiKey) {
+    return apiKey ?? "::anon::";
+}
+const TRACE_ID_RE = /^[0-9a-f]{32}$/;
+const SPAN_ID_RE = /^[0-9a-f]{16}$/;
+/**
+ * SPEC §7.3: build a non-recording remote parent from traceContext. With no
+ * parentSpanId, a synthetic parent span ID pins the trace ID and the created
+ * span is marked `atlan.internal.as_root`. Invalid IDs are ignored with a
+ * warning — never thrown.
+ */
+function remoteParentContext(traceContext, base) {
+    if (!traceContext)
+        return { context: base, asRoot: false };
+    const traceId = traceContext.traceId;
+    if (typeof traceId !== "string" || !TRACE_ID_RE.test(traceId) || /^0+$/.test(traceId)) {
+        logger_js_1.logger.warn(`ignoring traceContext with invalid traceId ${String(traceId)}`);
+        return { context: base, asRoot: false };
+    }
+    let spanId;
+    let asRoot;
+    let isRemote;
+    if (traceContext.parentSpanId !== undefined) {
+        spanId = traceContext.parentSpanId;
+        if (typeof spanId !== "string" || !SPAN_ID_RE.test(spanId) || /^0+$/.test(spanId)) {
+            logger_js_1.logger.warn(`ignoring traceContext with invalid parentSpanId ${String(spanId)}`);
+            return { context: base, asRoot: false };
+        }
+        asRoot = false;
+        isRemote = true;
+    }
+    else {
+        spanId = (0, ids_js_1.createSpanId)();
+        asRoot = true;
+        isRemote = false;
+    }
+    const parent = api_1.trace.wrapSpanContext({
+        traceId,
+        spanId,
+        isRemote,
+        traceFlags: api_1.TraceFlags.SAMPLED,
+    });
+    return { context: api_1.trace.setSpan(base, parent), asRoot };
+}
+function hasRealGlobalTracerProvider() {
+    const provider = api_1.trace.getTracerProvider();
+    const delegate = provider.getDelegate?.call(provider) ?? provider;
+    const name = delegate.constructor?.name;
+    return name !== undefined && name !== "NoopTracerProvider";
+}
+function buildResource(config) {
+    const attributes = {
+        [sc.SERVICE_NAME]: config.serviceName ?? "",
+        [sc.ATLAN_SDK_SCHEMA_VERSION]: sc.SCHEMA_VERSION,
+        [sc.ATLAN_SDK_LANGUAGE]: version_js_1.SDK_LANGUAGE,
+        [sc.ATLAN_SDK_VERSION]: version_js_1.SDK_VERSION,
+        [sc.ATLAN_CONSENT_STORE_CONTENT]: config.traceContent,
+    };
+    if (config.environment)
+        attributes[sc.ATLAN_ENVIRONMENT] = config.environment;
+    // resourceFromAttributes only — defaultResource() wires host/process
+    // detectors whose node-only CJS evaluates at bundle startup on edge runtimes.
+    return (0, resources_1.resourceFromAttributes)(attributes);
+}
+/**
+ * OTel JS ships a no-op global context manager by default (unlike Python's
+ * contextvars-backed context): `context.with` would silently lose propagation
+ * scopes and ambient parenting. Probe whether context actually propagates and
+ * register an AsyncLocalStorage manager when it does not — regardless of
+ * provider ownership, since context is a process-global concern orthogonal to
+ * providers. An app whose own manager already works is left untouched.
+ */
+const CONTEXT_PROBE_KEY = (0, api_1.createContextKey)("atlan.context_probe");
+function ensureContextManager() {
+    let works = false;
+    try {
+        api_1.context.with(api_1.context.active().setValue(CONTEXT_PROBE_KEY, true), () => {
+            works = api_1.context.active().getValue(CONTEXT_PROBE_KEY) === true;
+        });
+    }
+    catch {
+        works = false;
+    }
+    if (works)
+        return;
+    const manager = new context_manager_js_1.AlsContextManager();
+    if (!manager.available) {
+        logger_js_1.logger.debug("AsyncLocalStorage unavailable; ambient nesting disabled");
+        return;
+    }
+    try {
+        api_1.context.setGlobalContextManager(manager.enable());
+    }
+    catch {
+        logger_js_1.logger.debug("context manager registration failed; ambient nesting disabled");
+    }
+}
+class AtlanAI {
+    config;
+    /**
+     * The SDK's span processor, exposed so an application that owns its own
+     * TracerProvider can include it: `new NodeTracerProvider({ spanProcessors:
+     * [client.spanProcessor!, ...] })`.
+     */
+    spanProcessor = null;
+    provider = null;
+    mask;
+    ownsGlobal = false;
+    waitUntil;
+    shutdownDone = false;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.waitUntil = options.waitUntil;
+        this.mask = options.mask;
+        if (config.mode === "disabled")
+            return;
+        let exporter = options.spanExporter ?? (0, exporter_js_1.buildExporter)(config);
+        if (options.maskOtelSpans !== undefined) {
+            exporter = new masking_js_1.MaskingSpanExporter(exporter, options.maskOtelSpans);
+        }
+        this.spanProcessor = new processor_js_1.AtlanSpanProcessor(exporter, {
+            flushAt: config.debug ? 1 : config.flushAt,
+            flushIntervalS: config.debug ? 0.1 : config.flushIntervalS,
+            timeoutS: config.timeoutS,
+            shouldExportSpan: options.shouldExportSpan,
+            traceContent: config.traceContent,
+            mask: options.mask,
+            exportMode: config.debug ? "immediate" : (options.exportMode ?? "batch"),
+        });
+        const sampler = config.sampleRate < 1.0
+            ? new sdk_trace_base_1.ParentBasedSampler({ root: new sdk_trace_base_1.TraceIdRatioBasedSampler(config.sampleRate) })
+            : undefined;
+        this.provider = new sdk_trace_base_1.BasicTracerProvider({
+            resource: buildResource(config),
+            ...(sampler ? { sampler } : {}),
+            spanProcessors: [this.spanProcessor],
+        });
+        ensureContextManager();
+        if (!options.isolated) {
+            if (hasRealGlobalTracerProvider()) {
+                // OTel JS 2.x providers are sealed — the SDK cannot attach to the
+                // app's provider the way the Python SDK does. Private pipeline;
+                // foreign-span capture needs client.spanProcessor in the app's setup.
+                logger_js_1.logger.debug("an application TracerProvider is already registered; running a private " +
+                    "Atlan pipeline (pass client.spanProcessor into your provider to export " +
+                    "third-party spans to Atlan)");
+            }
+            else if (api_1.trace.setGlobalTracerProvider(this.provider)) {
+                this.ownsGlobal = true;
+            }
+        }
+        isomorph_js_1.iso.onExit(() => {
+            void this.flush().catch(() => undefined);
+        });
+    }
+    get isEnabled() {
+        return this.spanProcessor !== null;
+    }
+    /** The SDK's TracerProvider (null when disabled). Third-party tracers
+     * acquired from it flow through the Atlan pipeline (allowlist + enrichment). */
+    get tracerProvider() {
+        return this.provider;
+    }
+    getTracer() {
+        const provider = this.provider ?? api_1.trace.getTracerProvider();
+        return provider.getTracer(span_filter_js_1.ATLAN_SDK_SCOPE, version_js_1.SDK_VERSION);
+    }
+    /**
+     * Create or refresh a Visitor and return its canonical artifact identity.
+     * This never changes process-global identity; carry visitor.id through
+     * propagateAttributes({ visitorId: visitor.id }, fn) for one request/job.
+     */
+    identify(options) {
+        return (0, visitor_js_1.identifyVisitor)(this.config, options);
+    }
+    /** Create a span WITHOUT making it current; caller must call .end(). */
+    startSpan(name, options = {}) {
+        if (this.spanProcessor === null)
+            return (0, spans_js_1.noopSpan)(this.config);
+        let context;
+        let asRoot = false;
+        if (options.parent !== undefined) {
+            context = api_1.trace.setSpan(api_1.context.active(), options.parent.otelSpan);
+        }
+        else {
+            ({ context, asRoot } = remoteParentContext(options.traceContext, api_1.context.active()));
+        }
+        const otelSpan = this.getTracer().startSpan(name, options.startTime !== undefined ? { startTime: options.startTime } : {}, context);
+        const span = new spans_js_1.AtlanSpan(otelSpan, this.config, this.mask);
+        span._initialize(options.asType ?? "task", asRoot);
+        if (options.fields)
+            span.update(options.fields);
+        return span;
+    }
+    /**
+     * Create a span, make it current while `fn` runs, and end it on exit
+     * (sync return or promise settle). Exceptions are recorded, mark the span
+     * ERROR, and re-throw (SPEC §9.2).
+     */
+    startAsCurrentSpan(name, options, fn) {
+        if (this.spanProcessor === null)
+            return fn((0, spans_js_1.noopSpan)(this.config));
+        const { context, asRoot } = remoteParentContext(options.traceContext, api_1.context.active());
+        const otelSpan = this.getTracer().startSpan(name, options.startTime !== undefined ? { startTime: options.startTime } : {}, context);
+        const span = new spans_js_1.AtlanSpan(otelSpan, this.config, this.mask);
+        span._initialize(options.asType ?? "task", asRoot);
+        if (options.fields)
+            span.update(options.fields);
+        let spanContext = api_1.trace.setSpan(context, otelSpan);
+        // Register the trace's root span so scoreTrace() can find it (SPEC §9.4).
+        const existingRoot = context.getValue(spans_js_1.ROOT_SPAN_CONTEXT_KEY);
+        if (!(existingRoot instanceof spans_js_1.AtlanSpan && existingRoot.traceId === span.traceId)) {
+            spanContext = spanContext.setValue(spans_js_1.ROOT_SPAN_CONTEXT_KEY, span);
+        }
+        const endOnExit = options.endOnExit ?? true;
+        let result;
+        try {
+            result = api_1.context.with(spanContext, () => fn(span));
+        }
+        catch (error) {
+            span.recordFailure(error);
+            if (endOnExit)
+                span.end();
+            throw error;
+        }
+        if (result instanceof Promise) {
+            return result.then((value) => {
+                if (endOnExit)
+                    span.end();
+                return value;
+            }, (error) => {
+                span.recordFailure(error);
+                if (endOnExit)
+                    span.end();
+                throw error;
+            });
+        }
+        if (endOnExit)
+            span.end();
+        return result;
+    }
+    /** Force the processor pipeline to export (SPEC §10.3). */
+    flush() {
+        if (this.spanProcessor === null)
+            return Promise.resolve();
+        const flushing = this.spanProcessor.forceFlush().catch(() => {
+            logger_js_1.logger.debug("flush failed");
+        });
+        this.waitUntil?.(flushing);
+        return flushing;
+    }
+    async shutdown() {
+        if (this.shutdownDone || this.provider === null)
+            return;
+        this.shutdownDone = true;
+        try {
+            await this.provider.shutdown();
+        }
+        catch {
+            // SPEC §10.5 — never break the host app on teardown
+            logger_js_1.logger.debug("shutdown failed");
+        }
+    }
+}
+exports.AtlanAI = AtlanAI;
+/**
+ * Initialize the SDK. Idempotent per API key (SPEC §10.2). Throws
+ * AtlanConfigError only when an Atlan endpoint is configured without a
+ * workspace (SPEC §2.4); all other misconfiguration logs a warning and returns
+ * a disabled, no-op client.
+ */
+function init(options = {}) {
+    let config;
+    try {
+        config = (0, config_js_1.resolveConfig)(options);
+    }
+    catch (error) {
+        if (error instanceof config_js_1.AtlanConfigError)
+            throw error;
+        logger_js_1.logger.warn(`configuration failed (${String(error)}); tracing disabled`);
+        config = (0, config_js_1.resolveConfig)({ ...options, tracingEnabled: false });
+    }
+    (0, logger_js_1.setDebug)(config.debug);
+    const key = clientKey(config.apiKey);
+    const bucket = registry();
+    const existing = bucket.clients.get(key);
+    if (existing) {
+        bucket.defaultKey = key;
+        return existing;
+    }
+    const client = new AtlanAI(config, options);
+    bucket.clients.set(key, client);
+    bucket.defaultKey = key;
+    return client;
+}
+/**
+ * The most recently initialized client (or the one for `apiKey`). Returns a
+ * disabled no-op client when init was never called — every public API is safe
+ * to call uninitialized (SPEC §10.1).
+ */
+function getClient(apiKey) {
+    const bucket = registry();
+    const key = apiKey !== undefined ? clientKey(apiKey) : bucket.defaultKey;
+    const existing = key !== undefined ? bucket.clients.get(key) : undefined;
+    if (existing)
+        return existing;
+    return new AtlanAI((0, config_js_1.resolveConfig)({ tracingEnabled: false }));
+}
+/** Test hook: drop all registered clients (does not unregister globals). */
+function _resetForTests() {
+    const bucket = registry();
+    bucket.clients.clear();
+    bucket.defaultKey = undefined;
+}

package/dist/tracing/config.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Configuration resolution (SPEC §3).
+ *
+ * Precedence: explicit init options > ATLAN_* env > standard OTLP env >
+ * defaults. Misconfiguration never throws out of public APIs except the one
+ * spec-mandated fail-fast: a configured Atlan endpoint without a workspace
+ * (SPEC §2.4). On runtimes without ambient env (workerd), everything resolves
+ * from the init options alone.
+ */
+export declare const DEFAULT_BASE_URL = "https://agentgateway.atlan.engineering";
+/**
+ * Modes (SPEC §3.3): "atlan" exports to the gateway with Atlan headers; "otlp"
+ * is generic-collector mode driven purely by OTEL_EXPORTER_OTLP_* env;
+ * "disabled" is the no-op posture.
+ */
+export type Mode = "atlan" | "otlp" | "disabled";
+/** Thrown only for the spec-mandated fail-fast cases (SPEC §2.4). */
+export declare class AtlanConfigError extends Error {
+}
+export interface ResolvedConfig {
+    mode: Mode;
+    serviceName: string | undefined;
+    apiKey: string | undefined;
+    baseUrl: string;
+    workspaceId: string | undefined;
+    environment: string | undefined;
+    tracingEnabled: boolean;
+    traceContent: boolean;
+    sampleRate: number;
+    flushAt: number;
+    flushIntervalS: number;
+    timeoutS: number;
+    maxPayloadBytes: number;
+    debug: boolean;
+}
+export interface ConfigOptions {
+    serviceName?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    workspaceId?: string;
+    environment?: string;
+    tracingEnabled?: boolean;
+    traceContent?: boolean;
+    sampleRate?: number;
+}
+export declare function validAtlanBaseUrl(baseUrl: string): boolean;
+/**
+ * Resolve configuration; the returned mode may be "disabled". Throws
+ * AtlanConfigError only for a configured Atlan endpoint with no workspace
+ * (SPEC §2.4).
+ */
+export declare function resolveConfig(options?: ConfigOptions): ResolvedConfig;

package/dist/tracing/config.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Configuration resolution (SPEC §3).
+ *
+ * Precedence: explicit init options > ATLAN_* env > standard OTLP env >
+ * defaults. Misconfiguration never throws out of public APIs except the one
+ * spec-mandated fail-fast: a configured Atlan endpoint without a workspace
+ * (SPEC §2.4). On runtimes without ambient env (workerd), everything resolves
+ * from the init options alone.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtlanConfigError = exports.DEFAULT_BASE_URL = void 0;
+exports.validAtlanBaseUrl = validAtlanBaseUrl;
+exports.resolveConfig = resolveConfig;
+const isomorph_js_1 = require("./isomorph.js");
+const logger_js_1 = require("./logger.js");
+exports.DEFAULT_BASE_URL = "https://agentgateway.atlan.engineering";
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/** Thrown only for the spec-mandated fail-fast cases (SPEC §2.4). */
+class AtlanConfigError extends Error {
+}
+exports.AtlanConfigError = AtlanConfigError;
+function envBool(name, fallback) {
+    const value = isomorph_js_1.iso.env(name);
+    if (value === undefined)
+        return fallback;
+    return ["true", "1", "yes"].includes(value.trim().toLowerCase());
+}
+function envNumber(name, fallback, integer = false) {
+    const value = isomorph_js_1.iso.env(name);
+    if (value === undefined)
+        return fallback;
+    const parsed = integer ? Number.parseInt(value, 10) : Number.parseFloat(value);
+    if (Number.isNaN(parsed)) {
+        logger_js_1.logger.warn(`ignoring non-numeric ${name}=${value}`);
+        return fallback;
+    }
+    return parsed;
+}
+function otlpEnvEndpointConfigured() {
+    return Boolean(isomorph_js_1.iso.env("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT") ?? isomorph_js_1.iso.env("OTEL_EXPORTER_OTLP_ENDPOINT"));
+}
+function validAtlanBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === "https:")
+        return true;
+    return parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname);
+}
+/**
+ * Resolve configuration; the returned mode may be "disabled". Throws
+ * AtlanConfigError only for a configured Atlan endpoint with no workspace
+ * (SPEC §2.4).
+ */
+function resolveConfig(options = {}) {
+    const apiKey = options.apiKey ?? isomorph_js_1.iso.env("ATLAN_API_KEY");
+    const baseUrl = (options.baseUrl ?? isomorph_js_1.iso.env("ATLAN_BASE_URL") ?? exports.DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const workspaceId = options.workspaceId ?? isomorph_js_1.iso.env("ATLAN_WORKSPACE_ID");
+    const environment = options.environment ?? isomorph_js_1.iso.env("ATLAN_ENVIRONMENT");
+    const enabled = options.tracingEnabled ?? envBool("ATLAN_TRACING", true);
+    const content = options.traceContent ?? envBool("ATLAN_TRACE_CONTENT", true);
+    let rate = options.sampleRate ?? envNumber("ATLAN_SAMPLE_RATE", 1.0);
+    if (!(rate >= 0 && rate <= 1)) {
+        logger_js_1.logger.warn(`sample_rate ${rate} outside [0, 1]; using 1.0`);
+        rate = 1.0;
+    }
+    let mode = "disabled";
+    if (enabled) {
+        if (apiKey) {
+            mode = "atlan";
+        }
+        else if (otlpEnvEndpointConfigured()) {
+            mode = "otlp";
+        }
+        else {
+            logger_js_1.logger.warn("tracing disabled — no ATLAN_API_KEY and no OTEL_EXPORTER_OTLP_*_ENDPOINT configured");
+        }
+    }
+    if (mode === "atlan" && !validAtlanBaseUrl(baseUrl)) {
+        logger_js_1.logger.warn(`tracing disabled — base_url ${baseUrl} must be https (http allowed only for loopback hosts)`);
+        mode = "disabled";
+    }
+    if (mode !== "disabled" && !options.serviceName) {
+        logger_js_1.logger.warn('tracing disabled — serviceName is required, e.g. init({ serviceName: "my-agent" })');
+        mode = "disabled";
+    }
+    // SPEC §2.4: the one fail-fast. Never export to the gateway without a
+    // workspace — those traces land in workspace "default" and are effectively lost.
+    if (mode === "atlan" && !workspaceId) {
+        throw new AtlanConfigError("a workspace is required when exporting to an Atlan endpoint. " +
+            "Set ATLAN_WORKSPACE_ID or pass workspaceId to init().");
+    }
+    return {
+        mode,
+        serviceName: options.serviceName,
+        apiKey,
+        baseUrl,
+        workspaceId,
+        environment,
+        tracingEnabled: enabled,
+        traceContent: content,
+        sampleRate: rate,
+        flushAt: envNumber("ATLAN_FLUSH_AT", 64, true),
+        flushIntervalS: envNumber("ATLAN_FLUSH_INTERVAL", 5.0),
+        timeoutS: envNumber("ATLAN_TIMEOUT", 30.0),
+        maxPayloadBytes: envNumber("ATLAN_MAX_PAYLOAD_BYTES", 1024 * 1024, true),
+        debug: envBool("ATLAN_DEBUG", false),
+    };
+}