@antelopejs/interface-dms-saas 0.3.0 → 0.4.1

package/docs/3.lifecycle-and-usage.md

@@ -0,0 +1,95 @@
+---
+title: Lifecycle and usage
+description: Registration extras, durable workspace lifecycle consumers and idempotent invoice usage providers.
+---
+
+# Lifecycle and usage
+
+Use the direct subpaths below or the root's `invoiceLineItems` and `workspaceLifecycle` namespaces. Register consumers/providers from the owning module's lifecycle, not a request handler. Registrations replay when SaaS attaches or reloads and are released when their owner unloads.
+
+## Invoice line items
+
+Import from `/invoice-line-items`. `RegisterInvoiceLineItemsProvider(provider: InvoiceLineItemsProvider): void` registers `{ id: string, resolve: InvoiceLineItemsResolver }`. `UnregisterInvoiceLineItemsProvider(providerId: string): void` removes it; unknown IDs are ignored. Register during `construct()` and unregister during `stop()`.
+
+```ts [Contract]
+interface InvoiceLineItemsContext {
+  tenantId: string;
+  invoiceId: string;
+  currency: string;
+  periodStart: Date;
+  periodEnd: Date;
+  isPreview?: boolean;
+}
+
+interface InvoiceLineItem {
+  key: string;
+  description: string;
+  amountCents: number;
+  quantity?: number;
+  unit?: string;
+  metadata?: Record<string, string>;
+}
+
+type InvoiceLineItemsResolver = (
+  context: InvoiceLineItemsContext,
+) => Promise<InvoiceLineItem[]> | InvoiceLineItem[];
+```
+
+The runtime asks providers for `subscription_cycle` renewal invoices, not initial or one-off invoices. The dates cover the cycle just closed, clipped to the subscription's paid usage period. Complimentary/grace usage is excluded; no provider runs for an empty covered window. Read tenant-scoped, pre-aggregated usage because the resolver runs inside the webhook request.
+
+`amountCents` is the safe-integer line total in the invoice currency, including negative credits. Quantity and unit are audit metadata, not factors multiplied into the total. Zero amounts are dropped. Empty keys/descriptions, non-safe-integer amounts, keys containing `:`, or combined keys over 150 characters are invalid. Provider IDs must not contain `:`; registration throws if they do. IDs must be globally unique across modules: a collision replaces the earlier provider, and collisions before attachment can collapse silently.
+
+Keep each line key stable. The runtime injects at most one line per invoice/provider/key across webhook replays and concurrent workers. A throwing provider is logged and skipped so others can run, but partial/invalid injection ultimately fails the webhook to expose underbilling. Returning lines is not a guarantee that Stripe accepted the invoice items.
+
+Preview calls set `isPreview: true`, use a synthetic `upcoming_<subscription id>` invoice ID, and end at the request time. They quote usage without invoicing it. Do not mutate usage accounting inside a resolver. A failed resolver or invalid line makes the preview unavailable.
+
+### Line helpers
+
+`LINE_KEY_SEPARATOR` is `":"`. `buildInvoiceLineKey(providerId: string, key: string): string` joins the two fragments; it does not validate them.
+
+`selectInvoiceLineItemsToCreate(providerId: string, items: readonly InvoiceLineItem[], alreadyInjectedKeys: ReadonlySet<string>): InvoiceLineItemSelection` is synchronous and has no Stripe side effects. It returns `accepted: PreparedInvoiceLineItem[]` (`{ lineKey, item }`, with trimmed item keys) and `skipped: SkippedInvoiceLineItem[]` (`{ lineKey, reason }`). `SkippedLineItemReason` is `already_invoiced`, `duplicate_key`, `zero_amount`, or `invalid`. The set must contain full provider-prefixed keys. This selection helper does not itself provide transactional idempotency.
+
+## Workspace lifecycle
+
+Import from `/workspace-lifecycle`. `WORKSPACE_LIFECYCLE_TRANSITIONS` contains `created`, `suspended` and `reactivation_requested`; `WorkspaceLifecycleTransition` is their union.
+
+```ts [Contract]
+import type { WorkspaceLifecycleTransition } from "@antelopejs/interface-dms-saas/workspace-lifecycle";
+
+interface WorkspaceLifecycleMessage {
+  tenantId: string;
+  operationId: string;
+  transition: WorkspaceLifecycleTransition;
+  requestedAt: Date;
+}
+interface WorkspaceLifecycleReceipt {
+  receiptId: string;
+  effectiveAt?: Date;
+}
+interface WorkspaceLifecycleConsumer {
+  name: string;
+  transitions: readonly WorkspaceLifecycleTransition[];
+  consume(message: WorkspaceLifecycleMessage): Promise<WorkspaceLifecycleReceipt>;
+}
+interface WorkspaceLifecycleConsumerRegistration { unregister(): void; }
+
+declare function RegisterWorkspaceLifecycleConsumer(
+  consumer: WorkspaceLifecycleConsumer,
+): WorkspaceLifecycleConsumerRegistration;
+declare function UnregisterWorkspaceLifecycleConsumer(name: string): void;
+declare function IsWorkspaceProvisioningCommitted(tenantId: string): Promise<boolean>;
+```
+
+Names must match `/^[a-z][a-z0-9._-]{2,63}$/`; invalid names throw synchronously. Pick a stable unique name and explicitly select transitions. Unregister via the returned handle or by name when the module stops.
+
+Delivery is **at least once**. Deduplicate by `operationId`, durably link provisioned resources, then return a durable receipt. A rejection is not an acknowledgement. Suspension closes SaaS access before delivery; reactivation keeps access closed until every registered required consumer returns a receipt. `created` arrives after ownership, billing and pre-provisioning hooks succeed and the first invoice is paid, or no payment is required.
+
+`IsWorkspaceProvisioningCommitted` returns false for preparing, unpaid or cancelled self-service workspaces; true for committed creations and legacy/bootstrap tenants without a marker. It is not an existence, membership or access check. Storage and missing-implementation errors propagate; fail closed instead of treating an unavailable check as eligibility.
+
+## Registration and provisioning
+
+`TenantBeingProvisionedPayload` from `/provisioning` has `tenantId: string`, `userId: string`, and optional `extras: Record<string, unknown>`. Use it with the DMS `Hook.TENANT_BEING_PROVISIONED` hook; the hook handler returns `Promise<undefined>`, not `Promise<void>`.
+
+Listeners run serially inside provisioning, while the per-card lock is held, after workspace records exist but before registration returns. A throwing listener cancels registration and rolls back the runtime's tenant, subscription, Stripe customer and password-path account. Do not assume external side effects of your listener roll back automatically. Keep it to bounded persistence work rather than network provisioning; use durable `created` delivery for post-payment resources.
+
+Extras reach password and OAuth completion paths unchanged, are absent when nothing was captured, and remain consumer-owned. The runtime does not persist or return them. `/registration` exports `RegistrationExtrasLimits` and `REGISTRATION_EXTRAS_LIMITS`: `maxSerialisedBytes: 4096`, `maxKeys: 64`, `maxDepth: 4`. Public registration also rejects `__proto__`, `constructor`, and `prototype` keys. Rejected extras produce HTTP 400 `saas.errors.registration.extras_*` errors before listeners run.

