feat(billing): switch asset usage endpoint to limit offset pagination DEV-987

jsapp/js/api/models/assetUsageListParams.ts

@@ -12,11 +12,11 @@ The endpoints are grouped by area of intended use. Each category contains relate
 
 export type AssetUsageListParams = {
   /**
-   * A page number within the paginated result set.
+   * Number of results to return per page.
    */
-  page?: number
+  limit?: number
   /**
-   * Number of results to return per page.
+   * The initial index from which to return the results.
    */
-  page_size?: number
+  offset?: number
 }

jsapp/js/api/models/organizationAssetUsageResponse.ts → jsapp/js/api/models/customAssetUsage.ts

@@ -1,4 +1,4 @@
-import type { OrganizationAssetUsageResponseNlpUsageAllTime } from './organizationAssetUsageResponseNlpUsageAllTime'
+import type { DeploymentStatusEnum } from './deploymentStatusEnum'
 /**
  * Generated by orval v7.10.0 🍺
  * Do not edit manually.
@@ -10,15 +10,15 @@ The endpoints are grouped by area of intended use. Each category contains relate
 **General note**: All projects (whether deployed or draft), as well as all library content (questions, blocks, templates, and collections) in the user-facing application are represented in the API as "assets".
  * OpenAPI spec version: 2.0.0 (api_v2)
  */
-import type { OrganizationAssetUsageResponseNlpUsageCurrentPeriod } from './organizationAssetUsageResponseNlpUsageCurrentPeriod'
+import type { NlpUsage } from './nlpUsage'
 
