@agentuity/core 0.0.33 → 0.0.35

package/src/services/_util.ts

@@ -0,0 +1,117 @@
+import { safeStringify } from '../json';
+import type { Body } from './adapter';
+import { ServiceException } from './exception';
+
+export const buildUrl = (
+	base: string,
+	path: string,
+	subpath?: string,
+	query?: URLSearchParams
+): string => {
+	path = path.startsWith('/') ? path : `/${path}`;
+	let url = base.replace(/\/$/, '') + path;
+	if (subpath) {
+		subpath = subpath.startsWith('/') ? subpath : `/${subpath}`;
+		url += subpath;
+	}
+	if (query) {
+		url += `?${query.toString()}`;
+	}
+	return url;
+};
+
+export async function toServiceException(response: Response): Promise<ServiceException> {
+	switch (response.status) {
+		case 401:
+		case 403:
+			return new ServiceException('Unauthorized', response.status);
+		case 404:
+			return new ServiceException('Not Found', response.status);
+		default:
+	}
+	const ct = response.headers.get('content-type');
+	if (ct?.includes('json')) {
+		try {
+			const payload = (await response.json()) as { message?: string; error?: string };
+			if (payload.error) {
+				return new ServiceException(payload.error, response.status);
+			}
+			if (payload.message) {
+				return new ServiceException(payload.message, response.status);
+			}
+			return new ServiceException(JSON.stringify(payload), response.status);
+		} catch {
+			/** don't worry */
+		}
+	}
+	try {
+		const body = await response.text();
+		return new ServiceException(body, response.status);
+	} catch {
+		/* fall through */
+	}
+
+	return new ServiceException(response.statusText, response.status);
+}
+
+const binaryContentType = 'application/octet-stream';
+const textContentType = 'text/plain';
+const jsonContentType = 'application/json';
+
+export async function toPayload(data: unknown): Promise<[Body, string]> {
+	if (data === undefined || data === null) {
+		return ['', textContentType];
+	}
+	switch (typeof data) {
+		case 'string':
+			if (
+				(data.charAt(0) === '{' && data.charAt(data.length - 1) === '}') ||
+				(data.charAt(0) === '[' && data.charAt(data.length - 1) === ']')
+			) {
+				try {
+					JSON.parse(data);
+					return [data, jsonContentType];
+				} catch {
+					/* fall through */
+				}
+			}
+			return [data, textContentType];
+		case 'boolean':
+			return [String(data), textContentType];
+		case 'number':
+			return [String(data), textContentType];
+		case 'object': {
+			if (data instanceof ArrayBuffer) {
+				return [data, binaryContentType];
+			}
+			if (data instanceof Buffer) {
+				return [data, binaryContentType];
+			}
+			if (data instanceof ReadableStream) {
+				return [data, binaryContentType];
+			}
+			if (data instanceof Promise) {
+				return toPayload(await data);
+			}
+			if (data instanceof Function) {
+				return toPayload(data());
+			}
+			return [safeStringify(data), jsonContentType];
+		}
+	}
+	return ['', textContentType];
+}
+
+export async function fromResponse<T>(response: Response): Promise<T> {
+	const contentType = response.headers.get('content-type');
+	if (!contentType || contentType?.includes('/json')) {
+		return (await response.json()) as T;
+	}
+	if (contentType?.includes('text/')) {
+		return (await response.text()) as T;
+	}
+	if (contentType?.includes(binaryContentType)) {
+		return (await response.arrayBuffer()) as T;
+	}
+	throw new ServiceException(`Unsupported content-type: ${contentType}`, response.status);
+}

package/src/services/adapter.ts

@@ -0,0 +1,33 @@
+export interface FetchSuccessResponse<TData> {
+	ok: true;
+	data: TData;
+	response: Response;
+}
+
+export interface FetchErrorResponse {
+	ok: false;
+	data: never;
+	response: Response;
+}
+
+export type FetchResponse<T> = FetchErrorResponse | FetchSuccessResponse<T>;
+
+export type Body = string | Buffer | ArrayBuffer | ReadableStream;
+
+export interface FetchRequest {
+	method: 'GET' | 'PUT' | 'POST' | 'DELETE';
+	body?: Body;
+	signal?: AbortSignal;
+	contentType?: string;
+	headers?: Record<string, string>;
+	telemetry?: {
+		name: string;
+		attributes?: Record<string, string>;
+	};
+	binary?: true;
+	duplex?: 'half';
+}
+
+export interface FetchAdapter {
+	invoke<T>(url: string, options: FetchRequest): Promise<FetchResponse<T>>;
+}

package/src/services/exception.ts

@@ -0,0 +1,7 @@
+export class ServiceException extends Error {
+	statusCode: number;
+	constructor(message: string, statusCode: number) {
+		super(message);
+		this.statusCode = statusCode;
+	}
+}

package/src/services/index.ts

@@ -0,0 +1,7 @@
+export * from './adapter';
+export * from './exception';
+export * from './keyvalue';
+export * from './objectstore';
+export * from './stream';
+export * from './vector';
+export { buildUrl, toServiceException, toPayload, fromResponse } from './_util';

