@saasicat/spec 0.2.0

package/schemas/audit-event.schema.json

@@ -0,0 +1,73 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://saasicat.dev/schemas/audit-event.schema.json",
+    "title": "AuditEvent",
+    "description": "Language-neutral format of an AuditLog entry. Each consumer app has its own AuditLog table, same structure.",
+    "type": "object",
+    "required": ["id", "entity", "entityId", "action", "createdAt"],
+    "additionalProperties": false,
+    "properties": {
+        "id": { "type": "string", "format": "uuid" },
+        "tenantId": {
+            "type": ["string", "null"],
+            "description": "null = platform action (e.g. SUPER_ADMIN without tenant context)."
+        },
+        "userId": {
+            "type": ["string", "null"],
+            "description": "null = system / cron-triggered."
+        },
+        "userEmail": {
+            "type": ["string", "null"],
+            "format": "email",
+            "description": "Convenience lookup for display; backend resolves from userId."
+        },
+        "entity": {
+            "type": "string",
+            "description": "e.g. 'Tenant', 'PromoCode', 'Subscription', 'PlanVersion', 'User'."
+        },
+        "entityId": { "type": "string" },
+        "action": {
+            "type": "string",
+            "pattern": "^[A-Z][A-Z0-9_]+$",
+            "description": "SCREAMING_SNAKE_CASE, past-tense oriented. Examples: TENANT_SUSPEND, PILOT_GRANT, PROMO_CODE_CREATE, PLAN_VERSION_PUBLISH."
+        },
+        "changes": {
+            "type": ["object", "null"],
+            "description": "Freely structured JSON. Convention for field diffs: { field: { old, new } }. For workflow actions: { reason, actor_tag, ... }.",
+            "additionalProperties": true
+        },
+        "actorTag": {
+            "type": ["string", "null"],
+            "description": "Origin marker. Format: 'web:<email>:<sessionId>' or 'cli:<email>:<host>'."
+        },
+        "ipAddress": { "type": ["string", "null"] },
+        "userAgent": { "type": ["string", "null"] },
+        "createdAt": { "type": "string", "format": "date-time" }
+    },
+
+    "$defs": {
+        "ActorTagPattern": {
+            "type": "string",
+            "pattern": "^(web|cli):[^:]+:[^:]+$",
+            "description": "Mandatory format for actorTag."
+        },
+
+        "AuditQuery": {
+            "type": "object",
+            "description": "Query parameters for GET /api/v1/admin/audit. Template admin-api.openapi.yaml.",
+            "additionalProperties": false,
+            "properties": {
+                "tenantId": { "type": "string" },
+                "userId": { "type": "string" },
+                "entity": { "type": "string" },
+                "entityId": { "type": "string" },
+                "action": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" },
+                "actorTag": { "type": "string", "description": "Wildcard-capable, e.g. 'cli:*'." },
+                "from": { "type": "string", "format": "date-time" },
+                "to": { "type": "string", "format": "date-time" },
+                "page": { "type": "integer", "minimum": 1, "default": 1 },
+                "pageSize": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }
+            }
+        }
+    }
+}

package/schemas/plan-catalog.schema.json

