@saasicat/ui-vue 0.24.2 → 0.26.0

package/src/client/i18n/messages/errors.ts

@@ -0,0 +1,44 @@
+// What to tell a user when a request failed and the failing side said nothing
+// itself. Each key answers one question — "what went wrong" — so none of them
+// names an action; `common.errorLoadFailed` and its siblings do that.
+//
+// `adminErrorMessage()` reaches exactly one of these per error, and reaches a
+// key here only when the response carried no message of its own.
+//
+// `network`, `emptyResponse` and `unexpected` all describe a request with no
+// HTTP status and must not be swapped. The first two are reached only when a
+// seam declared which one it was (`markTransportFailure`, `markEmptyResponse`);
+// `unexpected` is what is left when nothing knows — including the JavaScript
+// faults that used to be reported as connection problems.
+
+import { defineMessages } from '../define.js';
+
+export const errorsMessages = defineMessages(
+    {
+        network: 'Die Anfrage konnte nicht abgeschlossen werden. Bitte Verbindung prüfen.',
+        emptyResponse:
+            'Der Server hat nichts zurückgegeben. Bitte prüfen, ob die Änderung angekommen ist.',
+        unauthorized: 'Die Sitzung ist abgelaufen. Bitte erneut anmelden.',
+        forbidden: 'Für diese Aktion fehlt die Berechtigung.',
+        notFound: 'Der angeforderte Eintrag existiert nicht mehr.',
+        conflict: 'Der Eintrag wurde zwischenzeitlich geändert. Bitte neu laden.',
+        validation: 'Die Eingaben wurden nicht akzeptiert.',
+        rateLimited: 'Zu viele Anfragen. Bitte kurz warten und erneut versuchen.',
+        server: 'Der Server konnte die Anfrage nicht verarbeiten.',
+        httpStatus: 'Die Anfrage ist fehlgeschlagen (HTTP {status}).',
+        unexpected: 'Es ist ein unerwarteter Fehler aufgetreten. Bitte erneut versuchen.',
+    },
+    {
+        network: 'The request could not be completed. Please check your connection.',
+        emptyResponse: 'The server returned nothing. Please check whether the change was applied.',
+        unauthorized: 'Your session has expired. Please sign in again.',
+        forbidden: 'You do not have permission for this action.',
+        notFound: 'The requested entry no longer exists.',
+        conflict: 'The entry changed in the meantime. Please reload.',
+        validation: 'The input was not accepted.',
+        rateLimited: 'Too many requests. Please wait a moment and try again.',
+        server: 'The server could not process the request.',
+        httpStatus: 'The request failed (HTTP {status}).',
+        unexpected: 'Something went wrong. Please try again.',
+    },
+);

package/src/client/i18n/messages/marketing.ts

@@ -130,9 +130,6 @@ export const marketingMessages = defineMessages(
             delete: 'Aktion löschen',
             deleteConfirm: 'Aktion „{label}“ wirklich löschen?',
         },
-        errors: {
-            projectionsApi: 'MarketingProjections-API antwortete mit HTTP {status}',
-        },
     },
     {
         topFeatures: 'Top features',
@@ -261,8 +258,5 @@ export const marketingMessages = defineMessages(
             delete: 'Delete promotion',
             deleteConfirm: 'Really delete promotion "{label}"?',
         },
-        errors: {
-            projectionsApi: 'MarketingProjections API responded with HTTP {status}',
-        },
     },
 );

package/src/client/i18n/messages/promos.ts

