@agentuity/core 1.0.33 → 1.0.34

package/src/services/machine/machine.ts

@@ -0,0 +1,228 @@
+import { z } from 'zod';
+import { APIResponseSchema, APIResponseSchemaNoData, APIClient } from '../api.ts';
+import { MachineResponseError } from './util.ts';
+
+// TODO: The old /cli/auth/machine/* endpoints should be aliased to redirect
+// to /cli/auth/org/* in the backend (app repo). Remove aliases in follow-up PR.
+
+export const MachineSchema = z
+	.object({
+		id: z.string().describe('Unique identifier for the machine.'),
+		instanceId: z.string().nullable().optional().describe('Cloud provider instance ID.'),
+		privateIPv4: z
+			.string()
+			.nullable()
+			.optional()
+			.describe('Private IPv4 address of the machine.'),
+		availabilityZone: z
+			.string()
+			.nullable()
+			.optional()
+			.describe('Cloud provider availability zone.'),
+		instanceType: z
+			.string()
+			.nullable()
+			.optional()
+			.describe('Cloud provider instance type (e.g., n1-standard-2).'),
+		instanceTags: z
+			.array(z.string())
+			.nullable()
+			.optional()
+			.describe('Tags assigned to the cloud instance.'),
+		deploymentCount: z
+			.number()
+			.optional()
+			.describe('Number of active deployments on this machine.'),
+		status: z
+			.string()
+			.describe('Current status of the machine (e.g., running, stopped, errored).'),
+		provider: z.string().describe('Cloud provider (e.g., gcp, aws).'),
+		region: z.string().describe('Cloud region where the machine is deployed.'),
+		startedAt: z
+			.string()
+			.nullable()
+			.optional()
+			.describe('ISO 8601 timestamp when the machine was started.'),
+		stoppedAt: z
+			.string()
+			.nullable()
+			.optional()
+			.describe('ISO 8601 timestamp when the machine was stopped.'),
+		pausedAt: z
+			.string()
+			.nullable()
+			.optional()
+			.describe('ISO 8601 timestamp when the machine was paused.'),
+		erroredAt: z
+			.string()
+			.nullable()
+			.optional()
+			.describe('ISO 8601 timestamp when the machine entered error state.'),
+		error: z
+			.string()
+			.nullable()
+			.optional()
+			.describe('Error message if the machine is in an error state.'),
+		orgId: z.string().nullable().optional().describe('Organization ID that owns this machine.'),
+		orgName: z
+			.string()
+			.nullable()
+			.optional()
+			.describe('Organization name that owns this machine.'),
+		createdAt: z.string().describe('ISO 8601 timestamp when the machine was created.'),
+		updatedAt: z
+			.string()
+			.nullable()
+			.optional()
+			.describe('ISO 8601 timestamp when the machine was last updated.'),
+		metadata: z
+			.record(z.string(), z.unknown())
+			.nullable()
+			.optional()
+			.describe('Arbitrary metadata associated with the machine.'),
+	})
+	.describe('Machine instance in the Agentuity infrastructure.');
+
+export const MachineListResponseSchema = APIResponseSchema(z.array(MachineSchema));
+export const MachineGetResponseSchema = APIResponseSchema(MachineSchema);
+export const MachineDeleteResponseSchema = APIResponseSchemaNoData();
+
+export type Machine = z.infer<typeof MachineSchema>;
+
+export async function machineList(
+	client: APIClient,
+	options?: { orgId?: string }
+): Promise<Machine[]> {
+	const headers = options?.orgId ? { 'x-agentuity-orgid': options.orgId } : undefined;
+	const resp = await client.get('/machine', MachineListResponseSchema, undefined, headers);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new MachineResponseError({ message: resp.message });
+}
+
+export async function machineGet(client: APIClient, machineId: string): Promise<Machine> {
+	const resp = await client.get(`/machine/${machineId}`, MachineGetResponseSchema);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new MachineResponseError({ message: resp.message });
+}
+
+export async function machineDelete(client: APIClient, machineId: string): Promise<void> {
+	const resp = await client.delete(`/machine/${machineId}`, MachineDeleteResponseSchema);
+	if (!resp.success) {
+		throw new MachineResponseError({ message: resp.message });
+	}
+}
+
+export const MachineDeploymentProjectSchema = z
+	.object({
+		id: z.string().describe('Unique identifier for the project.'),
+		name: z.string().describe('Human-readable project name.'),
+		identifier: z.string().describe('URL-safe project identifier.'),
+		domains: z.array(z.string()).describe('Custom domains assigned to this project.'),
+	})
+	.describe('Project associated with a machine deployment.');
+
+export type MachineDeploymentProject = z.infer<typeof MachineDeploymentProjectSchema>;
+
+export const MachineDeploymentResourcesSchema = z
+	.object({
+		cpuUnits: z.number().describe('CPU units allocated to the deployment.'),
+		memoryUnits: z.number().describe('Memory units allocated to the deployment.'),
+		diskUnits: z.number().describe('Disk units allocated to the deployment.'),
+	})
+	.describe('Resource allocation for a machine deployment.');
+
+export type MachineDeploymentResources = z.infer<typeof MachineDeploymentResourcesSchema>;
+
+export const MachineDeploymentSchema = z
+	.object({
+		id: z.string().describe('Unique identifier for the deployment.'),
+		identifier: z.string().optional().describe('URL-safe deployment identifier.'),
+		state: z.string().optional().describe('Current state of the deployment.'),
+		project: MachineDeploymentProjectSchema.nullable()
+			.optional()
+			.describe('Project associated with this deployment.'),
+		resources: MachineDeploymentResourcesSchema.nullable()
+			.optional()
+			.describe('Resource allocation for this deployment.'),
+		customDomains: z.array(z.string()).describe('Custom domains configured for this deployment.'),
+		paused: z.boolean().describe('Whether the deployment is currently paused.'),
+		pausedDuration: z.number().describe('Duration in seconds the deployment has been paused.'),
+		domainSuffix: z.string().describe('Domain suffix for the deployment URL.'),
+	})
+	.describe('Deployment running on a machine.');
+
+export const MachineDeploymentsResponseSchema = APIResponseSchema(z.array(MachineDeploymentSchema));
+
+export type MachineDeployment = z.infer<typeof MachineDeploymentSchema>;
+
+export async function machineDeployments(
+	client: APIClient,
+	machineId: string
+): Promise<MachineDeployment[]> {
+	const resp = await client.get(
+		`/machine/deployments/${machineId}`,
+		MachineDeploymentsResponseSchema
+	);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new MachineResponseError({ message: resp.message });
+}
+
+export const OrgAuthEnrollResponseSchema = APIResponseSchema(
+	z.object({
+		orgId: z.string().describe('Organization ID that was enrolled.'),
+	})
+);
+
+export async function orgAuthEnroll(
+	client: APIClient,
+	orgId: string,
+	publicKey: string
+): Promise<{ orgId: string }> {
+	const resp = await client.post(
+		'/cli/auth/org/enroll',
+		{ orgId, publicKey },
+		OrgAuthEnrollResponseSchema
+	);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new MachineResponseError({ message: resp.message });
+}
+
+export const OrgAuthStatusResponseSchema = APIResponseSchema(
+	z.object({
+		publicKey: z
+			.string()
+			.nullable()
+			.describe('Public key for the organization, or null if not enrolled.'),
+	})
+);
+
+export async function orgAuthStatus(
+	client: APIClient,
+	orgId: string
+): Promise<{ publicKey: string | null }> {
+	const resp = await client.get(`/cli/auth/org/status/${orgId}`, OrgAuthStatusResponseSchema);
+	if (resp.success) {
+		return resp.data;
+	}
+	throw new MachineResponseError({ message: resp.message });
+}
+
+export const OrgAuthUnenrollResponseSchema = APIResponseSchemaNoData();
+
+export async function orgAuthUnenroll(client: APIClient, orgId: string): Promise<void> {
+	const resp = await client.delete(
+		`/cli/auth/org/unenroll/${orgId}`,
+		OrgAuthUnenrollResponseSchema
+	);
+	if (!resp.success) {
+		throw new MachineResponseError({ message: resp.message });
+	}
+}

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/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/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/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' });
+}