@@ -0,0 +1,166 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://saasicat.dev/schemas/plan-catalog.schema.json",
+    "title": "PlanCatalog",
+    "description": "Language-neutral definition of a plan catalog + app identity for a SaaS app. Maintained by the consumer as a YAML/JSON file (`config/saas.yaml`) and mirrored into platform tables at backend boot.",
+    "type": "object",
+    "required": ["schemaVersion", "projectKey", "currency", "vatRate"],
+    "additionalProperties": false,
+    "properties": {
+        "schemaVersion": {
+            "type": "integer",
+            "const": 1
+        },
+        "projectKey": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]{1,30}$",
+            "description": "Unique key of the consuming project. Cross-audit marker."
+        },
+        "app": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "App identity block (branding + version). Consumed by AdminPublicBootController + AdminManifestConfigFactory.",
+            "required": ["name"],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Brand display name (e.g. \"My App\")."
+                },
+                "label": {
+                    "type": "string",
+                    "description": "Tag/subtitle in the brand block (e.g. \"SuperAdmin\")."
+                },
+                "version": {
+                    "type": "string",
+                    "description": "App version string (build info)."
+                },
+                "icon": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 8,
+                    "description": "Short abbreviation for the logo badge (e.g. \"ma\", \"da\")."
+                },
+                "logoUrl": {
+                    "type": "string",
+                    "format": "uri-reference",
+                    "description": "Optional URL to PNG/SVG; when set, the UI renders an <img> instead of the initials badge."
+                }
+            }
+        },
+        "currency": {
+            "type": "string",
+            "pattern": "^[A-Z]{3}$",
+            "description": "ISO 4217 currency code. EUR-only in phase 1."
+        },
+        "vatRate": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 100,
+            "description": "VAT rate in percent. Required (even when 0)."
+        },
+        "marketing": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "App-wide marketing configuration. SPEC_V2 §6.5.",
+            "required": ["availableLocales"],
+            "properties": {
+                "availableLocales": {
+                    "type": "array",
+                    "items": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "description": "Allowed language pool the app may market. First = default locale. From it the SuperAdmin activates a subset in the marketing catalog (LocaleManager)."
+                }
+            }
+        },
+        "features": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/FeatureDef" },
+            "description": "Master list of all feature flags of the project. Plans may only reference keys declared here."
+        },
+        "plans": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/PlanDef" },
+            "description": "Optional. When omitted, plans come exclusively from the AdminUI / DB."
+        }
+    },
+
+    "$defs": {
+        "FeatureDef": {
+            "type": "object",
+            "required": ["key"],
+            "additionalProperties": false,
+            "properties": {
+                "key": {
+                    "type": "string",
+                    "pattern": "^[A-Z][A-Z0-9_]+$",
+                    "description": "SCREAMING_SNAKE_CASE; unique per catalog."
+                },
+                "label": { "type": "string", "minLength": 1 },
+                "icon": { "type": "string" },
+                "tier": {
+                    "type": "string",
+                    "description": "Optional logical group. Convention: CORE / ADVANCED / PRO / BUSINESS / ENTERPRISE_ONLY."
+                },
+                "plannedOnly": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Marks that the feature is not in production (no plan or bundle references it)."
+                }
+            }
+        },
+
+        "PlanDef": {
+            "type": "object",
+            "required": ["id", "quotas", "features"],
+            "additionalProperties": false,
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "pattern": "^[A-Z][A-Z0-9_]+$",
+                    "description": "Plan ID. Freely chosen by the consumer (BASIC, STANDARD, ...). Ends up as a string in Subscription.plan."
+                },
+                "name": { "type": "string", "minLength": 1 },
+                "tagline": { "type": "string" },
+                "marketed": {
+                    "type": "boolean",
+                    "default": true,
+                    "description": "false = not selectable in self-service onboarding (e.g. ENTERPRISE)."
+                },
+                "popular": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Highlighted card in onboarding (max. 1 per catalog)."
+                },
+                "monthlyNet": {
+                    "type": ["number", "null"],
+                    "minimum": 0,
+                    "description": "Net monthly price. null = on request (sales contact)."
+                },
+                "yearlyNet": {
+                    "type": ["number", "null"],
+                    "minimum": 0,
+                    "description": "Net total amount per year for BillingCycle=YEARLY (not the effective monthly price). null = monthly only."
+                },
+                "quotas": {
+                    "type": "object",
+                    "patternProperties": {
+                        "^[a-z][A-Za-z0-9]*$": {
+                            "type": "integer",
+                            "description": "-1 = unlimited; 0 = not allowed; >0 = hard upper limit."
+                        }
+                    },
+                    "additionalProperties": false,
+                    "minProperties": 1
+                },
+                "features": {
+                    "type": "array",
+                    "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" },
+                    "uniqueItems": true,
+                    "description": "List of included feature keys; all must exist in features[].key."
+                }
+            }
+        }
+    }
+}

package/schemas/promo-code.schema.json

