@atlanai/sdk 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @atlanai/sdk
+
+TypeScript management client for the public Atlan Agent Gateway API. Use
+`AtlanClient` for stable service namespaces. Generated clients are available
+below `client.raw` and package subpaths under `@atlanai/sdk/raw/*`.
+
+Tracing is an authored follow-on and is not included in the current TypeScript
+package. It will not be generated from the management OpenAPI contract.
+
+## Local install
+
+Build the package from the repository root:
+
+```bash
+npm --prefix typescript ci --ignore-scripts
+npm --prefix typescript run build
+```
+
+Install the built checkout into a local project:
+
+```bash
+npm install /absolute/path/to/sdk/typescript --ignore-scripts
+```
+
+Pass the Gateway origin and bearer explicitly:
+
+```typescript
+import { AtlanClient, rawAgent } from "@atlanai/sdk";
+
+declare const process: { env: Record<string, string | undefined> };
+
+const client = new AtlanClient({
+  gatewayOrigin: process.env.ATLANAI_GATEWAY_URL!,
+  bearerToken: process.env.ATLANAI_TOKEN!,
+});
+
+const agentsApi = client.agents.apis.agents as rawAgent.AgentsApi;
+const page = await agentsApi.agentListAgents({ limit: 10 });
+console.log(page.items.length);
+```
+
+See [the complete local setup guide](../docs/getting-started.md) for direct
+Registry configuration and the current typed-namespace follow-up. The
+[generated TypeScript reference](../docs/reference/README.md) covers every raw
+operation and model.

package/dist/client.d.ts

