@saasicat/ui-vue 0.26.1 → 0.27.0

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

@@ -0,0 +1,145 @@
+// The bundle catalogue.
+//
+// Same two-stem shape as the plan catalogue, and for the same reason: a
+// version is read and created through its bundle
+// (`catalog/bundles/:bundleId/versions`), while every mutation of an existing
+// version addresses the version directly (`catalog/bundle-versions/:id`).
+//
+// Path parameters are interpolated without encoding, matching `useBundles` and
+// `useBundleVersions`. Encoding them would send ids containing `/`, `#` or `?`
+// to a different URL than they reach today — a behaviour change, and one that
+// belongs in a change that says so. The same note stands on `plans.resource`.
+
+import type {
+    BundleRow,
+    BundleVersionMutationResult,
+    BundleVersionRow,
+    CreateBundleData,
+    CreateBundleVersionDraftData,
+    UpdateBundleData,
+    UpdateBundleVersionDraftData,
+} 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 bundle version goes live. */
+export interface PublishBundleVersionOptions {
+    forceRegressive?: boolean;
+    allowZeroPrice?: boolean;
+    validFrom?: string | null;
+    validUntil?: string | null;
+}
+
+function bundlesUrl(ctx: ResourceContext): string {
+    return `${ctx.apiBase}/catalog/bundles`;
+}
+
+function bundleVersionsUrl(ctx: ResourceContext): string {
+    return `${ctx.apiBase}/catalog/bundle-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 bundle catalogue — read per project, like the plan catalogue.
+ *
+ * `create` takes the project from the context rather than from the caller, for
+ * the reason spelled out on `plansResource.create`: the composable this
+ * replaces made it the caller's job, so `list()` and `create()` read two
+ * different sources for one value and a stale one creates a bundle outside the
+ * project the list is showing.
+ */
+export const bundlesResource = defineResource(
+    'bundles',
+    {
+        list: async (http, ctx): Promise<BundleRow[]> =>
+            (await requestJson<BundleRow[]>(http, scoped(bundlesUrl(ctx), ctx))) ?? [],
+
+        create: (http, ctx, data: Omit<CreateBundleData, 'projectKey'>): Promise<BundleRow> =>
+            requestJsonBody<BundleRow>(http, bundlesUrl(ctx), 'Create returned no body', {
+                method: 'POST',
+                body: { ...data, projectKey: ctx.projectKey },
+            }),
+
+        update: (http, ctx, bundleId: string, data: UpdateBundleData): Promise<BundleRow> =>
+            requestJsonBody<BundleRow>(
+                http,
+                `${bundlesUrl(ctx)}/${bundleId}`,
+                'Update returned no body',
+                { method: 'PATCH', body: data },
+            ),
+
+        /** Marks the bundle deleted. */
+        softDelete: async (http, ctx, bundleId: string): Promise<void> => {
+            await requestJson(http, `${bundlesUrl(ctx)}/${bundleId}`, { method: 'DELETE' });
+        },
+    },
+    { projectScoped: true },
+);
+
+/**
+ * Bundle version lifecycle.
+ *
+ * `publish` is the request only. `useBundleVersions.publish` reloads the list
+ * afterwards, because publishing may supersede another version — but that is
+ * the composable keeping its own refs consistent, not part of the call. A
+ * descriptor operation that issued a second request would make every override
+ * inherit a reload it cannot see, and a page holding no list would pay for one
+ * it does not read.
+ */
+export const bundleVersionsResource = defineResource('bundleVersions', {
+    listForBundle: async (http, ctx, bundleId: string): Promise<BundleVersionRow[]> =>
+        (await requestJson<BundleVersionRow[]>(http, `${bundlesUrl(ctx)}/${bundleId}/versions`)) ??
+        [],
+
+    createDraft: (
+        http,
+        ctx,
+        bundleId: string,
+        data: Omit<CreateBundleVersionDraftData, 'bundleId'>,
+    ): Promise<BundleVersionMutationResult> =>
+        requestJsonBody<BundleVersionMutationResult>(
+            http,
+            `${bundlesUrl(ctx)}/${bundleId}/versions`,
+            'CreateDraft returned no body',
+            { method: 'POST', body: data },
+        ),
+
+    updateDraft: (
+        http,
+        ctx,
+        versionId: string,
+        data: UpdateBundleVersionDraftData,
+    ): Promise<BundleVersionMutationResult> =>
+        requestJsonBody<BundleVersionMutationResult>(
+            http,
+            `${bundleVersionsUrl(ctx)}/${versionId}`,
+            'UpdateDraft returned no body',
+            { method: 'PATCH', body: data },
+        ),
+
+    publish: (
+        http,
+        ctx,
+        versionId: string,
+        options: PublishBundleVersionOptions = {},
+    ): Promise<BundleVersionMutationResult> =>
+        requestJsonBody<BundleVersionMutationResult>(
+            http,
+            `${bundleVersionsUrl(ctx)}/${versionId}/publish`,
+            'Publish returned no body',
+            { method: 'POST', body: options },
+        ),
+
+    /**
+     * Discards a draft. A published version cannot be discarded — the API
+     * answers 422 `BUNDLE_VERSION_ALREADY_PUBLISHED`.
+     */
+    discardDraft: async (http, ctx, versionId: string): Promise<void> => {
+        await requestJson(http, `${bundleVersionsUrl(ctx)}/${versionId}`, { method: 'DELETE' });
+    },
+});

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

@@ -0,0 +1,160 @@
+// The capability / feature / quota catalogue.
+//
+// Every operation but one carries `?projectKey=…`, including the mutations —
+// the keys are unique per project, so the server needs it to address the row.
+// The exception is `syncDiscovery`, whose payload carries the snapshot and
+// whose endpoint takes no query; that asymmetry is the server's.
+//
+// `load()` in `useCatalogEntries` fetches the three lists in one `Promise.all`
+// and writes three refs. Here they are three operations: the descriptor's job
+// is the request, and which of them a caller needs — a page showing only
+// quotas asks for one — is the caller's to decide.
+
+import type {
+    CapabilityCatalogEntryRow,
+    CatalogEntryI18n,
+    DiscoverySnapshot,
+    FeatureCatalogEntryRow,
+    QuotaCatalogEntryRow,
+    ReviewCatalogEntryData,
+    SyncDiscoveryResult,
+    UpdateCatalogEntryBaseData,
+} from '@saasicat/types';
+
+import { defineResource, type ResourceContext } from './define-resource.js';
+import { requestJson, requestJsonBody } from './resource-request.js';
+
+function catalogUrl(ctx: ResourceContext): string {
+    return `${ctx.apiBase}/catalog`;
+}
+
+/** `?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 discovered catalogue and the review decisions taken on it.
+ *
+ * Entry keys are encoded on the way into the path — that is what
+ * `useCatalogEntries` does, and a feature key legitimately contains characters
+ * (`.`, `:`) that a code scan produces.
+ */
+export const catalogResource = defineResource(
+    'catalog',
+    {
+        capabilities: async (http, ctx): Promise<CapabilityCatalogEntryRow[]> =>
+            (await requestJson<CapabilityCatalogEntryRow[]>(
+                http,
+                scoped(`${catalogUrl(ctx)}/capabilities`, ctx),
+            )) ?? [],
+
+        features: async (http, ctx): Promise<FeatureCatalogEntryRow[]> =>
+            (await requestJson<FeatureCatalogEntryRow[]>(
+                http,
+                scoped(`${catalogUrl(ctx)}/features`, ctx),
+            )) ?? [],
+
+        quotas: async (http, ctx): Promise<QuotaCatalogEntryRow[]> =>
+            (await requestJson<QuotaCatalogEntryRow[]>(
+                http,
+                scoped(`${catalogUrl(ctx)}/quotas`, ctx),
+            )) ?? [],
+
+        reviewFeature: (
+            http,
+            ctx,
+            featureKey: string,
+            data: ReviewCatalogEntryData,
+        ): Promise<FeatureCatalogEntryRow> =>
+            requestJsonBody<FeatureCatalogEntryRow>(
+                http,
+                scoped(`${catalogUrl(ctx)}/features/${encodeURIComponent(featureKey)}/review`, ctx),
+                'Review returned no body',
+                { method: 'PATCH', body: data },
+            ),
+
+        reviewQuota: (
+            http,
+            ctx,
+            quotaKey: string,
+            data: ReviewCatalogEntryData,
+        ): Promise<QuotaCatalogEntryRow> =>
+            requestJsonBody<QuotaCatalogEntryRow>(
+                http,
+                scoped(`${catalogUrl(ctx)}/quotas/${encodeURIComponent(quotaKey)}/review`, ctx),
+                'Review returned no body',
+                { method: 'PATCH', body: data },
+            ),
+
+        /** The translations are wrapped in `{ i18n }` here, not by the caller. */
+        setFeatureI18n: (
+            http,
+            ctx,
+            featureKey: string,
+            i18n: CatalogEntryI18n,
+        ): Promise<FeatureCatalogEntryRow> =>
+            requestJsonBody<FeatureCatalogEntryRow>(
+                http,
+                scoped(`${catalogUrl(ctx)}/features/${encodeURIComponent(featureKey)}/i18n`, ctx),
+                'i18n returned no body',
+                { method: 'PATCH', body: { i18n } },
+            ),
+
+        setQuotaI18n: (
+            http,
+            ctx,
+            quotaKey: string,
+            i18n: CatalogEntryI18n,
+        ): Promise<QuotaCatalogEntryRow> =>
+            requestJsonBody<QuotaCatalogEntryRow>(
+                http,
+                scoped(`${catalogUrl(ctx)}/quotas/${encodeURIComponent(quotaKey)}/i18n`, ctx),
+                'i18n returned no body',
+                { method: 'PATCH', body: { i18n } },
+            ),
+
+        setFeatureBase: (
+            http,
+            ctx,
+            featureKey: string,
+            data: UpdateCatalogEntryBaseData,
+        ): Promise<FeatureCatalogEntryRow> =>
+            requestJsonBody<FeatureCatalogEntryRow>(
+                http,
+                scoped(`${catalogUrl(ctx)}/features/${encodeURIComponent(featureKey)}`, ctx),
+                'Base returned no body',
+                { method: 'PATCH', body: data },
+            ),
+
+        setQuotaBase: (
+            http,
+            ctx,
+            quotaKey: string,
+            data: UpdateCatalogEntryBaseData,
+        ): Promise<QuotaCatalogEntryRow> =>
+            requestJsonBody<QuotaCatalogEntryRow>(
+                http,
+                scoped(`${catalogUrl(ctx)}/quotas/${encodeURIComponent(quotaKey)}`, ctx),
+                'Base returned no body',
+                { method: 'PATCH', body: data },
+            ),
+
+        /**
+         * Writes a discovery snapshot into the catalogue.
+         *
+         * The request only. `useCatalogEntries.syncDiscovery` reloads the three
+         * lists afterwards, which is that composable keeping its refs true —
+         * not part of the call, and not something an override should inherit
+         * invisibly.
+         */
+        syncDiscovery: (http, ctx, snapshot: DiscoverySnapshot): Promise<SyncDiscoveryResult> =>
+            requestJsonBody<SyncDiscoveryResult>(
+                http,
+                `${catalogUrl(ctx)}/discovery/sync`,
+                'Sync returned no body',
+                { method: 'POST', body: { snapshot } },
+            ),
+    },
+    { projectScoped: true },
+);

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

@@ -0,0 +1,108 @@
+// The discovery snapshot — what a code scan found, before anyone reviewed it.
+//
+// The one family that does not go through `requestJson`, and the reason is the
+// ETag. `requestJson` collapses "204", "unparsable 2xx" and — since 304 is
+// neither `>= 400` nor 204 — "not modified" into the same `null`, which is
+// right for the catalogue family and wrong here: a caller that cannot tell a
+// cache hit from an empty answer either re-parses a body it does not have or
+// throws away the snapshot it already holds.
+//
+// So these two operations read the status themselves and answer with a
+// discriminated result. The conditional request stays the caller's decision —
+// the descriptor is given the tag it should revalidate against, rather than
+// holding one, because a descriptor is bound once and shared by every page
+// that asks for it.
+
+import { AdminError } from '../admin-error.js';
+import { requireServerAnswer } from '../http-json.js';
+import type { DiscoverySnapshot } from '@saasicat/types';
+
+import { defineResource, type ResourceContext } from './define-resource.js';
+
+/**
+ * The answer to a conditional read.
+ *
+ * `unchanged` carries no snapshot on purpose: the server said the caller's copy
+ * is current, and returning a re-fetched one would defeat the request.
+ */
+export type DiscoveryRead =
+    | { readonly status: 'unchanged' }
+    | {
+          readonly status: 'loaded';
+          readonly snapshot: DiscoverySnapshot;
+          /** `null` when the server sent none — revalidation is then a full read. */
+          readonly etag: string | null;
+      };
+
+function discoveryUrl(ctx: ResourceContext): string {
+    return `${ctx.apiBase}/discovery`;
+}
+
+function fail(status: number, method: string, url: string, message: string): AdminError {
+    return new AdminError({ status, url, method, message });
+}
+
+export const discoveryResource = defineResource('discovery', {
+    /**
+     * Reads the snapshot, revalidating against `etag` when one is passed.
+     *
+     * Pass `null` (or nothing) to force a full read — that is what
+     * `useDiscovery.reload()` does when the operator asks for fresh data.
+     */
+    read: async (http, ctx, etag: string | null = null): Promise<DiscoveryRead> => {
+        const url = discoveryUrl(ctx);
+        const headers: Record<string, string> = {};
+        if (etag) headers['If-None-Match'] = etag;
+
+        const response = await http(url, { method: 'GET', headers });
+        requireServerAnswer(response.status, 'GET', url, (diagnostic) =>
+            fail(response.status, 'GET', url, diagnostic),
+        );
+
+        if (response.status === 304) return { status: 'unchanged' };
+        if (response.status !== 200) {
+            throw fail(
+                response.status,
+                'GET',
+                url,
+                `Discovery endpoint responded with HTTP ${response.status}`,
+            );
+        }
+        return {
+            status: 'loaded',
+            snapshot: (await response.json()) as DiscoverySnapshot,
+            etag: response.headers.get('ETag'),
+        };
+    },
+
+    /**
+     * Re-runs the scan and returns what it found.
+     *
+     * Unconditional by construction: a rescan asks the server to look again,
+     * so revalidating against a tag the previous scan produced would answer
+     * with the snapshot the rescan was meant to replace.
+     */
+    rescan: async (http, ctx): Promise<{ snapshot: DiscoverySnapshot; etag: string | null }> => {
+        const url = `${discoveryUrl(ctx)}/rescan`;
+        const response = await http(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+        });
+        requireServerAnswer(response.status, 'POST', url, (diagnostic) =>
+            fail(response.status, 'POST', url, diagnostic),
+        );
+
+        if (response.status !== 200 && response.status !== 201) {
+            throw fail(
+                response.status,
+                'POST',
+                url,
+                `Discovery rescan responded with HTTP ${response.status}`,
+            );
+        }
+        return {
+            snapshot: (await response.json()) as DiscoverySnapshot,
+            etag: response.headers.get('ETag'),
+        };
+    },
+});