@@ -0,0 +1,214 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://saasicat.dev/schemas/promo-code.schema.json",
+    "title": "PromoCode",
+    "description": "Language-neutral definition of promo codes for the SaaS platform, including redemption lifecycle.",
+    "type": "object",
+    "$defs": {
+        "ValueType": {
+            "type": "string",
+            "enum": ["PERCENT", "ABSOLUTE"],
+            "description": "PERCENT: value is a percentage (1–100). ABSOLUTE: value is a net amount in the catalog currency."
+        },
+
+        "DurationType": {
+            "type": "string",
+            "enum": ["ONCE", "MONTHS", "BILLING_CYCLES"],
+            "description": "ONCE: one-time discount. MONTHS: durationValue months from redemption. BILLING_CYCLES: durationValue billing cycles."
+        },
+
+        "Status": {
+            "type": "string",
+            "enum": ["ACTIVE", "PAUSED", "EXHAUSTED", "EXPIRED"]
+        },
+
+        "BillingCycle": {
+            "type": "string",
+            "enum": ["MONTHLY", "YEARLY"]
+        },
+
+        "RedemptionStatus": {
+            "type": "string",
+            "enum": ["ACTIVE", "REVERSED", "EXPIRED"]
+        },
+
+        "ValidationResult": {
+            "type": "string",
+            "enum": [
+                "VALID",
+                "EXPIRED",
+                "EXHAUSTED",
+                "NOT_FOUND",
+                "PAUSED",
+                "NOT_APPLICABLE",
+                "FIRST_TIME_ONLY",
+                "ZERO_INVOICE_BLOCKED",
+                "MIN_AMOUNT_NOT_REACHED",
+                "RATE_LIMITED"
+            ]
+        },
+
+        "CreatePromoCodeRequest": {
+            "type": "object",
+            "required": ["code", "valueType", "value", "durationType"],
+            "additionalProperties": false,
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "pattern": "^[A-Z0-9_-]{4,32}$",
+                    "description": "Uppercase letters, digits, '-' and '_'. Checked case-insensitively, stored in UPPER."
+                },
+                "valueType": { "$ref": "#/$defs/ValueType" },
+                "value": {
+                    "type": "number",
+                    "exclusiveMinimum": 0,
+                    "multipleOf": 0.01,
+                    "description": "For PERCENT: 0.01–100. For ABSOLUTE: > 0 in catalog currency."
+                },
+                "durationType": { "$ref": "#/$defs/DurationType" },
+                "durationValue": {
+                    "type": ["integer", "null"],
+                    "minimum": 1,
+                    "maximum": 24,
+                    "description": "Required for MONTHS / BILLING_CYCLES, null for ONCE."
+                },
+                "validFrom": { "type": ["string", "null"], "format": "date-time" },
+                "validUntil": { "type": ["string", "null"], "format": "date-time" },
+                "maxRedemptions": { "type": ["integer", "null"], "minimum": 1 },
+                "appliesToPlans": {
+                    "type": "array",
+                    "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" },
+                    "uniqueItems": true,
+                    "description": "Empty = all plans."
+                },
+                "appliesToBilling": {
+                    "anyOf": [{ "$ref": "#/$defs/BillingCycle" }, { "type": "null" }]
+                },
+                "firstTimeCustomersOnly": { "type": "boolean", "default": true },
+                "minimumPlanAmountGross": {
+                    "type": ["number", "null"],
+                    "exclusiveMinimum": 0,
+                    "multipleOf": 0.01
+                },
+                "allowZeroInvoice": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Default: discount must not reduce the invoice to 0."
+                },
+                "description": { "type": ["string", "null"], "maxLength": 1000 },
+                "campaignTag": { "type": ["string", "null"], "maxLength": 100 },
+                "revenueDeductionAccount": {
+                    "type": ["string", "null"],
+                    "maxLength": 16,
+                    "description": "SKR account for accounting; project-specific."
+                }
+            }
+        },
+
+        "UpdatePromoCodeRequest": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "status": {
+                    "type": "string",
+                    "enum": ["ACTIVE", "PAUSED"]
+                },
+                "description": { "type": ["string", "null"], "maxLength": 1000 },
+                "validUntil": { "type": ["string", "null"], "format": "date-time" },
+                "maxRedemptions": { "type": ["integer", "null"], "minimum": 1 },
+                "campaignTag": { "type": ["string", "null"], "maxLength": 100 }
+            }
+        },
+
+        "PromoCode": {
+            "type": "object",
+            "required": [
+                "id",
+                "code",
+                "valueType",
+                "value",
+                "durationType",
+                "status",
+                "redemptionsCount"
+            ],
+            "additionalProperties": false,
+            "properties": {
+                "id": { "type": "string", "format": "uuid" },
+                "code": { "type": "string", "pattern": "^[A-Z0-9_-]{4,32}$" },
+                "valueType": { "$ref": "#/$defs/ValueType" },
+                "value": { "type": "number", "exclusiveMinimum": 0 },
+                "durationType": { "$ref": "#/$defs/DurationType" },
+                "durationValue": { "type": ["integer", "null"], "minimum": 1, "maximum": 24 },
+                "validFrom": { "type": ["string", "null"], "format": "date-time" },
+                "validUntil": { "type": ["string", "null"], "format": "date-time" },
+                "maxRedemptions": { "type": ["integer", "null"], "minimum": 1 },
+                "redemptionsCount": { "type": "integer", "minimum": 0 },
+                "appliesToPlans": {
+                    "type": "array",
+                    "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$" }
+                },
+                "appliesToBilling": {
+                    "anyOf": [{ "$ref": "#/$defs/BillingCycle" }, { "type": "null" }]
+                },
+                "firstTimeCustomersOnly": { "type": "boolean" },
+                "minimumPlanAmountGross": { "type": ["number", "null"] },
+                "allowZeroInvoice": { "type": "boolean" },
+                "status": { "$ref": "#/$defs/Status" },
+                "description": { "type": ["string", "null"] },
+                "campaignTag": { "type": ["string", "null"] },
+                "revenueDeductionAccount": { "type": ["string", "null"] },
+                "createdAt": { "type": "string", "format": "date-time" },
+                "deletedAt": { "type": ["string", "null"], "format": "date-time" }
+            }
+        },
+
+        "PromoCodeRedemption": {
+            "type": "object",
+            "required": [
+                "id",
+                "promoCodeId",
+                "subscriptionId",
+                "tenantId",
+                "appliedValueType",
+                "appliedValue",
+                "status",
+                "redeemedAt"
+            ],
+            "additionalProperties": false,
+            "properties": {
+                "id": { "type": "string", "format": "uuid" },
+                "promoCodeId": { "type": "string", "format": "uuid" },
+                "subscriptionId": { "type": "string", "format": "uuid" },
+                "tenantId": { "type": "string" },
+                "appliedValueType": { "$ref": "#/$defs/ValueType" },
+                "appliedValue": { "type": "number" },
+                "appliedDurationType": { "$ref": "#/$defs/DurationType" },
+                "appliedDurationValue": { "type": ["integer", "null"] },
+                "startsAt": { "type": "string", "format": "date-time" },
+                "endsAt": { "type": ["string", "null"], "format": "date-time" },
+                "status": { "$ref": "#/$defs/RedemptionStatus" },
+                "redeemedAt": { "type": "string", "format": "date-time" },
+                "reversedAt": { "type": ["string", "null"], "format": "date-time" }
+            }
+        },
+
+        "PromoCodeValidationLog": {
+            "type": "object",
+            "required": ["id", "codeAttempt", "result", "createdAt"],
+            "additionalProperties": false,
+            "properties": {
+                "id": { "type": "string", "format": "uuid" },
+                "promoCodeId": {
+                    "type": ["string", "null"],
+                    "format": "uuid",
+                    "description": "null for NOT_FOUND"
+                },
+                "codeAttempt": { "type": "string" },
+                "ipHash": { "type": ["string", "null"], "description": "no plaintext IP" },
+                "sessionId": { "type": ["string", "null"] },
+                "result": { "$ref": "#/$defs/ValidationResult" },
+                "createdAt": { "type": "string", "format": "date-time" }
+            }
+        }
+    }
+}