package/docs/4.pages-plans-data.md

@@ -0,0 +1,64 @@
+---
+title: Pages, plans and data
+description: Stable page extension anchors, plan projections and safe use of the canonical data exports.
+---
+
+# Pages, plans and data
+
+These contracts let consumers build backend-declared DMS pages without importing private SaaS controllers.
+
+## Page extensions
+
+Import from `/pages`. `tenantBillingPage` identifies `settings.workspace.billing` at `/settings/workspace/billing`. Its `components` exposes `freeAccessBanner`, `pastDueAlert`, `planCard`, `paymentMethod`, `billingForm`, `refundButton`, and `table` anchors. `TenantBillingPageComponentKey` is the union of those keys; `tenantBillingPageAnchorPaths` maps them to the current nested layout. Use keys instead of copying paths.
+
+`RegisterTenantBillingPageExtension(extension: TenantBillingPageExtension): TenantBillingPageExtensionRegistration` registers `{ name: string, components: readonly TenantBillingPageExtensionComponent[] }` and returns `{ unregister(): void }`. Registration may precede page loading; call the handle's `unregister()` during `stop()`.
+
+Each component has `key: string`, `component: Component`, and optional `order: number` (default 0). An anchored component adds `side: "before" | "after"` and `anchorKey: TenantBillingPageComponentKey`; an appended component has optional `side: "end"` and no anchor. These are exported as `TenantBillingPageExtensionComponentBase`, `TenantBillingPageAnchoredExtensionComponent`, and `TenantBillingPageAppendedExtensionComponent`. The plan/payment anchors resolve inside their column's stack, not to an extra grid column.
+
+`platformSaasModule: CategoryInfo` is a synchronous descriptor, not the canonical registered module object. `GetPlatformSaasModule(): Promise<CategoryInfo>` resolves that object after runtime attachment and rejects when unavailable. `platformWorkspaceDetailPage` identifies `modules.saas.customers.workspaces.detail`, with `header`, `summary` and `body` anchors.
+
+`RegisterPlatformWorkspaceDetailPageExtension(extension: PlatformWorkspaceDetailPageExtension): PlatformWorkspaceDetailPageExtensionRegistration` accepts `{ name: string, components: readonly PageExtensionComponent[] }` and returns an unregister handle. Use the DMS `PageExtensionComponent` placement contract for these blocks. These registrations do not grant access: the platform detail remains owner-only, and tenant page components need appropriate metadata/permissions.
+
+`/page-definitions` exports `MODULES_ROOT_DEFINITION: PageInfo`, `SAAS_MODULE_ID = "saas"`, and `SAAS_MODULE_DEFINITION` (full ID, full slug and module registration metadata). These are descriptors, not runtime registration functions. The workspace settings category itself comes from `@antelopejs/interface-dms/page`.
+
+```ts docs-check
+import { PageController, RegisterPage, workspaceSettingsCategory } from "@antelopejs/interface-dms/page";
+
+@RegisterPage()
+export class WorkspaceRegistriesController extends PageController("registries", {
+  displayName: "Registries",
+  category: workspaceSettingsCategory,
+  icon: "i-ph-package",
+  order: 10,
+}) {}
+```
+
+## Plan helpers
+
+Import from `/plans`. These helpers do not charge customers or authorize access.
+
+| Function | Contract |
+| --- | --- |
+| `monthlyPrice(plan: Plan): number` | Returns the price as a monthly amount; yearly prices divide by 12 |
+| `isDowngrade(current: Plan \| null, target: Plan, seats?: number): boolean` | Compares monthly cost, multiplying seat plans by at least one seat; seats default to 1. No current plan returns false; equal cost is not a downgrade |
+| `localizeFeature(feature: Feature, locale: string): Feature` | Applies localization to `displayName`, `description`, `tooltip`, and `unit`, listed by exported `FEATURE_LOCALIZED_FIELDS`; missing translations fall back to the table locale (`en`) |
+| `buildTenantPlanCatalog(planModel: PlanModel, featureModel: FeatureModel, plans: Plan[], locale: string): Promise<TenantPlanCatalog>` | Reads features, resolves plan inheritance, excludes unknown feature IDs and sorts plans/features by order; model read failures reject |
+
+`TenantPlanCatalog` has `plans: TenantPlanView[]` and `features: TenantPlanFeature[]`.
+
+- `TenantPlanView`: `_id: string`, `name: string`, `price: number`, `currency: string`, `interval: PlanInterval` (`month` or `year`), `order: number`, `checkoutAvailable: boolean`, and `featureValues: Record<string, unknown>`. Checkout availability reflects a Stripe price reference, not an authorization decision.
+- `TenantPlanFeature`: `featureId: string`, `displayName: string`, `tooltip: string | null`, `unit: string | null`, `valueType: FeatureValueType` (`boolean`, `number`, or `string`), `isDetailRow: boolean`, and `order: number`.
+
+Keep caller-supplied plan/model scopes authorized. The catalogue builder does not filter an arbitrary plan list to what a user may buy. Write localized feature values using the canonical model's `localize("*")` convention; see the [feature integration guide](/docs/modules/saas/extending#plan-feature-labels-and-values).
+
+## HiddenStringFilter
+
+`HiddenStringFilter(): PropertyDecorator` is exported from `/data-api` and `/hidden-filter`. It registers string comparisons, including `is` for `TableView.routeParamFilters`, without a visible `@Column`. Apply it to the data controller prototype field, such as `_instance` or `userId`.
+
+An unregistered filter can be silently dropped by the data API, so declaring a hidden route filter matters for scoping. The decorator itself does not authenticate a user or make a client-supplied tenant ID trustworthy; enforce the scope at the server authorization boundary.
+
+## Canonical database surface
+
+`/db` exports the table/model pairs for plans, features, subscriptions, billing info/state/settings, invoices, credit notes, refunds, legal documents, trial consumptions, segments, user segments, platform notes, plan migrations and Stripe webhook events. `/db/models` and `/db/tables` expose those groups separately. For example, `PlanModel` works with `Plan`, `FeatureModel` with `Feature`, and `TenantSubscriptionModel` with `TenantSubscription`; use their shipped TypeScript declarations for persistence fields and methods.
+
+These are registered persistence objects, not copies to redeclare. Imports have registration side effects; prefer type-only imports for types. Direct model writes bypass runtime orchestration and require correct tenant scope. See the [database boundary](./1.index.md#database-imports-have-side-effects) before writing seeds or imports, and [recompute derived billing state](./2.billing.md#recomputetenantbillingstate) after writing relevant records.

package/docs/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "composite": false,
+    "incremental": false,
+    "declaration": false,
+    "noEmit": true
+  },
+  "include": ["../src/**/*.ts", "./**/*.ts"]
+}