@@ -4,7 +4,6 @@ export const promosMessages = defineMessages(
     {
         title: 'Promo-Codes',
         createAction: 'Promo-Code anlegen',
-        apiErrorHttpStatus: 'Promotions-API antwortete mit HTTP {status}',
         list: {
             searchLabel: 'Suche (Code)',
             tileScheduled: 'Geplant',
@@ -103,7 +102,6 @@ export const promosMessages = defineMessages(
     {
         title: 'Promo codes',
         createAction: 'Create promo code',
-        apiErrorHttpStatus: 'Promotions API responded with HTTP {status}',
         list: {
             searchLabel: 'Search (code)',
             tileScheduled: 'Scheduled',

package/src/client/i18n/messages/shell.ts

@@ -11,6 +11,12 @@ export const shellMessages = defineMessages(
             roleBadge: 'SUPER ADMIN',
             logout: 'Abmelden',
             language: 'Sprache',
+            theme: {
+                label: 'Darstellung',
+                light: 'Hell',
+                dark: 'Dunkel',
+                system: 'System',
+            },
         },
         drawer: {
             docs: 'Doku öffnen',
@@ -83,6 +89,12 @@ export const shellMessages = defineMessages(
             roleBadge: 'SUPER ADMIN',
             logout: 'Sign out',
             language: 'Language',
+            theme: {
+                label: 'Appearance',
+                light: 'Light',
+                dark: 'Dark',
+                system: 'System',
+            },
         },
         drawer: {
             docs: 'Open documentation',

package/src/client/i18n/messages.ts

@@ -10,6 +10,7 @@ import { commonMessages } from './messages/common.js';
 import { dashboardMessages } from './messages/dashboard.js';
 import { discoveryMessages } from './messages/discovery.js';
 import { emailMessages } from './messages/email.js';
+import { errorsMessages } from './messages/errors.js';
 import { marketingMessages } from './messages/marketing.js';
 import { navMessages } from './messages/nav.js';
 import { pilotsMessages } from './messages/pilots.js';
@@ -25,6 +26,7 @@ import { usersMessages } from './messages/users.js';
 /** Complete platform catalog for one locale, keyed by namespace. */
 export type SaMessages = {
     readonly common: (typeof commonMessages)['de'];
+    readonly errors: (typeof errorsMessages)['de'];
     readonly nav: (typeof navMessages)['de'];
     readonly shell: (typeof shellMessages)['de'];
     readonly dashboard: (typeof dashboardMessages)['de'];
@@ -49,6 +51,7 @@ export type SaMessagesOverrides = PartialMessages<SaMessages>;
 function catalogFor(locale: SaBuiltinLocale): SaMessages {
     return {
         common: commonMessages[locale],
+        errors: errorsMessages[locale],
         nav: navMessages[locale],
         shell: shellMessages[locale],
         dashboard: dashboardMessages[locale],

package/src/client/index.ts

@@ -5,6 +5,9 @@
 //
 // Contents:
 //   - types:                HttpClient, KvStore, defaultHttpClient, defaultKvStore
+//   - http:                 createFetchHttpClient, createAxiosHttpClient
+//   - resources:            defineResource, bindResource, the endpoint descriptors
+//   - admin-error:          AdminError, toAdminError, adminErrorMessage
 //   - http-json:            JSON fetch helper over HttpClient
 //   - boot-loader:          BootLoader + BootLoadError
 //   - manifest-loader:      ManifestLoader with ETag cache + ManifestLoadError
@@ -16,6 +19,9 @@
 
 export * from './version.js';
 export * from './types.js';
+export * from './http/index.js';
+export * from './resources/index.js';
+export * from './admin-error.js';
 export * from './http-json.js';
 export * from './boot-loader.js';
 export * from './manifest-loader.js';

package/src/client/manifest-loader.ts

@@ -11,11 +11,27 @@
 //   - Subsequent call: GET with `If-None-Match: <etag>` → on 304 the
 //     cached body is returned, no re-parse needed. On 200 the
 //     cache is overwritten.
+//   - The two keys can come apart — a quota eviction, another tab clearing
+//     one of them, a store that took the first write and refused the second.
+//     A 304 then answers a question this loader asked on behalf of a body it
+//     no longer holds, and the repair is to forget the ETag and ask again
+//     unconditionally. See `load()`.
 //
 // Spec: admin-api.openapi.yaml `GET /admin/manifest`.
 
 import type { AdminManifest } from '@saasicat/types';
-import { defaultHttpClient, defaultKvStore, type HttpClient, type KvStore } from './types.js';
+import { markPlatformError } from './admin-error.js';
+import { requireServerAnswer } from './http-json.js';
+import {
+    defaultHttpClient,
+    defaultKvStore,
+    type HttpClient,
+    type HttpResponse,
+    type KvStore,
+} from './types.js';
+
+/** The conditional GET matched: no body was sent, so the cache has to answer. */
+const NOT_MODIFIED = 304;
 
 export interface ManifestLoaderOptions {
     /**
@@ -39,6 +55,11 @@ export interface ManifestLoaderOptions {
     getAuthToken?: () => string | null;
 }
 
+/**
+ * The manifest could not be loaded. Its `message` is a diagnostic for the log,
+ * never text for a screen — `markPlatformError` is what tells `toAdminError`
+ * so, and it is a promise this class has to keep at every throw site.
+ */
 export class ManifestLoadError extends Error {
     constructor(
         public readonly status: number,
@@ -46,6 +67,9 @@ export class ManifestLoadError extends Error {
     ) {
         super(message);
         this.name = 'ManifestLoadError';
+        // Identity, so `toAdminError` can tell this diagnostic from a
+        // consumer error whose message an operator needs to read.
+        markPlatformError(this);
     }
 }
 
@@ -82,27 +106,53 @@ export class ManifestLoader {
     /**
      * Loads the current manifest. On a cache hit (304) the cached
      * body is returned — otherwise the fresh server body.
+     *
+     * A 304 with no usable cached body is not a failure to report but one to
+     * undo: the request only carried `If-None-Match` because this loader put
+     * the ETag there, and the cache it validated against is this loader's own.
+     * So it drops the pair and asks once more without the header, which is the
+     * same recovery a person would have had to trigger by hand — except that
+     * the person reading an admin screen has neither this loader nor a
+     * console. Exactly one retry: a 304 to a request that asked nothing
+     * conditional is a server fault, and no repetition fixes it.
      */
     async load(): Promise<AdminManifest> {
         const cachedEtag = this.storage.get(this.etagKey);
+        const res = await this.request(cachedEtag);
+        if (res.status !== NOT_MODIFIED) return this.acceptFresh(res);
+
+        const cached = this.readCachedBody();
+        if (cached) return cached.body;
+
+        if (cachedEtag) {
+            this.clearCache();
+            const fresh = await this.request(null);
+            if (fresh.status !== NOT_MODIFIED) return this.acceptFresh(fresh);
+        }
+
+        throw new ManifestLoadError(
+            NOT_MODIFIED,
+            'Manifest endpoint answered HTTP 304 to a request without If-None-Match',
+        );
+    }
+
+    /** Sends the manifest GET, conditional when an ETag is supplied. */
+    private request(etag: string | null): Promise<HttpResponse> {
         const headers: Record<string, string> = {};
         const token = this.getAuthToken?.();
         if (token) headers.Authorization = `Bearer ${token}`;
-        if (cachedEtag) headers['If-None-Match'] = cachedEtag;
-
-        const res = await this.http(this.endpoint, { method: 'GET', headers });
-
-        if (res.status === 304) {
-            const cachedBody = this.readCachedBody();
-            if (!cachedBody) {
-                throw new ManifestLoadError(
-                    304,
-                    'Server returned 304 but the cache body is missing — call clearCache() and reload',
-                );
-            }
-            return cachedBody.body;
-        }
+        if (etag) headers['If-None-Match'] = etag;
+        return this.http(this.endpoint, { method: 'GET', headers });
+    }
 
+    /** Takes a non-304 response as the current manifest and caches it. */
+    private async acceptFresh(res: HttpResponse): Promise<AdminManifest> {
+        requireServerAnswer(
+            res.status,
+            'GET',
+            this.endpoint,
+            (diagnostic) => new ManifestLoadError(res.status, diagnostic),
+        );
         if (res.status !== 200) {
             throw new ManifestLoadError(
                 res.status,

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

@@ -0,0 +1,25 @@
+// The audit trail.
+//
+// This descriptor speaks the contract `useAuditEntries` speaks: `AuditQuery`
+// (`actorTag`, `from`, `to`, `entity`, …) over a paginated endpoint. The
+// package holds a second, incompatible one — `createAdminResourceClient`
+// sends `actor`/`since`/`limit` at `AdminAuditListFilter`, unpaginated, and
+// that is what `AuditPage.vue` receives through its `loadAudit` prop.
+//
+// Two audit contracts in one package is a defect, but it is not this change's
+// to settle: choosing either spelling here would send a different request than
+// one of the two callers sends today. The descriptor mirrors the composable it
+// is measured against, and the reconciliation belongs to the page rebuild that
+// can move both sides at once.
+
+import type { AuditEntry, AuditQuery } from '@saasicat/types';
+
+import { defineResource } from './define-resource.js';
+import { defineListOp, type ListFilterOf } from './list-resource.js';
+
+/** What the audit list can be narrowed by. The page number is not a filter. */
+export type AuditListFilter = ListFilterOf<AuditQuery>;
+
+export const auditResource = defineResource('audit', {
+    list: defineListOp<AuditEntry, AuditListFilter>((ctx) => `${ctx.apiBase}/audit`),
+});

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

@@ -0,0 +1,166 @@
+// A resource is a named set of operations over `(http, ctx, ...args)`.
+//
+// The point is to define an endpoint once. Today the same URL is assembled in
+// several places — `catalog/plans/:id/versions` is built by `usePlanVersions`
+// and again by `useLivePlanVersions`, and the JSON request/response dance
+// around it (`204` means empty, a 2xx body may be unparsable, `>= 400` throws
+// with the parsed body attached) is written out three times verbatim in this
+// package. An operation that lives in one place can be read, tested and
+// overridden in one place.
+//
+// Framework-free on purpose: no Vue, no refs. An op is a plain async function,
+// so it can be checked with `node --test` against `dist/` like the rest of
+// `src/client/`, and reused by a binding that is not Vue at all.
+
+import type { HttpClient } from '../types.js';
+
+/**
+ * What an operation needs to know about the app it runs in, beyond its own
+ * arguments.
+ *
+ * Today each composable takes these as its own options and each consumer
+ * passes them again per page. They are app-wide constants — which is why they
+ * belong in one context rather than in every signature.
+ */
+export interface ResourceContext {
+    /** Admin API root, e.g. `/api/v1/admin`. No trailing slash. */
+    readonly apiBase: string;
+    /** The project whose catalogue is being administered. */
+    readonly projectKey: string;
+    /** Active UI locale, for the operations whose payload is per-language. */
+    readonly locale: string;
+}
+
+/** One operation: everything it needs, in the order it needs it. */
+export type ResourceOp<A extends unknown[], R> = (
+    http: HttpClient,
+    ctx: ResourceContext,
+    ...args: A
+) => Promise<R>;
+
+/** The operations of one resource, keyed by name. */
+export type ResourceOps = Record<string, ResourceOp<never[], unknown>>;
+
+export interface ResourceDef<TOps extends ResourceOps> {
+    /** Name this resource is registered and overridden under. */
+    readonly key: string;
+    readonly ops: TOps;
+    /**
+     * Whether these operations read `ctx.projectKey`.
+     *
+     * Declared per descriptor rather than known centrally, because it is not a
+     * property of the registry: one of the four platform resources is
+     * project-scoped and three are not, and the tenant list would be refused
+     * for a project it never asks about. `bindResource` refuses to bind a
+     * descriptor that declares this against a context that names no project.
+     *
+     * `resources-declare-their-project-scope.test.js` drives every operation
+     * and fails when a declaration and what the operations actually read
+     * disagree — in either direction.
+     */
+    readonly projectScoped: boolean;
+}
+
+/** What a descriptor declares beyond its name and its operations. */
+export interface DefineResourceOptions {
+    /** See `ResourceDef.projectScoped`. Default `false`. */
+    projectScoped?: boolean;
+}
+
+/**
+ * The same operations with `(http, ctx)` already supplied — the form a page or
+ * a composable calls.
+ */
+export type Bound<TOps extends ResourceOps> = {
+    [K in keyof TOps]: TOps[K] extends ResourceOp<infer A, infer R>
+        ? (...args: A) => Promise<R>
+        : never;
+};
+
+/**
+ * Declares a resource.
+ *
+ * Deliberately thin — it exists to name the set and to fix the type, not to
+ * add behaviour. Anything it did at definition time would be a thing an
+ * override could not replace.
+ */
+export function defineResource<const TOps extends ResourceOps>(
+    key: string,
+    ops: TOps,
+    options: DefineResourceOptions = {},
+): ResourceDef<TOps> {
+    return { key, ops, projectScoped: options.projectScoped ?? false };
+}
+
+/**
+ * Refuses a project-scoped resource that has no project to be scoped to.
+ *
+ * An empty `projectKey` is not caught by anything downstream: the request goes
+ * out as `?projectKey=`, and an admin API that filters on it answers a list for
+ * no project at all — a valid-looking empty catalogue, with nothing on screen
+ * saying the shell was misconfigured. The same context then puts `projectKey:
+ * ''` in a create body, where it finally fails validation, one operator action
+ * and one screen later than the mistake.
+ *
+ * `usePlans` has refused this at construction from the start; a page reaching
+ * the same endpoints through the registry did not.
+ */
+function requireProjectKey(
+    def: { key: string; projectScoped: boolean },
+    ctx: ResourceContext,
+): void {
+    if (!def.projectScoped) return;
+    if (typeof ctx.projectKey === 'string' && ctx.projectKey.trim() !== '') return;
+    throw new Error(
+        `Resource "${def.key}" is project-scoped, but the context it is bound to names no ` +
+            'project. Its requests would go out as `?projectKey=`, which the admin API answers ' +
+            'for no project at all: the catalogue reads as empty and the first create fails ' +
+            'validation instead. Name the project this admin administers — `endpoints.projectKey` ' +
+            'for createSuperAdminApp(), `context.projectKey` for createResourceRegistry().',
+    );
+}
+
+/**
+ * Supplies `(http, ctx)` once and hands back the callable operations.
+ *
+ * The context is read at call time rather than captured per operation, so a
+ * context that changes — a locale the operator switches, a project the shell
+ * re-scopes — is picked up by calls made afterwards without rebinding.
+ */
+export function bindResource<TOps extends ResourceOps>(
+    def: ResourceDef<TOps>,
+    http: HttpClient,
+    ctx: ResourceContext | (() => ResourceContext),
+): Bound<TOps> {
+    const readContext = typeof ctx === 'function' ? ctx : () => ctx;
+    // Checked at binding AND before each call, and the two are not redundant.
+    //
+    // Binding is where an app's configuration is handed over, so it is the
+    // moment a missing option can still be reported as one — named at boot
+    // rather than at the click that reads an empty list. But the context is
+    // read per call by design (a locale the operator switches, a project the
+    // shell re-scopes), so a key that is present at boot can be gone later,
+    // and only checking then would send `?projectKey=` after all.
+    //
+    // The getter is consulted only when the resource is project-scoped: the
+    // public contract says the context is read when an operation runs, and a
+    // registry of unscoped resources whose context is built lazily must not be
+    // made to produce one at construction.
+    if (def.projectScoped) requireProjectKey(def, readContext());
+    const bound: Record<string, unknown> = {};
+    for (const [name, op] of Object.entries(def.ops)) {
+        // `async`, so a missing key REJECTS rather than throwing synchronously.
+        // An operation returns a promise, and a caller written as
+        // `plans.list().catch(handle)` would otherwise take an exception where
+        // it expected a rejection — the promise it means to catch never exists.
+        bound[name] = async (...args: never[]) => {
+            const context = readContext();
+            requireProjectKey(def, context);
+            return op(http, context, ...args);
+        };
+    }
+    // The loop cannot express, per key, that it produced exactly the operation
+    // `Bound<TOps>` names — the relationship holds across the whole record, not
+    // one entry at a time.
+    return bound as Bound<TOps>;
+}

package/src/client/resources/index.ts

@@ -0,0 +1,42 @@
+// The resource layer: every admin endpoint defined once, framework-free.
+//
+// Partial by design. The roster this is growing towards covers the whole admin
+// surface, and the descriptors land family by family as the composables that
+// own those endpoints are rebuilt on them — a descriptor nothing calls has
+// nothing keeping it honest.
+//
+// What is here so far: the plan catalogue, the tenant list and the audit
+// trail. What is not: bundles, catalog entries, discovery, marketing, promos,
+// users, pilots, email, subscriptions, dashboard.
+//
+// `tenants` and `audit` are called by `useResourceList`, not by `useTenants`
+// and `useAuditEntries` — those keep their own implementation and their own
+// signatures. The two sides are held to the same request by
+// `tests/resources-match-the-composables.test.js`, which drives both and
+// compares what reaches the client, in either direction.
+
+export * from './define-resource.js';
+export * from './resource-request.js';
+export * from './list-resource.js';
+export * from './plans.resource.js';
+export * from './tenants.resource.js';
+export * from './audit.resource.js';
+
+import { auditResource } from './audit.resource.js';
+import { planVersionsResource, plansResource } from './plans.resource.js';
+import { tenantsResource } from './tenants.resource.js';
+
+/**
+ * Every resource the shell offers by default.
+ *
+ * The registry binds these; an app overrides by key. Partial while the roster
+ * grows — a page whose resource is not here yet keeps its props.
+ */
+export const platformResources = {
+    plans: plansResource,
+    planVersions: planVersionsResource,
+    tenants: tenantsResource,
+    audit: auditResource,
+};
+
+export type PlatformResources = typeof platformResources;