@@ -0,0 +1,64 @@
+import { type Operation } from "./operations";
+import { type Resource } from "./resources";
+type TokenProvider = () => string | Promise<string>;
+type FetchImplementation = typeof fetch;
+type GeneratedConfiguration = {
+    accessToken?: (name?: string, scopes?: string[]) => string | Promise<string>;
+};
+type GeneratedModule = {
+    Configuration: new (options: Record<string, unknown>) => GeneratedConfiguration;
+    [name: string]: unknown;
+};
+export interface AtlanClientOptions {
+    gatewayOrigin: string;
+    bearerToken?: string;
+    tokenProvider?: TokenProvider;
+    timeoutMs?: number;
+    fetch?: FetchImplementation;
+    /**
+     * Default workspace for workspace-scoped operations, sent as
+     * `X-Atlan-Workspace-Id`. An operation's own workspace argument always wins:
+     * the generated runtime applies per-operation headers over configuration
+     * headers. Use {@link AtlanClient.withWorkspace} to switch at runtime.
+     */
+    workspace?: string;
+}
+export declare const WORKSPACE_HEADER = "X-Atlan-Workspace-Id";
+/** A generated operation reached by its contract method name off a namespace. */
+export type ForwardedOperation = (...args: never[]) => Promise<unknown>;
+/**
+ * A namespace plus the operations it forwards.
+ *
+ * The forwarded operations are resolved at call time, so they cannot be
+ * declared one by one and their arguments and results are not typed here. Reach
+ * an operation through `apis` when you want the generated signatures.
+ */
+export type Service = ServiceNamespace & Record<string, ForwardedOperation>;
+export declare class ServiceNamespace {
+    readonly name: string;
+    readonly configuration: GeneratedConfiguration;
+    readonly apis: Readonly<Record<string, object>>;
+    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">[]);
+}
+/** 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 class AtlanClient {
+    /** Per-service generated clients, for an operation the map has not surfaced. */
+    readonly raw: Readonly<Record<string, Service>>;
+    /** Every resource, keyed by its dotted path. */
+    readonly resources: Readonly<Record<string, Resource>>;
+    readonly workspace: string | undefined;
+    constructor(options: AtlanClientOptions);
+    /**
+     * Return a client scoped to `workspace`, reusing this one's `fetch`
+     * implementation, timeout, and credentials. Only the thin generated
+     * configuration and API objects are rebuilt; connection reuse is unaffected
+     * because the same `fetch` implementation serves both.
+     */
+    withWorkspace(workspace: string | undefined): AtlanClient;
+    private readonly rebind;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,291 @@
+"use strict";
+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.AtlanClient = exports.ServiceNamespace = exports.WORKSPACE_HEADER = void 0;
+exports.createService = createService;
+const agentRaw = __importStar(require("./raw/agent/index"));
+const apiRaw = __importStar(require("./raw/api/index"));
+const fileRaw = __importStar(require("./raw/file/index"));
+const mcpRaw = __importStar(require("./raw/mcp/index"));
+const modelRaw = __importStar(require("./raw/model/index"));
+const otelRaw = __importStar(require("./raw/otel/index"));
+const registryRaw = __importStar(require("./raw/registry/index"));
+const secretRaw = __importStar(require("./raw/secret/index"));
+const skillRaw = __importStar(require("./raw/skill/index"));
+const errors_1 = require("./errors");
+const operations_1 = require("./operations");
+const resources_1 = require("./resources");
+// Sent as the default workspace for workspace-scoped operations.
+exports.WORKSPACE_HEADER = "X-Atlan-Workspace-Id";
+class ServiceNamespace {
+    name;
+    configuration;
+    apis;
+    operations;
+    /** Contract method names for this service, used to resolve a forwarded call. */
+    operationMethods;
+    constructor(name, module, configuration, serviceOperations) {
+        this.name = name;
+        this.configuration = configuration;
+        this.operations = serviceOperations;
+        const operationMethods = new Set(serviceOperations.map((operation) => methodName(operation.operation_id)));
+        this.operationMethods = operationMethods;
+        const apis = {};
+        for (const [exportName, value] of Object.entries(module)) {
+            if (!exportName.endsWith("Api") || typeof value !== "function")
+                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);
+        }
+        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);
+    return forwardOperations(namespace, namespace.operationMethods);
+}
+/**
+ * Let a namespace answer an operation by its contract method name.
+ *
+ * Without this the facade cannot make a call: a namespace exposed only `apis`,
+ * so every operation had to be reached through the OpenAPI tag that happens to
+ * own it — the one identifier the contract renames (`skills` became `skill`,
+ * `files` became `file`). Python resolves the same way, so the two SDKs now
+ * present the same surface for the same contract.
+ *
+ * Resolution is deliberately strict. A name carried by two generated APIs
+ * throws rather than picking one, because silently choosing between two
+ * same-named operations would be a wrong call, not a convenience.
+ */
+function forwardOperations(namespace, operationMethods) {
+    const owners = new Map();
+    const ambiguous = new Set();
+    for (const api of Object.values(namespace.apis)) {
+        for (const method of operationMethods) {
+            if (typeof api[method] !== "function")
+                continue;
+            if (owners.has(method))
+                ambiguous.add(method);
+            else
+                owners.set(method, api);
+        }
+    }
+    // The generators prefix every method with the service, so the full name
+    // repeats what the namespace already said: `client.agents` then
+    // `agentCreateAgent`. The short name drops that prefix, which is how the
+    // operation reads in the contract and how a caller would guess it —
+    // `client.agents.createAgent(...)`. Both spellings resolve, because the long
+    // one is what every existing caller and published example uses, and across
+    // all 189 operations no short name collides with another, with an OpenAPI
+    // tag, or with a property of the namespace.
+    const prefixed = (property) => namespace.name + property.charAt(0).toUpperCase() + property.slice(1);
+    return new Proxy(namespace, {
+        get(target, property, receiver) {
+            if (typeof property !== "string" || Reflect.has(target, property)) {
+                return Reflect.get(target, property, receiver);
+            }
+            for (const candidate of [property, prefixed(property)]) {
+                if (ambiguous.has(candidate)) {
+                    throw new TypeError(`'${target.name}' has no unambiguous generated API or operation '${candidate}'`);
+                }
+                const owner = owners.get(candidate);
+                if (owner !== undefined) {
+                    // Bound to its own API so the generated method keeps its configuration.
+                    return owner[candidate].bind(owner);
+                }
+            }
+            return undefined;
+        },
+    });
+}
+function methodName(operationId) {
+    const [service, operation] = operationId.split(".", 2);
+    return service + operation.charAt(0).toUpperCase() + operation.slice(1);
+}
+function wrapGeneratedAPI(api, operationMethods) {
+    return new Proxy(api, {
+        get(target, property, receiver) {
+            const value = Reflect.get(target, property, receiver);
+            if (typeof property !== "string" || typeof value !== "function" || !operationMethods.has(property)) {
+                return value;
+            }
+            return async (...args) => {
+                try {
+                    return await Reflect.apply(value, target, args);
+                }
+                catch (error) {
+                    const response = error?.response;
+                    if (response instanceof Response) {
+                        throw await errors_1.AtlanAPIError.fromResponse(response);
+                    }
+                    throw error;
+                }
+            };
+        },
+    });
+}
+class AtlanClient {
+    /** Per-service generated clients, for an operation the map has not surfaced. */
+    raw;
+    /** Every resource, keyed by its dotted path. */
+    resources;
+    workspace;
+    constructor(options) {
+        const origin = validateOrigin(options.gatewayOrigin);
+        if (options.bearerToken !== undefined && options.tokenProvider !== undefined) {
+            throw new Error("configure bearerToken or tokenProvider, not both");
+        }
+        const timeoutMs = options.timeoutMs ?? 30_000;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw new Error("timeoutMs must be greater than zero");
+        }
+        const fetchApi = withTimeout(options.fetch ?? globalThis.fetch, timeoutMs);
+        const accessToken = safeTokenProvider(options.bearerToken, options.tokenProvider);
+        const workspace = validateWorkspace(options.workspace);
+        const modules = {
+            registry: registryRaw,
+            skill: skillRaw,
+            file: fileRaw,
+            agent: agentRaw,
+            mcp: mcpRaw,
+            secret: secretRaw,
+            model: modelRaw,
+            api: apiRaw,
+            otel: otelRaw,
+        };
+        const namespaces = {};
+        for (const service of operations_1.operationManifest.services) {
+            const module = modules[service.name];
+            const configuration = new module.Configuration({
+                basePath: origin + service.base_path,
+                fetchApi,
+                accessToken,
+                ...(workspace === undefined ? {} : { headers: { [exports.WORKSPACE_HEADER]: workspace } }),
+            });
+            namespaces[service.name] = createService(service.name, module, configuration, service.operations);
+        }
+        this.raw = Object.freeze(namespaces);
+        // Resources, not services. A service is a base path; a resource is what a
+        // caller is actually working with, so `client.sessions.messages` reads the
+        // way the API does.
+        const resources = (0, resources_1.buildResources)(resources_1.resourceMap, namespaces);
+        this.resources = Object.freeze(resources);
+        Object.assign(this, resources);
+        this.workspace = workspace;
+        // A closure rather than a stored options object: `bearerToken` must not sit
+        // in an enumerable field, where `JSON.stringify(client)` or a debug log
+        // would print it. Functions are skipped by both.
+        this.rebind = (next) => new AtlanClient({ ...options, workspace: next });
+    }
+    /**
+     * Return a client scoped to `workspace`, reusing this one's `fetch`
+     * implementation, timeout, and credentials. Only the thin generated
+     * configuration and API objects are rebuilt; connection reuse is unaffected
+     * because the same `fetch` implementation serves both.
+     */
+    withWorkspace(workspace) {
+        return this.rebind(workspace);
+    }
+    rebind;
+}
+exports.AtlanClient = AtlanClient;
+function validateWorkspace(workspace) {
+    if (workspace === undefined)
+        return undefined;
+    if (typeof workspace !== "string") {
+        throw new Error("workspace must be a string");
+    }
+    // A header value carrying a newline would let a caller inject further headers.
+    if (workspace.trim() !== workspace || /[\r\n]/.test(workspace)) {
+        throw new Error("workspace must not contain leading, trailing, or newline whitespace");
+    }
+    return workspace === "" ? undefined : workspace;
+}
+function safeTokenProvider(bearerToken, provider) {
+    // A closure, never the raw string. Handed a string, the generated
+    // Configuration retains it in an enumerable field, which puts the bearer
+    // token in `JSON.stringify(client)` and in any debug log of the facade.
+    if (bearerToken !== undefined)
+        return async () => bearerToken;
+    if (!provider)
+        return undefined;
+    return async () => {
+        try {
+            const token = await provider();
+            if (typeof token !== "string")
+                throw new Error("invalid token");
+            return token;
+        }
+        catch {
+            throw new Error("bearer token provider failed");
+        }
+    };
+}
+function withTimeout(baseFetch, timeoutMs) {
+    return async (input, init) => {
+        const controller = new AbortController();
+        const callerSignal = init?.signal;
+        const forwardAbort = () => controller.abort(callerSignal?.reason);
+        callerSignal?.addEventListener("abort", forwardAbort, { once: true });
+        const timer = setTimeout(() => controller.abort(new Error("request timed out")), timeoutMs);
+        try {
+            return await baseFetch(input, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+            callerSignal?.removeEventListener("abort", forwardAbort);
+        }
+    };
+}
+function validateOrigin(origin) {
+    const normalized = origin.trim().replace(/\/+$/, "");
+    let parsed;
+    try {
+        parsed = new URL(normalized);
+    }
+    catch {
+        throw new Error("gatewayOrigin must be an absolute HTTP(S) URL");
+    }
+    if (!["http:", "https:"].includes(parsed.protocol) || !parsed.host) {
+        throw new Error("gatewayOrigin must be an absolute HTTP(S) URL");
+    }
+    if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+        throw new Error("gatewayOrigin must not contain credentials, a query, or a fragment");
+    }
+    return normalized;
+}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+export declare class AtlanAPIError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly title: string;
+    readonly detail: string;
+    readonly traceId?: string;
+    constructor(options: {
+        status: number;
+        code?: string;
+        title?: string;
+        detail?: string;
+        traceId?: string;
+    });
+    static fromResponse(response: Response): Promise<AtlanAPIError>;
+}

