@agentuity/core 1.0.32 → 1.0.34

package/src/services/org/env-delete.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchemaNoData } from '../api.ts';
+import { OrgResponseError } from './util.ts';
+
+export const OrgEnvDeleteRequestSchema = z.object({
+	id: z.string().describe('the organization id'),
+	env: z.array(z.string()).optional().describe('environment variable keys to delete'),
+	secrets: z.array(z.string()).optional().describe('secret keys to delete'),
+});
+
+export const OrgEnvDeleteResponseSchema = APIResponseSchemaNoData();
+
+export type OrgEnvDeleteRequest = z.infer<typeof OrgEnvDeleteRequestSchema>;
+export type OrgEnvDeleteResponse = z.infer<typeof OrgEnvDeleteResponseSchema>;
+
+/**
+ * Delete environment variables and/or secrets from an organization.
+ * Provide arrays of keys to delete.
+ * Requires admin/owner role.
+ */
+export async function orgEnvDelete(client: APIClient, request: OrgEnvDeleteRequest): Promise<void> {
+	const { id, env, secrets } = request;
+
+	const resp = await client.request<OrgEnvDeleteResponse, Omit<OrgEnvDeleteRequest, 'id'>>(
+		'DELETE',
+		`/cli/organization/${encodeURIComponent(id)}/env`,
+		OrgEnvDeleteResponseSchema,
+		{
+			env,
+			secrets,
+		}
+	);
+
+	if (!resp.success) {
+		throw new OrgResponseError({ message: resp.message ?? 'failed to delete org env' });
+	}
+}

package/src/services/org/env-get.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchema } from '../api.ts';
+import { OrgResponseError } from './util.ts';
+
+export const OrgEnvDataSchema = z.object({
+	id: z.string().describe('the organization id'),
+	env: z.record(z.string(), z.string()).optional().describe('environment variables'),
+	secrets: z.record(z.string(), z.string()).optional().describe('secrets (may be masked)'),
+});
+
+export const OrgEnvGetResponseSchema = APIResponseSchema(OrgEnvDataSchema);
+
+export const OrgEnvGetOptionsSchema = z.object({
+	id: z.string().describe('Organization ID to fetch environment variables for'),
+	mask: z
+		.boolean()
+		.optional()
+		.describe('Whether secret values should be masked in the response (default true)'),
+});
+
+export type OrgEnvGetOptions = z.infer<typeof OrgEnvGetOptionsSchema>;
+export type OrgEnvGetResponse = z.infer<typeof OrgEnvGetResponseSchema>;
+
+export type OrgEnv = z.infer<typeof OrgEnvDataSchema>;
+
+/**
+ * Get environment variables and secrets for an organization.
+ * Secrets are masked by default unless mask=false is specified.
+ * Note: Unmasked values require admin/owner role.
+ */
+export async function orgEnvGet(client: APIClient, request: OrgEnvGetOptions): Promise<OrgEnv> {
+	const { id, mask = true } = request;
+
+	const resp = await client.get<OrgEnvGetResponse>(
+		`/cli/organization/${encodeURIComponent(id)}/env?mask=${mask}`,
+		OrgEnvGetResponseSchema
+	);
+
+	if (!resp.success) {
+		throw new OrgResponseError({ message: resp.message ?? 'failed to get org env' });
+	}
+
+	if (!resp.data) {
+		throw new OrgResponseError({ message: 'failed to get org env: no data returned' });
+	}
+
+	return resp.data;
+}

