@atlanai/sdk 0.2.3 → 0.2.4

package/dist/client.d.ts

@@ -42,10 +42,24 @@ export declare class ServiceNamespace {
     readonly operations: readonly Omit<Operation, "service">[];
     /** Contract method names for this service, used to resolve a forwarded call. */
     readonly operationMethods: ReadonlySet<string>;
-    constructor(name: string, module: GeneratedModule, configuration: GeneratedConfiguration, serviceOperations: readonly Omit<Operation, "service">[]);
+    /**
+     * Whether the configured credential is an API key rather than a user token.
+     * Only the credential's shape was read, never its value.
+     */
+    readonly apiKeyCredential: boolean;
+    constructor(name: string, module: GeneratedModule, configuration: GeneratedConfiguration, serviceOperations: readonly Omit<Operation, "service">[], apiKeyCredential?: boolean);
 }
 /** Build a namespace that also answers its operations by method name. */
-export declare function createService(name: string, module: GeneratedModule, configuration: GeneratedConfiguration, serviceOperations: readonly Omit<Operation, "service">[]): Service;
+export declare function createService(name: string, module: GeneratedModule, configuration: GeneratedConfiguration, serviceOperations: readonly Omit<Operation, "service">[], apiKeyCredential?: boolean): Service;
+/**
+ * Whether a credential is a signed JWT, which is the user-token shape.
+ *
+ * Only the structure is read, and the value is never logged or compared to a
+ * literal: three base64url segments whose first decodes to a JSON object. The
+ * gateway draws the same line itself - its 401 vocabulary splits
+ * `invalid_api_key`/`unknown_key` from the whole `token_*` family.
+ */
+export declare function looksLikeAJwt(token: string): boolean;
 export interface AtlanClient extends ResourceRoots {
 }
 export declare class AtlanClient {

package/dist/client.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AtlanClient = exports.ServiceNamespace = exports.WORKSPACE_HEADER = void 0;
 exports.createService = createService;
+exports.looksLikeAJwt = looksLikeAJwt;
 const agentRaw = __importStar(require("./raw/agent/index"));
 const apiRaw = __importStar(require("./raw/api/index"));
 const evalRaw = __importStar(require("./raw/eval/index"));
@@ -57,8 +58,14 @@ class ServiceNamespace {
     operations;
     /** Contract method names for this service, used to resolve a forwarded call. */
     operationMethods;
-    constructor(name, module, configuration, serviceOperations) {
+    /**
+     * Whether the configured credential is an API key rather than a user token.
+     * Only the credential's shape was read, never its value.
+     */
+    apiKeyCredential;
+    constructor(name, module, configuration, serviceOperations, apiKeyCredential = false) {
         this.name = name;
+        this.apiKeyCredential = apiKeyCredential;
         this.configuration = configuration;
         this.operations = serviceOperations;
         const operationMethods = new Set(serviceOperations.map((operation) => methodName(operation.operation_id)));
@@ -69,15 +76,15 @@ class ServiceNamespace {
                 continue;
             const name = exportName.replace(/Api$/, "").replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
             const raw = new value(configuration);
-            apis[name] = wrapGeneratedAPI(raw, operationMethods);
+            apis[name] = wrapGeneratedAPI(raw, operationMethods, apiKeyCredential);
         }
         this.apis = Object.freeze(apis);
     }
 }
 exports.ServiceNamespace = ServiceNamespace;
 /** Build a namespace that also answers its operations by method name. */
-function createService(name, module, configuration, serviceOperations) {
-    const namespace = new ServiceNamespace(name, module, configuration, serviceOperations);
+function createService(name, module, configuration, serviceOperations, apiKeyCredential = false) {
+    const namespace = new ServiceNamespace(name, module, configuration, serviceOperations, apiKeyCredential);
     return forwardOperations(namespace, namespace.operationMethods);
 }
 /**
@@ -138,7 +145,69 @@ function methodName(operationId) {
     const [service, operation] = operationId.split(".", 2);
     return service + operation.charAt(0).toUpperCase() + operation.slice(1);
 }
-function wrapGeneratedAPI(api, operationMethods) {
+/**
+ * Recover a success body the generated client would have thrown away.
+ *
+ * A handful of operations document their 200 as `application/json` with no
+ * schema. The generator reads that as "no response type" and renders the
+ * method as `Promise<void>`: it awaits the `…Raw` sibling and returns nothing,
+ * never calling `value()` at all. `GET /skill/v1/skills/{skill_id}` is one -
+ * the gateway sends the whole skill and the caller receives `undefined`, which
+ * makes a skill impossible to read back.
+ *
+ * Hand-fixing the contract would not hold, since `contracts/` is synced from
+ * the gateway. So the generated method is still the one called, with its own
+ * parameter defaults intact, over a receiver that keeps hold of the
+ * `ApiResponse` it discards. Only when the call resolves to `undefined` is
+ * that response read, and its body is still unconsumed precisely because the
+ * generated method ignored it. One request either way, and nothing changes for
+ * an operation whose body the generator already keeps.
+ */
+async function callKeepingBody(target, method, property, args) {
+    const rawName = `${property}Raw`;
+    if (typeof target[rawName] !== "function") {
+        return await Reflect.apply(method, target, args);
+    }
+    let captured;
+    const receiver = new Proxy(target, {
+        get(proxied, name, self) {
+            const member = Reflect.get(proxied, name, self);
+            if (name !== rawName || typeof member !== "function")
+                return member;
+            return async (...rawArgs) => {
+                captured = (await Reflect.apply(member, proxied, rawArgs));
+                return captured;
+            };
+        },
+    });
+    const result = await Reflect.apply(method, receiver, args);
+    if (result !== undefined || captured === undefined)
+        return result;
+    return await recoverValue(captured);
+}
+async function recoverValue(response) {
+    let value;
+    try {
+        value = await response.value?.();
+    }
+    catch {
+        // The generated method already read the body; there is nothing to recover.
+        return undefined;
+    }
+    if (value !== undefined || !response.raw)
+        return value;
+    const contentType = response.raw.headers.get("content-type") ?? "";
+    if (!contentType.toLowerCase().includes("json"))
+        return value;
+    try {
+        return await response.raw.json();
+    }
+    catch {
+        // An empty or unparseable body is the `void` the generator promised.
+        return value;
+    }
+}
+function wrapGeneratedAPI(api, operationMethods, apiKeyCredential) {
     return new Proxy(api, {
         get(target, property, receiver) {
             const value = Reflect.get(target, property, receiver);
@@ -147,22 +216,58 @@ function wrapGeneratedAPI(api, operationMethods) {
             }
             return async (...args) => {
                 try {
-                    return await Reflect.apply(value, target, args);
+                    return await callKeepingBody(target, value, property, args);
                 }
                 catch (error) {
                     const response = error?.response;
                     if (response instanceof Response) {
-                        throw await errors_1.AtlanAPIError.fromResponse(response);
+                        throw annotateCredential(await errors_1.AtlanAPIError.fromResponse(response), apiKeyCredential);
                     }
                     const cause = error?.cause;
                     if (cause instanceof errors_1.AtlanAPIError)
-                        throw cause;
+                        throw annotateCredential(cause, apiKeyCredential);
                     throw error;
                 }
             };
         },
     });
 }
+/**
+ * Say which kind of credential a 403 was refused for.
+ *
+ * A bare "403 forbidden" sends people hunting for a missing role when the
+ * credential kind is the whole story: the same POST an API key is refused is
+ * accepted from a user token.
+ */
+function annotateCredential(error, apiKeyCredential) {
+    if (error.status !== 403 || !apiKeyCredential)
+        return error;
+    return error.withHint("the configured credential is an API key, not a user token; the gateway grants " +
+        "an API key a narrower set of permissions - creating an agent or a skill, for " +
+        "one, is refused for an API key and accepted for a user token from " +
+        "`atlanai auth login` (read it with `atlanai auth token`)");
+}
+/**
+ * Whether a credential is a signed JWT, which is the user-token shape.
+ *
+ * Only the structure is read, and the value is never logged or compared to a
+ * literal: three base64url segments whose first decodes to a JSON object. The
+ * gateway draws the same line itself - its 401 vocabulary splits
+ * `invalid_api_key`/`unknown_key` from the whole `token_*` family.
+ */
+function looksLikeAJwt(token) {
+    const segments = token.split(".");
+    if (segments.length !== 3 || segments.some((segment) => segment === ""))
+        return false;
+    try {
+        const header = segments[0].replace(/-/g, "+").replace(/_/g, "/");
+        const decoded = JSON.parse(atob(header));
+        return typeof decoded === "object" && decoded !== null && !Array.isArray(decoded);
+    }
+    catch {
+        return false;
+    }
+}
 class AtlanClient {
     /** Per-service generated clients, for an operation the map has not surfaced. */
     raw;
@@ -181,6 +286,10 @@ class AtlanClient {
         const fetchApi = withTimeout(options.fetch ?? globalThis.fetch, timeoutMs);
         const accessToken = safeTokenProvider(options.bearerToken, options.tokenProvider);
         const workspace = validateWorkspace(options.workspace);
+        // Read once, from the shape alone. A tokenProvider is left unclassified
+        // rather than called here: resolving it early could refresh a credential
+        // nobody asked for yet.
+        const apiKeyCredential = options.bearerToken !== undefined && !looksLikeAJwt(options.bearerToken);
         const modules = {
             registry: registryRaw,
             skill: skillRaw,
@@ -202,7 +311,7 @@ class AtlanClient {
                 accessToken,
                 ...(workspace === undefined ? {} : { headers: { [exports.WORKSPACE_HEADER]: workspace } }),
             });
-            namespaces[service.name] = createService(service.name, module, configuration, service.operations);
+            namespaces[service.name] = createService(service.name, module, configuration, service.operations, apiKeyCredential);
         }
         this.raw = Object.freeze(namespaces);
         // Resources, not services. A service is a base path; a resource is what a

package/dist/errors.d.ts

@@ -4,13 +4,22 @@ export declare class AtlanAPIError extends Error {
     readonly title: string;
     readonly detail: string;
     readonly traceId?: string;
+    /**
+     * Set by the SDK when it, not the gateway, knows why the call failed - a
+     * 403 refused for the kind of credential configured, for instance. Never
+     * server-supplied, so unlike `detail` it is safe to put in the message.
+     */
+    readonly hint: string;
     constructor(options: {
         status: number;
         code?: string;
         title?: string;
         detail?: string;
         traceId?: string;
+        hint?: string;
     });
+    /** The same failure, carrying a client-side explanation in its message. */
+    withHint(hint: string): AtlanAPIError;
     static fromResponse(response: Response): Promise<AtlanAPIError>;
     static fromConnectionError(timedOut?: boolean): AtlanAPIError;
 }

package/dist/errors.js

@@ -7,11 +7,21 @@ class AtlanAPIError extends Error {
     title;
     detail;
     traceId;
+    /**
+     * Set by the SDK when it, not the gateway, knows why the call failed - a
+     * 403 refused for the kind of credential configured, for instance. Never
+     * server-supplied, so unlike `detail` it is safe to put in the message.
+     */
+    hint;
     constructor(options) {
         const suffix = options.code ? ` (${options.code})` : "";
+        const hint = options.hint ? `; ${options.hint}` : "";
+        // `detail` stays out: it is server text and may echo what was sent.
+        // `traceId` is an opaque correlation id and is what support asks for.
+        const trace = options.traceId ? ` [trace_id=${options.traceId}]` : "";
         const message = options.status === 0
             ? `${options.title ?? "Could not reach the Atlan Gateway"}${options.detail ? `; ${options.detail}` : ""}`
-            : `Atlan API request failed with status ${options.status}${suffix}`;
+            : `Atlan API request failed with status ${options.status}${suffix}${trace}${hint}`;
         super(message);
         this.name = "AtlanAPIError";
         this.status = options.status;
@@ -19,6 +29,18 @@ class AtlanAPIError extends Error {
         this.title = options.title ?? "";
         this.detail = options.detail ?? "";
         this.traceId = options.traceId;
+        this.hint = options.hint ?? "";
+    }
+    /** The same failure, carrying a client-side explanation in its message. */
+    withHint(hint) {
+        return new AtlanAPIError({
+            status: this.status,
+            code: this.code,
+            title: this.title,
+            detail: this.detail,
+            traceId: this.traceId,
+            hint,
+        });
     }
     static async fromResponse(response) {
         let problem = {};

package/dist/evals.d.ts

@@ -28,6 +28,47 @@ export interface ContextManifest {
 export declare function createContextManifest(input: readonly ContextItem[]): Promise<ContextManifest>;
 /** Resolve one dataset by artifact ID or exact name, never fuzzy matching. */
 export declare function resolveDataset(client: AtlanClient, idOrExactName: string, workspaceId?: string): Promise<unknown>;
+/**
+ * The Registry handle for the case called `key` inside `datasetId`.
+ *
+ * Deterministic, so pushing the same suite twice lands on the same row, and
+ * dataset-scoped, so the same suite can also be pushed into a new dataset.
+ */
+export declare function recordName(datasetId: string, key: string): Promise<string>;
+/** What one case in a pushed suite ended up as. */
+export interface RecordPush {
+    readonly key: string;
+    readonly name: string;
+    readonly id: string;
+    readonly action: "created" | "updated" | "unchanged";
+    readonly record: unknown;
+}
+/** A pushed suite: the dataset it landed in and what each case did. */
+export interface DatasetPush {
+    readonly dataset: unknown;
+    readonly id: string;
+    readonly created: boolean;
+    readonly records: readonly RecordPush[];
+}
+/**
+ * Create or update each case, so the same suite can be pushed repeatedly.
+ *
+ * Each record's `name` is the developer's key for the case: it becomes the
+ * row's `displayName` and keys the Registry handle. A case already in the
+ * dataset is patched when its content moved and left alone when it did not.
+ */
+export declare function pushRecords(client: AtlanClient, datasetId: string, records: Iterable<Record<string, unknown>>, workspaceId?: string): Promise<RecordPush[]>;
+/**
+ * Push a suite under `name`, creating the dataset the first time only.
+ *
+ * Idempotent: run it again after correcting an expected value and the
+ * correction lands on the same rows, in the same dataset, without a 409.
+ */
+export declare function pushDataset(client: AtlanClient, name: string, records: Iterable<Record<string, unknown>>, options?: {
+    workspaceId?: string;
+    displayName?: string;
+    description?: string;
+}): Promise<DatasetPush>;
 export interface StartExperimentOptions {
     contextManifest?: ContextManifest;
 }
@@ -35,17 +76,59 @@ export declare class EvalRun {
     readonly experiment: unknown;
     readonly dataset: unknown;
     readonly contextManifest?: ContextManifest | undefined;
+    /**
+     * The session id stamped on every span this run emits.
+     *
+     * It is the only join key the gateway promotes off an eval span that can
+     * reach the run's subject: `recordExperimentSession` registers this value
+     * against the experiment's subject.
+     */
     constructor(experiment: unknown, dataset: unknown, contextManifest?: ContextManifest | undefined);
     get id(): string;
     get experimentId(): string;
-    /** Options for `propagateAttributes` from `@atlanai/sdk/tracing`. */
+    /** Stable across retries because the experiment is the resumable unit. */
+    get sessionId(): string;
+    /**
+     * Options for `propagateAttributes` from `@atlanai/sdk/tracing`.
+     *
+     * Carries the experiment join and the subject join. A nested
+     * `propagateAttributes({ sessionId })` still wins for the spans inside it.
+     */
     get traceOptions(): {
         experimentId: string;
+        sessionId: string;
         metadata?: Record<string, unknown>;
     };
 }
 /** Create a running experiment over a dataset ID or exact dataset name. */
 export declare function startExperiment(client: AtlanClient, dataset: string, body: Readonly<Record<string, unknown>>, options?: StartExperimentOptions): Promise<EvalRun>;
+export interface ExperimentTracesOptions {
+    limit?: number;
+}
+/**
+ * Every trace an experiment recorded, newest first.
+ *
+ * **The experiment is the scope eval traces are filed under.** A subject's own
+ * Traces tab (`GET /agent/v1/agents/{id}/traces`) resolves on the trace's
+ * *creator identity*, so it lists a run only when the run's spans were exported
+ * with that agent's own credential. An eval exported with your user key or a
+ * service-account key is filed under that identity instead, and the agent's
+ * Traces tab reads empty even though every trace exists. That is not the traces
+ * going missing; it is a different scope. Read them here, and call
+ * `recordExperimentSession` so the run is also reachable from the subject's
+ * Sessions tab.
+ *
+ * To fill the agent's own Traces tab, export the spans as the agent: pass
+ * `logger: initLogger({ apiKey: <the agent's credential> })` while the
+ * management `client` keeps your own, since the agent's identity is not
+ * entitled to create experiments.
+ */
+export declare function experimentTraces(client: AtlanClient, experimentId: string, options?: ExperimentTracesOptions): Promise<unknown[]>;
+export interface RecordExperimentSessionOptions {
+    sessionStatus?: string;
+    title?: string;
+}
+export declare function recordExperimentSession(client: AtlanClient, run: EvalRun, options?: RecordExperimentSessionOptions): Promise<unknown | undefined>;
 export interface EvalCase<Input, Expected = unknown, Metadata = Record<string, unknown>> {
     input: Input;
     expected?: Expected;
@@ -147,6 +230,13 @@ export interface EvalResultWithSummary<Input, Output, Expected, Metadata> {
     dataset: unknown;
     summary: Record<string, unknown>;
     results: EvalCaseResult<Input, Output, Expected, Metadata>[];
+    /** The session id stamped on every span of the run. */
+    sessionId: string;
+    /**
+     * The `session` record that binds the run to the experiment's subject.
+     * `undefined` when the experiment named no subject to bind it to.
+     */
+    session?: unknown;
 }
 /** Structural trace surface keeps the management bundle decoupled at build time. */
 export interface EvalTraceSpan {
@@ -169,13 +259,46 @@ export interface EvalTraceLogger {
     readonly client: EvalTraceClient;
     flush(): Promise<void>;
 }
+export declare function Eval<Input, Output, Expected = unknown, Metadata extends Record<string, unknown> = Record<string, unknown>>(name: string, evaluator: Evaluator<Input, Output, Expected, Metadata>, options?: EvalOptions): Promise<EvalResultWithSummary<Input, Output, Expected, Metadata>>;
+/** One gate result. `ok` is undefined when only a human can answer it. */
+export interface VerificationCheck {
+    readonly gate: number;
+    readonly name: string;
+    readonly ok: boolean | undefined;
+    readonly detail: string;
+}
+/** The structured report `verifyExperiment` returns. */
+export interface ExperimentVerification {
+    readonly experimentId: string;
+    readonly experiment: unknown;
+    readonly checks: readonly VerificationCheck[];
+    readonly results: readonly unknown[];
+    readonly traceIds: readonly string[];
+    readonly verifiedTraceIds: readonly string[];
+    /** Checks that failed. */
+    readonly failures: readonly VerificationCheck[];
+    /** Checks a human has to decide. They do not make `ok` false. */
+    readonly manual: readonly VerificationCheck[];
+    readonly ok: boolean;
+    /** Turn a failed gate into an exception, for use in CI. */
+    raiseForStatus(): void;
+    toString(): string;
+}
+export interface VerifyExperimentOptions {
+    /** Fail the gate unless exactly this many result rows exist. */
+    readonly expectedCaseCount?: number;
+    /** How many case traces to read spans for. `null` reads every one. */
+    readonly maxTraces?: number | null;
+}
 /**
- * Run a complete Registry evaluation from a compact Braintrust-shaped definition.
+ * Run the documented seven-point evidence gate over a finished experiment.
+ *
+ * Reads the experiment, its result rows, its trace list and the spans of up to
+ * `maxTraces` case traces, and reports whether the evidence chain actually
+ * holds. It only reads; nothing is written.
  *
- * Every case is a root OTel trace. Task/provider spans and scorer spans nest
- * beneath it, verdicts cite immutable Registry scorer versions, result rows
- * carry the root trace ID, traces flush before summary, and the experiment is
- * explicitly finalized.
+ * Gate 7, the content and masking policy, cannot be decided from the data and
+ * is reported as a manual check rather than silently passed.
  */
-export declare function Eval<Input, Output, Expected = unknown, Metadata extends Record<string, unknown> = Record<string, unknown>>(name: string, evaluator: Evaluator<Input, Output, Expected, Metadata>, options?: EvalOptions): Promise<EvalResultWithSummary<Input, Output, Expected, Metadata>>;
+export declare function verifyExperiment(client: unknown, experimentId: string, options?: VerifyExperimentOptions): Promise<ExperimentVerification>;
 export {};