@neon/tools 0.5.0 → 0.7.0

package/dist/lib/ergonomic/bind.d.ts

@@ -0,0 +1,57 @@
+import { type NeonClient, type NeonConfig, type Paginated } from "@neon/sdk";
+import * as z from "zod";
+import { type NeonOperationId, operationFactories } from "../../operations.gen.js";
+import { type NeonBearerCredential } from "../auth.js";
+import type { JsonSafe, NeonTool, NeonToolAnnotations, NeonToolExecutionContext } from "../operation.js";
+import type { NeonToolId } from "./ids.js";
+export interface ToolClientOptions {
+    apiKey?: NeonBearerCredential;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    wait?: NeonConfig["wait"];
+}
+type Snake<S extends string> = S extends `${infer Head}${infer Rest}` ? Head extends Uppercase<Head> ? Head extends Lowercase<Head> ? `${Head}${Snake<Rest>}` : `_${Lowercase<Head>}${Snake<Rest>}` : `${Head}${Snake<Rest>}` : S;
+type LastSegment<Id extends string> = Id extends `${string}.${infer Rest}` ? LastSegment<Rest> : Id;
+type ResourcePath<Id extends string, Acc extends string = ""> = Id extends `${infer Head}.${infer Rest}` ? ResourcePath<Rest, Acc extends "" ? Head : `${Acc}.${Head}`> : Acc;
+type SnakeDots<Id extends string> = Id extends `${infer Head}.${infer Rest}` ? `${Snake<Head>}_${SnakeDots<Rest>}` : Snake<Id>;
+export type PublishedId<Id extends string> = Id extends `${string}.${string}` ? `${Snake<LastSegment<Id>>}_${SnakeDots<ResourcePath<Id>>}` : Snake<Id>;
+export declare const publishedId: <Id extends string>(id: Id) => PublishedId<Id>;
+export declare const toolClient: (options: ToolClientOptions, context?: NeonToolExecutionContext) => NeonClient<true>;
+export declare const collectObjectList: (neon: NeonClient<true>, input: {
+    project_id: string;
+    branch_id: string;
+    bucket_name: string;
+    prefix?: string;
+    delimiter?: string;
+    limit?: number;
+}, signal?: AbortSignal) => Promise<{
+    folders: string[];
+    objects: import("@neon/sdk").BucketObject[];
+    prefix: string;
+}>;
+export declare const collectPages: <T>(list: Paginated<T>, maxItems?: number) => Promise<T[]>;
+export declare const bindTool: <const InputSchema extends z.ZodType, const Id extends string, Output>(options: ToolClientOptions, tool: Omit<NeonTool<InputSchema, Id, JsonSafe<Awaited<Output>>>, "execute">, run: (neon: NeonClient<true>, input: z.output<InputSchema>, signal?: AbortSignal) => Promise<Output>) => NeonTool<InputSchema, Id, JsonSafe<Awaited<Output>>>;
+type GeneratedTool<G extends NeonOperationId> = ReturnType<(typeof operationFactories)[G]>;
+type GeneratedSchema<G extends NeonOperationId> = GeneratedTool<G>["inputSchema"];
+type GeneratedInput<G extends NeonOperationId> = z.output<GeneratedSchema<G>>;
+type GeneratedArg<G extends NeonOperationId> = z.input<GeneratedSchema<G>>;
+type FromGeneratedMeta = {
+    list?: boolean;
+    annotations?: NeonToolAnnotations;
+    requiresApproval?: boolean;
+};
+type OmittedInput<G extends NeonOperationId, Keys extends string> = Omit<GeneratedInput<G>, Keys>;
+type OmittedArg<G extends NeonOperationId, Keys extends string> = Omit<GeneratedArg<G>, Keys>;
+export declare function fromGenerated<const Id extends NeonToolId, const G extends NeonOperationId, Output>(options: ToolClientOptions, spec: FromGeneratedMeta & {
+    id: Id;
+    generated: G;
+    run: (neon: NeonClient<true>, input: GeneratedInput<G>, signal?: AbortSignal) => Promise<Output>;
+}): NeonTool<GeneratedSchema<G>, PublishedId<Id>, JsonSafe<Awaited<Output>>>;
+export declare function fromGenerated<const Id extends NeonToolId, const G extends NeonOperationId, const Keys extends keyof GeneratedInput<G> & string, Output>(options: ToolClientOptions, spec: FromGeneratedMeta & {
+    id: Id;
+    generated: G;
+    omit: readonly Keys[];
+    run: (neon: NeonClient<true>, input: OmittedInput<G, Keys>, signal?: AbortSignal) => Promise<Output>;
+}): NeonTool<z.ZodType<OmittedInput<G, Keys>, OmittedArg<G, Keys>>, PublishedId<Id>, JsonSafe<Awaited<Output>>>;
+export {};
+//# sourceMappingURL=bind.d.ts.map

package/dist/lib/ergonomic/bind.d.ts.map

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

package/dist/lib/ergonomic/bind.js

