feat(api): add usage analytics breakdown endpoint

Stainless-Generated-From: d6ccc6a

Author: manu4543

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 47
+configured_endpoints: 48

src/Accounts/Usage/UsageGetParams.php

@@ -12,6 +12,10 @@
 /**
  * Get the account usage information between two dates. Note that the API response includes data from the start date while excluding data from the end date. In other words, the data covers the period starting from the specified start date up to, but not including, the end date.
  *
+ * For an agency account, the returned usage is aggregated across the agency and all of its child accounts that are billed to it.
+ *
+ * The response is cached for 6 hours per account, date range and requested metrics.
+ *
  * @see ImageKit\Services\Accounts\UsageService::get()
  *
  * @phpstan-type UsageGetParamsShape = array{endDate: string, startDate: string}

src/Accounts/UsageAnalytics/RequestBandwidthEntry.php

@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ImageKit\Accounts\UsageAnalytics;
+
+use ImageKit\Core\Attributes\Required;
+use ImageKit\Core\Concerns\SdkModel;
+use ImageKit\Core\Contracts\BaseModel;
+
+/**
+ * @phpstan-type RequestBandwidthEntryShape = array{
+ *   bandwidthBytes: float, requestCount: float
+ * }
+ */
+final class RequestBandwidthEntry implements BaseModel
+{
+    /** @use SdkModel<RequestBandwidthEntryShape> */
+    use SdkModel;
+
+    /**
+     * Total bandwidth used in bytes.
+     */
+    #[Required]
+    public float $bandwidthBytes;
+
+    /**
+     * Number of requests.
+     */
+    #[Required]
+    public float $requestCount;
+
+    /**
+     * `new RequestBandwidthEntry()` is missing required properties by the API.
+     *
+     * To enforce required parameters use
+     * ```
+     * RequestBandwidthEntry::with(bandwidthBytes: ..., requestCount: ...)
+     * ```
+     *
+     * Otherwise ensure the following setters are called
+     *
+     * ```
+     * (new RequestBandwidthEntry)->withBandwidthBytes(...)->withRequestCount(...)
+     * ```
+     */
+    public function __construct()
+    {
+        $this->initialize();
+    }
+
+    /**
+     * Construct an instance from the required parameters.
+     *
+     * You must use named parameters to construct any parameters with a default value.
+     */
+    public static function with(
+        float $bandwidthBytes,
+        float $requestCount
+    ): self {
+        $self = new self;
+
+        $self['bandwidthBytes'] = $bandwidthBytes;
+        $self['requestCount'] = $requestCount;
+
+        return $self;
+    }
+
+    /**
+     * Total bandwidth used in bytes.
+     */
+    public function withBandwidthBytes(float $bandwidthBytes): self
+    {
+        $self = clone $this;
+        $self['bandwidthBytes'] = $bandwidthBytes;
+
+        return $self;
+    }
+
+    /**
+     * Number of requests.
+     */
+    public function withRequestCount(float $requestCount): self
+    {
+        $self = clone $this;
+        $self['requestCount'] = $requestCount;
+
+        return $self;
+    }
+}

src/Accounts/UsageAnalytics/UsageAnalyticsGetParams.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ImageKit\Accounts\UsageAnalytics;
+
+use ImageKit\Core\Attributes\Required;
+use ImageKit\Core\Concerns\SdkModel;
+use ImageKit\Core\Concerns\SdkParams;
+use ImageKit\Core\Contracts\BaseModel;
+
+/**
+ * **Note:** This API is currently in beta.
+ *
+ * Get the account analytics data between two dates. The response covers the period from the start date to the end date, both dates inclusive. Both dates are interpreted as UTC calendar days.
+ *
+ * The returned data is scoped to the requesting account only. Unlike `/v1/accounts/usage`, an agency account's analytics are not aggregated across its child accounts.
+ *
+ * The response is cached for 5 minutes per account and date range. Use `generatedAt` to check how fresh the returned data is.
+ *
+ * @see ImageKit\Services\Accounts\UsageAnalyticsService::get()
+ *
+ * @phpstan-type UsageAnalyticsGetParamsShape = array{
+ *   endDate: string, startDate: string
+ * }
+ */
+final class UsageAnalyticsGetParams implements BaseModel
+{
+    /** @use SdkModel<UsageAnalyticsGetParamsShape> */
+    use SdkModel;
+    use SdkParams;
+
+    /**
+     * Specify an `endDate` in `YYYY-MM-DD` format, interpreted as a UTC calendar day. It should be after the `startDate`. The difference between `startDate` and `endDate` should be less than 90 days.
+     */
+    #[Required]
+    public string $endDate;
+
+    /**
+     * Specify a `startDate` in `YYYY-MM-DD` format, interpreted as a UTC calendar day. It should be before the `endDate`. The difference between `startDate` and `endDate` should be less than 90 days.
+     */
+    #[Required]
+    public string $startDate;
+
+    /**
+     * `new UsageAnalyticsGetParams()` is missing required properties by the API.
+     *
+     * To enforce required parameters use
+     * ```
+     * UsageAnalyticsGetParams::with(endDate: ..., startDate: ...)
+     * ```
+     *
+     * Otherwise ensure the following setters are called
+     *
+     * ```
+     * (new UsageAnalyticsGetParams)->withEndDate(...)->withStartDate(...)
+     * ```
+     */
+    public function __construct()
+    {
+        $this->initialize();
+    }
+
+    /**
+     * Construct an instance from the required parameters.
+     *
+     * You must use named parameters to construct any parameters with a default value.
+     */
+    public static function with(string $endDate, string $startDate): self
+    {
+        $self = new self;
+
+        $self['endDate'] = $endDate;
+        $self['startDate'] = $startDate;
+
+        return $self;
+    }
+
+    /**
+     * Specify an `endDate` in `YYYY-MM-DD` format, interpreted as a UTC calendar day. It should be after the `startDate`. The difference between `startDate` and `endDate` should be less than 90 days.
+     */
+    public function withEndDate(string $endDate): self
+    {
+        $self = clone $this;
+        $self['endDate'] = $endDate;
+
+        return $self;
+    }
+
+    /**
+     * Specify a `startDate` in `YYYY-MM-DD` format, interpreted as a UTC calendar day. It should be before the `endDate`. The difference between `startDate` and `endDate` should be less than 90 days.
+     */
+    public function withStartDate(string $startDate): self
+    {
+        $self = clone $this;
+        $self['startDate'] = $startDate;
+
+        return $self;
+    }
+}