@saasicat/ui-vue 0.24.2 → 0.26.0

package/src/client/resources/list-resource.ts

@@ -0,0 +1,176 @@
+// What a paginated admin list asks for, and what it gets back.
+//
+// One decision, written once. `useApiList` assembles `?page=…&pageSize=…` plus
+// the filter, `createAdminResourceClient` assembles the filter half of the same
+// thing for the endpoints that do not page, and every list descriptor would
+// have been a third and fourth expression of it. They agreed by coincidence
+// rather than by construction: three copies of "an empty value is omitted" is
+// three chances for one of them to start sending `status=null` and filter every
+// row away.
+//
+// Framework-free like the rest of `src/client/`: a URL, a body shape and the
+// arithmetic around the page number. The reactive half — refs, watchers, the
+// two controls — is `useResourceList`'s.
+
+import type { ResourceContext, ResourceOp } from './define-resource.js';
+import { requestJson } from './resource-request.js';
+
+/** 1-based: the page a list starts on, and the one a changed filter returns to. */
+export const LIST_FIRST_PAGE = 1;
+
+/**
+ * What the admin API falls back to when `pageSize` is absent. Sent explicitly
+ * rather than relied on, so the URL states what it asked for.
+ */
+export const LIST_PAGE_SIZE_DEFAULT = 50;
+
+/**
+ * The largest page the admin API serves. There is no "all" to pass on, which is
+ * why `SERVER_PAGE_SIZE_OPTIONS` leaves Quasar's `ALL_ROWS` out as well.
+ */
+export const LIST_PAGE_SIZE_MAX = 200;
+
+/** The two parameters the pagination owns; a filter may not carry them. */
+export const LIST_PAGINATION_PARAMS = ['page', 'pageSize'] as const;
+
+/**
+ * A filter without the two keys the pagination owns.
+ *
+ * The platform's filter types (`TenantListFilter`, `AuditQuery`) declare
+ * `page` and `pageSize` because they were once passed as one object. Serialised
+ * after the pagination they silently overwrite it — `goToPage(3)` moves the ref
+ * while the request asks for page 7 — so a descriptor takes the filter without
+ * them and the page number travels in its own field.
+ */
+export type ListFilterOf<TFilter> = Omit<TFilter, 'page' | 'pageSize'>;
+
+/** Everything one list request varies: which page, how big, filtered by what. */
+export interface ListQuery<TFilter extends object = Record<string, unknown>> {
+    /** 1-based. Defaults to `LIST_FIRST_PAGE`. */
+    page?: number;
+    /** Defaults to `LIST_PAGE_SIZE_DEFAULT`. */
+    pageSize?: number;
+    /** Serialised as `?key=value`; see `isSentInQuery` for what is left out. */
+    filter?: TFilter;
+}
+
+/**
+ * One page of a list, as the admin API answers it.
+ *
+ * `total` is optional because it is genuinely absent from some answers: a
+ * controller returning a bare array has reported the rows it sent and nothing
+ * about the rest, and an envelope may omit the field altogether. A number
+ * invented here would read as "rows matching the filter" under a paginator that
+ * then offers pages nobody can reach.
+ */
+export interface ResourceListPage<T> {
+    items: T[];
+    /** Rows matching the filter — only when the server said so. */
+    total?: number;
+    /** What the server echoed back about the page it served, when it echoed anything. */
+    page?: number;
+    pageSize?: number;
+}
+
+/** A list operation: the query in, one page out. */
+export type ListOp<TRow, TFilter extends object = Record<string, unknown>> = ResourceOp<
+    [query?: ListQuery<TFilter>],
+    ResourceListPage<TRow>
+>;
+
+/**
+ * Whether a filter value reaches the query string at all.
+ *
+ * `undefined`, `null` and `''` are the three spellings of "not filtered" that
+ * a form produces, and sending them would filter on the literal text `null`.
+ * Everything else goes as `String(value)` — including `0` and `false`, which
+ * are answers, not absences.
+ */
+export function isSentInQuery(value: unknown): boolean {
+    return value !== undefined && value !== null && value !== '';
+}
+
+function appendFilter(params: URLSearchParams, filter: object | undefined): void {
+    for (const [key, value] of Object.entries(filter ?? {})) {
+        if (!isSentInQuery(value)) continue;
+        params.set(key, String(value));
+    }
+}
+
+/**
+ * `?a=b` for a filter on its own, or `''` when nothing survives — the form the
+ * admin endpoints that do not page take their filter in.
+ */
+export function filterQueryString(filter: object): string {
+    const params = new URLSearchParams();
+    appendFilter(params, filter);
+    const query = params.toString();
+    return query ? `?${query}` : '';
+}
+
+/**
+ * The URL one page of a list is requested from.
+ *
+ * `page` and `pageSize` are always present and always first — an endpoint that
+ * ignores them is free to, but the request says which page it meant. The filter
+ * follows in its own insertion order, and the endpoint may already carry a
+ * query of its own.
+ */
+export function listUrl<TFilter extends object>(
+    endpoint: string,
+    query: ListQuery<TFilter> = {},
+): string {
+    const params = new URLSearchParams();
+    params.set('page', String(query.page ?? LIST_FIRST_PAGE));
+    params.set('pageSize', String(query.pageSize ?? LIST_PAGE_SIZE_DEFAULT));
+    appendFilter(params, query.filter);
+    return `${endpoint}${endpoint.includes('?') ? '&' : '?'}${params.toString()}`;
+}
+
+/**
+ * Reads whatever a list endpoint answered into one page.
+ *
+ * Both shapes are real: some controllers return a bare array, others the
+ * `{ items, page, pageSize, total }` envelope. Accepting only the envelope is
+ * what once rendered three tenants as an empty table (see
+ * `use-api-list-shape.test.js`). What the answer did not state stays absent
+ * rather than being filled in — the caller decides what "no total" means for
+ * its paginator.
+ */
+export function readListPage<T>(raw: unknown): ResourceListPage<T> {
+    if (Array.isArray(raw)) return { items: raw as T[], total: raw.length };
+    if (raw === null || typeof raw !== 'object') return { items: [], total: 0 };
+    const body = raw as { items?: unknown; total?: unknown; page?: unknown; pageSize?: unknown };
+    const page: ResourceListPage<T> = {
+        items: Array.isArray(body.items) ? (body.items as T[]) : [],
+    };
+    if (typeof body.total === 'number') page.total = body.total;
+    if (typeof body.page === 'number') page.page = body.page;
+    if (typeof body.pageSize === 'number') page.pageSize = body.pageSize;
+    return page;
+}
+
+/** Keeps a requested page on the 1-based scale the API counts on. */
+export function clampListPage(page: number): number {
+    return Math.max(LIST_FIRST_PAGE, Math.floor(page));
+}
+
+/** Keeps a requested page size inside the 1..`LIST_PAGE_SIZE_MAX` the API serves. */
+export function clampListPageSize(size: number): number {
+    return Math.min(LIST_PAGE_SIZE_MAX, Math.max(1, Math.floor(size)));
+}
+
+/**
+ * A list operation over one endpoint: the second of a pair, and the reason it
+ * is a function rather than two hand-written descriptors.
+ *
+ * The endpoint is a function of the context so a `context` override on the
+ * registry — an app pointing one resource at a legacy base — reaches it without
+ * the descriptor knowing.
+ */
+export function defineListOp<TRow, TFilter extends object = Record<string, unknown>>(
+    endpoint: (ctx: ResourceContext) => string,
+): ListOp<TRow, TFilter> {
+    return async (http, ctx, query) =>
+        readListPage<TRow>(await requestJson(http, listUrl(endpoint(ctx), query)));
+}