@@ -0,0 +1,126 @@
+import { missingBearerCredential, requireBearerCredential } from "../auth.js";
+import { toToolResult } from "../result.js";
+import { operationFactories } from "../../operations.gen.js";
+import { NeonError, createNeonClient } from "@neon/sdk";
+import * as z from "zod";
+//#region src/lib/ergonomic/bind.ts
+const ALL_PAGES = " This tool returns every page. Pass limit to cap how many items come back. Do not pass a cursor.";
+const inertClient = createNeonClient({ apiKey: "unused" }).client;
+const snakeSegment = (segment) => segment.replace(/[A-Z]/g, (character) => `_${character.toLowerCase()}`);
+const publishedId = (id) => {
+	const dot = id.lastIndexOf(".");
+	if (dot === -1) return snakeSegment(id);
+	return `${snakeSegment(id.slice(dot + 1))}_${id.slice(0, dot).split(".").map(snakeSegment).join("_")}`;
+};
+const resolveApiKey = (options, context) => {
+	if (context !== void 0 && "apiKey" in context) {
+		if (context.apiKey === void 0) throw new TypeError("A Neon API key or OAuth access token is required");
+		return requireBearerCredential(context.apiKey);
+	}
+	return options.apiKey === void 0 ? missingBearerCredential : requireBearerCredential(options.apiKey);
+};
+const toolClient = (options, context) => createNeonClient({
+	apiKey: resolveApiKey(options, context),
+	throwOnError: true,
+	waitForReadiness: true,
+	...options.baseUrl === void 0 ? {} : { baseUrl: options.baseUrl },
+	...options.fetch === void 0 ? {} : { fetch: options.fetch },
+	...options.wait === void 0 ? {} : { wait: options.wait }
+});
+const objectListPage = (value) => {
+	if ("objects" in value && "folders" in value) return value;
+	if ("error" in value && value.error !== void 0) throw value.error;
+	if ("data" in value && value.data !== void 0) return value.data;
+	throw new NeonError("Object list returned no data.", "client");
+};
+const collectObjectList = async (neon, input, signal) => {
+	const folders = [];
+	const objects = [];
+	let prefix = "";
+	let cursor;
+	for (;;) {
+		const page = objectListPage(await neon.storage.objects.list(input.project_id, input.branch_id, input.bucket_name, {
+			...input.prefix === void 0 ? {} : { prefix: input.prefix },
+			...input.delimiter === void 0 ? {} : { delimiter: input.delimiter },
+			...input.limit === void 0 ? {} : { limit: input.limit },
+			...cursor === void 0 ? {} : { cursor }
+		}, { signal }));
+		for (const folder of page.folders) {
+			if (input.limit !== void 0 && folders.length + objects.length >= input.limit) break;
+			folders.push(folder);
+		}
+		for (const object of page.objects) {
+			if (input.limit !== void 0 && folders.length + objects.length >= input.limit) break;
+			objects.push(object);
+		}
+		prefix = page.prefix;
+		if (input.limit !== void 0 && folders.length + objects.length >= input.limit) break;
+		if (page.next_cursor) {
+			cursor = page.next_cursor;
+			continue;
+		}
+		if (page.is_truncated) throw new NeonError("Object list was truncated without a next cursor.", "client");
+		break;
+	}
+	return {
+		folders,
+		objects,
+		prefix
+	};
+};
+const collectPages = async (list, maxItems) => {
+	if (maxItems === void 0) {
+		const result = await list.all();
+		if (result.error) throw result.error;
+		if (result.data === void 0) throw new NeonError("List returned no data.", "client");
+		return result.data;
+	}
+	const items = [];
+	let cursor;
+	for (;;) {
+		const result = await list.page(cursor);
+		if (result.error) throw result.error;
+		if (result.data === void 0) throw new NeonError("List returned no data.", "client");
+		items.push(...result.data.items);
+		if (items.length >= maxItems) return items.slice(0, maxItems);
+		if (!result.data.cursor || result.data.items.length === 0) break;
+		cursor = result.data.cursor;
+	}
+	return items;
+};
+const bindTool = (options, tool, run) => ({
+	...tool,
+	async execute(input, context) {
+		const parsed = await tool.inputSchema.parseAsync(input);
+		const result = await run(toolClient(options, context), parsed, context?.signal);
+		return toToolResult(result);
+	}
+});
+function fromGenerated(options, spec) {
+	const generated = operationFactories[spec.generated](inertClient);
+	const schema = generated.inputSchema;
+	const inputSchema = spec.omit === void 0 || spec.omit.length === 0 ? schema : omitObjectKeys(schema, spec.omit);
+	return {
+		operationId: spec.id,
+		id: publishedId(spec.id),
+		title: generated.title,
+		description: spec.list ? `${generated.description.trimEnd()}${ALL_PAGES}` : generated.description,
+		inputSchema,
+		annotations: spec.annotations ?? generated.annotations,
+		requiresApproval: spec.requiresApproval ?? generated.requiresApproval,
+		metadata: generated.metadata,
+		async execute(input, context) {
+			const parsed = await inputSchema.parseAsync(input);
+			const result = await spec.run(toolClient(options, context), parsed, context?.signal);
+			return toToolResult(result);
+		}
+	};
+}
+const omitObjectKeys = (schema, keys) => {
+	if (!(schema instanceof z.ZodObject)) throw new TypeError("Generated tool input schemas must be objects");
+	const mask = {};
+	for (const key of keys) mask[key] = true;
+	return schema.omit(mask);
+};
+//#endregion
+export { bindTool, collectObjectList, collectPages, fromGenerated, publishedId, toolClient };