@saasicat/cli 0.26.0 → 0.27.0

package/templates/init/config/saas.yaml.tpl

@@ -0,0 +1,30 @@
+schemaVersion: 1
+projectKey: __PROJECT_KEY__
+
+app:
+    name: __APP_LABEL__
+    label: __APP_LABEL__ Cockpit
+
+currency: EUR
+vatRate: 19.0
+
+marketing:
+    availableLocales: [en]
+
+# The quickstart path: plans live here, and `loadPlanCatalogFromFile` reads
+# them at boot. Apps that let operators manage plans in the SuperAdmin UI drop
+# this block and pass `dbCatalog` instead — see docs/quickstart.md.
+plans:
+    - id: STARTER
+      name: Starter
+      monthlyNet: 9
+      yearlyNet: 90
+      features: [__FEATURE_KEY__]
+      quotas:__STARTER_QUOTAS__
+    - id: PRO
+      name: Pro
+      popular: true
+      monthlyNet: 29
+      yearlyNet: 290
+      features: [__FEATURE_KEY__]
+      quotas:__PRO_QUOTAS__

package/templates/init/src/auth/password.hasher.ts.tpl

@@ -0,0 +1,33 @@
+import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
+import { Injectable } from '@nestjs/common';
+import type { PasswordHasher } from '@saasicat/types';
+
+const KEY_LENGTH = 64;
+
+/**
+ * scrypt, so the SuperAdmin setup wizard works before you have decided.
+ *
+ * Deliberately not a default the platform ships: hashing is a decision with
+ * consequences, and a framework that picks one for you picks it for everyone.
+ * For production, argon2id with tuned parameters — this class is the seam.
+ */
+@Injectable()
+export class __HASHER_CLASS__ implements PasswordHasher {
+    async hash(plain: string): Promise<string> {
+        const salt = randomBytes(16).toString('hex');
+        const derived = scryptSync(plain, salt, KEY_LENGTH).toString('hex');
+        return `scrypt:${salt}:${derived}`;
+    }
+
+    async verify(hash: string, plain: string): Promise<boolean> {
+        const [scheme, salt, derived] = hash.split(':');
+        if (scheme !== 'scrypt' || !salt || !derived) return false;
+        const candidate = scryptSync(plain, salt, KEY_LENGTH);
+        const stored = Buffer.from(derived, 'hex');
+        // `timingSafeEqual` THROWS on unequal lengths, so a truncated or
+        // corrupted stored hash would be a 500 rather than a failed login.
+        // The length is not a secret; comparing it first leaks nothing.
+        if (stored.length !== candidate.length) return false;
+        return timingSafeEqual(candidate, stored);
+    }
+}

package/templates/init/src/saas/admin-manifest.contribution.ts.tpl

@@ -0,0 +1,33 @@
+import type { ManifestContribution } from '@saasicat/types';
+
+/**
+ * What this app adds to the SuperAdmin UI.
+ *
+ * The platform derives capabilities for every standard module it mounts —
+ * discovery, catalogue, tenants, users, audit, subscriptions, promo codes.
+ * What it cannot derive is anything of yours, so this file is where an
+ * app-specific dashboard card or project page is declared.
+ *
+ * Without a registered contribution the sidebar is empty: the nav builder
+ * drops every page whose `requiredCapability` is not `true`.
+ */
+export const __MANIFEST_CONST__: ManifestContribution = {
+    capabilities: {
+        'dashboard.read': true,
+    },
+
+    dashboard: {
+        kpiCards: [
+            {
+                id: '__PROJECT_KEY__.tenants',
+                label: 'Tenants',
+                // Served by your own controller — the platform does not know
+                // what your KPIs count.
+                endpoint: '__API_BASE__/stats/tenants',
+                displayHint: { type: 'value', icon: 'business' },
+                slotPriority: 90,
+                requiredCapability: 'dashboard.read',
+            },
+        ],
+    },
+};

package/templates/init/src/saas/admin.module.ts.tpl

@@ -0,0 +1,24 @@
+import { Module, type OnModuleInit } from '@nestjs/common';
+// From `/platform`, not `/admin`: the CJS bundles do not share code between
+// entries, so only this entry hands out the same class object that
+// `SaaSiCatModule` registered.
+import { AdminManifestService } from '@saasicat/nest/platform';
+
+import { __MANIFEST_CONST__ } from './admin-manifest.contribution';
+
+/**
+ * Registers this app's manifest contribution.
+ *
+ * Add the controllers that serve your dashboard KPIs here — the contribution
+ * declares the cards, this module is what mounts the endpoints they point at.
+ */
+@Module({
+    controllers: [],
+})
+export class __ADMIN_MODULE_CLASS__ implements OnModuleInit {
+    constructor(private readonly manifest: AdminManifestService) {}
+
+    onModuleInit(): void {
+        this.manifest.register(__MANIFEST_CONST__);
+    }
+}

