@agentuity/server 0.1.16 → 0.1.18

package/src/api/sandbox/snapshot.ts

@@ -6,9 +6,28 @@ const SnapshotFileInfoSchema = z
 	.object({
 		path: z.string().describe('File path within the snapshot'),
 		size: z.number().describe('File size in bytes'),
+		sha256: z.string().describe('SHA256 hash of the file contents'),
+		contentType: z.string().describe('MIME type of the file'),
+		mode: z.number().describe('Unix file mode/permissions (e.g., 0o644)'),
 	})
 	.describe('Information about a file in a snapshot');
 
+const SnapshotOrgInfoSchema = z
+	.object({
+		id: z.string().describe('Organization ID'),
+		name: z.string().describe('Organization name'),
+		slug: z.string().nullable().optional().describe('Organization slug for building full name'),
+	})
+	.describe('Organization information for public snapshots');
+
+const SnapshotUserInfoSchema = z
+	.object({
+		id: z.string().describe('User ID'),
+		firstName: z.string().nullable().optional().describe('User first name'),
+		lastName: z.string().nullable().optional().describe('User last name'),
+	})
+	.describe('User information for private snapshots');
+
 const SnapshotInfoSchema = z
 	.object({
 		snapshotId: z.string().describe('Unique identifier for the snapshot'),
@@ -22,7 +41,12 @@ const SnapshotInfoSchema = z
 			.describe(
 				'Display name for the snapshot (URL-safe: letters, numbers, underscores, dashes)'
 			),
+		fullName: z
+			.string()
+			.optional()
+			.describe('Full name with org slug for public snapshots (@slug/name:tag)'),
 		description: z.string().nullable().optional().describe('Description of the snapshot'),
+		message: z.string().nullable().optional().describe('Build message for the snapshot'),
 		tag: z.string().nullable().optional().describe('Tag for the snapshot (defaults to "latest")'),
 		sizeBytes: z.number().describe('Total size of the snapshot in bytes'),
 		fileCount: z.number().describe('Number of files in the snapshot'),
@@ -31,6 +55,15 @@ const SnapshotInfoSchema = z
 			.nullable()
 			.optional()
 			.describe('ID of the parent snapshot (for incremental snapshots)'),
+		public: z.boolean().optional().describe('Whether the snapshot is publicly accessible'),
+		orgName: z.string().optional().describe('Organization name (for public snapshots)'),
+		orgSlug: z.string().optional().describe('Organization slug (for public snapshots)'),
+		org: SnapshotOrgInfoSchema.nullable()
+			.optional()
+			.describe('Organization details (for public snapshots)'),
+		user: SnapshotUserInfoSchema.nullable()
+			.optional()
+			.describe('User who pushed the snapshot (for private snapshots)'),
 		createdAt: z.string().describe('ISO timestamp when the snapshot was created'),
 		downloadUrl: z.string().optional().describe('URL to download the snapshot archive'),
 		files: z
@@ -57,9 +90,50 @@ const SnapshotListDataSchema = z
 const SnapshotListResponseSchema = APIResponseSchema(SnapshotListDataSchema);
 const SnapshotDeleteResponseSchema = APIResponseSchemaNoData();
 
+const SnapshotLineageEntrySchema = z
+	.object({
+		snapshotId: z.string().describe('Unique identifier for the snapshot'),
+		name: z
+			.string()
+			.describe(
+				'Display name for the snapshot (URL-safe: letters, numbers, underscores, dashes)'
+			),
+		fullName: z
+			.string()
+			.optional()
+			.describe('Full name with org slug for public snapshots (@slug/name:tag)'),
+		message: z.string().nullable().optional().describe('Build message for the snapshot'),
+		tag: z.string().nullable().optional().describe('Tag for the snapshot'),
+		parentSnapshotId: z
+			.string()
+			.nullable()
+			.optional()
+			.describe('ID of the parent snapshot in the lineage'),
+		public: z.boolean().describe('Whether the snapshot is publicly accessible'),
+		org: SnapshotOrgInfoSchema.nullable()
+			.optional()
+			.describe('Organization details (for public snapshots)'),
+		user: SnapshotUserInfoSchema.nullable()
+			.optional()
+			.describe('User who pushed the snapshot (for private snapshots)'),
+		createdAt: z.string().describe('ISO timestamp when the snapshot was created'),
+	})
+	.describe('A single entry in the snapshot lineage chain');
+
+const SnapshotLineageDataSchema = z
+	.object({
+		lineage: z.array(SnapshotLineageEntrySchema).describe('Ordered list of snapshots in lineage'),
+		total: z.number().describe('Total number of snapshots in the lineage'),
+	})
+	.describe('Snapshot lineage response');
+
+const SnapshotLineageResponseSchema = APIResponseSchema(SnapshotLineageDataSchema);
+
 export type SnapshotFileInfo = z.infer<typeof SnapshotFileInfoSchema>;
 export type SnapshotInfo = z.infer<typeof SnapshotInfoSchema>;
 export type SnapshotListResponse = z.infer<typeof SnapshotListDataSchema>;
+export type SnapshotLineageEntry = z.infer<typeof SnapshotLineageEntrySchema>;
+export type SnapshotLineageResponse = z.infer<typeof SnapshotLineageDataSchema>;
 
 const _SnapshotCreateParamsSchema = z
 	.object({
@@ -67,6 +141,10 @@ const _SnapshotCreateParamsSchema = z
 		name: z.string().optional().describe('Display name for the snapshot'),
 		description: z.string().optional().describe('Description of the snapshot'),
 		tag: z.string().optional().describe('Tag for the snapshot'),
+		public: z
+			.boolean()
+			.optional()
+			.describe('Whether to make the snapshot publicly accessible (default: false)'),
 		orgId: z.string().optional().describe('Organization ID'),
 	})
 	.describe('Parameters for creating a snapshot');
@@ -102,11 +180,31 @@ const _SnapshotTagParamsSchema = z
 	})
 	.describe('Parameters for tagging a snapshot');
 