package/src/services/keyvalue.ts

@@ -0,0 +1,185 @@
+import { FetchAdapter } from './adapter';
+import { buildUrl, toServiceException, toPayload } from './_util';
+
+/**
+ * the result of a data operation when the data is found
+ */
+export interface DataResultFound<T> {
+	/**
+	 * the data from the result of the operation
+	 */
+	data: T;
+
+	/**
+	 * the content type of the data
+	 */
+	contentType: string;
+
+	/**
+	 * the data was found
+	 */
+	exists: true;
+}
+
+/**
+ * the result of a data operation when the data is not found
+ */
+export interface DataResultNotFound {
+	data: never;
+	/**
+	 * the data was not found
+	 */
+	exists: false;
+}
+
+/**
+ * the result of a data operation
+ */
+export type DataResult<T> = DataResultFound<T> | DataResultNotFound;
+
+export interface KeyValueStorageSetParams {
+	/**
+	 * the number of milliseconds to keep the value in the cache
+	 */
+	ttl?: number;
+	/**
+	 * the content type of the value
+	 */
+	contentType?: string;
+}
+
+export interface KeyValueStorage {
+	/**
+	 * get a value from the key value storage
+	 *
+	 * @param name - the name of the key value storage
+	 * @param key - the key to get the value of
+	 * @returns the DataResult object
+	 */
+	get<T>(name: string, key: string): Promise<DataResult<T>>;
+
+	/**
+	 * set a value in the key value storage
+	 *
+	 * @param name - the name of the key value storage
+	 * @param key - the key to set the value of
+	 * @param value - the value to set in any of the supported data types
+	 * @param params - the KeyValueStorageSetParams
+	 */
+	set<T = unknown>(
+		name: string,
+		key: string,
+		value: T,
+		params?: KeyValueStorageSetParams
+	): Promise<void>;
+
+	/**
+	 * delete a value from the key value storage
+	 *
+	 * @param name - the name of the key value storage
+	 * @param key - the key to delete
+	 */
+	delete(name: string, key: string): Promise<void>;
+}
+
+export class KeyValueStorageService implements KeyValueStorage {
+	#adapter: FetchAdapter;
+	#baseUrl: string;
+
+	constructor(baseUrl: string, adapter: FetchAdapter) {
+		this.#adapter = adapter;
+		this.#baseUrl = baseUrl;
+	}
+
+	async get<T>(name: string, key: string): Promise<DataResult<T>> {
+		const url = buildUrl(
+			this.#baseUrl,
+			`/kv/2025-03-17/${encodeURIComponent(name)}/${encodeURIComponent(key)}`
+		);
+		const signal = AbortSignal.timeout(10_000);
+		const res = await this.#adapter.invoke<T>(url, {
+			method: 'GET',
+			signal,
+			telemetry: {
+				name: 'agentuity.keyvalue.get',
+				attributes: {
+					name,
+					key,
+				},
+			},
+		});
+		if (res.ok) {
+			return {
+				data: res.data,
+				contentType: res.response.headers.get('content-type') ?? 'application/octet-stream',
+				exists: true,
+			};
+		}
+		if (res.response.status === 404) {
+			return { exists: false } as DataResultNotFound;
+		}
+		throw await toServiceException(res.response);
+	}
+
+	async set<T = unknown>(
+		name: string,
+		key: string,
+		value: T,
+		params?: KeyValueStorageSetParams
+	): Promise<void> {
+		let ttlstr = '';
+		if (params?.ttl) {
+			if (params.ttl < 60) {
+				throw new Error(`ttl for keyvalue set must be at least 60 seconds, got ${params.ttl}`);
+			}
+			ttlstr = `/${params.ttl}`;
+		}
+		const url = buildUrl(
+			this.#baseUrl,
+			`/kv/2025-03-17/${encodeURIComponent(name)}/${encodeURIComponent(key)}${ttlstr}`
+		);
+		const [body, contentType] = await toPayload(value);
+		const signal = AbortSignal.timeout(30_000);
+		const res = await this.#adapter.invoke<T>(url, {
+			method: 'PUT',
+			signal,
+			body,
+			contentType: params?.contentType || contentType,
+			telemetry: {
+				name: 'agentuity.keyvalue.set',
+				attributes: {
+					name,
+					key,
+					ttl: ttlstr,
+				},
+			},
+		});
+		if (res.ok) {
+			return;
+		}
+		throw await toServiceException(res.response);
+	}
+
+	async delete(name: string, key: string): Promise<void> {
+		const url = buildUrl(
+			this.#baseUrl,
+			`/kv/2025-03-17/${encodeURIComponent(name)}/${encodeURIComponent(key)}`
+		);
+		const signal = AbortSignal.timeout(30_000);
+		const res = await this.#adapter.invoke(url, {
+			method: 'DELETE',
+			signal,
+			telemetry: {
+				name: 'agentuity.keyvalue.delete',
+				attributes: {
+					name,
+					key,
+				},
+			},
+		});
+		if (res.ok) {
+			return;
+		}
+		throw await toServiceException(res.response);
+	}
+}