package/package.json

@@ -1,15 +1,28 @@
 {
   "name": "@antelopejs/interface-dms-saas",
-  "version": "0.3.0",
-  "description": "Public interfaces for the DMS SaaS module",
+  "version": "0.4.1",
+  "description": "AntelopeJS interface for the DMS SaaS module: billing, plans, registration, workspace pages and lifecycle extension points.",
+  "keywords": [
+    "antelopejs",
+    "billing",
+    "dms",
+    "interface",
+    "saas"
+  ],
+  "homepage": "https://dms.antelopejs.com/docs/modules/saas/extending",
+  "bugs": {
+    "url": "https://github.com/AntelopeJS/dms-saas/issues"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/AntelopeJS/dms-saas.git"
+    "url": "git+https://github.com/AntelopeJS/dms-saas.git",
+    "directory": "packages/interface-dms-saas"
   },
   "files": [
     "dist",
     "!dist/.tsbuildinfo",
+    "docs",
     "package.json",
     "README.md",
     "LICENSE"
@@ -57,13 +70,13 @@
     "prepack": "pnpm run build"
   },
   "dependencies": {
-    "@antelopejs/interface-data-api": ">=0.1.9 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.3.1 <1.0.0"
+    "@antelopejs/interface-data-api": ">=0.2.2 <1.0.0",
+    "@antelopejs/interface-dms": ">=0.7.2 <1.0.0"
   },
   "devDependencies": {
-    "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.8 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.1.7 <1.0.0",
+    "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
+    "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
+    "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0",
     "@types/node": "^24.0.0",
     "knip": "^6.34.0",
     "oxfmt": "^0.66.0",
@@ -75,9 +88,9 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.8 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.1.7 <1.0.0"
+    "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
+    "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
+    "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0"
   },
   "packageManager": "pnpm@10.2.0",
   "antelopeJs": {}