package/src/client/resources/index.ts

@@ -1,41 +1,79 @@
 // 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.
+// The roster is complete for what the platform serves. Three names from the
+// original plan are deliberately absent, and each is absent for a reason a
+// grep can confirm rather than a decision taken here:
 //
-// 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.
+//   - `pilots` — no platform controller serves `/admin/pilots`, and none is
+//     planned. The endpoints exist in one consumer's own backend
+//     (`vereinsfux/apps/api`), which is why `PilotsPage` takes them as props.
+//     A platform default would be an invented API that happens to match one
+//     app and breaks the next.
+//   - `email` — the same, for `/admin/platform-email/*`.
+//   - `dashboard` — the platform does serve `/admin/stats/dashboard`, but
+//     `DashboardPage` never asks for it: every KPI card fetches the `endpoint`
+//     its manifest entry declares. A descriptor with a hardcoded path would
+//     contradict `KpiCardDef.endpoint`, and nothing would call it.
 //
-// `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.
+// What is here instead is one descriptor per family the platform owns, plus
+// the split the sources forced: the plan's single `promos` turned out to be
+// two unrelated resources — `promoCodes` (`/admin/promo-codes`, a string a
+// customer types) and `promotions` (`/admin/catalog/promotions`, a price rule
+// on a catalogue entry). They share four operation names and nothing else.
+//
+// Every descriptor is measured against the implementation it mirrors:
+// `tests/resources-match-the-composables.test.js` drives both sides with the
+// same arguments and compares what reaches the client, in either direction. A
+// descriptor with no such partner is not added — there would be nothing
+// keeping it honest.
 
 export * from './define-resource.js';
 export * from './resource-request.js';
 export * from './list-resource.js';
 export * from './plans.resource.js';