package/src/client/resources/plans.resource.ts

@@ -0,0 +1,169 @@
+// The plan catalogue endpoints.
+//
+// Two path stems, and the asymmetry is the server's, not a mistake here:
+// reading and creating versions goes through the plan
+// (`catalog/plans/:planId/versions`), while every mutation of an existing
+// version addresses the version directly (`catalog/plan-versions/:id`).
+//
+// Path parameters are interpolated without encoding, which is what the
+// composables do today. Encoding them would be the safer default — but ids
+// containing `/`, `#` or `?` would then reach a different URL than they reach
+// now, and that is a behaviour change, not a fix. It belongs in a change that
+// says so.
+
+import type {
+    CreatePlanData,
+    CreatePlanVersionDraftData,
+    PlanRow,
+    PlanVersionMutationResult,
+    PlanVersionRow,
+    UpdatePlanData,
+    UpdatePlanVersionDraftData,
+} from '@saasicat/types';
+
+import { defineResource, type ResourceContext } from './define-resource.js';
+
+import { requestJson, requestJsonBody } from './resource-request.js';
+
+/** What `publish` may override at the moment a version goes live. */
+export interface PublishPlanVersionOptions {
+    forceRegressive?: boolean;
+    allowZeroPrice?: boolean;
+    validFrom?: string | null;
+    validUntil?: string | null;
+}
+
+function plansUrl(ctx: ResourceContext): string {
+    return `${ctx.apiBase}/catalog/plans`;
+}
+
+function versionsUrl(ctx: ResourceContext): string {
+    return `${ctx.apiBase}/catalog/plan-versions`;
+}
+
+/** `?projectKey=…` — the key is a literal, only the value is encoded. */
+function scoped(url: string, ctx: ResourceContext): string {
+    return `${url}?projectKey=${encodeURIComponent(ctx.projectKey)}`;
+}
+
+/**
+ * The plan catalogue — the one platform resource that is read per project.
+ *
+ * `list`, `tenantCounts` and `create` all carry `ctx.projectKey`, so binding
+ * this against a context that names no project is refused rather than sent (see
+ * `bindResource`). Its three siblings address a plan or a version by id and are
+ * not declared here.
+ */
+export const plansResource = defineResource(
+    'plans',
+    {
+        list: async (http, ctx): Promise<PlanRow[]> =>
+            (await requestJson<PlanRow[]>(http, scoped(plansUrl(ctx), ctx))) ?? [],
+
+        tenantCounts: async (http, ctx): Promise<Record<string, number>> =>
+            (await requestJson<Record<string, number>>(
+                http,
+                scoped(`${plansUrl(ctx)}/tenant-counts`, ctx),
+            )) ?? {},
+
+        /**
+         * The project comes from the context, not from the caller.
+         *
+         * The endpoint takes it in the body, and the composable this replaces
+         * made that the caller's job — so a page had to keep hold of the
+         * project it was administering just to create in it, and `list()` and
+         * `create()` read two different sources for one value. A stale one
+         * creates a plan outside the project the list is showing.
+         */
+        create: (http, ctx, data: Omit<CreatePlanData, 'projectKey'>): Promise<PlanRow> =>
+            requestJsonBody<PlanRow>(http, plansUrl(ctx), 'Create returned no body', {
+                method: 'POST',
+                body: { ...data, projectKey: ctx.projectKey },
+            }),
+
+        update: (http, ctx, planId: string, data: UpdatePlanData): Promise<PlanRow> =>
+            requestJsonBody<PlanRow>(
+                http,
+                `${plansUrl(ctx)}/${planId}`,
+                'Update returned no body',
+                {
+                    method: 'PATCH',
+                    body: data,
+                },
+            ),
+
+        /** Marks the plan deleted. Fails while it still has versions. */
+        softDelete: async (http, ctx, planId: string): Promise<void> => {
+            await requestJson(http, `${plansUrl(ctx)}/${planId}`, { method: 'DELETE' });
+        },
+
+        /** Removes the plan for good. 422 `PLAN_HAS_VERSIONS` when it cannot. */
+        hardDelete: async (http, ctx, planId: string): Promise<void> => {
+            await requestJson(http, `${plansUrl(ctx)}/${planId}/purge`, { method: 'DELETE' });
+        },
+    },
+    { projectScoped: true },
+);
+
+export const planVersionsResource = defineResource('planVersions', {
+    listForPlan: async (http, ctx, planId: string): Promise<PlanVersionRow[]> =>
+        (await requestJson<PlanVersionRow[]>(http, `${plansUrl(ctx)}/${planId}/versions`)) ?? [],
+
+    createDraft: (
+        http,
+        ctx,
+        planId: string,
+        data: Omit<CreatePlanVersionDraftData, 'planId'>,
+    ): Promise<PlanVersionMutationResult> =>
+        requestJsonBody<PlanVersionMutationResult>(
+            http,
+            `${plansUrl(ctx)}/${planId}/versions`,
+            'CreateDraft returned no body',
+            { method: 'POST', body: data },
+        ),
+
+    updateDraft: (
+        http,
+        ctx,
+        versionId: string,
+        data: UpdatePlanVersionDraftData,
+    ): Promise<PlanVersionMutationResult> =>
+        requestJsonBody<PlanVersionMutationResult>(
+            http,
+            `${versionsUrl(ctx)}/${versionId}`,
+            'UpdateDraft returned no body',
+            { method: 'PATCH', body: data },
+        ),
+
+    publish: (
+        http,
+        ctx,
+        versionId: string,
+        options: PublishPlanVersionOptions = {},
+    ): Promise<PlanVersionMutationResult> =>
+        requestJsonBody<PlanVersionMutationResult>(
+            http,
+            `${versionsUrl(ctx)}/${versionId}/publish`,
+            'Publish returned no body',
+            { method: 'POST', body: options },
+        ),
+
+    discardDraft: async (http, ctx, versionId: string): Promise<void> => {
+        await requestJson(http, `${versionsUrl(ctx)}/${versionId}`, { method: 'DELETE' });
+    },
+
+    /**
+     * Ends a live version on `endsAt`, with no successor. Idempotent — a
+     * second call with another date overwrites the first.
+     *
+     * `endsAt` is the date itself, not a payload: the endpoint's body is
+     * `{ endsAt }` and wrapping it is this operation's job, not the caller's.
+     */
+    terminate: (http, ctx, versionId: string, endsAt: string): Promise<PlanVersionRow> =>
+        requestJsonBody<PlanVersionRow>(
+            http,
+            `${versionsUrl(ctx)}/${versionId}/terminate`,
+            'Terminate returned no body',
+            { method: 'POST', body: { endsAt } },
+        ),
+});

