@cerebro-labs/agentnava-sdk 0.26.0

package/http.js

@@ -0,0 +1,192 @@
+// The transport. Everything else in this SDK is objects and method names.
+import { AgentNavaError, networkError } from "./errors.js";
+import { SDK_VERSION } from "./version.js";
+/** Tells the server which SDK is calling, on every request.
+ *
+ *  WHY A CUSTOM HEADER AND NOT `User-Agent`. `User-Agent` is on the fetch
+ *  spec's forbidden-header list, so a browser DROPS it SILENTLY: the request
+ *  still goes, the header just is not there, and the server sees a client of
+ *  unknown age with nothing to indicate anything went wrong. A header we name
+ *  ourselves is sent by every runtime the same way. `X-AgentNava-User-Id`
+ *  already exists on this API, so the shape is not new.
+ *
+ *  WHAT IT IS FOR. Not gating: the server does not refuse an old client on
+ *  sight. It is so the question "who would break if we removed this field"
+ *  has an answer that is a query rather than a guess. Once the package is on
+ *  a public registry, a customer can pin 0.25.0 and still be calling in three
+ *  years, and we have no other way to know they exist.
+ *
+ *  The runtime note is best-effort and deliberately coarse. It separates Node
+ *  from Bun from a browser, which is the distinction that explains most
+ *  support questions, and carries nothing identifying. */
+const CLIENT_HEADER = 'X-AgentNava-Client';
+function runtimeTag() {
+    const g = globalThis;
+    if (g.Bun?.version)
+        return `bun/${g.Bun.version}`;
+    if (g.process?.versions?.node)
+        return `node/${g.process.versions.node}`;
+    if (g.document !== undefined)
+        return 'browser';
+    return 'unknown';
+}
+/** `agentnava-sdk/0.25.0 (node/22.20.0)`. Computed once: it cannot change
+ *  within a process, and rebuilding it per request buys nothing. */
+const CLIENT_ID = `agentnava-sdk/${SDK_VERSION} (${runtimeTag()})`;
+const DEFAULT_BASE_URL = 'https://api.agentnava.com';
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** Read a variable without assuming which runtime we are on.
+ *
+ *  This SDK runs in Node, Bun, Deno, Workers and a browser bundle. `process` is
+ *  absent in several of those and touching it throws rather than returning
+ *  undefined, so the access is guarded rather than defaulted. */
+function readEnv(name) {
+    try {
+        const proc = globalThis.process;
+        return proc?.env?.[name];
+    }
+    catch {
+        return undefined;
+    }
+}
+export class Http {
+    #apiKey;
+    #baseURL;
+    #timeout;
+    #doFetch;
+    constructor(options = {}) {
+        const key = options.apiKey ?? readEnv('AGENTNAVA_API_KEY');
+        // Thrown at construction, not at the first call. A missing key is a
+        // configuration mistake, and finding it three layers into an async call
+        // stack makes it look like the call was at fault.
+        if (!key) {
+            throw new AgentNavaError({
+                message: 'No API key. Pass `AgentNava.getWorkspace({ apiKey })` or set AGENTNAVA_API_KEY in the environment.',
+                code: 'no_api_key',
+                status: 401,
+            });
+        }
+        this.#apiKey = key;
+        this.#baseURL = (options.baseURL ?? readEnv('AGENTNAVA_BASE_URL') ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.#timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.#doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    url(path, query) {
+        const url = new URL(this.#baseURL + path);
+        for (const [k, v] of Object.entries(query ?? {})) {
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        }
+        return url.toString();
+    }
+    /** Make the request and hand back the raw Response, errors already thrown. */
+    async send(path, options = {}) {
+        const headers = {
+            Authorization: `Bearer ${this.#apiKey}`,
+            [CLIENT_HEADER]: CLIENT_ID,
+        };
+        let body;
+        if (options.bytes !== undefined) {
+            body = options.bytes;
+            headers['Content-Type'] = options.contentType ?? 'application/octet-stream';
+        }
+        else if (options.body !== undefined) {
+            body = JSON.stringify(options.body);
+            headers['Content-Type'] = 'application/json';
+        }
+        // The caller's signal and our timeout both have to be able to abort, and
+        // AbortSignal.any is too new to rely on across every runtime this ships to.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.#timeout);
+        const onAbort = () => controller.abort();
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        let res;
+        try {
+            res = await this.#doFetch(this.url(path, options.query), {
+                method: options.method ?? 'GET',
+                headers,
+                ...(body !== undefined && { body }),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (options.signal?.aborted)
+                throw err;
+            throw networkError(controller.signal.aborted
+                ? `Request to ${path} timed out after ${this.#timeout}ms`
+                : `Request to ${path} failed: ${err instanceof Error ? err.message : String(err)}`, err);
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', onAbort);
+        }
+        if (!res.ok)
+            throw await toError(res, path);
+        return res;
+    }
+    async request(path, options = {}) {
+        const res = await this.send(path, options);
+        // 204, and any other empty body, is a successful nothing rather than a
+        // JSON parse error.
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        if (text.length === 0)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new AgentNavaError({
+                message: `Expected JSON from ${path}, got: ${text.slice(0, 200)}`,
+                code: 'bad_response',
+                status: res.status,
+            });
+        }
+    }
+    get(path, query) {
+        return this.request(path, { method: 'GET', ...(query && { query }) });
+    }
+    post(path, body, query) {
+        return this.request(path, { method: 'POST', body, ...(query && { query }) });
+    }
+    patch(path, body) {
+        return this.request(path, { method: 'PATCH', body });
+    }
+    delete(path, query) {
+        return this.request(path, { method: 'DELETE', ...(query && { query }) });
+    }
+}
+/** Turn a failed Response into the one error type this SDK throws. */
+async function toError(res, path) {
+    let message = `${res.status} from ${path}`;
+    let code = `http_${res.status}`;
+    try {
+        const text = await res.text();
+        if (text) {
+            try {
+                const parsed = JSON.parse(text);
+                message = parsed.message ?? parsed.error ?? text.slice(0, 300);
+                if (parsed.code)
+                    code = parsed.code;
+            }
+            catch {
+                message = text.slice(0, 300);
+            }
+        }
+    }
+    catch {
+        // A body we cannot read is not worth failing over; the status still is.
+    }
+    const retryAfterHeader = res.headers.get('retry-after');
+    const retryAfter = retryAfterHeader ? Number(retryAfterHeader) : undefined;
+    const requestId = res.headers.get('x-request-id') ?? undefined;
+    return new AgentNavaError({
+        message,
+        code,
+        status: res.status,
+        ...(retryAfter !== undefined && Number.isFinite(retryAfter) && { retryAfter }),
+        ...(requestId !== undefined && { requestId }),
+    });
+}
+//# sourceMappingURL=http.js.map