package/templates/init/src/saas/feature-ui-registry.ts.tpl

@@ -0,0 +1,16 @@
+import type { FeatureUiRegistry } from '@saasicat/types';
+
+/**
+ * Labels and icons for the feature and quota keys discovery finds in your code.
+ *
+ * It does not decide what exists — the `@RequireFeature` and `@DefinesQuota`
+ * decorators do, and the scanner reads them at boot. This only stops the
+ * SuperAdmin catalogue from showing raw keys. Icons are Material Symbols names.
+ */
+export const __REGISTRY_CONST__: FeatureUiRegistry = {
+    __FEATURE_KEY__: {
+        label: '__APP_LABEL__',
+        description: 'What this feature lets a tenant do.',
+        icon: 'check_circle',
+    },
+};

package/templates/init/src/saas/persistence-without-hasher.ts.tpl

@@ -0,0 +1,24 @@
+import { prismaPersistence } from '@saasicat/adapter-prisma';
+
+import { PrismaService } from '../prisma/prisma.service';
+
+/**
+ * Every repository the platform needs, from one Prisma client.
+ *
+ * The `--skip-hasher` variant. The bundle is still generated — an app without
+ * one fails `core.adapters-bound` on its first boot — but it names no hasher,
+ * because you said you have your own.
+ *
+ * Bind it before the SuperAdmin setup wizard or self-registration runs: both
+ * write a password, and neither can do it without one.
+ */
+export const persistence = prismaPersistence({
+    client: PrismaService,
+    // passwordHasher: YourHasher,
+    // If your models are called something else, map them here:
+    // `adminResources: { delegates: { tenant: 'organization' },
+    //                    fields: { tenant: { users: 'members' } } }`
+    // — see docs/migrating-an-existing-app.md. Left out on purpose otherwise:
+    // the tenant row counter defaults to whatever the mapping says the users
+    // relation is called, and naming it here would hardcode `users` past that.
+});

package/templates/init/src/saas/persistence.ts.tpl

@@ -0,0 +1,22 @@
+import { prismaPersistence } from '@saasicat/adapter-prisma';
+
+import { PrismaService } from '../prisma/prisma.service';
+import { __HASHER_CLASS__ } from '../auth/__HASHER_FILE__';
+
+/**
+ * Every repository the platform needs, from one Prisma client.
+ *
+ * Split out of `app.module.ts` so the wiring is one import there and the
+ * decisions are visible here: which client, which hasher, and what the
+ * SuperAdmin tenant list counts.
+ */
+export const persistence = prismaPersistence({
+    client: PrismaService,
+    passwordHasher: __HASHER_CLASS__,
+    // If your models are called something else, map them here:
+    // `adminResources: { delegates: { tenant: 'organization' },
+    //                    fields: { tenant: { users: 'members' } } }`
+    // — see docs/migrating-an-existing-app.md. Left out on purpose otherwise:
+    // the tenant row counter defaults to whatever the mapping says the users
+    // relation is called, and naming it here would hardcode `users` past that.
+});

package/templates/init/src/saas/quota.provider.ts.tpl

@@ -0,0 +1,31 @@
+import { Injectable } from '@nestjs/common';
+import { DefinesQuota } from '@saasicat/nest/discovery';
+import type { QuotaProvider } from '@saasicat/types';
+
+import { PrismaService } from '../prisma/prisma.service';
+
+/**
+ * What is countable, and how to count it.
+ *
+ * The decorator is the single source of truth — discovery reads it at boot and
+ * the quota becomes reviewable in the SuperAdmin UI. `count()` is what
+ * `@EnforceQuota('__QUOTA_KEY__')` calls at request time, so it has to be cheap.
+ */
+@Injectable()
+@DefinesQuota({
+    key: '__QUOTA_KEY__',
+    label: '__QUOTA_LABEL__',
+    unit: 'count',
+    // continuous | monthlyReset | hardCap — hardCap refuses at the limit.
+    policy: 'hardCap',
+    feature: '__FEATURE_KEY__',
+})
+export class __QUOTA_CLASS__ implements QuotaProvider {
+    readonly key = '__QUOTA_KEY__';
+
+    constructor(private readonly prisma: PrismaService) {}
+
+    async count(tenantId: string): Promise<number> {
+        return this.prisma.__QUOTA_MODEL__.count({ where: { tenantId } });
+    }
+}