package/src/client/resources/resource-request.ts

@@ -0,0 +1,117 @@
+// The JSON request/response policy the admin catalogue endpoints share.
+//
+// This exact function is written out three times in the package today —
+// `use-plans.ts` contains two byte-identical copies of it in one file, and
+// `use-bundles.ts` and `use-catalog-entries.ts` a third and fourth — differing
+// only in the message they put on the error. The policy itself is one
+// decision, so it is written once here.
+//
+// It is NOT the policy the tenant-side billing composables use: those check
+// `>= 400` before the 204 branch, read the error body with `text()` as a
+// fallback, and let an unparsable 2xx reject with the raw parse error. Those
+// three are mutually incompatible and belong to a different audience — see the
+// tenant package split. Nothing here should be pointed at them.
+
+import { AdminError, readErrorCode, readErrorDetail } from '../admin-error.js';
+import { requireServerAnswer } from '../http-json.js';
+import type { HttpClient } from '../types.js';
+
+export interface ResourceRequestInit {
+    /** Default `GET`. */
+    method?: string;
+    /** Serialised here — the `HttpClient` contract only carries strings. */
+    body?: unknown;
+    /** Merged over the defaults, so a caller's header wins. */
+    headers?: Record<string, string>;
+}
+
+/**
+ * Sends a request and returns the parsed body, or `null` when there was none.
+ *
+ * `null` covers both a `204` and a 2xx whose body would not parse. The two are
+ * deliberately not distinguished: every caller treats them the same way — a
+ * list turns `null` into `[]`, a mutation turns it into a failure — and no
+ * endpoint in this family answers a mutation with an empty 200 on purpose.
+ *
+ * A non-2xx throws an `AdminError` carrying the parsed body, so a caller can
+ * still branch on `status` and `body.code` the way the pages do today.
+ *
+ * A client that resolved without an HTTP status throws before any of that: no
+ * status means the request never reached the server, which is a transport
+ * failure and not an answer this function may read.
+ */
+export async function requestJson<T>(
+    http: HttpClient,
+    url: string,
+    init: ResourceRequestInit = {},
+): Promise<T | null> {
+    const method = init.method ?? 'GET';
+    const response = await http(url, {
+        method,
+        headers: { 'content-type': 'application/json', ...init.headers },
+        body: init.body === undefined ? undefined : JSON.stringify(init.body),
+    });
+
+    // Before anything is read off the response: a client that reports a
+    // network, CORS or abort failure by RESOLVING with `status: 0` — the shape
+    // `HttpClient` permits and `requireServerAnswer` exists for — otherwise
+    // arrives here as a successful answer with no body. A list would then be
+    // empty with nothing wrong on screen, and a mutation would tell the
+    // operator their change may have been applied when the request never left
+    // the machine.
+    requireServerAnswer(
+        response.status,
+        method,
+        url,
+        (diagnostic) =>
+            new AdminError({ status: response.status, url, method, message: diagnostic }),
+    );
+
+    if (response.status === 204) return null;
+    const body = await response.json().catch(() => null);
+    if (response.status >= 400) {
+        throw new AdminError({
+            status: response.status,
+            code: readErrorCode(body),
+            body,
+            // The third place this had to be read, and the second time it was
+            // read a narrower way: without `detail` a page migrating onto these
+            // resources loses "Plan already exists" and shows the generic
+            // status sentence instead. One decision, one function.
+            detail: readErrorDetail(body),
+            url,
+            method,
+        });
+    }
+    return body as T | null;
+}
+
+/**
+ * Reads the body of a request that must answer with one.
+ *
+ * The empty case is a failure rather than a `null` the caller has to re-check:
+ * a create that returns nothing has not told us what it created. Raised with
+ * `status: 0`, because no HTTP status went wrong — the response was a 2xx.
+ */
+export async function requestJsonBody<T>(
+    http: HttpClient,
+    url: string,
+    what: string,
+    init: ResourceRequestInit = {},
+): Promise<T> {
+    const body = await requestJson<T>(http, url, init);
+    if (body === null || body === undefined) {
+        throw new AdminError({
+            status: 0,
+            url,
+            method: init.method ?? 'GET',
+            // `what` is a diagnostic — "Create returned no body" — so it goes
+            // on `message`, not `detail`. As `detail` it out-ranked the
+            // localized wording and the operator read an English internal
+            // string instead of being told the change may already have landed.
+            message: what,
+            emptyResponse: true,
+        });
+    }
+    return body;
+}