+const _SnapshotLineageParamsSchema = z
+	.object({
+		snapshot: z
+			.string()
+			.optional()
+			.describe('Snapshot ID or name:tag to start lineage from (e.g., "sss_xxx" or "myimage:v1")'),
+		name: z
+			.string()
+			.optional()
+			.describe('Snapshot name to start lineage from (uses latest if tag not specified)'),
+		tag: z.string().optional().describe('Tag to use with name parameter'),
+		limit: z
+			.number()
+			.optional()
+			.describe('Maximum number of snapshots to return in lineage (default: 100, max: 1000)'),
+		orgId: z.string().optional().describe('Organization ID'),
+	})
+	.describe('Parameters for getting snapshot lineage');
+
 export type SnapshotCreateParams = z.infer<typeof _SnapshotCreateParamsSchema>;
 export type SnapshotGetParams = z.infer<typeof _SnapshotGetParamsSchema>;
 export type SnapshotListParams = z.infer<typeof _SnapshotListParamsSchema>;
 export type SnapshotDeleteParams = z.infer<typeof _SnapshotDeleteParamsSchema>;
 export type SnapshotTagParams = z.infer<typeof _SnapshotTagParamsSchema>;
+export type SnapshotLineageParams = z.infer<typeof _SnapshotLineageParamsSchema>;
 
 function buildQueryString(params: Record<string, string | number | undefined>): string {
 	const query = new URLSearchParams();
@@ -131,11 +229,11 @@ export async function snapshotCreate(
 	client: APIClient,
 	params: SnapshotCreateParams
 ): Promise<SnapshotInfo> {
-	const { sandboxId, name, description, tag, orgId } = params;
+	const { sandboxId, name, description, tag, public: isPublic, orgId } = params;
 	const queryString = buildQueryString({ orgId });
 	const url = `/sandbox/${API_VERSION}/${sandboxId}/snapshot${queryString}`;
 
-	const body: Record<string, string> = {};
+	const body: Record<string, string | boolean> = {};
 	if (name) {
 		body.name = name;
 	}
@@ -145,6 +243,9 @@ export async function snapshotCreate(
 	if (tag) {
 		body.tag = tag;
 	}
+	if (isPublic !== undefined) {
+		body.public = isPublic;
+	}
 
 	const resp = await client.post<z.infer<typeof SnapshotCreateResponseSchema>>(
 		url,
@@ -269,6 +370,49 @@ export async function snapshotTag(
 	throw new SandboxResponseError({ message: resp.message });
 }
 
+/**
+ * Gets the lineage (ancestry chain) of a snapshot.
+ *
+ * Returns an ordered list of snapshots from the specified snapshot (or latest by name)
+ * walking back through parentSnapshotId references to the root.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters specifying which snapshot to get lineage for
+ * @returns Ordered list of snapshots in the lineage (newest to oldest)
+ * @throws {SandboxResponseError} If the snapshot is not found or request fails
+ *
+ * @example
+ * // Get lineage starting from a specific snapshot ID
+ * const lineage = await snapshotLineage(client, { snapshot: 'snp_abc123' });
+ *
+ * @example
+ * // Get lineage starting from the latest snapshot with a given name
+ * const lineage = await snapshotLineage(client, { name: 'myapp' });
+ *
+ * @example
+ * // Get lineage starting from a specific name:tag
+ * const lineage = await snapshotLineage(client, { name: 'myapp', tag: 'v1.0.0' });
+ */
+export async function snapshotLineage(
+	client: APIClient,
+	params: SnapshotLineageParams
+): Promise<SnapshotLineageResponse> {
+	const { snapshot, name, tag, limit, orgId } = params;
+	const queryString = buildQueryString({ snapshot, name, tag, limit, orgId });
+	const url = `/sandbox/${API_VERSION}/snapshots/lineage${queryString}`;
+
+	const resp = await client.get<z.infer<typeof SnapshotLineageResponseSchema>>(
+		url,
+		SnapshotLineageResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new SandboxResponseError({ message: resp.message });
+}
+
 // ===== Snapshot Build API =====
 
 const _SnapshotBuildInitParamsSchema = z
@@ -283,6 +427,10 @@ const _SnapshotBuildInitParamsSchema = z
 			.describe('SHA-256 hash of snapshot content for change detection'),
 		force: z.boolean().optional().describe('Force rebuild even if content is unchanged'),
 		encrypt: z.boolean().optional().describe('Request encryption for the snapshot archive'),
+		public: z
+			.boolean()
+			.optional()
+			.describe('Make snapshot public (enables virus scanning, disables encryption)'),
 		orgId: z.string().optional().describe('Organization ID'),
 	})
 	.describe('Parameters for initializing a snapshot build');
@@ -293,8 +441,7 @@ const SnapshotBuildInitResponseSchema = z
 		uploadUrl: z
 			.string()
 			.optional()
-			.describe('Pre-signed URL for uploading the snapshot archive'),
-		s3Key: z.string().optional().describe('S3 key where the snapshot will be stored'),
+			.describe('Pre-signed URL for uploading the snapshot archive (private snapshots only)'),
 		publicKey: z
 			.string()
 			.optional()
@@ -340,7 +487,8 @@ export async function snapshotBuildInit(
 	client: APIClient,
 	params: SnapshotBuildInitParams
 ): Promise<SnapshotBuildInitResponse> {
-	const { runtime, name, description, tag, contentHash, force, encrypt, orgId } = params;
+	const { runtime, name, description, tag, contentHash, force, encrypt, public: isPublic, orgId } =
+		params;
 	const queryString = buildQueryString({ orgId });
 	const url = `/sandbox/${API_VERSION}/snapshots/build${queryString}`;
 
@@ -351,6 +499,7 @@ export async function snapshotBuildInit(
 	if (contentHash) body.contentHash = contentHash;
 	if (force) body.force = force;
 	if (encrypt) body.encrypt = encrypt;
+	if (isPublic !== undefined) body.public = isPublic;
 
 	const resp = await client.post<z.infer<typeof SnapshotBuildInitAPIResponseSchema>>(
 		url,
@@ -402,3 +551,72 @@ export async function snapshotBuildFinalize(
 
 	throw new SandboxResponseError({ message: resp.message });
 }
+
+// ===== Snapshot Upload API (for public snapshots) =====
+
+const SnapshotUploadResponseSchema = z
+	.object({
+		success: z.boolean().describe('Whether the upload was successful'),
+		scanned: z.boolean().describe('Whether the upload was virus scanned'),
+		message: z.string().optional().describe('Optional message'),
+	})
+	.describe('Response from snapshot upload API');
+
+const _SnapshotUploadAPIResponseSchema = APIResponseSchema(SnapshotUploadResponseSchema);
+
+export type SnapshotUploadResponse = z.infer<typeof SnapshotUploadResponseSchema>;
+
+export interface SnapshotUploadParams {
+	snapshotId: string;
+	body: Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | string | Blob;
+	contentLength: number;
+	orgId?: string;
+}
+
+/**
+ * Upload a public snapshot archive via Catalyst (with virus scanning).
+ * This should only be used when snapshotBuildInit returns no uploadUrl.
+ *
+ * @param client - The API client to use for the request
+ * @param params - Parameters including snapshotId and the archive body
+ * @returns Upload result with scan status
+ * @throws {SandboxResponseError} If the upload fails or malware is detected
+ */
+export async function snapshotUpload(
+	client: APIClient,
+	params: SnapshotUploadParams
+): Promise<SnapshotUploadResponse> {
+	const { snapshotId, body, contentLength, orgId } = params;
+	const queryString = buildQueryString({ orgId });
+	const url = `/sandbox/${API_VERSION}/snapshots/${snapshotId}/upload${queryString}`;
+
+	const response = await client.rawPut(url, body, 'application/gzip', undefined, {
+		'Content-Length': String(contentLength),
+		Accept: 'application/json',
+	});
+
+	if (!response.ok) {
+		const text = await response.text();
+		let message = `Upload failed: ${response.status} ${response.statusText}`;
+		try {
+			const json = JSON.parse(text);
+			if (json.message) {
+				message = json.message;
+			} else if (json.error) {
+				message = typeof json.error === 'string' ? json.error : JSON.stringify(json.error);
+			}
+		} catch {
+			if (text) {
+				message = text;
+			}
+		}
+		throw new SandboxResponseError({ message });
+	}
+
+	const data = (await response.json()) as z.infer<typeof _SnapshotUploadAPIResponseSchema>;
+	if (data.success) {
+		return data.data;
+	}
+
+	throw new SandboxResponseError({ message: data.message });
+}