package/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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","sourcesContent":["// The transport. Everything else in this SDK is objects and method names.\n\nimport { AgentNavaError, networkError } from './errors.ts';\nimport { SDK_VERSION } from './version.ts';\n\nexport interface ClientOptions {\n\t/** Defaults to `AGENTNAVA_API_KEY` from the environment. */\n\tapiKey?: string;\n\t/** Defaults to `https://api.agentnava.com`. */\n\tbaseURL?: string;\n\t/** Per-request timeout in milliseconds. Default 60_000. */\n\ttimeout?: number;\n\t/** Swap the fetch implementation, for tests or a proxy. */\n\tfetch?: typeof globalThis.fetch;\n}\n\n/** Tells the server which SDK is calling, on every request.\n *\n *  WHY A CUSTOM HEADER AND NOT `User-Agent`. `User-Agent` is on the fetch\n *  spec's forbidden-header list, so a browser DROPS it SILENTLY: the request\n *  still goes, the header just is not there, and the server sees a client of\n *  unknown age with nothing to indicate anything went wrong. A header we name\n *  ourselves is sent by every runtime the same way. `X-AgentNava-User-Id`\n *  already exists on this API, so the shape is not new.\n *\n *  WHAT IT IS FOR. Not gating: the server does not refuse an old client on\n *  sight. It is so the question \"who would break if we removed this field\"\n *  has an answer that is a query rather than a guess. Once the package is on\n *  a public registry, a customer can pin 0.25.0 and still be calling in three\n *  years, and we have no other way to know they exist.\n *\n *  The runtime note is best-effort and deliberately coarse. It separates Node\n *  from Bun from a browser, which is the distinction that explains most\n *  support questions, and carries nothing identifying. */\nconst CLIENT_HEADER = 'X-AgentNava-Client';\n\nfunction runtimeTag(): string {\n\tconst g = globalThis as {\n\t\tBun?: { version?: string };\n\t\tprocess?: { versions?: { node?: string } };\n\t\tdocument?: unknown;\n\t};\n\tif (g.Bun?.version) return `bun/${g.Bun.version}`;\n\tif (g.process?.versions?.node) return `node/${g.process.versions.node}`;\n\tif (g.document !== undefined) return 'browser';\n\treturn 'unknown';\n}\n\n/** `agentnava-sdk/0.25.0 (node/22.20.0)`. Computed once: it cannot change\n *  within a process, and rebuilding it per request buys nothing. */\nconst CLIENT_ID = `agentnava-sdk/${SDK_VERSION} (${runtimeTag()})`;\n\nconst DEFAULT_BASE_URL = 'https://api.agentnava.com';\nconst DEFAULT_TIMEOUT_MS = 60_000;\n\n/** Read a variable without assuming which runtime we are on.\n *\n *  This SDK runs in Node, Bun, Deno, Workers and a browser bundle. `process` is\n *  absent in several of those and touching it throws rather than returning\n *  undefined, so the access is guarded rather than defaulted. */\nfunction readEnv(name: string): string | undefined {\n\ttry {\n\t\tconst proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;\n\t\treturn proc?.env?.[name];\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nexport interface RequestOptions {\n\tmethod?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';\n\t/** Sent as a JSON body. Mutually exclusive with `bytes`. */\n\tbody?: unknown;\n\t/** Sent as the raw body, for file writes. Mutually exclusive with `body`. */\n\tbytes?: ArrayBuffer | Uint8Array;\n\tcontentType?: string;\n\tquery?: Record<string, string | number | boolean | undefined>;\n\t/* THERE IS DELIBERATELY NO `raw` FLAG.\n\t *\n\t * One was declared here, described as \"return the Response untouched\", and\n\t * read by nothing. `request` parses JSON unconditionally, so every caller\n\t * that asked for `raw: true` got a parsed body and then called `.text()` or\n\t * `.arrayBuffer()` on it. `kb.files.text()` and `kb.files.get()` were broken\n\t * for every developer from the day they shipped, and the flag is why: it made\n\t * the call site look correct.\n\t *\n\t * Use `send()` for a Response and `request<T>()` for parsed JSON. Two methods\n\t * that differ by return type cannot be confused the way one method with a\n\t * boolean can. */\n\tsignal?: AbortSignal;\n}\n\nexport class Http {\n\treadonly #apiKey: string;\n\treadonly #baseURL: string;\n\treadonly #timeout: number;\n\treadonly #doFetch: typeof globalThis.fetch;\n\n\tconstructor(options: ClientOptions = {}) {\n\t\tconst key = options.apiKey ?? readEnv('AGENTNAVA_API_KEY');\n\t\t// Thrown at construction, not at the first call. A missing key is a\n\t\t// configuration mistake, and finding it three layers into an async call\n\t\t// stack makes it look like the call was at fault.\n\t\tif (!key) {\n\t\t\tthrow new AgentNavaError({\n\t\t\t\tmessage:\n\t\t\t\t\t'No API key. Pass `AgentNava.getWorkspace({ apiKey })` or set AGENTNAVA_API_KEY in the environment.',\n\t\t\t\tcode: 'no_api_key',\n\t\t\t\tstatus: 401,\n\t\t\t});\n\t\t}\n\t\tthis.#apiKey = key;\n\t\tthis.#baseURL = (options.baseURL ?? readEnv('AGENTNAVA_BASE_URL') ?? DEFAULT_BASE_URL).replace(\n\t\t\t/\\/+$/,\n\t\t\t'',\n\t\t);\n\t\tthis.#timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;\n\t\tthis.#doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);\n\t}\n\n\tprivate url(path: string, query?: RequestOptions['query']): string {\n\t\tconst url = new URL(this.#baseURL + path);\n\t\tfor (const [k, v] of Object.entries(query ?? {})) {\n\t\t\tif (v !== undefined) url.searchParams.set(k, String(v));\n\t\t}\n\t\treturn url.toString();\n\t}\n\n\t/** Make the request and hand back the raw Response, errors already thrown. */\n\tasync send(path: string, options: RequestOptions = {}): Promise<Response> {\n\t\tconst headers: Record<string, string> = {\n\t\t\tAuthorization: `Bearer ${this.#apiKey}`,\n\t\t\t[CLIENT_HEADER]: CLIENT_ID,\n\t\t};\n\t\tlet body: BodyInit | undefined;\n\t\tif (options.bytes !== undefined) {\n\t\t\tbody = options.bytes as BodyInit;\n\t\t\theaders['Content-Type'] = options.contentType ?? 'application/octet-stream';\n\t\t} else if (options.body !== undefined) {\n\t\t\tbody = JSON.stringify(options.body);\n\t\t\theaders['Content-Type'] = 'application/json';\n\t\t}\n\n\t\t// The caller's signal and our timeout both have to be able to abort, and\n\t\t// AbortSignal.any is too new to rely on across every runtime this ships to.\n\t\tconst controller = new AbortController();\n\t\tconst timer = setTimeout(() => controller.abort(), this.#timeout);\n\t\tconst onAbort = () => controller.abort();\n\t\toptions.signal?.addEventListener('abort', onAbort, { once: true });\n\n\t\tlet res: Response;\n\t\ttry {\n\t\t\tres = await this.#doFetch(this.url(path, options.query), {\n\t\t\t\tmethod: options.method ?? 'GET',\n\t\t\t\theaders,\n\t\t\t\t...(body !== undefined && { body }),\n\t\t\t\tsignal: controller.signal,\n\t\t\t});\n\t\t} catch (err) {\n\t\t\tif (options.signal?.aborted) throw err;\n\t\t\tthrow networkError(\n\t\t\t\tcontroller.signal.aborted\n\t\t\t\t\t? `Request to ${path} timed out after ${this.#timeout}ms`\n\t\t\t\t\t: `Request to ${path} failed: ${err instanceof Error ? err.message : String(err)}`,\n\t\t\t\terr,\n\t\t\t);\n\t\t} finally {\n\t\t\tclearTimeout(timer);\n\t\t\toptions.signal?.removeEventListener('abort', onAbort);\n\t\t}\n\n\t\tif (!res.ok) throw await toError(res, path);\n\t\treturn res;\n\t}\n\n\tasync request<T>(path: string, options: RequestOptions = {}): Promise<T> {\n\t\tconst res = await this.send(path, options);\n\t\t// 204, and any other empty body, is a successful nothing rather than a\n\t\t// JSON parse error.\n\t\tif (res.status === 204) return undefined as T;\n\t\tconst text = await res.text();\n\t\tif (text.length === 0) return undefined as T;\n\t\ttry {\n\t\t\treturn JSON.parse(text) as T;\n\t\t} catch {\n\t\t\tthrow new AgentNavaError({\n\t\t\t\tmessage: `Expected JSON from ${path}, got: ${text.slice(0, 200)}`,\n\t\t\t\tcode: 'bad_response',\n\t\t\t\tstatus: res.status,\n\t\t\t});\n\t\t}\n\t}\n\n\tget<T>(path: string, query?: RequestOptions['query']): Promise<T> {\n\t\treturn this.request<T>(path, { method: 'GET', ...(query && { query }) });\n\t}\n\tpost<T>(path: string, body?: unknown, query?: RequestOptions['query']): Promise<T> {\n\t\treturn this.request<T>(path, { method: 'POST', body, ...(query && { query }) });\n\t}\n\tpatch<T>(path: string, body?: unknown): Promise<T> {\n\t\treturn this.request<T>(path, { method: 'PATCH', body });\n\t}\n\tdelete<T>(path: string, query?: RequestOptions['query']): Promise<T> {\n\t\treturn this.request<T>(path, { method: 'DELETE', ...(query && { query }) });\n\t}\n}\n\n/** Turn a failed Response into the one error type this SDK throws. */\nasync function toError(res: Response, path: string): Promise<AgentNavaError> {\n\tlet message = `${res.status} from ${path}`;\n\tlet code = `http_${res.status}`;\n\ttry {\n\t\tconst text = await res.text();\n\t\tif (text) {\n\t\t\ttry {\n\t\t\t\tconst parsed = JSON.parse(text) as { message?: string; code?: string; error?: string };\n\t\t\t\tmessage = parsed.message ?? parsed.error ?? text.slice(0, 300);\n\t\t\t\tif (parsed.code) code = parsed.code;\n\t\t\t} catch {\n\t\t\t\tmessage = text.slice(0, 300);\n\t\t\t}\n\t\t}\n\t} catch {\n\t\t// A body we cannot read is not worth failing over; the status still is.\n\t}\n\n\tconst retryAfterHeader = res.headers.get('retry-after');\n\tconst retryAfter = retryAfterHeader ? Number(retryAfterHeader) : undefined;\n\tconst requestId = res.headers.get('x-request-id') ?? undefined;\n\n\treturn new AgentNavaError({\n\t\tmessage,\n\t\tcode,\n\t\tstatus: res.status,\n\t\t...(retryAfter !== undefined && Number.isFinite(retryAfter) && { retryAfter }),\n\t\t...(requestId !== undefined && { requestId }),\n\t});\n}\n"]}