package/src/client/resources/tenants.resource.ts

@@ -0,0 +1,27 @@
+// The tenant list.
+//
+// One operation, deliberately: the list `useTenants` requests today. Tenant
+// detail, suspend and reactivate still live in `createAdminResourceClient` and
+// move here with the page that calls them — a descriptor nothing calls has
+// nothing keeping it honest.
+//
+// The request pages; the controller does not. `AdminResourcesPort.listTenants`
+// takes `status`/`plan`/`search` and answers with a bare array — no `page`, no
+// `total` — while the paginated `TenantPort.list` no controller exposes returns
+// `Paginated<TenantDto>`. So `page` and `pageSize` go out on every request and
+// today nothing on the far side reads them. That is exactly what `useApiList`
+// has been sending, and reproducing it is the point: what the server does with
+// the parameters is the server's to change, and a descriptor that quietly sent
+// less would be a different request wearing the same name.
+
+import type { TenantDto, TenantListFilter } from '@saasicat/types';
+
+import { defineResource } from './define-resource.js';
+import { defineListOp, type ListFilterOf } from './list-resource.js';
+
+/** What the tenants list can be narrowed by. The page number is not a filter. */
+export type TenantsListFilter = ListFilterOf<TenantListFilter>;
+
+export const tenantsResource = defineResource('tenants', {
+    list: defineListOp<TenantDto, TenantsListFilter>((ctx) => `${ctx.apiBase}/tenants`),
+});