package/dist/errors.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtlanAPIError = void 0;
+class AtlanAPIError extends Error {
+    status;
+    code;
+    title;
+    detail;
+    traceId;
+    constructor(options) {
+        const suffix = options.code ? ` (${options.code})` : "";
+        super(`Atlan API request failed with status ${options.status}${suffix}`);
+        this.name = "AtlanAPIError";
+        this.status = options.status;
+        this.code = options.code ?? "";
+        this.title = options.title ?? "";
+        this.detail = options.detail ?? "";
+        this.traceId = options.traceId;
+    }
+    static async fromResponse(response) {
+        let problem = {};
+        try {
+            const contentLength = Number(response.headers.get("content-length") ?? "0");
+            if (!contentLength || contentLength <= 1 << 20) {
+                const decoded = await response.clone().json();
+                if (decoded && typeof decoded === "object" && !Array.isArray(decoded)) {
+                    problem = decoded;
+                }
+            }
+        }
+        catch {
+            // A malformed/non-problem body must not be copied into the safe error.
+        }
+        return new AtlanAPIError({
+            status: response.status,
+            code: typeof problem.code === "string" ? problem.code : "",
+            title: typeof problem.title === "string" ? problem.title : "",
+            detail: typeof problem.detail === "string" ? problem.detail : "",
+            traceId: typeof problem.trace_id === "string" ? problem.trace_id : undefined,
+        });
+    }
+}
+exports.AtlanAPIError = AtlanAPIError;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { AtlanClient, ServiceNamespace, createService } from "./client";
+export type { AtlanClientOptions, ForwardedOperation, Service } from "./client";
+export { buildResources, resourceMap } from "./resources";
+export type { Resource, ResourceOperation } from "./resources";
+export { AtlanAPIError } from "./errors";
+export { operationManifest, operations } from "./operations";
+export type { Operation, OperationManifest, ServiceContract } from "./operations";
+export * as rawAgent from "./raw/agent/index";
+export * as rawAPI from "./raw/api/index";
+export * as rawFile from "./raw/file/index";
+export * as rawMCP from "./raw/mcp/index";
+export * as rawModel from "./raw/model/index";
+export * as rawOTel from "./raw/otel/index";
+export * as rawRegistry from "./raw/registry/index";
+export * as rawSecret from "./raw/secret/index";
+export * as rawSkill from "./raw/skill/index";