package/src/services/org/env-update.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { APIClient, APIResponseSchemaNoData } from '../api.ts';
+import { OrgResponseError } from './util.ts';
+
+export const OrgEnvUpdateRequestSchema = z.object({
+	id: z.string().describe('the organization id'),
+	env: z.record(z.string(), z.string()).optional().describe('environment variables to set/update'),
+	secrets: z.record(z.string(), z.string()).optional().describe('secrets to set/update'),
+});
+
+export const OrgEnvUpdateResponseSchema = APIResponseSchemaNoData();
+
+export type OrgEnvUpdateRequest = z.infer<typeof OrgEnvUpdateRequestSchema>;
+export type OrgEnvUpdateResponse = z.infer<typeof OrgEnvUpdateResponseSchema>;
+
+/**
+ * Update environment variables and/or secrets for an organization.
+ * This will merge the provided env/secrets with existing values.
+ * Requires admin/owner role.
+ * Keys starting with 'AGENTUITY_' (except AGENTUITY_PUBLIC_) are filtered out.
+ */
+export async function orgEnvUpdate(client: APIClient, request: OrgEnvUpdateRequest): Promise<void> {
+	const { id, env, secrets } = request;
+
+	const resp = await client.request<OrgEnvUpdateResponse, Omit<OrgEnvUpdateRequest, 'id'>>(
+		'PUT',
+		`/cli/organization/${id}/env`,
+		OrgEnvUpdateResponseSchema,
+		{
+			env,
+			secrets,
+		}
+	);
+
+	if (!resp.success) {
+		throw new OrgResponseError({ message: resp.message ?? 'failed to update org env' });
+	}
+}

package/src/services/org/index.ts

@@ -0,0 +1,6 @@
+export * from './env-delete.ts';
+export * from './env-get.ts';
+export * from './env-update.ts';
+export * from './list.ts';
+export * from './resources.ts';
+export * from './util.ts';

package/src/services/org/list.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { OrgResponseError } from './util.ts';
+
+export const ListOrganizationsResponse = z.array(
+	z.object({
+		id: z.string().describe('the unique id for the organization'),
+		name: z.string().describe('the name of the organization'),
+	})
+);
+export const ListOrganizationsResponseSchema = APIResponseSchema(ListOrganizationsResponse);
+
+export type ListOrganizationsResponse = z.infer<typeof ListOrganizationsResponseSchema>;
+export type OrganizationList = z.infer<typeof ListOrganizationsResponse>;
+
+/**
+ * List all organizations
+ *
+ * @param client
+ * @returns
+ */
+export async function listOrganizations(client: APIClient): Promise<OrganizationList> {
+	const resp = await client.get('/cli/organization', ListOrganizationsResponseSchema);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new OrgResponseError({ message: resp.message });
+}

package/src/services/org/resources.ts