+export * from './bundles.resource.js';
+export * from './catalog.resource.js';
+export * from './discovery.resource.js';
+export * from './marketing.resource.js';
+export * from './promo-codes.resource.js';
+export * from './promotions.resource.js';
 export * from './tenants.resource.js';
+export * from './users.resource.js';
+export * from './subscriptions.resource.js';
 export * from './audit.resource.js';
 
 import { auditResource } from './audit.resource.js';
+import { bundleVersionsResource, bundlesResource } from './bundles.resource.js';
+import { catalogResource } from './catalog.resource.js';
+import { discoveryResource } from './discovery.resource.js';
+import { marketingResource } from './marketing.resource.js';
 import { planVersionsResource, plansResource } from './plans.resource.js';
+import { promoCodesResource } from './promo-codes.resource.js';
+import { promotionsResource } from './promotions.resource.js';
+import { subscriptionsResource } from './subscriptions.resource.js';
 import { tenantsResource } from './tenants.resource.js';
+import { usersResource } from './users.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.
+ * The registry binds these; an app overrides by key. A page whose data is
+ * app-owned — pilots, platform e-mail — keeps its props, because there is no
+ * platform default to override.
  */
 export const platformResources = {
     plans: plansResource,
     planVersions: planVersionsResource,
+    bundles: bundlesResource,
+    bundleVersions: bundleVersionsResource,
+    catalog: catalogResource,
+    discovery: discoveryResource,
+    marketing: marketingResource,
+    promoCodes: promoCodesResource,
+    promotions: promotionsResource,
     tenants: tenantsResource,
+    users: usersResource,
+    subscriptions: subscriptionsResource,
     audit: auditResource,
 };
 

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

