From 57627d4718d351f423df2def0f4eca76baa2080f Mon Sep 17 00:00:00 2001 From: CodeCasterNL Date: Sun, 30 May 2021 21:25:59 +0200 Subject: [PATCH] #64: interface ALL the (public) things --- src/PVOutput.Net/IPVOutputClient.cs | 91 +++++++++++++ src/PVOutput.Net/Modules/ExtendedService.cs | 26 +--- src/PVOutput.Net/Modules/FavouriteService.cs | 18 +-- src/PVOutput.Net/Modules/InsolationService.cs | 36 +---- .../Modules/Interfaces/IExtendedService.cs | 35 +++++ .../Modules/Interfaces/IFavouriteService.cs | 22 +++ .../Modules/Interfaces/IInsolationService.cs | 45 +++++++ .../Modules/Interfaces/IMissingService.cs | 24 ++++ .../Interfaces/INotificationService.cs | 43 ++++++ .../Modules/Interfaces/IOutputService.cs | 88 ++++++++++++ .../Modules/Interfaces/ISearchService.cs | 127 ++++++++++++++++++ .../Modules/Interfaces/IStatisticsService.cs | 39 ++++++ .../Modules/Interfaces/IStatusService.cs | 108 +++++++++++++++ .../Modules/Interfaces/ISupplyService.cs | 23 ++++ .../Modules/Interfaces/ISystemService.cs | 44 ++++++ .../Modules/Interfaces/ITeamService.cs | 41 ++++++ src/PVOutput.Net/Modules/MissingService.cs | 15 +-- .../Modules/NotificationService.cs | 36 +---- src/PVOutput.Net/Modules/OutputService.cs | 71 ++-------- src/PVOutput.Net/Modules/SearchService.cs | 107 +++------------ src/PVOutput.Net/Modules/StatisticsService.cs | 29 +--- src/PVOutput.Net/Modules/StatusService.cs | 91 ++----------- src/PVOutput.Net/Modules/SupplyService.cs | 19 +-- src/PVOutput.Net/Modules/SystemService.cs | 34 +---- src/PVOutput.Net/Modules/TeamService.cs | 35 +---- .../PVOutput.Net.csproj.DotSettings | 2 + src/PVOutput.Net/PVOutputClient.cs | 98 +++++--------- .../Modules/Search/SearchServiceTests.cs | 2 +- 28 files changed, 838 insertions(+), 511 deletions(-) create mode 100644 src/PVOutput.Net/IPVOutputClient.cs create mode 100644 src/PVOutput.Net/Modules/Interfaces/IExtendedService.cs create mode 100644 src/PVOutput.Net/Modules/Interfaces/IFavouriteService.cs create mode 100644 src/PVOutput.Net/Modules/Interfaces/IInsolationService.cs create mode 100644 src/PVOutput.Net/Modules/Interfaces/IMissingService.cs create mode 100644 src/PVOutput.Net/Modules/Interfaces/INotificationService.cs create mode 100644 src/PVOutput.Net/Modules/Interfaces/IOutputService.cs create mode 100644 src/PVOutput.Net/Modules/Interfaces/ISearchService.cs create mode 100644 src/PVOutput.Net/Modules/Interfaces/IStatisticsService.cs create mode 100644 src/PVOutput.Net/Modules/Interfaces/IStatusService.cs create mode 100644 src/PVOutput.Net/Modules/Interfaces/ISupplyService.cs create mode 100644 src/PVOutput.Net/Modules/Interfaces/ISystemService.cs create mode 100644 src/PVOutput.Net/Modules/Interfaces/ITeamService.cs create mode 100644 src/PVOutput.Net/PVOutput.Net.csproj.DotSettings diff --git a/src/PVOutput.Net/IPVOutputClient.cs b/src/PVOutput.Net/IPVOutputClient.cs new file mode 100644 index 0000000..6a2f112 --- /dev/null +++ b/src/PVOutput.Net/IPVOutputClient.cs @@ -0,0 +1,91 @@ +using PVOutput.Net.Modules; + +namespace PVOutput.Net +{ + /// + /// The client used to communicate with the PVOutput service. + /// + public interface IPVOutputClient + { + /// ApiKey to use with authenticating. + string ApiKey { get; set; } + + /// Id of the currently owned system used for authenticating. + int OwnedSystemId { get; set; } + + /// Indicates whether or not the client should throw exceptions when the api returns errors. + bool ThrowResponseExceptions { get; set; } + + /// + /// The output service. + /// See the official API information. + /// + IOutputService Output { get; } + + /// + /// The system service. + /// See the official API information. + /// + ISystemService System { get; } + + /// + /// The status service. + /// See the official API information. + /// + IStatusService Status { get; } + + /// + /// The statistic service. + /// See the official API information. + /// + IStatisticsService Statistics { get; } + + /// + /// The missing service. + /// See the official API information. + /// + IMissingService Missing { get; } + + /// + /// The team service. + /// See the official API information. + /// + ITeamService Team { get; } + + /// + /// The extended service. + /// See the official API information. + /// + IExtendedService Extended { get; } + + /// + /// The favourite service. + /// See the official API information. + /// + IFavouriteService Favourite { get; } + + /// + /// The insolation service. + /// See the official API information. + /// + IInsolationService Insolation { get; } + + /// + /// The supply service. + /// See the official API information. + /// + ISupplyService Supply { get; } + + /// + /// The search service + /// See the official API information. + /// + ISearchService Search { get; } + + /// + /// The notification service + /// See the official API information. + /// + INotificationService Notification { get; } + } +} diff --git a/src/PVOutput.Net/Modules/ExtendedService.cs b/src/PVOutput.Net/Modules/ExtendedService.cs index a212f8f..8b628eb 100644 --- a/src/PVOutput.Net/Modules/ExtendedService.cs +++ b/src/PVOutput.Net/Modules/ExtendedService.cs @@ -1,6 +1,5 @@ using System; using System.Collections.Generic; -using System.Text; using System.Threading; using System.Threading.Tasks; using Dawn; @@ -12,23 +11,14 @@ namespace PVOutput.Net.Modules { - /// - /// The Get Extended service retrieves system daily extended data. - /// See the official API information. - /// Note: this is a donation only service. - /// - public sealed class ExtendedService : BaseService + /// + public sealed class ExtendedService : BaseService, IExtendedService { internal ExtendedService(PVOutputClient client) : base(client) { } - /// - /// Retrieve most recently created extended data. - /// Note: this is a donation only request. - /// - /// A cancellation token for the request. - /// Most recent extended data. + /// public Task> GetRecentExtendedDataAsync(CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -40,15 +30,7 @@ public Task> GetRecentExtendedDataAsync(Cancellation return handler.ExecuteSingleItemRequestAsync(new ExtendedRequest(), loggingScope, cancellationToken); } - /// - /// Retrieve extended data for a certain period. - /// Note: this is a donation only request. - /// - /// Minimum DateTime for the requested range. - /// Maximum DateTime for the requested range. - /// Optional limit of number of items. 50 is the maximum. - /// A cancellation token for the request. - /// List of extended data objects. + /// public Task> GetExtendedDataForPeriodAsync(DateTime fromDate, DateTime toDate, int? limit = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() diff --git a/src/PVOutput.Net/Modules/FavouriteService.cs b/src/PVOutput.Net/Modules/FavouriteService.cs index 5ce1877..f023bb4 100644 --- a/src/PVOutput.Net/Modules/FavouriteService.cs +++ b/src/PVOutput.Net/Modules/FavouriteService.cs @@ -1,6 +1,4 @@ -using System; -using System.Collections.Generic; -using System.Text; +using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; using PVOutput.Net.Objects; @@ -11,22 +9,14 @@ namespace PVOutput.Net.Modules { - /// - /// The Get Favourite service retrieves the systems in your favourites or another user's favourites. - /// See the official API information. - /// - public sealed class FavouriteService : BaseService + /// + public sealed class FavouriteService : BaseService, IFavouriteService { internal FavouriteService(PVOutputClient client) : base(client) { } - /// - /// Retrieves the favourites for the owned system, or another. - /// - /// Optional SystemId to request the favourites for. - /// A cancellation token for the request. - /// List of favourites. + /// public Task> GetFavouritesAsync(int? systemId = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() diff --git a/src/PVOutput.Net/Modules/InsolationService.cs b/src/PVOutput.Net/Modules/InsolationService.cs index 94ac232..4cc1ad8 100644 --- a/src/PVOutput.Net/Modules/InsolationService.cs +++ b/src/PVOutput.Net/Modules/InsolationService.cs @@ -1,9 +1,7 @@ using System; using System.Collections.Generic; -using System.Text; using System.Threading; using System.Threading.Tasks; -using Microsoft.Extensions.Logging; using PVOutput.Net.Objects; using PVOutput.Net.Objects.Core; using PVOutput.Net.Requests.Handler; @@ -12,24 +10,14 @@ namespace PVOutput.Net.Modules { - /// - /// The Get Insolation service retrieves 5-minute insolation data (power and energy) under ideal weather conditions. - /// See the official API information. - /// Note: this is a donation only service. - /// - public sealed class InsolationService : BaseService + /// + public sealed class InsolationService : BaseService, IInsolationService { internal InsolationService(PVOutputClient client) : base(client) { } - /// - /// Get insolation data for own system. - /// Note: this is a donation only request. - /// - /// The DateTime to calculate the insolation for. If empty, the current date will be calculated. - /// A cancellation token for the request. - /// Insolation data for the owned system. + /// public Task> GetInsolationForOwnSystemAsync(DateTime? date = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -43,14 +31,7 @@ public Task> GetInsolationForOwnSystemAsync(D return response; } - /// - /// Get insolation data for a system. - /// Note: this is a donation only request. - /// - /// Id of the system to get insolation for. - /// The DateTime to calculate the insolation for. If empty, the current date will be calculated. - /// A cancellation token for the request. - /// Insolation data for the requested system. + /// public Task> GetInsolationForSystemAsync(int systemId, DateTime? date = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -65,14 +46,7 @@ public Task> GetInsolationForSystemAsync(int return response; } - /// - /// Get insolation data for a location. - /// Note: this is a donation only request. - /// - /// GPS coordinate, to request insolation for. - /// The DateTime to calculate the insolation for. If empty, the current date will be calculated. - /// A cancellation token for the request. - /// Insolation data for the requested location. + /// public Task> GetInsolationForLocationAsync(PVCoordinate coordinate, DateTime? date = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() diff --git a/src/PVOutput.Net/Modules/Interfaces/IExtendedService.cs b/src/PVOutput.Net/Modules/Interfaces/IExtendedService.cs new file mode 100644 index 0000000..e7b017e --- /dev/null +++ b/src/PVOutput.Net/Modules/Interfaces/IExtendedService.cs @@ -0,0 +1,35 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using PVOutput.Net.Objects; +using PVOutput.Net.Responses; + +namespace PVOutput.Net.Modules +{ + /// + /// The Get Extended service retrieves system daily extended data. + /// See the official API information. + /// Note: this is a donation only service. + /// + public interface IExtendedService + { + /// + /// Retrieve most recently created extended data. + /// Note: this is a donation only request. + /// + /// A cancellation token for the request. + /// Most recent extended data. + Task> GetRecentExtendedDataAsync(CancellationToken cancellationToken = default); + + /// + /// Retrieve extended data for a certain period. + /// Note: this is a donation only request. + /// + /// Minimum DateTime for the requested range. + /// Maximum DateTime for the requested range. + /// Optional limit of number of items. 50 is the maximum. + /// A cancellation token for the request. + /// List of extended data objects. + Task> GetExtendedDataForPeriodAsync(DateTime fromDate, DateTime toDate, int? limit = null, CancellationToken cancellationToken = default); + } +} diff --git a/src/PVOutput.Net/Modules/Interfaces/IFavouriteService.cs b/src/PVOutput.Net/Modules/Interfaces/IFavouriteService.cs new file mode 100644 index 0000000..ca819f8 --- /dev/null +++ b/src/PVOutput.Net/Modules/Interfaces/IFavouriteService.cs @@ -0,0 +1,22 @@ +using System.Threading; +using System.Threading.Tasks; +using PVOutput.Net.Objects; +using PVOutput.Net.Responses; + +namespace PVOutput.Net.Modules +{ + /// + /// The Get Favourite service retrieves the systems in your favourites or another user's favourites. + /// See the official API information. + /// + public interface IFavouriteService + { + /// + /// Retrieves the favourites for the owned system, or another. + /// + /// Optional SystemId to request the favourites for. + /// A cancellation token for the request. + /// List of favourites. + Task> GetFavouritesAsync(int? systemId = null, CancellationToken cancellationToken = default); + } +} diff --git a/src/PVOutput.Net/Modules/Interfaces/IInsolationService.cs b/src/PVOutput.Net/Modules/Interfaces/IInsolationService.cs new file mode 100644 index 0000000..83eedc6 --- /dev/null +++ b/src/PVOutput.Net/Modules/Interfaces/IInsolationService.cs @@ -0,0 +1,45 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using PVOutput.Net.Objects; +using PVOutput.Net.Responses; + +namespace PVOutput.Net.Modules +{ + /// + /// The Get Insolation service retrieves 5-minute insolation data (power and energy) under ideal weather conditions. + /// See the official API information. + /// Note: this is a donation only service. + /// + public interface IInsolationService + { + /// + /// Get insolation data for own system. + /// Note: this is a donation only request. + /// + /// The DateTime to calculate the insolation for. If empty, the current date will be calculated. + /// A cancellation token for the request. + /// Insolation data for the owned system. + Task> GetInsolationForOwnSystemAsync(DateTime? date = null, CancellationToken cancellationToken = default); + + /// + /// Get insolation data for a system. + /// Note: this is a donation only request. + /// + /// Id of the system to get insolation for. + /// The DateTime to calculate the insolation for. If empty, the current date will be calculated. + /// A cancellation token for the request. + /// Insolation data for the requested system. + Task> GetInsolationForSystemAsync(int systemId, DateTime? date = null, CancellationToken cancellationToken = default); + + /// + /// Get insolation data for a location. + /// Note: this is a donation only request. + /// + /// GPS coordinate, to request insolation for. + /// The DateTime to calculate the insolation for. If empty, the current date will be calculated. + /// A cancellation token for the request. + /// Insolation data for the requested location. + Task> GetInsolationForLocationAsync(PVCoordinate coordinate, DateTime? date = null, CancellationToken cancellationToken = default); + } +} diff --git a/src/PVOutput.Net/Modules/Interfaces/IMissingService.cs b/src/PVOutput.Net/Modules/Interfaces/IMissingService.cs new file mode 100644 index 0000000..f6d197f --- /dev/null +++ b/src/PVOutput.Net/Modules/Interfaces/IMissingService.cs @@ -0,0 +1,24 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using PVOutput.Net.Objects; +using PVOutput.Net.Responses; + +namespace PVOutput.Net.Modules +{ + /// + /// The Get Missing service retrieves a list of output dates missing from a system. + /// See the official API information. + /// + public interface IMissingService + { + /// + /// Retrieves a list of output dates with no data + /// + /// Minimum date for the requested range. + /// Maximum date for the requested range. + /// A cancellation token for the request. + /// List of missing dates + Task> GetMissingDaysInPeriodAsync(DateTime fromDate, DateTime toDate, CancellationToken cancellationToken = default); + } +} diff --git a/src/PVOutput.Net/Modules/Interfaces/INotificationService.cs b/src/PVOutput.Net/Modules/Interfaces/INotificationService.cs new file mode 100644 index 0000000..adcd0f0 --- /dev/null +++ b/src/PVOutput.Net/Modules/Interfaces/INotificationService.cs @@ -0,0 +1,43 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using PVOutput.Net.Responses; + +namespace PVOutput.Net.Modules +{ + /// + /// The Notification service enables (de-)registering alert notifications. + /// See the official API information. + /// + public interface INotificationService + { + /// + /// Registers an application for a notification. + /// + /// ApplicationId to register the notification under. + /// The url that should get called for each notification. + /// A specific type of alert to send, leave empty for all alert types. + /// A cancellation token for the request. + /// If the operation succeeded. + Task RegisterNotificationAsync(string applicationId, string callbackUrl, int? alertType = null, CancellationToken cancellationToken = default); + + /// + /// Registers an application for a notification. + /// + /// ApplicationId to register the notification under. + /// The uri that should get called for each notification. + /// A specific type of alert to send, leave empty for all alert types. + /// A cancellation token for the request. + /// If the operation succeeded. + Task RegisterNotificationAsync(string applicationId, Uri callbackUri, int? alertType = null, CancellationToken cancellationToken = default); + + /// + /// Deregisters an application for a notification. + /// + /// ApplicationId to register the notification under. + /// A specific type of alert to send, leave empty for all alert types. + /// A cancellation token for the request. + /// If the operation succeeded. + Task DeregisterNotificationAsync(string applicationId, int? alertType = null, CancellationToken cancellationToken = default); + } +} diff --git a/src/PVOutput.Net/Modules/Interfaces/IOutputService.cs b/src/PVOutput.Net/Modules/Interfaces/IOutputService.cs new file mode 100644 index 0000000..b023d49 --- /dev/null +++ b/src/PVOutput.Net/Modules/Interfaces/IOutputService.cs @@ -0,0 +1,88 @@ +using System; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using PVOutput.Net.Builders; +using PVOutput.Net.Enums; +using PVOutput.Net.Objects; +using PVOutput.Net.Responses; + +namespace PVOutput.Net.Modules +{ + /// + /// The Output service handles daily output information for individual systems. + /// See the official API information. + /// + public interface IOutputService + { + /// + /// Retrieve daily output for a date. + /// + /// Date to retrieve the output for. + /// Also retrieve insolation information. Note: this is a donation only parameter. + /// Retrieve output for a specific system. Note: this is a donation only parameter. + /// A cancellation token for the request. + /// Output for the requested date. + Task> GetOutputForDateAsync(DateTime date, bool getInsolation = false, int? systemId = null, CancellationToken cancellationToken = default); + + /// + /// Retrieve daily outputs for a period. + /// + /// Minimum date for the requested range. + /// Maximum date for the requested range. + /// Also retrieve insolation information. Note: this is a donation only parameter. + /// Retrieve output for a specific system. Note: this is a donation only parameter. + /// A cancellation token for the request. + /// Outputs for the requested period. + Task> GetOutputsForPeriodAsync(DateTime fromDate, DateTime toDate, bool getInsolation = false, int? systemId = null, CancellationToken cancellationToken = default); + + /// + /// Retrieve daily output for a team. + /// + /// Date to retrieve the output for. + /// Team to retrieve the output for. + /// A cancellation token for the request. + /// Team output for the requested date. + Task> GetTeamOutputForDateAsync(DateTime date, int teamId, CancellationToken cancellationToken = default); + + /// + /// Retrieve daily team outputs for a period. + /// + /// Minimum date for the requested range. + /// Maximum date for the requested range. + /// Team to retrieve the output for. + /// A cancellation token for the request. + /// Team outputs Outputs for the requested period. + Task> GetTeamOutputsForPeriodAsync(DateTime fromDate, DateTime toDate, int teamId, CancellationToken cancellationToken = default); + + /// + /// Retrieve aggregated outputs for a period. + /// + /// Minimum DateTime for the requested range. + /// Maximum DateTime for the requested range. + /// Period to aggregate the outputs in. + /// A cancellation token for the request. + /// Aggregated outputs for the requested period. + Task> GetAggregatedOutputsAsync(DateTime fromDate, DateTime toDate, AggregationPeriod period, CancellationToken cancellationToken = default); + + /// + /// Adds a single daily output to the owned system. + /// See the official API information. + /// Use the to create objects. + /// + /// The output to add. + /// A cancellation token for the request. + /// If the operation succeeded. + Task AddOutputAsync(IOutputPost output, CancellationToken cancellationToken = default); + + /// + /// Adds a list of outputs to the owned system. + /// See the official API information. + /// Use the to create objects. + /// + /// Outputs to add. 30 outputs is the maximum, 100 for donation + /// A cancellation token for the request. + /// If the operation succeeded. + Task AddBatchOutputAsync(IEnumerable outputs, CancellationToken cancellationToken = default); + } +} diff --git a/src/PVOutput.Net/Modules/Interfaces/ISearchService.cs b/src/PVOutput.Net/Modules/Interfaces/ISearchService.cs new file mode 100644 index 0000000..ebd4ccb --- /dev/null +++ b/src/PVOutput.Net/Modules/Interfaces/ISearchService.cs @@ -0,0 +1,127 @@ +using System.Threading; +using System.Threading.Tasks; +using PVOutput.Net.Enums; +using PVOutput.Net.Objects; +using PVOutput.Net.Responses; + +namespace PVOutput.Net.Modules +{ + /// + /// The Search service retrieves a list of systems matching the given search query. + /// See the official API information. + /// + public interface ISearchService + { + /// + /// Retrieves a list of systems matching the provided query. + /// See this page for help with the query syntax. + /// + /// A search query to retrieve systems for. + /// A GPS coordinate, used for distance queries. + /// A cancellation token for the request. + /// A list of search results. + Task> SearchAsync(string searchQuery, PVCoordinate? coordinate = null, CancellationToken cancellationToken = default); + + /// + /// Search for systems by name. + /// + /// Name to search for. + /// If true the name should start with the value. Otherwise the search is performed using a contains method. + /// A cancellation token for the request. + /// A list of search results. + Task> SearchByNameAsync(string name, bool useStartsWith = true, CancellationToken cancellationToken = default); + + /// + /// Search for systems that have either a postcode or total size that begins with a value. + /// + /// Value to search for. + /// A cancellation token for the request. + /// A list of search results. + Task> SearchByPostcodeOrSizeAsync(int value, CancellationToken cancellationToken = default); + + /// + /// Search for systems by postcode. + /// + /// Postcode to search for. + /// A cancellation token for the request. + /// A list of search results. + Task> SearchByPostcodeAsync(string postcode, CancellationToken cancellationToken = default); + + /// + /// Search for systems by size. + /// + /// Size to search for. + /// A cancellation token for the request. + /// A list of search results. + Task> SearchBySizeAsync(int value, CancellationToken cancellationToken = default); + + /// + /// Search for systems by panel. + /// + /// Panel to search for. + /// A cancellation token for the request. + /// A list of search results. + Task> SearchByPanelAsync(string panel, CancellationToken cancellationToken = default); + + /// + /// Search for systems by inverter. + /// + /// Inverter to search for. + /// If true the name should start with the value. Otherwise the search is performed using a contains method. + /// A cancellation token for the request. + /// A list of search results. + Task> SearchByInverterAsync(string inverter, bool useStartsWith = true, CancellationToken cancellationToken = default); + + /// + /// Search for systems by distance. + /// + /// Postcode to search from. + /// Distance to search with (25 is the maximum). + /// Country code of the postcode to search in (eg. "nl"). + /// A cancellation token for the request. + /// A list of search results. + Task> SearchByDistanceAsync(int postcode, int kilometers, string countryCode, CancellationToken cancellationToken = default); + + /// + /// Search for systems by distance. + /// + /// GPS coordinate to search from. + /// Distance to search with (25 is the maximum). + /// A cancellation token for the request. + /// A list of search results. + Task> SearchByDistanceAsync(PVCoordinate coordinate, int kilometers, CancellationToken cancellationToken = default); + + /// + /// Search for systems by team name. + /// + /// Team name to search for. + /// A cancellation token for the request. + /// A list of search results. + Task> SearchByTeamAsync(string teamName, CancellationToken cancellationToken = default); + + /// + /// Search for systems by orientation. + /// + /// Orientation to search for. + /// Name to search for. + /// If true the name should start with the value. Otherwise the search is performed using a contains method. + /// A cancellation token for the request. + /// A list of search results. + Task> SearchByOrientationAsync(Orientation orientation, string name = null, bool useStartsWith = true, CancellationToken cancellationToken = default); + + /// + /// Search for systems by tilt. + /// + /// Tilt to search for (should be within 2.5 degrees of this value). + /// A cancellation token for the request. + /// A list of search results. + Task> SearchByTiltAsync(int tilt, CancellationToken cancellationToken = default); + + /// + /// Retrieve your favourite systems. + /// + /// A cancellation token for the request. + /// A list of search results. + Task> GetFavouritesAsync(CancellationToken cancellationToken = default); + } +} diff --git a/src/PVOutput.Net/Modules/Interfaces/IStatisticsService.cs b/src/PVOutput.Net/Modules/Interfaces/IStatisticsService.cs new file mode 100644 index 0000000..bafd6c0 --- /dev/null +++ b/src/PVOutput.Net/Modules/Interfaces/IStatisticsService.cs @@ -0,0 +1,39 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using PVOutput.Net.Objects; +using PVOutput.Net.Responses; + +namespace PVOutput.Net.Modules +{ + /// + /// The Get Statistic service retrieves system statistical information. + /// See the official API information. + /// + public interface IStatisticsService + { + /// + /// Retrieve lifetime statistics for a system. + /// Donation makes it possible to retrieve any system + /// + /// Whether or not to include consumption and import data. System owner only. + /// Whether or not to include credit and debit data. System owner only. + /// Id of the system to retrieve statistical information for. + /// A cancellation token for the request. + /// Lifetime statistical information + Task> GetLifetimeStatisticsAsync(bool includeConsumptionAndImport = false, bool includeCreditDebit = false, int? systemId = null, CancellationToken cancellationToken = default); + + /// + /// Retrieve lifetime statistics for a system, in a certain period. + /// Donation makes it possible to retrieve any system + /// + /// Minimum date for the requested range. + /// Maximum date for the requested range. + /// Whether or not to include consumption and import data. System owner only. + /// Whether or not to include credit and debit data. System owner only. + /// Id of the system to retrieve statistical information for. + /// A cancellation token for the request. + /// Statistical information for the requested period. + Task> GetStatisticsForPeriodAsync(DateTime fromDate, DateTime toDate, bool includeConsumptionAndImport = false, bool includeCreditDebit = false, int? systemId = null, CancellationToken cancellationToken = default); + } +} diff --git a/src/PVOutput.Net/Modules/Interfaces/IStatusService.cs b/src/PVOutput.Net/Modules/Interfaces/IStatusService.cs new file mode 100644 index 0000000..e73b094 --- /dev/null +++ b/src/PVOutput.Net/Modules/Interfaces/IStatusService.cs @@ -0,0 +1,108 @@ +using System; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using PVOutput.Net.Builders; +using PVOutput.Net.Objects; +using PVOutput.Net.Responses; + +namespace PVOutput.Net.Modules +{ + /// + /// The Status service handles system status information and live output data. + /// See the official API information. + /// + public interface IStatusService + { + /// + /// Get the system status at a specific moment. + /// + /// Moment to retrieve the system status for. + /// Retrieve status for a specific system. Note: this is a donation only parameter. + /// A cancellation token for the request. + /// Status at the specified moment. + Task> GetStatusForDateTimeAsync(DateTime moment, int? systemId = null, CancellationToken cancellationToken = default); + + /// + /// Get the status history for a specific period. + /// + /// Minimum datetime for the requested range. + /// Maximum datetime for the requested range. + /// Order the statuses in ascending order instead of descending. + /// Retrieve statuses for a specific system. Note: this is a donation only parameter. + /// Also retrieve extended data. Note: this is a donation only parameter. + /// Limit the number of retrieved statuses. + /// A cancellation token for the request. + /// Statusses for the specified period. + Task> GetHistoryForPeriodAsync(DateTime fromDateTime, DateTime toDateTime, bool ascending = false, int? systemId = null, bool extendedData = false, int? limit = null, CancellationToken cancellationToken = default); + + /// + /// Gets the day statistics for specific period. + /// + /// Minimum datetime for the requested range. + /// Maximum datetime for the requested range. + /// Retrieve statuses for a specific system. Note: this is a donation only parameter. + /// A cancellation token for the request. + /// Day statistics for the specified period. + Task> GetDayStatisticsForPeriodAsync(DateTime fromDateTime, DateTime toDateTime, int? systemId = null, CancellationToken cancellationToken = default); + + /// + /// Adds a single status to the owned system. + /// See the official API information. + /// Use the to create objects. + /// + /// The status to add. + /// A cancellation token for the request. + /// If the operation succeeded. + Task AddStatusAsync(IStatusPost status, CancellationToken cancellationToken = default); + + /// + /// Adds multiple statuses to the owned system. + /// See the official API information. + /// Use the to create objects. + /// + /// The statuses to add. + /// A cancellation token for the request. + /// If the operation succeeded. + Task> AddBatchStatusAsync(IEnumerable statuses, CancellationToken cancellationToken = default); + + /// + /// Adds multiple statuses to the owned system. + /// See the official API information. + /// Use the to create objects. + /// + /// The statuses to add. + /// Sets whether or not the provided data is cumulative. + /// A cancellation token for the request. + /// If the operation succeeded. + Task> AddBatchStatusAsync(IEnumerable statuses, bool isCumulative, CancellationToken cancellationToken = default); + + /// + /// Adds multiple statuses to the owned system. + /// See the official API information. + /// Use the to create objects. + /// + /// The statuses to add. + /// A cancellation token for the request. + /// If the operation succeeded. + Task> AddBatchNetStatusAsync(IEnumerable statuses, CancellationToken cancellationToken = default); + + /// + /// Deletes a status on the specified moment. + /// See the official API information. + /// + /// The moment to delete the status for. This can only be today or yesterday. + /// A cancellation token for the request. + /// If the operation succeeded. + Task DeleteStatusAsync(DateTime moment, CancellationToken cancellationToken = default); + + /// + /// Deletes all statuses on the specified date. + /// See the official API information. + /// + /// The date to delete all statuses for. This can only be today or yesterday. + /// A cancellation token for the request. + /// If the operation succeeded. + Task DeleteAllStatusesOnDateAsync(DateTime date, CancellationToken cancellationToken = default); + } +} diff --git a/src/PVOutput.Net/Modules/Interfaces/ISupplyService.cs b/src/PVOutput.Net/Modules/Interfaces/ISupplyService.cs new file mode 100644 index 0000000..16f4887 --- /dev/null +++ b/src/PVOutput.Net/Modules/Interfaces/ISupplyService.cs @@ -0,0 +1,23 @@ +using System.Threading; +using System.Threading.Tasks; +using PVOutput.Net.Objects; +using PVOutput.Net.Responses; + +namespace PVOutput.Net.Modules +{ + /// + /// The Get Supply service displays aggregated live generation and consumption data. + /// See the official API information. + /// + public interface ISupplyService + { + /// + /// Retrieves live generation and consumption data + /// + /// A timezone identifier in the 'Europe/London' format. Will default to GMT+0 if empty. + /// Region key in the '1:queensland' format. Donation only option. + /// A cancellation token for the request. + /// List of supply information + Task> GetSupplyAsync(string timeZone = null, string regionKey = null, CancellationToken cancellationToken = default); + } +} diff --git a/src/PVOutput.Net/Modules/Interfaces/ISystemService.cs b/src/PVOutput.Net/Modules/Interfaces/ISystemService.cs new file mode 100644 index 0000000..6117f84 --- /dev/null +++ b/src/PVOutput.Net/Modules/Interfaces/ISystemService.cs @@ -0,0 +1,44 @@ +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using PVOutput.Net.Builders; +using PVOutput.Net.Objects; +using PVOutput.Net.Responses; + +namespace PVOutput.Net.Modules +{ + /// + /// The Get System service retrieves system information. + /// See the official API information. + /// + public interface ISystemService + { + /// + /// Retrieves information for the owned system. + /// + /// A cancellation token for the request. + /// Information of the owned system. + Task> GetOwnSystemAsync(CancellationToken cancellationToken = default); + + /// + /// Retrieves information for a system. + /// Note: this is a donation only request. + /// + /// Id of the system to request information for + /// A cancellation token for the request. + /// Information of the requested system. + Task> GetOtherSystemAsync(int systemId, CancellationToken cancellationToken = default); + + /// + /// Updates a system's name or extended data values. + /// Use the to create definition for extended data values. + /// See the official API information. + /// + /// The system to update. + /// A new name for the system. + /// List of modified extended data definitions. + /// A cancellation token for the request. + /// If the operation succeeded. + Task PostSystem(int systemId, string systemName = null, IEnumerable dataDefinitions = null, CancellationToken cancellationToken = default); + } +} diff --git a/src/PVOutput.Net/Modules/Interfaces/ITeamService.cs b/src/PVOutput.Net/Modules/Interfaces/ITeamService.cs new file mode 100644 index 0000000..214c034 --- /dev/null +++ b/src/PVOutput.Net/Modules/Interfaces/ITeamService.cs @@ -0,0 +1,41 @@ +using System.Threading; +using System.Threading.Tasks; +using PVOutput.Net.Objects; +using PVOutput.Net.Responses; + +namespace PVOutput.Net.Modules +{ + /// + /// The Team service retrieves team information and joins/leaves teams. + /// See the official API information. + /// + public interface ITeamService + { + /// + /// Retrieves information for a team, that must be owned. + /// Donation makes it possible to retrieve any team. + /// + /// Id of the team to retrieve information for. + /// A cancellation token for the request. + /// Team information. + Task> GetTeamAsync(int teamId, CancellationToken cancellationToken = default); + + /// + /// Adds a system to a team. + /// See the official API information. + /// + /// Id of the team to join. + /// A cancellation token for the request. + /// If the operation succeeded. + Task JoinTeamAsync(int teamId, CancellationToken cancellationToken = default); + + /// + /// Removes a system from a team. + /// See the official API information. + /// + /// Id of the team to leave. + /// A cancellation token for the request. + /// If the operation succeeded. + Task LeaveTeamAsync(int teamId, CancellationToken cancellationToken = default); + } +} diff --git a/src/PVOutput.Net/Modules/MissingService.cs b/src/PVOutput.Net/Modules/MissingService.cs index dc2b2d2..106c4f9 100644 --- a/src/PVOutput.Net/Modules/MissingService.cs +++ b/src/PVOutput.Net/Modules/MissingService.cs @@ -11,24 +11,15 @@ namespace PVOutput.Net.Modules { - /// - /// The Get Missing service retrieves a list of output dates missing from a system. - /// See the official API information. - /// - public sealed class MissingService : BaseService + /// + public sealed class MissingService : BaseService, IMissingService { internal MissingService(PVOutputClient client) : base(client) { } - /// - /// Retrieves a list of output dates with no data - /// - /// Minimum date for the requested range. - /// Maximum date for the requested range. - /// A cancellation token for the request. - /// List of missing dates + /// public Task> GetMissingDaysInPeriodAsync(DateTime fromDate, DateTime toDate, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() diff --git a/src/PVOutput.Net/Modules/NotificationService.cs b/src/PVOutput.Net/Modules/NotificationService.cs index 9b9c67d..5ba2d79 100644 --- a/src/PVOutput.Net/Modules/NotificationService.cs +++ b/src/PVOutput.Net/Modules/NotificationService.cs @@ -1,11 +1,8 @@ using System; using System.Collections.Generic; -using System.Runtime.CompilerServices; using System.Threading; using System.Threading.Tasks; using Dawn; -using PVOutput.Net.Builders; -using PVOutput.Net.Objects; using PVOutput.Net.Objects.Core; using PVOutput.Net.Requests.Handler; using PVOutput.Net.Requests.Modules; @@ -13,11 +10,8 @@ namespace PVOutput.Net.Modules { - /// - /// The Notification service enables (de-)registering alert notifications. - /// See the official API information. - /// - public sealed class NotificationService : BaseService + /// + public sealed class NotificationService : BaseService, INotificationService { /// /// Alert for a new private message. @@ -103,14 +97,7 @@ internal NotificationService(PVOutputClient client) : base(client) { } - /// - /// Registers an application for a notification. - /// - /// ApplicationId to register the notification under. - /// The url that should get called for each notification. - /// A specific type of alert to send, leave empty for all alert types. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task RegisterNotificationAsync(string applicationId, string callbackUrl, int? alertType = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -130,14 +117,7 @@ public Task RegisterNotificationAsync(string applicationI } - /// - /// Registers an application for a notification. - /// - /// ApplicationId to register the notification under. - /// The uri that should get called for each notification. - /// A specific type of alert to send, leave empty for all alert types. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task RegisterNotificationAsync(string applicationId, Uri callbackUri, int? alertType = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -157,13 +137,7 @@ public Task RegisterNotificationAsync(string applicationI return handler.ExecutePostRequestAsync(new RegisterNotificationRequest() { ApplicationId = applicationId, CallbackUri = callbackUri, AlertType = alertType }, loggingScope, cancellationToken); } - /// - /// Deregisters an application for a notification. - /// - /// ApplicationId to register the notification under. - /// A specific type of alert to send, leave empty for all alert types. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task DeregisterNotificationAsync(string applicationId, int? alertType = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() diff --git a/src/PVOutput.Net/Modules/OutputService.cs b/src/PVOutput.Net/Modules/OutputService.cs index cb8ee93..85406ab 100644 --- a/src/PVOutput.Net/Modules/OutputService.cs +++ b/src/PVOutput.Net/Modules/OutputService.cs @@ -3,7 +3,6 @@ using System.Threading; using System.Threading.Tasks; using Dawn; -using PVOutput.Net.Builders; using PVOutput.Net.Enums; using PVOutput.Net.Objects; using PVOutput.Net.Objects.Core; @@ -13,24 +12,14 @@ namespace PVOutput.Net.Modules { - /// - /// The Output service handles daily output information for individual systems. - /// See the official API information. - /// - public sealed class OutputService : BaseService + /// + public sealed class OutputService : BaseService, IOutputService { internal OutputService(PVOutputClient client) : base(client) { } - /// - /// Retrieve daily output for a date. - /// - /// Date to retrieve the output for. - /// Also retrieve insolation information. Note: this is a donation only parameter. - /// Retrieve output for a specific system. Note: this is a donation only parameter. - /// A cancellation token for the request. - /// Output for the requested date. + /// public Task> GetOutputForDateAsync(DateTime date, bool getInsolation = false, int? systemId = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -47,15 +36,7 @@ public Task> GetOutputForDateAsync(DateTime date, bool return handler.ExecuteSingleItemRequestAsync(new OutputRequest { FromDate = date, ToDate = date, SystemId = systemId, Insolation = getInsolation }, loggingScope, cancellationToken); } - /// - /// Retrieve daily outputs for a period. - /// - /// Minimum date for the requested range. - /// Maximum date for the requested range. - /// Also retrieve insolation information. Note: this is a donation only parameter. - /// Retrieve output for a specific system. Note: this is a donation only parameter. - /// A cancellation token for the request. - /// Outputs for the requested period. + /// public Task> GetOutputsForPeriodAsync(DateTime fromDate, DateTime toDate, bool getInsolation = false, int? systemId = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -74,13 +55,7 @@ public Task> GetOutputsForPeriodAsync(DateTime fr return handler.ExecuteArrayRequestAsync(new OutputRequest { FromDate = fromDate, ToDate = toDate, SystemId = systemId, Insolation = getInsolation }, loggingScope, cancellationToken); } - /// - /// Retrieve daily output for a team. - /// - /// Date to retrieve the output for. - /// Team to retrieve the output for. - /// A cancellation token for the request. - /// Team output for the requested date. + /// public Task> GetTeamOutputForDateAsync(DateTime date, int teamId, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -96,14 +71,7 @@ public Task> GetTeamOutputForDateAsync(DateTime da return handler.ExecuteSingleItemRequestAsync(new OutputRequest { FromDate = date, ToDate = date, TeamId = teamId }, loggingScope, cancellationToken); } - /// - /// Retrieve daily team outputs for a period. - /// - /// Minimum date for the requested range. - /// Maximum date for the requested range. - /// Team to retrieve the output for. - /// A cancellation token for the request. - /// Team outputs Outputs for the requested period. + /// public Task> GetTeamOutputsForPeriodAsync(DateTime fromDate, DateTime toDate, int teamId, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -121,14 +89,7 @@ public Task> GetTeamOutputsForPeriodAsync(Dat return handler.ExecuteArrayRequestAsync(new OutputRequest { FromDate = fromDate, ToDate = toDate, TeamId = teamId }, loggingScope, cancellationToken); } - /// - /// Retrieve aggregated outputs for a period. - /// - /// Minimum DateTime for the requested range. - /// Maximum DateTime for the requested range. - /// Period to aggregate the outputs in. - /// A cancellation token for the request. - /// Aggregated outputs for the requested period. + /// public Task> GetAggregatedOutputsAsync(DateTime fromDate, DateTime toDate, AggregationPeriod period, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -146,14 +107,7 @@ public Task> GetAggregatedOutputsAsync( return handler.ExecuteArrayRequestAsync(new OutputRequest { FromDate = fromDate, ToDate = toDate, Aggregation = period }, loggingScope, cancellationToken); } - /// - /// Adds a single daily output to the owned system. - /// See the official API information. - /// Use the to create objects. - /// - /// The output to add. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task AddOutputAsync(IOutputPost output, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -167,14 +121,7 @@ public Task AddOutputAsync(IOutputPost output, Cancellati return handler.ExecutePostRequestAsync(new AddOutputRequest() { Output = output }, loggingScope, cancellationToken); } - /// - /// Adds a list of outputs to the owned system. - /// See the official API information. - /// Use the to create objects. - /// - /// Outputs to add. 30 outputs is the maximum, 100 for donation - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task AddBatchOutputAsync(IEnumerable outputs, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() diff --git a/src/PVOutput.Net/Modules/SearchService.cs b/src/PVOutput.Net/Modules/SearchService.cs index 6530aaf..3175ad6 100644 --- a/src/PVOutput.Net/Modules/SearchService.cs +++ b/src/PVOutput.Net/Modules/SearchService.cs @@ -1,7 +1,6 @@ using System; using System.Collections.Generic; using System.Globalization; -using System.Text; using System.Threading; using System.Threading.Tasks; using Dawn; @@ -14,25 +13,15 @@ namespace PVOutput.Net.Modules { - /// - /// The Search service retrieves a list of systems matching the given search query. - /// See the official API information. - /// - public sealed class SearchService : BaseService + /// + public sealed class SearchService : BaseService, ISearchService { internal SearchService(PVOutputClient client) : base(client) { } - /// - /// Retrieves a list of systems matching the provided query. - /// See this page for help with the query syntax. - /// - /// A search query to retrieve systems for. - /// A GPS coordinate, used for distance queries. - /// A cancellation token for the request. - /// A list of search results. + /// public Task> SearchAsync(string searchQuery, PVCoordinate? coordinate = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -48,13 +37,7 @@ public Task> SearchAsync(string searc return handler.ExecuteArrayRequestAsync(new SearchRequest { SearchQuery = searchQuery, Coordinate = coordinate }, loggingScope, cancellationToken); } - /// - /// Search for systems by name. - /// - /// Name to search for. - /// If true the name should start with the value. Otherwise the search is performed using a contains method. - /// A cancellation token for the request. - /// A list of search results. + /// public Task> SearchByNameAsync(string name, bool useStartsWith = true, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -72,12 +55,7 @@ public Task> SearchByNameAsync(string return handler.ExecuteArrayRequestAsync(new SearchRequest { SearchQuery = query }, loggingScope, cancellationToken); } - /// - /// Search for systems that have either a postcode or total size that begins with a value. - /// - /// Value to search for. - /// A cancellation token for the request. - /// A list of search results. + /// public Task> SearchByPostcodeOrSizeAsync(int value, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -93,12 +71,7 @@ public Task> SearchByPostcodeOrSizeAs return handler.ExecuteArrayRequestAsync(new SearchRequest { SearchQuery = query }, loggingScope, cancellationToken); } - /// - /// Search for systems by postcode. - /// - /// Postcode to search for. - /// A cancellation token for the request. - /// A list of search results. + /// public Task> SearchByPostcodeAsync(string postcode, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -114,12 +87,7 @@ public Task> SearchByPostcodeAsync(st return handler.ExecuteArrayRequestAsync(new SearchRequest { SearchQuery = searchQuery }, loggingScope, cancellationToken); } - /// - /// Search for systems by size. - /// - /// Size to search for. - /// A cancellation token for the request. - /// A list of search results. + /// public Task> SearchBySizeAsync(int value, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -137,12 +105,7 @@ public Task> SearchBySizeAsync(int va return handler.ExecuteArrayRequestAsync(new SearchRequest { SearchQuery = searchQuery }, loggingScope, cancellationToken); } - /// - /// Search for systems by panel. - /// - /// Panel to search for. - /// A cancellation token for the request. - /// A list of search results. + /// public Task> SearchByPanelAsync(string panel, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -158,13 +121,7 @@ public Task> SearchByPanelAsync(strin return handler.ExecuteArrayRequestAsync(new SearchRequest { SearchQuery = searchQuery }, loggingScope, cancellationToken); } - /// - /// Search for systems by inverter. - /// - /// Inverter to search for. - /// If true the name should start with the value. Otherwise the search is performed using a contains method. - /// A cancellation token for the request. - /// A list of search results. + /// public Task> SearchByInverterAsync(string inverter, bool useStartsWith = true, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -181,14 +138,7 @@ public Task> SearchByInverterAsync(st return handler.ExecuteArrayRequestAsync(new SearchRequest { SearchQuery = searchQuery }, loggingScope, cancellationToken); } - /// - /// Search for systems by distance. - /// - /// Postcode to search from. - /// Distance to search with (25 is the maximum). - /// Country code of the postcode to search in (eg. "nl"). - /// A cancellation token for the request. - /// A list of search results. + /// public Task> SearchByDistanceAsync(int postcode, int kilometers, string countryCode, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -209,13 +159,7 @@ public Task> SearchByDistanceAsync(in return handler.ExecuteArrayRequestAsync(new SearchRequest { SearchQuery = query, CountryCode = countryCode }, loggingScope, cancellationToken); } - /// - /// Search for systems by distance. - /// - /// GPS coordinate to search from. - /// Distance to search with (25 is the maximum). - /// A cancellation token for the request. - /// A list of search results. + /// public Task> SearchByDistanceAsync(PVCoordinate coordinate, int kilometers, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -233,12 +177,7 @@ public Task> SearchByDistanceAsync(PV return handler.ExecuteArrayRequestAsync(new SearchRequest { SearchQuery = query, Coordinate = coordinate }, loggingScope, cancellationToken); } - /// - /// Search for systems by team name. - /// - /// Team name to search for. - /// A cancellation token for the request. - /// A list of search results. + /// public Task> SearchByTeamAsync(string teamName, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -254,14 +193,7 @@ public Task> SearchByTeamAsync(string return handler.ExecuteArrayRequestAsync(new SearchRequest { SearchQuery = searchQuery }, loggingScope, cancellationToken); } - /// - /// Search for systems by orientation. - /// - /// Orientation to search for. - /// Name to search for. - /// If true the name should start with the value. Otherwise the search is performed using a contains method. - /// A cancellation token for the request. - /// A list of search results. + /// public Task> SearchByOrientationAsync(Orientation orientation, string name = null, bool useStartsWith = true, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -284,12 +216,7 @@ public Task> SearchByOrientationAsync return handler.ExecuteArrayRequestAsync(new SearchRequest { SearchQuery = query }, loggingScope, cancellationToken); } - /// - /// Search for systems by tilt. - /// - /// Tilt to search for (should be within 2.5 degrees of this value). - /// A cancellation token for the request. - /// A list of search results. + /// public Task> SearchByTiltAsync(int tilt, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -307,11 +234,7 @@ public Task> SearchByTiltAsync(int ti return handler.ExecuteArrayRequestAsync(new SearchRequest { SearchQuery = searchQuery }, loggingScope, cancellationToken); } - /// - /// Retrieve your favourite systems. - /// - /// A cancellation token for the request. - /// A list of search results. + /// public Task> GetFavouritesAsync(CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() diff --git a/src/PVOutput.Net/Modules/StatisticsService.cs b/src/PVOutput.Net/Modules/StatisticsService.cs index 04dacc5..dd935f6 100644 --- a/src/PVOutput.Net/Modules/StatisticsService.cs +++ b/src/PVOutput.Net/Modules/StatisticsService.cs @@ -11,25 +11,14 @@ namespace PVOutput.Net.Modules { - /// - /// The Get Statistic service retrieves system statistical information. - /// See the official API information. - /// - public sealed class StatisticsService : BaseService + /// + public sealed class StatisticsService : BaseService, IStatisticsService { internal StatisticsService(PVOutputClient client) : base(client) { } - /// - /// Retrieve lifetime statistics for a system. - /// Donation makes it possible to retrieve any system - /// - /// Whether or not to include consumption and import data. System owner only. - /// Whether or not to include credit and debit data. System owner only. - /// Id of the system to retrieve statistical information for. - /// A cancellation token for the request. - /// Lifetime statistical information + /// public Task> GetLifetimeStatisticsAsync(bool includeConsumptionAndImport = false, bool includeCreditDebit = false, int? systemId = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -44,17 +33,7 @@ public Task> GetLifetimeStatisticsAsync(bool includ return handler.ExecuteSingleItemRequestAsync(new StatisticRequest { SystemId = systemId, IncludeConsumptionImport = includeConsumptionAndImport, IncludeCreditDebit = includeCreditDebit }, loggingScope, cancellationToken); } - /// - /// Retrieve lifetime statistics for a system, in a certain period. - /// Donation makes it possible to retrieve any system - /// - /// Minimum date for the requested range. - /// Maximum date for the requested range. - /// Whether or not to include consumption and import data. System owner only. - /// Whether or not to include credit and debit data. System owner only. - /// Id of the system to retrieve statistical information for. - /// A cancellation token for the request. - /// Statistical information for the requested period. + /// public Task> GetStatisticsForPeriodAsync(DateTime fromDate, DateTime toDate, bool includeConsumptionAndImport = false, bool includeCreditDebit = false, int? systemId = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() diff --git a/src/PVOutput.Net/Modules/StatusService.cs b/src/PVOutput.Net/Modules/StatusService.cs index 8953e22..be8b281 100644 --- a/src/PVOutput.Net/Modules/StatusService.cs +++ b/src/PVOutput.Net/Modules/StatusService.cs @@ -3,8 +3,6 @@ using System.Threading; using System.Threading.Tasks; using Dawn; -using PVOutput.Net.Builders; -using PVOutput.Net.Enums; using PVOutput.Net.Objects; using PVOutput.Net.Objects.Core; using PVOutput.Net.Requests.Handler; @@ -13,23 +11,14 @@ namespace PVOutput.Net.Modules { - /// - /// The Status service handles system status information and live output data. - /// See the official API information. - /// - public sealed class StatusService : BaseService + /// + public sealed class StatusService : BaseService, IStatusService { internal StatusService(PVOutputClient client) : base(client) { } - /// - /// Get the system status at a specific moment. - /// - /// Moment to retrieve the system status for. - /// Retrieve status for a specific system. Note: this is a donation only parameter. - /// A cancellation token for the request. - /// Status at the specified moment. + /// public Task> GetStatusForDateTimeAsync(DateTime moment, int? systemId = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -45,17 +34,7 @@ public Task> GetStatusForDateTimeAsync(DateTime moment return handler.ExecuteSingleItemRequestAsync(new GetStatusRequest { Date = moment, SystemId = systemId }, loggingScope, cancellationToken); } - /// - /// Get the status history for a specific period. - /// - /// Minimum datetime for the requested range. - /// Maximum datetime for the requested range. - /// Order the statuses in ascending order instead of descending. - /// Retrieve statuses for a specific system. Note: this is a donation only parameter. - /// Also retrieve extended data. Note: this is a donation only parameter. - /// Limit the number of retrieved statuses. - /// A cancellation token for the request. - /// Statusses for the specified period. + /// public Task> GetHistoryForPeriodAsync(DateTime fromDateTime, DateTime toDateTime, bool ascending = false, int? systemId = null, bool extendedData = false, int? limit = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -76,14 +55,7 @@ public Task> GetHistoryForPeriodAsync(Date new GetStatusRequest { Date = fromDateTime.Date, From = fromDateTime, To = toDateTime, Ascending = ascending, SystemId = systemId, Extended = extendedData, Limit = limit, History = true }, loggingScope, cancellationToken); } - /// - /// Gets the day statistics for specific period. - /// - /// Minimum datetime for the requested range. - /// Maximum datetime for the requested range. - /// Retrieve statuses for a specific system. Note: this is a donation only parameter. - /// A cancellation token for the request. - /// Day statistics for the specified period. + /// public Task> GetDayStatisticsForPeriodAsync(DateTime fromDateTime, DateTime toDateTime, int? systemId = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -100,14 +72,7 @@ public Task> GetDayStatisticsForPeriodAsync(Dat return handler.ExecuteSingleItemRequestAsync(new GetDayStatisticsRequest { Date = fromDateTime.Date, From = fromDateTime, To = toDateTime, SystemId = systemId }, loggingScope, cancellationToken); } - /// - /// Adds a single status to the owned system. - /// See the official API information. - /// Use the to create objects. - /// - /// The status to add. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task AddStatusAsync(IStatusPost status, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -121,14 +86,7 @@ public Task AddStatusAsync(IStatusPost status, Cancellati return handler.ExecutePostRequestAsync(new AddStatusRequest() { StatusPost = status }, loggingScope, cancellationToken); } - /// - /// Adds multiple statuses to the owned system. - /// See the official API information. - /// Use the to create objects. - /// - /// The statuses to add. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task> AddBatchStatusAsync(IEnumerable statuses, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -142,15 +100,7 @@ public Task> AddBatchStatusAsync(I return handler.ExecuteArrayRequestAsync(new AddBatchStatusRequest() { StatusPosts = statuses }, loggingScope, cancellationToken); } - /// - /// Adds multiple statuses to the owned system. - /// See the official API information. - /// Use the to create objects. - /// - /// The statuses to add. - /// Sets whether or not the provided data is cumulative. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task> AddBatchStatusAsync(IEnumerable statuses, bool isCumulative, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -165,14 +115,7 @@ public Task> AddBatchStatusAsync(I return handler.ExecuteArrayRequestAsync(new AddBatchStatusRequest() { StatusPosts = statuses, Cumulative = isCumulative }, loggingScope, cancellationToken); } - /// - /// Adds multiple statuses to the owned system. - /// See the official API information. - /// Use the to create objects. - /// - /// The statuses to add. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task> AddBatchNetStatusAsync(IEnumerable statuses, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -186,13 +129,7 @@ public Task> AddBatchNetStatusAsyn return handler.ExecuteArrayRequestAsync(new AddBatchNetStatusRequest() { StatusPosts = statuses }, loggingScope, cancellationToken); } - /// - /// Deletes a status on the specified moment. - /// See the official API information. - /// - /// The moment to delete the status for. This can only be today or yesterday. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task DeleteStatusAsync(DateTime moment, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -207,13 +144,7 @@ public Task DeleteStatusAsync(DateTime moment, Cancellati return handler.ExecutePostRequestAsync(new DeleteStatusRequest() { Timestamp = moment }, loggingScope, cancellationToken); } - /// - /// Deletes all statuses on the specified date. - /// See the official API information. - /// - /// The date to delete all statuses for. This can only be today or yesterday. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task DeleteAllStatusesOnDateAsync(DateTime date, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() diff --git a/src/PVOutput.Net/Modules/SupplyService.cs b/src/PVOutput.Net/Modules/SupplyService.cs index eb2e894..fc32bac 100644 --- a/src/PVOutput.Net/Modules/SupplyService.cs +++ b/src/PVOutput.Net/Modules/SupplyService.cs @@ -1,6 +1,4 @@ -using System; -using System.Collections.Generic; -using System.Text; +using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; using PVOutput.Net.Objects; @@ -11,24 +9,15 @@ namespace PVOutput.Net.Modules { - /// - /// The Get Supply service displays aggregated live generation and consumption data. - /// See the official API information. - /// - public sealed class SupplyService : BaseService + /// + public sealed class SupplyService : BaseService, ISupplyService { internal SupplyService(PVOutputClient client) : base(client) { } - /// - /// Retrieves live generation and consumption data - /// - /// A timezone identifier in the 'Europe/London' format. Will default to GMT+0 if empty. - /// Region key in the '1:queensland' format. Donation only option. - /// A cancellation token for the request. - /// List of supply information + /// public Task> GetSupplyAsync(string timeZone = null, string regionKey = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() diff --git a/src/PVOutput.Net/Modules/SystemService.cs b/src/PVOutput.Net/Modules/SystemService.cs index 1b0b8fa..9df7e0e 100644 --- a/src/PVOutput.Net/Modules/SystemService.cs +++ b/src/PVOutput.Net/Modules/SystemService.cs @@ -1,9 +1,7 @@ using System.Collections.Generic; -using System.Runtime.CompilerServices; using System.Threading; using System.Threading.Tasks; using Dawn; -using PVOutput.Net.Builders; using PVOutput.Net.Objects; using PVOutput.Net.Objects.Core; using PVOutput.Net.Requests.Handler; @@ -12,21 +10,14 @@ namespace PVOutput.Net.Modules { - /// - /// The Get System service retrieves system information. - /// See the official API information. - /// - public sealed class SystemService : BaseService + /// > + public sealed class SystemService : BaseService, ISystemService { internal SystemService(PVOutputClient client) : base(client) { } - /// - /// Retrieves information for the owned system. - /// - /// A cancellation token for the request. - /// Information of the owned system. + /// public Task> GetOwnSystemAsync(CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -39,13 +30,7 @@ public Task> GetOwnSystemAsync(CancellationToken cance return handler.ExecuteSingleItemRequestAsync(new SystemRequest(), loggingScope, cancellationToken); } - /// - /// Retrieves information for a system. - /// Note: this is a donation only request. - /// - /// Id of the system to request information for - /// A cancellation token for the request. - /// Information of the requested system. + /// public Task> GetOtherSystemAsync(int systemId, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -58,16 +43,7 @@ public Task> GetOtherSystemAsync(int systemId, Cancell return handler.ExecuteSingleItemRequestAsync(new SystemRequest { SystemId = systemId, MonthlyEstimates = false }, loggingScope, cancellationToken); } - /// - /// Updates a system's name or extended data values. - /// Use the to create definition for extended data values. - /// See the official API information. - /// - /// The system to update. - /// A new name for the system. - /// List of modified extended data definitions. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task PostSystem(int systemId, string systemName = null, IEnumerable dataDefinitions = null, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() diff --git a/src/PVOutput.Net/Modules/TeamService.cs b/src/PVOutput.Net/Modules/TeamService.cs index 7f4fdf7..c5db3cf 100644 --- a/src/PVOutput.Net/Modules/TeamService.cs +++ b/src/PVOutput.Net/Modules/TeamService.cs @@ -1,6 +1,4 @@ -using System; -using System.Collections.Generic; -using System.Text; +using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; using PVOutput.Net.Objects; @@ -11,23 +9,14 @@ namespace PVOutput.Net.Modules { - /// - /// The Team service retrieves team information and joins/leaves teams. - /// See the official API information. - /// - public sealed class TeamService : BaseService + /// + public sealed class TeamService : BaseService, ITeamService { internal TeamService(PVOutputClient client) : base(client) { } - /// - /// Retrieves information for a team, that must be owned. - /// Donation makes it possible to retrieve any team. - /// - /// Id of the team to retrieve information for. - /// A cancellation token for the request. - /// Team information. + /// public Task> GetTeamAsync(int teamId, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -40,13 +29,7 @@ public Task> GetTeamAsync(int teamId, CancellationToken return handler.ExecuteSingleItemRequestAsync(new TeamRequest { TeamId = teamId }, loggingScope, cancellationToken); } - /// - /// Adds a system to a team. - /// See the official API information. - /// - /// Id of the team to join. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task JoinTeamAsync(int teamId, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() @@ -59,13 +42,7 @@ public Task JoinTeamAsync(int teamId, CancellationToken c return handler.ExecutePostRequestAsync(new JoinTeamRequest() { TeamId = teamId }, loggingScope, cancellationToken); } - /// - /// Removes a system from a team. - /// See the official API information. - /// - /// Id of the team to leave. - /// A cancellation token for the request. - /// If the operation succeeded. + /// public Task LeaveTeamAsync(int teamId, CancellationToken cancellationToken = default) { var loggingScope = new Dictionary() diff --git a/src/PVOutput.Net/PVOutput.Net.csproj.DotSettings b/src/PVOutput.Net/PVOutput.Net.csproj.DotSettings new file mode 100644 index 0000000..1e066de --- /dev/null +++ b/src/PVOutput.Net/PVOutput.Net.csproj.DotSettings @@ -0,0 +1,2 @@ + + True \ No newline at end of file diff --git a/src/PVOutput.Net/PVOutputClient.cs b/src/PVOutput.Net/PVOutputClient.cs index a35b339..28a099c 100644 --- a/src/PVOutput.Net/PVOutputClient.cs +++ b/src/PVOutput.Net/PVOutputClient.cs @@ -4,14 +4,11 @@ using PVOutput.Net.DependencyInjection; using PVOutput.Net.Modules; using PVOutput.Net.Requests; -using PVOutput.Net.Requests.Handler; namespace PVOutput.Net { - /// - /// The client used to communicate with the PVOutput service. - /// - public sealed class PVOutputClient + /// + public sealed class PVOutputClient : IPVOutputClient { internal const string PVOutputBaseUri = @"https://pvoutput.org/service/r2/"; @@ -41,86 +38,51 @@ internal ILogger Logger } } - /// ApiKey to use with authenticating. + + /// public string ApiKey { get; set; } - /// Id of the currently owned system used for authenticating. + /// public int OwnedSystemId { get; set; } - /// Indicates whether or not the client should throw exceptions when the api returns errors. + /// public bool ThrowResponseExceptions { get; set; } = true; - /// - /// The output service. - /// See the official API information. - /// - public OutputService Output { get; private set; } + /// + public IOutputService Output { get; private set; } - /// - /// The system service. - /// See the official API information. - /// - public SystemService System { get; private set; } + /// + public ISystemService System { get; private set; } - /// - /// The status service. - /// See the official API information. - /// - public StatusService Status { get; private set; } + /// + public IStatusService Status { get; private set; } - /// - /// The statistic service. - /// See the official API information. - /// - public StatisticsService Statistics { get; private set; } + /// + public IStatisticsService Statistics { get; private set; } - /// - /// The missing service. - /// See the official API information. - /// - public MissingService Missing { get; private set; } + /// + public IMissingService Missing { get; private set; } - /// - /// The team service. - /// See the official API information. - /// - public TeamService Team { get; private set; } + /// + public ITeamService Team { get; private set; } - /// - /// The extended service. - /// See the official API information. - /// - public ExtendedService Extended { get; private set; } + /// + public IExtendedService Extended { get; private set; } - /// - /// The favourite service. - /// See the official API information. - /// - public FavouriteService Favourite { get; private set; } + /// + public IFavouriteService Favourite { get; private set; } - /// - /// The insolation service. - /// See the official API information. - /// - public InsolationService Insolation { get; private set; } + /// + public IInsolationService Insolation { get; private set; } - /// - /// The supply service. - /// See the official API information. - /// - public SupplyService Supply { get; private set; } + /// + public ISupplyService Supply { get; private set; } - /// - /// The search service - /// See the official API information. - /// - public SearchService Search { get; private set; } + /// + public ISearchService Search { get; private set; } - /// - /// The notification service - /// See the official API information. - /// - public NotificationService Notification { get; private set; } + /// + public INotificationService Notification { get; private set; } /// /// Creates a new PVOutputClient. diff --git a/tests/PVOutput.Net.Tests/Modules/Search/SearchServiceTests.cs b/tests/PVOutput.Net.Tests/Modules/Search/SearchServiceTests.cs index b1bd093..f015547 100644 --- a/tests/PVOutput.Net.Tests/Modules/Search/SearchServiceTests.cs +++ b/tests/PVOutput.Net.Tests/Modules/Search/SearchServiceTests.cs @@ -159,7 +159,7 @@ public async Task SearchService_SearchByDistanceWithCoordinate_CallsCorrectUri() AssertStandardResponse(response); } - private async Task TestSpecificSearchQuery(Func>> searchQuery, string queryStringResult) + private async Task TestSpecificSearchQuery(Func>> searchQuery, string queryStringResult) { PVOutputClient client = TestUtility.GetMockClient(out MockHttpMessageHandler testProvider); testProvider.ExpectUriFromBase(SEARCH_URL)