@@ -0,0 +1,140 @@
+import { SortDirectionSchema } from '../pagination.ts';
+import { z } from 'zod';
+import { APIResponseSchema, APIClient } from '../api.ts';
+import { OrgResourceResponseError } from './util.ts';
+
+export const OrgS3Resource = z.object({
+	bucket_name: z.string().describe('the S3 bucket name'),
+	access_key: z.string().nullable().optional().describe('the S3 access key'),
+	secret_key: z.string().nullable().optional().describe('the S3 secret key'),
+	region: z.string().nullable().optional().describe('the S3 region'),
+	endpoint: z.string().nullable().optional().describe('the S3 endpoint'),
+	cloud_region: z.string().describe('the cloud region where this resource is provisioned'),
+	org_id: z.string().describe('the organization ID that owns this resource'),
+	org_name: z.string().describe('the organization name that owns this resource'),
+	bucket_type: z.string().describe('the bucket type (user or snapshots)'),
+	internal: z.boolean().describe('whether this is a system-managed bucket'),
+	description: z.string().nullable().optional().describe('optional description of the bucket'),
+	object_count: z
+		.number()
+		.int()
+		.nonnegative()
+		.optional()
+		.describe('number of objects in this bucket'),
+	total_size: z.number().int().nonnegative().optional().describe('total size of objects in bytes'),
+	last_event_at: z.string().optional().describe('last activity timestamp (ISO8601)'),
+});
+
+export const OrgDBResource = z.object({
+	name: z.string().describe('the database name'),
+	description: z.string().nullable().optional().describe('optional description of the database'),
+	username: z.string().nullable().optional().describe('the database username'),
+	password: z.string().nullable().optional().describe('the database password'),
+	url: z.string().nullable().optional().describe('the full database connection URL'),
+	cloud_region: z.string().describe('the cloud region where this resource is provisioned'),
+	org_id: z.string().describe('the organization ID that owns this resource'),
+	org_name: z.string().describe('the organization name that owns this resource'),
+	internal: z.boolean().describe('whether this is a system-managed database (KV/Vector/Queue)'),
+});
+
+export const OrgResourceListResponse = z.object({
+	s3: z.array(OrgS3Resource),
+	db: z.array(OrgDBResource),
+});
+
+export const OrgResourceListResponseSchema = APIResponseSchema(OrgResourceListResponse);
+
+export type OrgResourceListResponse = z.infer<typeof OrgResourceListResponseSchema>;
+export type OrgResourceList = z.infer<typeof OrgResourceListResponse>;
+export type OrgS3Resource = z.infer<typeof OrgS3Resource>;
+export type OrgDBResource = z.infer<typeof OrgDBResource>;
+
+export type ResourceSortField = 'name' | 'created' | 'region';
+
+export const ResourceSortFieldSchema = z.enum(['name', 'created', 'region']);
+
+export const ListOrgResourcesOptionsSchema = z.object({
+	type: z
+		.enum(['all', 's3', 'db'])
+		.optional()
+		.describe('Optional resource type filter; defaults to all resources'),
+	name: z.string().optional().describe('Optional case-insensitive resource name filter'),
+	orgId: z.string().optional().describe('Optional org id header value for CLI token auth'),
+	limit: z.number().optional().describe('Optional maximum number of resources to return'),
+	offset: z.number().optional().describe('Optional pagination offset'),
+	sort: ResourceSortFieldSchema.optional().describe('Optional sort field'),
+	direction: SortDirectionSchema.optional().describe('Optional sort direction'),
+});
+
+export type ListOrgResourcesOptions = z.infer<typeof ListOrgResourcesOptionsSchema>;
+
+/**
+ * List all resources for the authenticated organization (across all regions)
+ *
+ * @param client - Catalyst API client (must be authenticated)
+ * @param options - Optional filters including orgId for CLI auth
+ * @returns List of S3 and DB resources with their cloud regions
+ *
+ * @example
+ * // Get all resources (SDK auth - orgId from context)
+ * const all = await listOrgResources(client);
+ *
+ * @example
+ * // Get all resources (CLI auth - orgId required)
+ * const all = await listOrgResources(client, { orgId: 'org_123' });
+ *
+ * @example
+ * // Get only S3 buckets
+ * const s3Only = await listOrgResources(client, { type: 's3', orgId: 'org_123' });
+ *
+ * @example
+ * // Get only DBs
+ * const dbsOnly = await listOrgResources(client, { type: 'db', orgId: 'org_123' });
+ */
+export async function listOrgResources(
+	client: APIClient,
+	options?: ListOrgResourcesOptions
+): Promise<OrgResourceList> {
+	const params = new URLSearchParams();
+	if (options?.type && options.type !== 'all') {
+		params.set('type', options.type);
+	}
+	if (options?.name) {
+		params.set('name', options.name);
+	}
+	if (options?.limit !== undefined) {
+		params.set('limit', options.limit.toString());
+	}
+	if (options?.offset !== undefined) {
+		params.set('offset', options.offset.toString());
+	}
+	if (options?.sort) {
+		params.set('sort', options.sort);
+	}
+	if (options?.direction) {
+		params.set('direction', options.direction);
+	}
+
+	const query = params.toString();
+	const url = `/resource${query ? `?${query}` : ''}`;
+
+	// Build headers - include orgId for CLI auth
+	const headers: Record<string, string> = {};
+	if (options?.orgId) {
+		headers['x-agentuity-orgid'] = options.orgId;
+	}
+
+	const resp = await client.request<OrgResourceListResponse>(
+		'GET',
+		url,
+		OrgResourceListResponseSchema,
+		undefined,
+		undefined,
+		undefined,
+		headers
+	);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new OrgResourceResponseError({ message: resp.message });
+}

package/src/services/org/util.ts

@@ -0,0 +1,4 @@
+import { StructuredError } from '../../error.ts';
+
+export const OrgResponseError = StructuredError('OrgResponseError');
+export const OrgResourceResponseError = StructuredError('OrgResourceResponseError');

package/src/services/pagination.ts