@@ -0,0 +1,121 @@
+// Marketing projections and the locale settings that go with them.
+//
+// Two endpoints under one key because they are one screen's data:
+// `MarketingCatalogPage` reads the projections and the active-locale set
+// together, and today it reaches the second one with a hand-written `fetch`
+// through its own `httpClient` prop while the first goes through
+// `useMarketingProjections`. One resource, two stems.
+//
+// The list filter keeps the composable's parameter order — `projectKey`,
+// `targetType`, `targetVersionId`, `locale` — because that is the URL the
+// page requests today and a reordered query string is a different request to
+// anything that caches or logs one.
+
+import type {
+    CreateMarketingProjectionData,
+    MarketingProjectionRow,
+    MarketingSettingsRow,
+    UpdateMarketingProjectionData,
+} from '@saasicat/types';
+
+import { defineResource, type ResourceContext } from './define-resource.js';
+import { requestJson, requestJsonBody } from './resource-request.js';
+
+/**
+ * What the projection list can be narrowed by, beyond the bound project.
+ *
+ * `projectKey` is deliberately absent: it comes from the context, so a page
+ * cannot list one project's projections while creating in another.
+ */
+export interface MarketingProjectionsFilter {
+    targetType?: string;
+    targetVersionId?: string;
+    locale?: string;
+}
+
+function projectionsUrl(ctx: ResourceContext): string {
+    return `${ctx.apiBase}/catalog/marketing-projections`;
+}
+
+function settingsUrl(ctx: ResourceContext): string {
+    return `${ctx.apiBase}/catalog/marketing-settings`;
+}
+
+export const marketingResource = defineResource(
+    'marketing',
+    {
+        listProjections: async (
+            http,
+            ctx,
+            filter: MarketingProjectionsFilter = {},
+        ): Promise<MarketingProjectionRow[]> => {
+            const params = new URLSearchParams();
+            params.set('projectKey', ctx.projectKey);
+            if (filter.targetType) params.set('targetType', filter.targetType);
+            if (filter.targetVersionId) params.set('targetVersionId', filter.targetVersionId);
+            if (filter.locale) params.set('locale', filter.locale);
+            return (
+                (await requestJson<MarketingProjectionRow[]>(
+                    http,
+                    `${projectionsUrl(ctx)}?${params.toString()}`,
+                )) ?? []
+            );
+        },
+
+        /**
+         * The request only. `useMarketingProjections.create` reloads the list
+         * afterwards because a unique-tuple insert can change what the filter
+         * matches — that is the composable keeping its refs true, not part of
+         * the call.
+         */
+        createProjection: (
+            http,
+            ctx,
+            data: CreateMarketingProjectionData,
+        ): Promise<MarketingProjectionRow> =>
+            requestJsonBody<MarketingProjectionRow>(
+                http,
+                projectionsUrl(ctx),
+                'Create returned no body',
+                { method: 'POST', body: data },
+            ),
+
+        updateProjection: (
+            http,
+            ctx,
+            id: string,
+            data: UpdateMarketingProjectionData,
+        ): Promise<MarketingProjectionRow> =>
+            requestJsonBody<MarketingProjectionRow>(
+                http,
+                `${projectionsUrl(ctx)}/${id}`,
+                'Update returned no body',
+                { method: 'PATCH', body: data },
+            ),
+
+        deleteProjection: async (http, ctx, id: string): Promise<void> => {
+            await requestJson(http, `${projectionsUrl(ctx)}/${id}`, { method: 'DELETE' });
+        },
+
+        /**
+         * The activated locale subset, or `null` when none was ever stored.
+         *
+         * `null` means the full pool is active — the server's answer for "no
+         * row", and the state the page falls back to.
+         */
+        settings: (http, ctx): Promise<MarketingSettingsRow | null> =>
+            requestJson<MarketingSettingsRow>(
+                http,
+                `${settingsUrl(ctx)}?projectKey=${encodeURIComponent(ctx.projectKey)}`,
+            ),
+
+        /** `PUT`, not `PATCH`: the endpoint replaces the set it is given. */
+        saveSettings: async (http, ctx, activeLocales: readonly string[]): Promise<void> => {
+            await requestJson(http, settingsUrl(ctx), {
+                method: 'PUT',
+                body: { projectKey: ctx.projectKey, activeLocales },
+            });
+        },
+    },
+    { projectScoped: true },
+);