-export interface OrganizationAssetUsageResponse {
-  asset: string
-  asset__name: string
-  nlp_usage_current_period: OrganizationAssetUsageResponseNlpUsageCurrentPeriod
-  nlp_usage_all_time: OrganizationAssetUsageResponseNlpUsageAllTime
-  storage_bytes: number
-  submission_count_current_period: number
-  submission_count_all_time: number
-  deployment_status: string
+export interface CustomAssetUsage {
+  readonly asset: string
+  readonly asset__name: string
+  readonly nlp_usage_current_period: NlpUsage
+  readonly nlp_usage_all_time: NlpUsage
+  readonly storage_bytes: number
+  readonly submission_count_current_period: number
+  readonly submission_count_all_time: number
+  readonly deployment_status: DeploymentStatusEnum
 }

jsapp/js/api/models/deploymentStatusEnum.ts

@@ -0,0 +1,25 @@
+/**
+ * Generated by orval v7.10.0 🍺
+ * Do not edit manually.
+ * KoboToolbox Primary API
+ * This page documents all KoboToolbox API endpoints, except for those implementing the OpenRosa protocol, which are [documented separately](/api/openrosa/docs/).
+
+The endpoints are grouped by area of intended use. Each category contains related endpoints, with detailed documentation on usage and configuration. Use this as a reference to quickly find the right endpoint for managing projects, forms, data, permissions, integrations, logs, and organizational resources.
+
+**General note**: All projects (whether deployed or draft), as well as all library content (questions, blocks, templates, and collections) in the user-facing application are represented in the API as "assets".
+ * OpenAPI spec version: 2.0.0 (api_v2)
+ */
+
+/**
+ * * `archived` - archived
+ * `deployed` - deployed
+ * `draft` - draft
+ */
+export type DeploymentStatusEnum = (typeof DeploymentStatusEnum)[keyof typeof DeploymentStatusEnum]
+
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const DeploymentStatusEnum = {
+  archived: 'archived',
+  deployed: 'deployed',
+  draft: 'draft',
+} as const

jsapp/js/api/models/organizationAssetUsageResponseNlpUsageAllTime.ts → jsapp/js/api/models/nlpUsage.ts

@@ -10,7 +10,7 @@ The endpoints are grouped by area of intended use. Each category contains relate
  * OpenAPI spec version: 2.0.0 (api_v2)
  */
 
-export type OrganizationAssetUsageResponseNlpUsageAllTime = {
+export interface NlpUsage {
   total_nlp_asr_seconds: number
   total_nlp_mt_characters: number
 }

jsapp/js/api/models/organizationAssetUsageResponseNlpUsageCurrentPeriod.ts → jsapp/js/api/models/organizationsAssetUsageListParams.ts

@@ -10,7 +10,13 @@ The endpoints are grouped by area of intended use. Each category contains relate
  * OpenAPI spec version: 2.0.0 (api_v2)
  */
 
-export type OrganizationAssetUsageResponseNlpUsageCurrentPeriod = {
-  total_nlp_asr_seconds: number
-  total_nlp_mt_characters: number
+export type OrganizationsAssetUsageListParams = {
+  /**
+   * Paginate results with limit parameter
+   */
+  limit?: number
+  /**
+   * Paginate results with offset parameter
+   */
+  offset?: number
 }

jsapp/js/api/models/paginatedOrganizationAssetUsageResponseList.ts → jsapp/js/api/models/paginatedCustomAssetUsageList.ts

@@ -9,13 +9,13 @@ The endpoints are grouped by area of intended use. Each category contains relate
 **General note**: All projects (whether deployed or draft), as well as all library content (questions, blocks, templates, and collections) in the user-facing application are represented in the API as "assets".
  * OpenAPI spec version: 2.0.0 (api_v2)
  */
-import type { OrganizationAssetUsageResponse } from './organizationAssetUsageResponse'
+import type { CustomAssetUsage } from './customAssetUsage'
 
-export interface PaginatedOrganizationAssetUsageResponseList {
+export interface PaginatedCustomAssetUsageList {
   count: number
   /** @nullable */
   next?: string | null
   /** @nullable */
   previous?: string | null
-  results: OrganizationAssetUsageResponse[]
+  results: CustomAssetUsage[]
 }

jsapp/js/api/react-query/user-team-organization-usage.ts

@@ -47,6 +47,8 @@ import type { OrganizationResponse } from '../models/organizationResponse'
 
 import type { OrganizationServiceUsageResponse } from '../models/organizationServiceUsageResponse'
 
+import type { OrganizationsAssetUsageListParams } from '../models/organizationsAssetUsageListParams'
+
 import type { OrganizationsInvitesListParams } from '../models/organizationsInvitesListParams'
 
 import type { OrganizationsListParams } from '../models/organizationsListParams'
@@ -57,14 +59,14 @@ import type { PaginatedAssetList } from '../models/paginatedAssetList'
 
 import type { PaginatedAssetUsageResponseList } from '../models/paginatedAssetUsageResponseList'
 
+import type { PaginatedCustomAssetUsageList } from '../models/paginatedCustomAssetUsageList'
+
 import type { PaginatedEmailAddressList } from '../models/paginatedEmailAddressList'
 
 import type { PaginatedInviteResponseList } from '../models/paginatedInviteResponseList'
 
 import type { PaginatedMemberListResponseList } from '../models/paginatedMemberListResponseList'
 
-import type { PaginatedOrganizationAssetUsageResponseList } from '../models/paginatedOrganizationAssetUsageResponseList'
-
 import type { PaginatedOrganizationResponseList } from '../models/paginatedOrganizationResponseList'
 
 import type { PaginatedProjectViewAssetResponseList } from '../models/paginatedProjectViewAssetResponseList'
@@ -495,85 +497,106 @@ export const useOrganizationsPartialUpdate = <TError = ErrorObject | ErrorDetail
 Tracks the total usage of each asset for the user in the given organization
 
  */
-export type organizationsAssetUsageRetrieveResponse200 = {
-  data: PaginatedOrganizationAssetUsageResponseList
+export type organizationsAssetUsageListResponse200 = {
+  data: PaginatedCustomAssetUsageList
   status: 200
 }
 
-export type organizationsAssetUsageRetrieveResponse404 = {
+export type organizationsAssetUsageListResponse404 = {
   data: ErrorDetail
   status: 404
 }
 
-export type organizationsAssetUsageRetrieveResponseComposite =
-  | organizationsAssetUsageRetrieveResponse200
-  | organizationsAssetUsageRetrieveResponse404
+export type organizationsAssetUsageListResponseComposite =
+  | organizationsAssetUsageListResponse200
+  | organizationsAssetUsageListResponse404
 
-export type organizationsAssetUsageRetrieveResponse = organizationsAssetUsageRetrieveResponseComposite & {
+export type organizationsAssetUsageListResponse = organizationsAssetUsageListResponseComposite & {
   headers: Headers
 }
 
-export const getOrganizationsAssetUsageRetrieveUrl = (uidOrganization: string) => {
-  return `/api/v2/organizations/${uidOrganization}/asset_usage/`
+export const getOrganizationsAssetUsageListUrl = (
+  uidOrganization: string,
+  params?: OrganizationsAssetUsageListParams,
+) => {
+  const normalizedParams = new URLSearchParams()
+
+  Object.entries(params || {}).forEach(([key, value]) => {
+    if (value !== undefined) {
+      normalizedParams.append(key, value === null ? 'null' : value.toString())
+    }
+  })
+
+  const stringifiedParams = normalizedParams.toString()
+
+  return stringifiedParams.length > 0
+    ? `/api/v2/organizations/${uidOrganization}/asset_usage/?${stringifiedParams}`
+    : `/api/v2/organizations/${uidOrganization}/asset_usage/`
 }
 
-export const organizationsAssetUsageRetrieve = async (
+export const organizationsAssetUsageList = async (
   uidOrganization: string,
+  params?: OrganizationsAssetUsageListParams,
   options?: RequestInit,
-): Promise<organizationsAssetUsageRetrieveResponse> => {
-  return fetchWithAuth<organizationsAssetUsageRetrieveResponse>(
-    getOrganizationsAssetUsageRetrieveUrl(uidOrganization),
+): Promise<organizationsAssetUsageListResponse> => {
+  return fetchWithAuth<organizationsAssetUsageListResponse>(
+    getOrganizationsAssetUsageListUrl(uidOrganization, params),
     {
       ...options,
       method: 'GET',
     },
   )
 }
 
-export const getOrganizationsAssetUsageRetrieveQueryKey = (uidOrganization: string) => {
-  return ['api', 'v2', 'organizations', uidOrganization, 'asset_usage'] as const
+export const getOrganizationsAssetUsageListQueryKey = (
+  uidOrganization: string,
+  params?: OrganizationsAssetUsageListParams,
+) => {
+  return ['api', 'v2', 'organizations', uidOrganization, 'asset_usage', ...(params ? [params] : [])] as const
 }
 
-export const getOrganizationsAssetUsageRetrieveQueryOptions = <
-  TData = Awaited<ReturnType<typeof organizationsAssetUsageRetrieve>>,
+export const getOrganizationsAssetUsageListQueryOptions = <
+  TData = Awaited<ReturnType<typeof organizationsAssetUsageList>>,
   TError = ErrorDetail,
 >(
   uidOrganization: string,
+  params?: OrganizationsAssetUsageListParams,
   options?: {
-    query?: UseQueryOptions<Awaited<ReturnType<typeof organizationsAssetUsageRetrieve>>, TError, TData>
+    query?: UseQueryOptions<Awaited<ReturnType<typeof organizationsAssetUsageList>>, TError, TData>
     request?: SecondParameter<typeof fetchWithAuth>
   },
 ) => {
   const { query: queryOptions, request: requestOptions } = options ?? {}
 
-  const queryKey = queryOptions?.queryKey ?? getOrganizationsAssetUsageRetrieveQueryKey(uidOrganization)
+  const queryKey = queryOptions?.queryKey ?? getOrganizationsAssetUsageListQueryKey(uidOrganization, params)
 
-  const queryFn: QueryFunction<Awaited<ReturnType<typeof organizationsAssetUsageRetrieve>>> = ({ signal }) =>
-    organizationsAssetUsageRetrieve(uidOrganization, { signal, ...requestOptions })
+  const queryFn: QueryFunction<Awaited<ReturnType<typeof organizationsAssetUsageList>>> = ({ signal }) =>
+    organizationsAssetUsageList(uidOrganization, params, { signal, ...requestOptions })
 
   return { queryKey, queryFn, enabled: !!uidOrganization, ...queryOptions } as UseQueryOptions<
-    Awaited<ReturnType<typeof organizationsAssetUsageRetrieve>>,
+    Awaited<ReturnType<typeof organizationsAssetUsageList>>,
     TError,
     TData
   > & { queryKey: QueryKey }
 }
 
-export type OrganizationsAssetUsageRetrieveQueryResult = NonNullable<
-  Awaited<ReturnType<typeof organizationsAssetUsageRetrieve>>
+export type OrganizationsAssetUsageListQueryResult = NonNullable<
+  Awaited<ReturnType<typeof organizationsAssetUsageList>>
 >
-export type OrganizationsAssetUsageRetrieveQueryError = ErrorDetail
+export type OrganizationsAssetUsageListQueryError = ErrorDetail
 
-export function useOrganizationsAssetUsageRetrieve<
-  TData = Awaited<ReturnType<typeof organizationsAssetUsageRetrieve>>,
+export function useOrganizationsAssetUsageList<
+  TData = Awaited<ReturnType<typeof organizationsAssetUsageList>>,
   TError = ErrorDetail,
 >(
   uidOrganization: string,
+  params?: OrganizationsAssetUsageListParams,
   options?: {
-    query?: UseQueryOptions<Awaited<ReturnType<typeof organizationsAssetUsageRetrieve>>, TError, TData>
+    query?: UseQueryOptions<Awaited<ReturnType<typeof organizationsAssetUsageList>>, TError, TData>
     request?: SecondParameter<typeof fetchWithAuth>
   },
 ): UseQueryResult<TData, TError> & { queryKey: QueryKey } {
-  const queryOptions = getOrganizationsAssetUsageRetrieveQueryOptions(uidOrganization, options)
+  const queryOptions = getOrganizationsAssetUsageListQueryOptions(uidOrganization, params, options)
 
   const query = useQuery(queryOptions) as UseQueryResult<TData, TError> & { queryKey: QueryKey }
 

kobo/apps/organizations/views.py

@@ -32,7 +32,6 @@
     MemberPatchRequest,
 )
 from kpi.schema_extensions.v2.organizations.serializers import (
-    OrganizationAssetUsageResponse,
     OrganizationPatchPayload,
     OrganizationServiceUsageResponse,
 )
@@ -144,11 +143,28 @@ def get_queryset(self, *args, **kwargs):
     asset_usage=extend_schema(
         description=read_md('kpi', 'organizations/org_asset_usage.md'),
         responses=open_api_200_ok_response(
-            OrganizationAssetUsageResponse(many=True),
+            CustomAssetUsageSerializer(many=True),
             require_auth=False,
             raise_access_forbidden=False,
             validate_payload=False,
         ),
+        parameters=[
+            OpenApiParameter(
+                name='offset',
+                type=int,
+                location=OpenApiParameter.QUERY,
+                required=False,
+                description='Paginate results with offset parameter',
+            ),
+            OpenApiParameter(
+                name='limit',
+                type=int,
+                location=OpenApiParameter.QUERY,
+                required=False,
+                description='Paginate results with limit parameter',
+            ),
+        ],
+        operation_id='api_v2_organizations_asset_usage_list',
     ),
     assets=extend_schema(
         description=read_md('kpi', 'organizations/org_assets.md'),

kpi/paginators.py

@@ -119,14 +119,6 @@ def get_paginated_response_schema(self, schema):
         }
 
 
-class AssetUsagePagination(PageNumberPagination):
-    """
-    Pagination class for usage project breakdown table.
-    """
-    page_size = 8
-    page_size_query_param = 'page_size'
-
-
 class DataPagination(LimitOffsetPagination):
     """
     Pagination class for submissions.

kpi/schema_extensions/v2/organizations/serializers.py

@@ -2,29 +2,8 @@
 
 from kobo.apps.organizations.models import OrganizationType
 from kpi.utils.schema_extensions.serializers import inline_serializer_class
-from .fields import (
-    AssetField,
-    NlpUsageAllTime,
-    NlpUsageCurrentPeriod,
-    TotalNlpUsageField,
-    TotalSubmissionCountField,
-)
 from ..service_usage.fields import BalancesField
-
-OrganizationAssetUsageResponse = inline_serializer_class(
-    name='OrganizationAssetUsageResponse',
-    fields={
-        'asset': AssetField(),
-        'asset__name': serializers.CharField(),
-        'nlp_usage_current_period': NlpUsageCurrentPeriod(),
-        'nlp_usage_all_time': NlpUsageAllTime(),
-        'storage_bytes': serializers.IntegerField(),
-        'submission_count_current_period': serializers.IntegerField(),
-        'submission_count_all_time': serializers.IntegerField(),
-        'deployment_status': serializers.CharField(),
-    },
-)
-
+from .fields import TotalNlpUsageField, TotalSubmissionCountField
 
 OrganizationServiceUsageResponse = inline_serializer_class(
     name='OrganizationServiceUsageResponse',