@@ -1,27 +1,56 @@
+import { z } from 'zod';
+
 /** Sort direction for list operations */
-export type SortDirection = 'asc' | 'desc';
+export const SortDirectionSchema = z
+	.enum(['asc', 'desc'])
+	.describe('Sort direction for list operations (ascending or descending).');
+
+export type SortDirection = z.infer<typeof SortDirectionSchema>;
 
 /** Base pagination parameters used by all list operations */
-export interface PaginationParams {
-	/** Maximum number of items to return */
-	limit?: number;
-	/** Number of items to skip for pagination */
-	offset?: number;
-}
+export const PaginationParamsSchema = z.object({
+	limit: z.number().int().nonnegative().optional().describe('Maximum number of items to return'),
+	offset: z
+		.number()
+		.int()
+		.nonnegative()
+		.optional()
+		.describe('Number of items to skip for pagination'),
+});
+
+export type PaginationParams = z.infer<typeof PaginationParamsSchema>;
 
 /** Sort parameters generic over allowed field names */
-export interface SortParams<F extends string = string> {
+export const SortParamsSchema = <F extends z.ZodTypeAny>(sortFieldSchema: F) =>
+	z.object({
+		sort: sortFieldSchema.optional().describe('Field to sort by'),
+		direction: SortDirectionSchema.optional().describe("Sort direction (default: 'desc')"),
+	});
+
+export type SortParams<F extends string = string> = {
 	/** Field to sort by */
 	sort?: F;
 	/** Sort direction (default: 'desc') */
 	direction?: SortDirection;
-}
+};
 
 /** Combined list parameters = pagination + sorting */
+export const ListParamsSchema = <F extends z.ZodTypeAny>(sortFieldSchema: F) =>
+	PaginationParamsSchema.merge(SortParamsSchema(sortFieldSchema));
+
 export type ListParams<F extends string = string> = PaginationParams & SortParams<F>;
 
 /** Standard paginated list response */
