@autobusal/admin-api-consumers 1.0.0 → 1.2.0

package/Browse.tsx

@@ -1,6 +1,6 @@
 import { TFunction } from 'i18next';
-import { useSearchParams } from 'react-router-dom';
-import { Meta, Table, Row } from '@autobusal/common';
+import { Link, useSearchParams } from 'react-router-dom';
+import { Meta, Table, Row, Button } from '@autobusal/common';
 import { usePage, useBreadcrumbs } from '@autobusal/hooks';
 import { DisplayStatus, getParams, success } from '@autobusal/utilities';
 import { useGetApiConsumers, useDeleteApiConsumer } from './services';
@@ -80,8 +80,13 @@ const Browse = ({ url, t }: Props): JSX.Element => {
         fetching={ isFetching }
         t={ t }
         actions={ [
-          'create', 'search', 'view', 'delete'
+          'create', 'search', 'extra', 'view', 'delete'
         ] }
+        extra={
+          <Link to={ `${ url }/receivables` }>
+            <Button type="button" size="medium" subtype="secondary" noMargin text={ t('admin_api_consumers.receivables.title', { ns: 'common' }) } />
+          </Link>
+        }
         handlers={ {
           delete: onDelete
         } }

package/CHANGELOG.md

@@ -1,9 +1,37 @@
 # Changelog
 
+## 1.2.0
+
+### Added
+
+- **Credit limit on the partner form, running balance on receivables.** A
+  Mode 1 partner now sells against a running account (obtapi Payments\
+  External\Charge): every sale debits the net they owe, cancellations
+  credit it back, and recorded settlements raise it. `credit_limit` is the
+  floor - 0 means prepaid (deposit before selling), a positive number means
+  postpaid down to -that-much. The receivables table shows the live
+  `balance` and `headroom` alongside the statement figures, deliberately
+  from two books: when they disagree, something needs investigating.
+
 All notable changes to `@autobusal/admin-api-consumers` are documented here.
 This project adheres to [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-07-27
+
+### Added
+
+- Package 3 of the external-routes plan: **receivables reports + settlements**.
+  `Receivables.tsx` is a per-partner dashboard for a selectable period
+  (orders/tickets/gross amount/commission/net/settled/outstanding, the
+  last two accumulated all-time regardless of the period filter).
+  `ReceivablesManage.tsx` is the per-partner drill-down (ticket-level order
+  rows, doubling as the CSV/dispute document via a plain browser-download
+  link to the backend export endpoint - no frontend CSV generation, same
+  convention as `@autobusal/account-reports`), plus a settlements section
+  to record/list/delete actual payments received. Backed by obtapi's
+  `App\Http\Controllers\ApiConsumers\ReportsController`.
+
 ## [1.0.0] - 2026-07-27
 
 ### Added

package/Manage.tsx

@@ -131,6 +131,16 @@ const Manage = ({ url, t }: Props): JSX.Element => {
           type: 'select',
           value: data?.user.comissions?.unique ?? 0,
           values: getAllowed(t)
+        }, {
+          // Claude - 2026-08-22: the floor of the partner's running
+          // account. 0 = prepaid (they deposit before they can sell);
+          // a positive number = postpaid down to -that-much. "Unlimited"
+          // is a big number typed on purpose, never a switch.
+          label: t('admin_api_consumers.manage.credit_limit', { ns: 'common' }),
+          name: 'credit_limit',
+          type: 'text',
+          value: data?.credit_limit ?? 0,
+          rules: 'required|numeric'
         }, {
           label: t('admin_api_consumers.manage.status', { ns: 'common' }),
           name: 'status',

package/Receivables.tsx

@@ -0,0 +1,96 @@
+import { useState } from 'react';
+import { TFunction } from 'i18next';
+import { Link } from 'react-router-dom';
+import { Meta, Box } from '@autobusal/common';
+import { usePage, useBreadcrumbs } from '@autobusal/hooks';
+import { Table, Filters } from './styles';
+import { useGetReceivables } from './services';
+
+interface Props {
+  url: string
+  t: TFunction<'common'>
+}
+
+const Receivables = ({ url, t }: Props): JSX.Element => {
+  usePage('api_consumers');
+
+  useBreadcrumbs(t('admin_api_consumers.receivables.title', { ns: 'common' }), [{ name: t('admin_api_consumers.browse.title', { ns: 'common' }), url }]);
+
+  const [ from, setFrom ] = useState<string>('');
+  const [ to, setTo ] = useState<string>('');
+
+  const { data, isLoading } = useGetReceivables({ from: from || undefined, to: to || undefined });
+
+  return (
+    <Meta title={ t('admin_api_consumers.receivables.title', { ns: 'common' }) }>
+      <h1>{ t('admin_api_consumers.receivables.title', { ns: 'common' }) }</h1>
+
+      <Filters>
+        <div>
+          <label>{ t('admin_api_consumers.receivables.from', { ns: 'common' }) }</label>
+          <input type="date" value={ from } onChange={ (e) => setFrom(e.target.value) } />
+        </div>
+
+        <div>
+          <label>{ t('admin_api_consumers.receivables.to', { ns: 'common' }) }</label>
+          <input type="date" value={ to } onChange={ (e) => setTo(e.target.value) } />
+        </div>
+      </Filters>
+
+      { isLoading ? <Box /> : (
+        <div className="box">
+          <Table>
+            <thead>
+              <tr>
+                <th>{ t('admin_api_consumers.receivables.company', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.orders', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.tickets', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.amount', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.commission', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.net', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.settled', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.outstanding', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.balance', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.headroom', { ns: 'common' }) }</th>
+                <th />
+              </tr>
+            </thead>
+
+            <tbody>
+              { data?.map(row => (
+                <tr key={ row.agent_id }>
+                  <td>{ row.company }</td>
+                  <td>{ row.orders }</td>
+                  <td>{ row.tickets }</td>
+                  <td>{ row.amount.toFixed(2) }</td>
+                  <td>{ row.commission.toFixed(2) }</td>
+                  <td>{ row.net.toFixed(2) }</td>
+                  <td>{ row.settled.toFixed(2) }</td>
+                  <td>{ row.outstanding.toFixed(2) }</td>
+                  { /* the running account: negative is what they owe right
+                       now; headroom is what they can still sell before
+                       their credit floor refuses them */ }
+                  <td>{ row.balance.toFixed(2) }</td>
+                  <td>{ row.headroom.toFixed(2) }</td>
+                  <td>
+                    <Link to={ `${ url }/receivables/${ row.agent_id }?from=${ from }&to=${ to }` }>
+                      { t('admin_api_consumers.receivables.view', { ns: 'common' }) }
+                    </Link>
+                  </td>
+                </tr>
+              )) }
+
+              { data?.length === 0 && (
+                <tr>
+                  <td colSpan={ 9 }>{ t('admin_api_consumers.receivables.empty', { ns: 'common' }) }</td>
+                </tr>
+              ) }
+            </tbody>
+          </Table>
+        </div>
+      ) }
+    </Meta>
+  );
+};
+
+export default Receivables;

package/ReceivablesManage.tsx

@@ -0,0 +1,207 @@
+import { useState } from 'react';
+import { TFunction } from 'i18next';
+import { useParams, useSearchParams } from 'react-router-dom';
+import { Meta, BackWithTitle, Button, Box } from '@autobusal/common';
+import { usePage, useBreadcrumbs } from '@autobusal/hooks';
+import { success } from '@autobusal/utilities';
+import { Table, SectionTitle, Filters } from './styles';
+import { useGetReceivableDrilldown, downloadReceivablesExport, useGetSettlements, useStoreSettlement, useDeleteSettlement } from './services';
+
+interface Props {
+  url: string
+  t: TFunction<'common'>
+}
+
+const ReceivablesManage = ({ url, t }: Props): JSX.Element => {
+  const params = useParams();
+  const [ searchParams ] = useSearchParams();
+
+  const agentId = Number(params.agent_id);
+  const from = searchParams.get('from') || undefined;
+  const to = searchParams.get('to') || undefined;
+
+  usePage('api_consumers');
+
+  useBreadcrumbs(t('admin_api_consumers.receivables.drilldown_title', { ns: 'common' }), [
+    { name: t('admin_api_consumers.browse.title', { ns: 'common' }), url },
+    { name: t('admin_api_consumers.receivables.title', { ns: 'common' }), url: `${ url }/receivables` }
+  ]);
+
+  const { data, isLoading } = useGetReceivableDrilldown({ agent_id: agentId, from, to });
+  const { data: settlements, isLoading: isLoadingSettlements, refetch: refetchSettlements } = useGetSettlements(agentId);
+
+  const { mutate: StoreSettlement, isPending } = useStoreSettlement();
+  const { mutate: DeleteSettlement } = useDeleteSettlement();
+
+  const [ isExporting, setIsExporting ] = useState<boolean>(false);
+
+  const onExport = (): void => {
+    setIsExporting(true);
+
+    downloadReceivablesExport({ agent_id: agentId, from, to })
+      .finally(() => setIsExporting(false));
+  };
+
+  const [ period, setPeriod ] = useState<string>('');
+  const [ amountReceived, setAmountReceived ] = useState<string>('');
+  const [ receivedAt, setReceivedAt ] = useState<string>('');
+  const [ note, setNote ] = useState<string>('');
+
+  const onRecordSettlement = (): void => {
+    StoreSettlement({
+      agent_id: agentId,
+      period: period ? `${ period }-01` : '',
+      amount_received: amountReceived,
+      received_at: receivedAt,
+      note
+    }, {
+      onSuccess: () => {
+        success(t('admin_api_consumers.receivables.settlement_saved', { ns: 'common' }));
+
+        setPeriod('');
+        setAmountReceived('');
+        setReceivedAt('');
+        setNote('');
+
+        refetchSettlements();
+      }
+    });
+  };
+
+  const onDeleteSettlement = (id: number): void => {
+    if (!window.confirm(t('table.confirm', { ns: 'common' }))) {
+      return;
+    }
+
+    DeleteSettlement(id, {
+      onSuccess: () => refetchSettlements()
+    });
+  };
+
+  return (
+    <Meta title={ t('admin_api_consumers.receivables.drilldown_title', { ns: 'common' }) }>
+      <BackWithTitle title={ t('admin_api_consumers.receivables.drilldown_title', { ns: 'common' }) } to={ `${ url }/receivables` } t={ t } />
+
+      <Filters>
+        <Button
+          type="button"
+          size="medium"
+          subtype="secondary"
+          loading={ isExporting }
+          text={ t('admin_api_consumers.receivables.export_csv', { ns: 'common' }) }
+          onClick={ onExport }
+        />
+      </Filters>
+
+      { isLoading ? <Box /> : (
+        <div className="box">
+          <Table>
+            <thead>
+              <tr>
+                <th>{ t('admin_api_consumers.receivables.order', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.sale_date', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.route', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.travel_date', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.amount', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.commission', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.net', { ns: 'common' }) }</th>
+              </tr>
+            </thead>
+
+            <tbody>
+              { data?.data.map(order => (
+                <tr key={ order.id }>
+                  <td>{ order.hash }</td>
+                  <td>{ order.created_at }</td>
+                  <td>{ order.route?.name ?? '-' }</td>
+                  <td>{ order.date_travel ?? '-' }</td>
+                  <td>{ order.amount }</td>
+                  <td>{ order.comission_agent }</td>
+                  <td>{ order.net }</td>
+                </tr>
+              )) }
+
+              { data?.data.length === 0 && (
+                <tr>
+                  <td colSpan={ 7 }>{ t('admin_api_consumers.receivables.empty', { ns: 'common' }) }</td>
+                </tr>
+              ) }
+            </tbody>
+          </Table>
+        </div>
+      ) }
+
+      <SectionTitle>{ t('admin_api_consumers.receivables.settlements', { ns: 'common' }) }</SectionTitle>
+
+      { isLoadingSettlements ? <Box /> : (
+        <div className="box">
+          <Table>
+            <thead>
+              <tr>
+                <th>{ t('admin_api_consumers.receivables.period', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.amount_received', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.received_at', { ns: 'common' }) }</th>
+                <th>{ t('admin_api_consumers.receivables.note', { ns: 'common' }) }</th>
+                <th />
+              </tr>
+            </thead>
+
+            <tbody>
+              { settlements?.map(item => (
+                <tr key={ item.id }>
+                  <td>{ item.period.slice(0, 7) }</td>
+                  <td>{ item.amount_received }</td>
+                  <td>{ item.received_at.slice(0, 10) }</td>
+                  <td>{ item.note ?? '-' }</td>
+                  <td>
+                    <button type="button" onClick={ () => onDeleteSettlement(item.id) }>{ t('table.actions.delete', { ns: 'common' }) }</button>
+                  </td>
+                </tr>
+              )) }
+
+              { settlements?.length === 0 && (
+                <tr>
+                  <td colSpan={ 5 }>{ t('admin_api_consumers.receivables.no_settlements', { ns: 'common' }) }</td>
+                </tr>
+              ) }
+            </tbody>
+          </Table>
+        </div>
+      ) }
+
+      <SectionTitle>{ t('admin_api_consumers.receivables.record_settlement', { ns: 'common' }) }</SectionTitle>
+
+      <Filters>
+        <div>
+          <label>{ t('admin_api_consumers.receivables.period', { ns: 'common' }) }</label>
+          <input type="month" value={ period } onChange={ (e) => setPeriod(e.target.value) } />
+        </div>
+
+        <div>
+          <label>{ t('admin_api_consumers.receivables.amount_received', { ns: 'common' }) }</label>
+          <input type="number" step="0.01" value={ amountReceived } onChange={ (e) => setAmountReceived(e.target.value) } />
+        </div>
+
+        <div>
+          <label>{ t('admin_api_consumers.receivables.received_at', { ns: 'common' }) }</label>
+          <input type="date" value={ receivedAt } onChange={ (e) => setReceivedAt(e.target.value) } />
+        </div>
+
+        <div>
+          <label>{ t('admin_api_consumers.receivables.note', { ns: 'common' }) }</label>
+          <input type="text" value={ note } onChange={ (e) => setNote(e.target.value) } />
+        </div>
+
+        <Button
+          type="button"
+          size="medium"
+          loading={ isPending }
+          text={ t('admin_api_consumers.receivables.save_settlement', { ns: 'common' }) }
+          onClick={ onRecordSettlement }
+        />
+      </Filters>
+    </Meta>
+  );
+};
+
+export default ReceivablesManage;

package/index.ts

@@ -1,7 +1,11 @@
 import Browse from './Browse';
 import Manage from './Manage';
+import Receivables from './Receivables';
+import ReceivablesManage from './ReceivablesManage';
 
 export {
   Browse,
-  Manage
+  Manage,
+  Receivables,
+  ReceivablesManage
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobusal/admin-api-consumers",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "author": "Ferjolt Ozuni",
   "type": "module",
   "main": "index.ts"

package/services.ts

@@ -3,7 +3,7 @@ import { apiClient } from '@autobusal/providers';
 import { PaginationData } from '@autobusal/providers/types/pagination';
 import { TableParamsData } from '@autobusal/providers/types/other';
 import { DropdownData } from '@autobusal/providers/types/other';
-import { ApiConsumerData } from './types';
+import { ApiConsumerData, ReceivableData, ReceivableOrderData, SettlementData } from './types';
 
 export const useGetApiConsumers = (params: TableParamsData): UseQueryResult<PaginationData<ApiConsumerData>> => (
   useQuery({
@@ -144,3 +144,101 @@ export const useRegenerateApiConsumerToken = (): UseMutationResult<{ api_token:
     )
   })
 );
+
+// Edited: Ferjolt Ozuni - Date: 2026-07-27
+// Package 3 - API partner receivables reports + settlements
+
+export const useGetReceivables = (params: { from?: string, to?: string }): UseQueryResult<ReceivableData[]> => (
+  useQuery({
+    queryKey: ['admin-api-consumers-receivables', params],
+    queryFn: async () => (
+      await apiClient
+        .get('/api/api_consumers/admin/reports/receivables', { params })
+        .then(response => (
+          response.data
+        ))
+    )
+  })
+);
+
+export const useGetReceivableDrilldown = (params: { agent_id: number, from?: string, to?: string, page?: number }): UseQueryResult<PaginationData<ReceivableOrderData>> => (
+  useQuery({
+    queryKey: ['admin-api-consumers-drilldown', params],
+    queryFn: async () => (
+      await apiClient
+        .get('/api/api_consumers/admin/reports/drilldown', { params })
+        .then(response => (
+          response.data
+        ))
+    )
+  })
+);
+
+// Edited: Ferjolt Ozuni - Date: 2026-07-27
+// A plain cross-origin `<a href>` straight to obtapi (the
+// @autobusal/account-reports' Downloads.tsx convention this was first
+// modeled on) does NOT authenticate here: a top-level browser navigation
+// never carries the bearer-mode Authorization header (it lives in
+// localStorage, JS-only), and confirmed live there's no separate session
+// cookie backing it either - the export 401'd/500'd depending on whether
+// the browser even sent a Referer. Downloading through `apiClient`
+// instead reuses the SAME authenticated request path as every other call
+// in the app (bearer header or BFF cookie, whichever the brand uses) and
+// works regardless of auth mode.
+export const downloadReceivablesExport = async (params: { agent_id: number, from?: string, to?: string }): Promise<void> => {
+  const response = await apiClient.get('/api/api_consumers/admin/reports/export', {
+    params,
+    responseType: 'blob'
+  });
+
+  const url = window.URL.createObjectURL(new Blob([response.data], { type: 'text/csv' }));
+  const link = document.createElement('a');
+
+  link.href = url;
+  link.download = `receivables-${ params.agent_id }.csv`;
+
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+
+  window.URL.revokeObjectURL(url);
+};
+
+export const useGetSettlements = (agentId: number): UseQueryResult<SettlementData[]> => (
+  useQuery({
+    queryKey: ['admin-api-consumers-settlements', { agentId }],
+    queryFn: async () => (
+      await apiClient
+        .get('/api/api_consumers/admin/reports/settlements', { params: { agent_id: agentId } })
+        .then(response => (
+          response.data
+        ))
+    )
+  })
+);
+
+export const useStoreSettlement = (): UseMutationResult<void, Error, Record<string, any>, unknown> => (
+  useMutation({
+    mutationKey: ['admin-api-consumers-settlements-store'],
+    mutationFn: async (data: Record<string, any>) => (
+      await apiClient
+        .post('/api/api_consumers/admin/reports/settlements', data)
+        .then(response => (
+          response.data
+        ))
+    )
+  })
+);
+
+export const useDeleteSettlement = (): UseMutationResult<void, Error, number, unknown> => (
+  useMutation({
+    mutationKey: ['admin-api-consumers-settlements-delete'],
+    mutationFn: async (id: number) => (
+      await apiClient
+        .delete('/api/api_consumers/admin/reports/settlements', { params: { id } })
+        .then(response => (
+          response.data
+        ))
+    )
+  })
+);

package/styles.ts

@@ -29,3 +29,45 @@ export const TokenActions = styled.div`
   display: flex;
   gap: 10px;
 `;
+
+// Edited: Ferjolt Ozuni - Date: 2026-07-27
+// Package 3 - receivables/settlements tables + filters, matching
+// @autobusal/admin-external's plain-table approach (this data isn't
+// paginated the same way as the generic <Table>/<Row> components assume)
+export const Table = styled.table`
+  width: 100%;
+  border-collapse: collapse;
+
+  th, td {
+    text-align: left;
+    padding: 10px 12px;
+    border-bottom: 1px solid ${ props => props.theme.primary.neutral };
+  }
+
+  th {
+    font-size: ${ props => props.theme.size.sm };
+    color: ${ props => props.theme.font.faded };
+  }
+`;
+
+export const Actions = styled.div`
+  display: flex;
+  gap: 10px;
+`;
+
+export const SectionTitle = styled.h2`
+  margin: 25px 0 10px;
+`;
+
+export const Filters = styled.div`
+  display: flex;
+  gap: 15px;
+  align-items: flex-end;
+  flex-wrap: wrap;
+  margin-bottom: 20px;
+
+  input {
+    padding: 8px 10px;
+    border-radius: 6px;
+  }
+`;

package/types.ts

@@ -6,6 +6,10 @@ export interface ApiConsumerData {
   operators: (number | string)[]
   external_providers: (number | string)[]
   is_api_consumer: boolean
+  // Claude - 2026-08-22: the running account and its floor - see
+  // ReceivableData below for what they mean
+  funds?: number
+  credit_limit?: number
   user: {
     id: number
     email: string
@@ -17,3 +21,48 @@ export interface ApiConsumerData {
     }
   }
 }
+
+// Edited: Ferjolt Ozuni - Date: 2026-07-27
+// Package 3 - API partner receivables reports + settlements
+export interface ReceivableData {
+  agent_id: number
+  company: string
+  email: string
+  orders: number
+  tickets: number
+  amount: number
+  commission: number
+  net: number
+  settled: number
+  outstanding: number
+  // Claude - 2026-08-22: the LIVE running account (debited per sale,
+  // credited by settlements) and its floor - alongside the statement
+  // figures, which describe the same debt from the frozen columns. When
+  // balance and -outstanding disagree, something needs investigating.
+  balance: number
+  credit_limit: number
+  headroom: number
+}
+
+export interface ReceivableOrderData {
+  id: number
+  hash: string
+  tickets: number
+  date_travel: string
+  amount: number
+  comission_agent: number
+  net: number
+  created_at: string
+  route?: { id: number, name: string }
+  passengers?: { id: number, first_name: string, last_name: string, bus_seat?: number }[]
+}
+
+export interface SettlementData {
+  id: number
+  api_user_id: number
+  period: string
+  amount_received: string
+  received_at: string
+  note?: string
+  created_at: string
+}