package/dist/index.js

@@ -0,0 +1,57 @@
+"use strict";
+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.rawSkill = exports.rawSecret = exports.rawRegistry = exports.rawOTel = exports.rawModel = exports.rawMCP = exports.rawFile = exports.rawAPI = exports.rawAgent = exports.operations = exports.operationManifest = exports.AtlanAPIError = exports.resourceMap = exports.buildResources = exports.createService = exports.ServiceNamespace = exports.AtlanClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "AtlanClient", { enumerable: true, get: function () { return client_1.AtlanClient; } });
+Object.defineProperty(exports, "ServiceNamespace", { enumerable: true, get: function () { return client_1.ServiceNamespace; } });
+Object.defineProperty(exports, "createService", { enumerable: true, get: function () { return client_1.createService; } });
+var resources_1 = require("./resources");
+Object.defineProperty(exports, "buildResources", { enumerable: true, get: function () { return resources_1.buildResources; } });
+Object.defineProperty(exports, "resourceMap", { enumerable: true, get: function () { return resources_1.resourceMap; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "AtlanAPIError", { enumerable: true, get: function () { return errors_1.AtlanAPIError; } });
+var operations_1 = require("./operations");
+Object.defineProperty(exports, "operationManifest", { enumerable: true, get: function () { return operations_1.operationManifest; } });
+Object.defineProperty(exports, "operations", { enumerable: true, get: function () { return operations_1.operations; } });
+exports.rawAgent = __importStar(require("./raw/agent/index"));
+exports.rawAPI = __importStar(require("./raw/api/index"));
+exports.rawFile = __importStar(require("./raw/file/index"));
+exports.rawMCP = __importStar(require("./raw/mcp/index"));
+exports.rawModel = __importStar(require("./raw/model/index"));
+exports.rawOTel = __importStar(require("./raw/otel/index"));
+exports.rawRegistry = __importStar(require("./raw/registry/index"));
+exports.rawSecret = __importStar(require("./raw/secret/index"));
+exports.rawSkill = __importStar(require("./raw/skill/index"));