package/src/client/types.ts

@@ -1,5 +1,7 @@
 // Shared configuration types for all UI-Vue loaders/composables.
 
+import { createFetchHttpClient } from './http/fetch-http-client.js';
+
 /**
  * Minimal abstraction over `fetch`. Consumers may pass their own
  * implementation (e.g. an axios wrapper that already injects auth headers
@@ -87,9 +89,14 @@ function resolveLocalStorage(): Storage | null {
 }
 
 /**
- * Default `HttpClient` over `fetch`. Consumers pass their own variant
- * through when they need auth headers / tenant headers / retry logic.
+ * Default `HttpClient` over `fetch`, with no base URL and no headers of its
+ * own. Consumers pass their own variant when they need auth headers, tenant
+ * headers or retry logic — `createFetchHttpClient({ headers })` and
+ * `createAxiosHttpClient(instance)` are the two the package ships.
+ *
+ * It delegates rather than calling `fetch` itself so that there is one
+ * implementation to reason about instead of two that drift.
  */
 export function defaultHttpClient(): HttpClient {
-    return (url, init) => fetch(url, init);
+    return createFetchHttpClient();
 }

package/src/components/BundleVersionPublishDialog.vue

@@ -50,7 +50,7 @@
 
                 <div>
                     <q-toggle v-model="allowZeroPrice" :label="msg.publishDialog.allowZeroPrice" />
-                    <p class="bvpd__label" style="margin-top: 6px">
+                    <p class="bvpd__label" style="margin-top: var(--sa-space-3)">
                         {{ msg.publishDialog.allowZeroPriceHint }}
                     </p>
                 </div>