-export interface PaginatedList<T> {
+export const PaginatedListSchema = <T extends z.ZodTypeAny>(itemSchema: T) =>
+	z.object({
+		data: z.array(itemSchema).describe('Array of items'),
+		total: z.number().describe('Total number of items matching the query'),
+		limit: z.number().describe('Number of items requested per page'),
+		offset: z.number().describe('Number of items skipped'),
+		hasMore: z.boolean().describe('Whether more items are available'),
+	});
+
+export type PaginatedList<T> = {
 	/** Array of items */
 	data: T[];
 	/** Total number of items matching the query */
@@ -32,4 +61,4 @@ export interface PaginatedList<T> {
 	offset: number;
 	/** Whether more items are available */
 	hasMore: boolean;
-}
+};

package/src/services/project/agent.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import type { APIClient } from '../api.ts';
+import { APIResponseSchema } from '../api.ts';
+import { AgentNotFoundError, ProjectResponseError } from './util.ts';
+
+export const AgentSchema = z.object({
+	id: z.string().describe('Agent ID (same as identifier)'),
+	name: z.string().describe('Agent name'),
+	description: z.string().nullable().describe('Agent description'),
+	identifier: z.string().describe('Agent identifier'),
+	deploymentId: z.string().nullable().describe('Deployment ID'),
+	devmode: z.boolean().describe('Whether agent is in development mode'),
+	metadata: z.record(z.string(), z.unknown()).nullable().describe('Agent metadata'),
+	createdAt: z.string().describe('Creation timestamp'),
+	updatedAt: z.string().describe('Last update timestamp'),
+	evals: z
+		.array(
+			z.object({
+				id: z.string().describe('Evaluation ID'),
+				name: z.string().describe('Evaluation name'),
+				description: z.string().nullable().describe('Evaluation description'),
+				identifier: z.string().nullable().describe('Evaluation identifier'),
+				devmode: z.boolean().describe('Whether evaluation is in development mode'),
+				createdAt: z.string().describe('Creation timestamp'),
+				updatedAt: z.string().describe('Last update timestamp'),
+			})
+		)
+		.describe('Associated evaluations'),
+});
+
+export const AgentListResponseSchema = APIResponseSchema(z.array(AgentSchema));
+export const AgentGetResponseSchema = APIResponseSchema(z.array(AgentSchema));
+
+export type Agent = z.infer<typeof AgentSchema>;
+
+/**
+ * List agents for a project
+ */
+export async function projectAgentList(
+	client: APIClient,
+	projectId: string,
+	options?: {
+		deploymentId?: string;
+		orgId?: string;
+	}
+): Promise<Agent[]> {
+	const queryParams = new URLSearchParams();
+	if (options?.deploymentId) {
+		queryParams.set('deploymentId', options.deploymentId);
+	}
+	if (options?.orgId) {
+		queryParams.set('orgId', options.orgId);
+	}
+
+	const url = `/cli/agent/${projectId}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
+
+	const resp = await client.get(url, AgentListResponseSchema);
+
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new ProjectResponseError({ message: resp.message });
+}
+
+/**
+ * Get a specific agent by identifier
+ */
+export async function projectAgentGet(
+	client: APIClient,
+	projectId: string,
+	agentId: string
+): Promise<Agent> {
+	const resp = await client.get(
+		`/cli/agent/${projectId}?identifier=${agentId}`,
+		AgentGetResponseSchema
+	);
+
+	if (resp.success) {
+		const agent = resp.data[0];
+		if (resp.data.length === 0 || agent === undefined) {
+			throw new AgentNotFoundError({ id: agentId, message: `Agent not found: ${agentId}` });
+		}
+		return agent;
+	}
+	throw new ProjectResponseError({ message: resp.message });
+}

package/src/services/project/create.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { ProjectResponseError } from './util.ts';
+
+export const CreateProjectRequestSchema = z.object({
+	name: z.string().max(255).min(1).describe('the name of the new project'),
+	description: z.string().max(255).min(0).optional().describe('the description of the project'),
+	tags: z.array(z.string()).optional().describe('tags for the project'),
+	orgId: z.string().max(255).min(1).describe('the organization id to create the project in'),
+	cloudRegion: z.string().describe('the cloud region to create the project'),
+	domains: z.array(z.string()).optional().describe('the custom domains for this project'),
+});
+
+export const NewProjectSchema = z.object({
+	id: z.string().describe('the unique id for the project'),
+	sdkKey: z.string().describe('the SDK key for the project'),
+});
+
+export const CreateProjectResponseSchema = APIResponseSchema(NewProjectSchema);
+
+export type CreateProjectRequest = z.infer<typeof CreateProjectRequestSchema>;
+export type CreateProjectResponse = z.infer<typeof CreateProjectResponseSchema>;
+export type NewProject = z.infer<typeof NewProjectSchema>;
+
+/**
+ * Create a new Project
+ *
+ * @param client
+ * @param body
+ * @returns
+ */
+export async function projectCreate(
+	client: APIClient,
+	body: CreateProjectRequest
+): Promise<NewProject> {
+	const resp = await client.request<CreateProjectResponse, CreateProjectRequest>(
+		'POST',
+		'/cli/project',
+		CreateProjectResponseSchema,
+		body,
+		CreateProjectRequestSchema
+	);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new ProjectResponseError({ message: resp.message });
+}

package/src/services/project/delete.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { ProjectResponseError } from './util.ts';
+
+export const ProjectDeleteRequestSchema = z
+	.object({ ids: z.array(z.string()).describe('Array of project IDs to delete.') })
+	.describe('Request to delete one or more projects.');
+export const ProjectDeleteResponseSchema = APIResponseSchema(z.array(z.string()));
+
+type ProjectDeleteRequest = z.infer<typeof ProjectDeleteRequestSchema>;
+type ProjectDeleteResponse = z.infer<typeof ProjectDeleteResponseSchema>;
+
+export async function projectDelete(client: APIClient, ...ids: string[]): Promise<string[]> {
+	const resp = await client.request<ProjectDeleteResponse, ProjectDeleteRequest>(
+		'DELETE',
+		'/cli/project',
+		ProjectDeleteResponseSchema,
+		{ ids },
+		ProjectDeleteRequestSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new ProjectResponseError({ message: resp.message ?? 'failed to delete project' });
+}