using System.Collections.Immutable;
using Connected.Annotations;
using Connected.Notifications;
using Connected.ServiceModel;

namespace Logistics.Types.Serials;
/// <summary>
/// The service for manipulating with serials. A <see cref="ISerial"/> is a fundamental
/// entity used by labeling and traceability systems.
/// </summary>
[Service]
[ServiceUrl(LogisticsUrls.Serials)]
public interface ISerialService : IServiceNotifications<long>
{
	/// <summary>
	/// Queries all serial numbers.
	/// </summary>
	/// <param name="args">The optional arguments specifiying the
	/// behavior of the result set.</param>
	/// <returns>A list of <see cref="ISerial"/> entities.</returns>
	[ServiceMethod(ServiceMethodVerbs.Get | ServiceMethodVerbs.Post)]
	Task<ImmutableList<ISerial>> Query(QueryArgs? args);
	/// <summary>
	/// Performs a lookup on the serials for the specified set of ids.
	/// </summary>
	/// <param name="args">The arguments containing the list of ids for
	/// which the entities will be returned.</param>
	/// <returns>A list of entities that matches the specified ids.</returns>
	[ServiceMethod(ServiceMethodVerbs.Get | ServiceMethodVerbs.Post)]
	Task<ImmutableList<ISerial>> Query(PrimaryKeyListArgs<long> args);
	/// <summary>
	/// Returns the first serial that matches the specified id.
	/// </summary>
	/// <param name="args">The arguments containing the id of the entity.</param>
	/// <returns>The <see cref="ISerial"/> if found, <c>null</c> otherwise.</returns>
	[ServiceMethod(ServiceMethodVerbs.Get | ServiceMethodVerbs.Post)]
	Task<ISerial?> Select(PrimaryKeyArgs<long> args);
	/// <summary>
	/// Returns the first serial with the specified value.
	/// </summary>
	/// <param name="args">The arguments containing the value for which serial
	/// entity will be returned.</param>
	/// <returns>The <see cref="ISerial"/> if found, <c>null</c> otherwise.</returns>
	[ServiceMethod(ServiceMethodVerbs.Get | ServiceMethodVerbs.Post)]
	Task<ISerial?> Select(SelectSerialArgs args);
	/// <summary>
	/// Inserts a new serial number.
	/// </summary>
	/// <param name="args">The arguments containing the properties of the new serial.</param>
	/// <returns>The id of the newly inserted serial.</returns>
	[ServiceMethod(ServiceMethodVerbs.Post | ServiceMethodVerbs.Put)]
	Task<long> Insert(InsertSerialArgs args);
	/// <summary>
	/// Updates an existing serial.
	/// </summary>
	/// <param name="args">The arguments containing properties which will change the entity.</param>
	[ServiceMethod(ServiceMethodVerbs.Post | ServiceMethodVerbs.Patch)]
	Task Update(UpdateSerialArgs args);
	/// <summary>
	/// Performs a partial update on the serial.
	/// </summary>
	/// <param name="args">The arguments containing properties which has to be updated.</param>
	[ServiceMethod(ServiceMethodVerbs.Post | ServiceMethodVerbs.Patch)]
	Task Patch(PatchArgs<long> args);
	/// <summary>
	/// Peranently deletes the serial from the storage.
	/// </summary>
	/// <param name="args">The arguments containing the id of the entity to be deleted.</param>
	[ServiceMethod(ServiceMethodVerbs.Post | ServiceMethodVerbs.Delete)]
	Task Delete(PrimaryKeyArgs<long> args);
}