package/import-tools.d.ts

@@ -0,0 +1,282 @@
+import type { HttpTool } from './types.ts';
+/** Something a human has to look at before these tools are good. */
+export type ImportWarningKind = 
+/** The source had no description worth showing a model. */
+'description-missing'
+/** A credential was found and replaced with a secret placeholder. */
+ | 'credential-stripped'
+/** The request body is a shape we cannot express (file upload, form-data). */
+ | 'unsupported-body'
+/** More tools than a model chooses well between. */
+ | 'too-many-tools'
+/** A `{{variable}}` the source never defined. */
+ | 'undefined-variable'
+/** Two endpoints produced the same tool name. */
+ | 'name-collision'
+/** A parameter was renamed to something the API will accept. */
+ | 'param-renamed';
+export interface ImportWarning {
+    kind: ImportWarningKind;
+    /** The tool it concerns, when it concerns one. */
+    tool?: string;
+    message: string;
+}
+export interface ImportedSecret {
+    /** Create this with `ws.secrets.create({ name, value })`. */
+    name: string;
+    /** The tools that reference it. */
+    usedBy: string[];
+    /** Where in the source it came from, so you can find the real value. */
+    from: string;
+}
+export interface ImportedTools {
+    /** Drafts. Read them before you ship them. */
+    tools: HttpTool[];
+    /** Secrets these tools need. None of them carries a value: see the note on
+     *  credentials in this module's header. */
+    secrets: ImportedSecret[];
+    /** Everything a human should decide. Never silently resolved. */
+    warnings: ImportWarning[];
+}
+export interface ImportOptions {
+    /** Name for the credential these requests authenticate with. Defaults are
+     *  derived from the header (`Authorization` becomes `API_TOKEN`), which is
+     *  fine for one API and confusing once you have three. */
+    secretName?: string;
+    /** Keep only the operations you want. Returning everything is rarely right:
+     *  a model picks markedly worse between forty tools than between eight. */
+    include?: (candidate: {
+        name: string;
+        method: string;
+        url: string;
+    }) => boolean;
+    /** Above this many tools, a `too-many-tools` warning is added. */
+    warnAbove?: number;
+}
+/** A tool name the API will accept: `^[a-z][a-z0-9_]{0,63}$`. */
+export declare function toolNameFrom(raw: string, fallback?: string): string;
+/** A param name the API will accept: `^[A-Za-z][A-Za-z0-9_]*$`.
+ *
+ *  THE WIRE NAME IS NOT THE PARAM NAME, and conflating them is what broke this.
+ *  An API's query key is whatever the API says it is (`page-size`,
+ *  `filter[status]`), while a param name is an identifier both our validator and
+ *  the runtime's placeholder regex constrain to `[A-Za-z][A-Za-z0-9_]*`. Copying
+ *  the wire name into the param name produced `400 params has invalid key
+ *  "page-size"` on documents that are completely ordinary, which is exactly the
+ *  unactionable 400 `uniqueName` exists to avoid. So the key on the wire keeps
+ *  its spelling and only the identifier is normalised. */
+export declare function paramNameFrom(raw: string, fallback?: string): string;
+interface PostmanItem {
+    name?: string;
+    request?: PostmanRequest | string;
+    item?: PostmanItem[];
+    description?: string;
+}
+interface PostmanRequest {
+    method?: string;
+    url?: string | {
+        raw?: string;
+        host?: string[];
+        path?: string[];
+        query?: {
+            key?: string;
+            value?: string;
+            description?: string;
+            disabled?: boolean;
+        }[];
+    };
+    header?: {
+        key?: string;
+        value?: string;
+        disabled?: boolean;
+    }[];
+    body?: {
+        mode?: string;
+        raw?: string;
+    };
+    description?: string;
+    auth?: {
+        type?: string;
+        [k: string]: unknown;
+    };
+}
+export interface PostmanCollection {
+    info?: {
+        name?: string;
+        description?: string;
+    };
+    item?: PostmanItem[];
+    variable?: {
+        key?: string;
+        value?: string;
+    }[];
+    auth?: {
+        type?: string;
+        [k: string]: unknown;
+    };
+}
+/**
+ * Draft tools from a Postman collection export (v2.0 or v2.1).
+ *
+ * WHY POSTMAN AND NOT ONLY OPENAPI. OpenAPI is tidier; a collection is truer. It
+ * holds the requests somebody has actually run, with the header names that
+ * really work and real values in the body, which is what a tool has to
+ * reproduce. Teams also already have one, and the best format to ask for is the
+ * one nobody has to make.
+ *
+ * WHAT IT COSTS: a collection has no parameter TYPES, so every parameter comes
+ * back a string. That is usually right and always safe; `fromOpenApi` gives real
+ * types where a document exists.
+ *
+ * VARIABLES. Postman writes `{{baseUrl}}`, which is the same shape as our own
+ * placeholders, so they map across almost directly. A variable the collection
+ * DEFINES is substituted, unless it holds something that looks like a
+ * credential, in which case it becomes a secret instead of being inlined. An
+ * undefined variable becomes a secret too, with a warning, because the
+ * alternative is a URL with a placeholder nothing resolves.
+ */
+export declare function fromPostman(collection: PostmanCollection, options?: ImportOptions): ImportedTools;
+interface OpenApiParam {
+    name?: string;
+    in?: string;
+    required?: boolean;
+    description?: string;
+    schema?: {
+        type?: string;
+        enum?: (string | number)[];
+    };
+}
+interface OpenApiOperation {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    parameters?: OpenApiParam[];
+    requestBody?: {
+        content?: Record<string, unknown>;
+    };
+    security?: unknown[];
+}
+export interface OpenApiDocument {
+    openapi?: string;
+    swagger?: string;
+    info?: {
+        title?: string;
+    };
+    servers?: {
+        url?: string;
+    }[];
+    host?: string;
+    basePath?: string;
+    schemes?: string[];
+    paths?: Record<string, Record<string, OpenApiOperation>>;
+    components?: {
+        securitySchemes?: Record<string, {
+            type?: string;
+            scheme?: string;
+            name?: string;
+            in?: string;
+        }>;
+    };
+    securityDefinitions?: Record<string, {
+        type?: string;
+        name?: string;
+        in?: string;
+    }>;
+    security?: unknown[];
+}
+/**
+ * Draft tools from an OpenAPI 3 or Swagger 2 document.
+ *
+ * WHAT THIS GIVES THAT POSTMAN DOES NOT: real parameter types and required
+ * flags, which is exactly the shape `HttpToolParam` wants, and an enum where the
+ * document declares one. FastAPI publishes this at `/openapi.json` without
+ * anybody writing it, so for a FastAPI shop this is usually the richer source.
+ *
+ * WHAT IT STILL DOES NOT GIVE: a description a model can choose on. `summary`
+ * is written for a developer reading a reference. Read the warnings.
+ */
+export declare function fromOpenApi(doc: OpenApiDocument, options?: ImportOptions): ImportedTools;
+/**
+ * Fetch an OpenAPI document and draft tools from it.
+ *
+ * THE FETCH GOES TO YOUR SERVER, NOT OURS. Pass `headers` if the document itself
+ * is behind auth. Nothing about the document is sent to AgentNava: the drafts
+ * are built in this process and you decide what to do with them.
+ */
+export declare function fromOpenApiUrl(url: string, options?: ImportOptions & {
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+}): Promise<ImportedTools>;
+/**
+ * Draft one tool from a curl command.
+ *
+ * THE LOWEST BAR ON PURPOSE. A team with no collection and no document still has
+ * a curl command that works, usually pasted in a chat thread, and that is enough
+ * to start. Handles the flags people actually use: `-X`, `-H`, `-d`/`--data`,
+ * `--data-raw`, `--url`, and a bare URL.
+ *
+ * Give it a `name` and a `description`: a curl command carries neither, and the
+ * description is the field that decides whether the agent picks this tool.
+ */
+export declare function fromCurl(command: string, options?: ImportOptions & {
+    name?: string;
+    description?: string;
+}): ImportedTools;
+/** Where a draft comes from. Exactly one key. */
+export type ImportSource = 
+/** An OpenAPI 3 or Swagger 2 document you already have in memory. */
+{
+    openapi: OpenApiDocument;
+}
+/** A URL serving one. FastAPI publishes `/openapi.json` for free. The fetch
+ *  goes to YOUR server; nothing is sent to AgentNava. */
+ | {
+    openapiUrl: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+}
+/** A Postman collection export, v2.0 or v2.1. */
+ | {
+    postman: PostmanCollection;
+}
+/** One working curl command. */
+ | {
+    curl: string;
+    name?: string;
+    description?: string;
+};
+/**
+ * Draft tools from whatever a company already has.
+ *
+ * NO SOURCE IS THE PRIMARY ONE, and that is deliberate. Which artifact a team
+ * can hand you is an accident of what they already keep, not a statement about
+ * how good their API is:
+ *
+ *   OpenAPI    the actual standard, and what every API gateway publishes
+ *              (Apigee, MuleSoft, Kong, Azure APIM). Gives real parameter
+ *              TYPES, required flags and enums. Often auto-generated, which
+ *              means the descriptions are frequently empty.
+ *   Postman    the most widely used API client there is, and for many teams the
+ *              only artifact anybody maintains. No parameter types, but it holds
+ *              the requests somebody has actually RUN: the header names that
+ *              really work and real example bodies.
+ *   curl       the lowest bar. A team with neither of the above still has a
+ *              command that works, usually pasted in a chat thread.
+ *
+ * They all produce the same reviewable shape, because the useful step is not the
+ * parsing. It is what comes after: choosing which operations an agent should
+ * have and writing what each one is for.
+ *
+ * ```ts
+ * const draft = await importTools({ openapiUrl: 'https://api.acme.com/openapi.json' });
+ * const draft =       importTools({ postman: collection });
+ * const draft =       importTools({ curl: 'curl -X POST https://api.acme.com/refunds -d ...' });
+ * ```
+ */
+export declare function importTools(source: Exclude<ImportSource, {
+    openapiUrl: string;
+}>, options?: ImportOptions): ImportedTools;
+export declare function importTools(source: Extract<ImportSource, {
+    openapiUrl: string;
+}>, options?: ImportOptions): Promise<ImportedTools>;
+export {};